Documentation Index
Fetch the complete documentation index at: https://mintlify.com/kingstinct/react-native-healthkit/llms.txt
Use this file to discover all available pages before exploring further.
Background delivery allows your app to receive updates when specific HealthKit data changes, even when your app isn’t running.
Enable background delivery
enableBackgroundDelivery
Enable background delivery for a specific data type.
function enableBackgroundDelivery(
typeIdentifier: ObjectTypeIdentifier,
updateFrequency: UpdateFrequency
): Promise<boolean>
typeIdentifier
ObjectTypeIdentifier
required
The HealthKit data type to monitor for changes
How frequently to receive updates:
UpdateFrequency.immediate - As soon as data changesUpdateFrequency.hourly - Once per hourUpdateFrequency.daily - Once per dayUpdateFrequency.weekly - Once per week
Promise<boolean> - Resolves to true if successful
import { enableBackgroundDelivery, UpdateFrequency } from '@kingstinct/react-native-healthkit';
// Enable immediate background updates for heart rate
await enableBackgroundDelivery(
'HKQuantityTypeIdentifierHeartRate',
UpdateFrequency.immediate
);
// Enable hourly background updates for steps
await enableBackgroundDelivery(
'HKQuantityTypeIdentifierStepCount',
UpdateFrequency.hourly
);
Background delivery requires the “Background Modes” capability with
“Background fetch” enabled in your Xcode project.
Disable background delivery
disableBackgroundDelivery
Disable background delivery for a specific data type.
function disableBackgroundDelivery(
typeIdentifier: ObjectTypeIdentifier
): Promise<boolean>
typeIdentifier
ObjectTypeIdentifier
required
The HealthKit data type to stop monitoring
Promise<boolean> - Resolves to true if successful
import { disableBackgroundDelivery } from '@kingstinct/react-native-healthkit';
await disableBackgroundDelivery('HKQuantityTypeIdentifierHeartRate');
disableAllBackgroundDelivery
Disable background delivery for all data types.
function disableAllBackgroundDelivery(): Promise<boolean>
Promise<boolean> - Resolves to true if successful
import { disableAllBackgroundDelivery } from '@kingstinct/react-native-healthkit';
await disableAllBackgroundDelivery();
Complete example
import {
requestAuthorization,
enableBackgroundDelivery,
subscribeToChanges,
UpdateFrequency,
} from '@kingstinct/react-native-healthkit';
// 1. Request authorization
await requestAuthorization({
toRead: ['HKQuantityTypeIdentifierHeartRate'],
});
// 2. Enable background delivery
await enableBackgroundDelivery(
'HKQuantityTypeIdentifierHeartRate',
UpdateFrequency.immediate
);
// 3. Subscribe to changes
const unsubscribe = subscribeToChanges(
'HKQuantityTypeIdentifierHeartRate',
() => {
console.log('Heart rate data changed!');
// Fetch new data...
}
);
// Later: Clean up
unsubscribe();
await disableBackgroundDelivery('HKQuantityTypeIdentifierHeartRate');
Best practices
Use anchored queries to efficiently sync only new and changed data when your
app receives a background update.
import {
subscribeToChanges,
queryQuantitySamplesWithAnchor,
} from '@kingstinct/react-native-healthkit';
let savedAnchor: string | undefined;
subscribeToChanges('HKQuantityTypeIdentifierStepCount', async () => {
// Only fetch data that changed since last sync
const { newAnchor, samples, deletedSamples } =
await queryQuantitySamplesWithAnchor(
'HKQuantityTypeIdentifierStepCount',
{
anchor: savedAnchor,
limit: 100,
}
);
// Process new and deleted samples
console.log(`${samples.length} new, ${deletedSamples.length} deleted`);
// Save anchor for next sync
savedAnchor = newAnchor;
});
Background delivery doesn’t guarantee immediate delivery. The system may
delay or coalesce updates to preserve battery life.
Setup requirements
Native setup
Add the background mode capability in Xcode:
- Open your project in Xcode
- Select your target
- Go to “Signing & Capabilities”
- Click ”+ Capability” and add “Background Modes”
- Check “Background fetch”
Expo setup
Add to your app.json:
{
"expo": {
"ios": {
"infoPlist": {
"UIBackgroundModes": ["fetch"]
}
}
}
}