Please consult the following guides on requirements and restrictions of Apple HealthKit and Android Health Connect:

The Health SDK guide focuses on the API usage of the Health SDK.

SDK configuration

The Health SDK must be configured before use. The configuration is persistent, so you can do this only once, immediately after a successful authentication with the Core SDK.

Ask user for health data permissions

Before the SDK can read any data, you need to ask the end user to grant health data permissions.

import VitalHealthKit

await VitalHealthKitClient.shared.ask(
  readPermissions: [.activity, .workout, .sleep],
  writePermissions: []

Note that the OS only prompts the end user once for each resource type. Subsequent requests are gracefully ignored by the OS.

Automatic Data Sync

Vital Health SDK automates data sync for you on both Android and iOS. Please first consult the provider-specific guides for the requirements and setup instructions:


Sync is automatically…
Activated onAll resource types you have asked permission for.
Triggered byTwo behaviours:
  • Foreground: Apple HealthKit immediately delivers buffered and new changes.
  • Background: Hourly batch delivery of changes, subject to OS throttling.

HealthKit change notification is an always-on behaviour.

If you did not configure Apple HealthKit Background Delivery as instructed, your app will not receive any HealthKit change notification while it is in background. In turn, background sync would not occur.


Sync is automatically…
Activated onAll resource types you have asked permission for.
Triggered byTwo mechanisms:

Sync On App Launch is an always-on behaviour. Background Sync (Experimental) is an opt-in behaviour.

Please refer to the Android Health Connect guide for the full context and required configuration of these two behaviours.

Background Sync Frequency

Vital Health SDK schedules hourly background sync with both Apple HealthKit and Android Health Connect, provided that you have:

  1. Configured Apple HealthKit Background Delivery as per instruction; and
  2. Configured Health Connect Background Sync (Experimental) and request user permissions (when necessary) as per instruction.

However, this schedule is only advisory. The OS has full discretion to defer the scheduled time based on runtime constraints like battery power, as well as platform background execution policies. For more detailed explanation, please refer to:

In other words, your product experience should not assume near real-time availability of wearable data, since the norm is a variable delay ranging from an hour to a day. Longer delay is also possible due to the lack of Internet connectivity, e.g., a long-haul flight, or an off-the-grid trip.

The only possible exception is when your product experience does involve active usage of your consumer app with an active Internet connection. For example, iOS 17+ supports third-party apps initiating an Apple Watch workout session that would be live synced with your iPhone app.

Pausing Data Synchronization

You can pause and unpause data sync at any time, without having to sign-out the user from the Vital Mobile SDK. Note that pausing data sync does not reset the incremental sync progress and does not trigger a historical stage upon unpause. It only “freezes” the sync progress.

Manually start data sync

You can force data sync to start with syncData().

Writing data

You can also write data back to Apple HealthKit and Android Health Connect:

Not all resources are writable in both iOS and Android. Please refer to the health_resource.dart file.

Sync Status

You can observe the syncStatus stream for continuous updates on the health data sync status.