Skip to main content

Background work

The SDK has separate background paths for Bluetooth result delivery, Android Health Connect import, and Apple HealthKit observer delivery. They have different permissions, persistence needs, and operating-system limits.

Bluetooth result delivery​

Enable backgroundSync on BTProvider and provide durable storage plus an onResult callback. The SDK stores a result before delivery and removes it after the callback resolves. Delivery is at least once, so use the stable result id as an idempotency key when saving it.

Do not use in-memory storage for readings that must survive process death. The queue can contain large ECG results; choose storage with enough capacity and a deletion/retention policy appropriate for health data.

import { createFileQueueStorage } from '@ovok/native/bt-management';

<BTProvider
  bleManager={bleManager}
  acceptedDevices={acceptedDevices}
  backgroundSync={{
    enabled: true,
    storage: createFileQueueStorage(),
    restoreStateIdentifier: 'com.example.app.bluetooth',
    onResult: async (result) => saveMeasurement(result),
    maxRetries: 3,
    retryBackoffMs: 30_000,
  }}
/>

The host app remains responsible for authentication and uploading queued results. A background service does not preserve the React tree or restore a signed-in client for you.

Android Health Connect scheduling​

Scheduled import uses a headless task and WorkManager; it is separate from Bluetooth background delivery. Register a task that restores the client, patient identity, and mapping, then schedule it using the background-sync subpath. Android may defer work to meet system constraints, so an interval is not an exact execution time.

The minimum WorkManager interval is 15 minutes. Cancel scheduled work when the user disables the feature. Request Health Connect’s background-read permission separately from foreground read permission.

iOS restoration and HealthKit delivery​

iOS controls when Bluetooth restoration and HealthKit observer work can run. Keep the restoration identifier stable and configure required background modes and service UUIDs. These settings allow the operating system to relaunch eligible work; they do not guarantee continuous scanning or immediate delivery.

Before shipping​

  • Test with the app backgrounded, terminated, and relaunched on real devices.
  • Test denied and revoked permissions, disconnected networks, retries, and exhausted queue items.
  • Ensure the receiving API deduplicates by result ID.
  • Explain background activity and notifications to the person using the app.
  • Review the platform's background-work and store policies for each permission requested.