Skip to main content

AppleHealthSync

Render this component inside an AppleHealthAuthorizationProvider to import the HealthKit types requested by the screen. It starts the initial sync when mounted, watches for HealthKit changes, and reports progress through callbacks. It renders no visible UI.

import { DataSync } from "@ovok/native/data-sync";
import { HKQuantityTypeIdentifier } from "@kingstinct/react-native-healthkit";

<DataSync.AppleHealthAuthorizationProvider
  readIdentifiers={[HKQuantityTypeIdentifier.bodyMass]}
>
  <DataSync.AppleHealthSync
    dataToSync={appleDataToSync}
    chunkSize={250}
    wifiOnly
    onProgress={setProgress}
    onError={handleSyncError}
  />
</DataSync.AppleHealthAuthorizationProvider>;

Props​

PropRequiredDefaultDescription
dataToSyncYes—Maps HealthSyncKey values to HealthKit sample identifiers and observation codes.
chunkSizeNo250Maximum source records read in a provider page.
wifiOnlyNofalsePause when the device is connected over a non-Wi-Fi network.
backgroundDeliveryNo—Enable HealthKit background delivery for mapped identifiers.
onProgressNo—Receive the partial per-key progress map.
onErrorNo—Receive an Error, FHIR Bundle<Resource>, or null.

Each dataToSync value contains typeIdentifiers, an optional minDate, and an optional mode. See the HealthKit and Health Connect guide for the mapping rules and default modes.

Behavior​

  • The component uses the active OvokClient and patient profile from @ovok/core context. Mount it after both are ready.
  • A first import reads the most recent 30 days by default. Set minDate when the feature needs an earlier initial boundary.
  • Existing observations and HealthKit query anchors guide later reads. Configure client storage if anchors should survive app restarts.
  • Progress updates include idle, started, syncing, paused, failed, or completed; pause reasons are offline and wifi-only.
  • Offline connectivity pauses the service. wifiOnly also pauses it on cellular, then the service resumes when the network meets the policy.

backgroundDelivery={{ frequency }} enables HealthKit observer delivery for each mapped identifier. The default frequency is hourly. Add the HealthKit background capability in the native config and rebuild the app. iOS decides when observer work runs; the option is not a fixed schedule.

Keep AppleHealthSync mounted while the app should receive observer updates. When the component unmounts, it removes the subscriptions and disables background delivery for the mapped identifiers.

HealthKit does not expose read-denial state. Empty sample results do not necessarily mean that the import configuration is wrong.