Overview

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.

Configure your App Delegate (iOS only)

This applies to all iOS integrations — Native iOS, React Native or Flutter.

You must configure your App Delegate as instructed if you use Vital Health SDK on iOS. Not doing so may result in missing background delivery, or app process termination by the operating system.

In your AppDelegate’s application(_:didFinishLaunchingWithOptions:) implementation, it must call Vital Health SDK automaticConfiguration() synchronously before it returns.

Vital needs to register various handlers with the system frameworks like Apple HealthKit and BackgroundTasks. These frameworks require said registrations to be completed before the “app finished launching” moment [1] [2].

For React Native and Flutter apps, the AppDelegate is part of the template Swift or Objective-C code in your generated Xcode project.

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.

Regardless of whether the user has granted or denied the permissions, any subsequent re-request would be non-interactive and returns instantly. This is because the operating system only prompts the end user once for each resource type.

If you wish to provide a way for users to review their permission grants or denials, you can inform them of the system app location where they can do so.

The health data read permission prompted is managed by the operating system. Vital cannot customize or alter its behaviour.

Check if your app has asked for permissions before

You can check if your app has already asked the user at least once before, for permissions on a specific VitalResource.

Because Ask for Permission are gracefully ignored by the operating system beyond the first time, checking before asking can help you skip the parts of your UX journey that only makes sense to users going through Ask for Permission for the first time.

The only exception to this behaviour is when a VitalResource pulls a new data type introduced in a new OS release. In this scenario, calling Ask for Permission would result in a OS permission prompt that asks for permissions on specifically those new data types.

If you wish to provide a way for users to review their permission grants or denials, you can inform them of the system app location where they can do so.

Check if a read permission was granted or denied (⚠️ Spoiler: You can’t)

Vital Health SDK allows you to ask for permission and check if your app has asked for permission before.

However, Vital Health SDK cannot tell you:

  1. Whether or not a user has granted or denied a read permission after the Ask for Permission has concluded.
  2. The state of a read permission at any exact moment — granted or denied.

Apple made a deliberate choice to conceal the state of HealthKit data type read permissions from third-party apps. Quoting Apple’s own words (as at 27 September 2024):

To help prevent possible leaks of sensitive health information, your app cannot determine whether or not a user has granted permission to read data.

If you are not given permission, it simply appears as if there is no data of the requested type in the HealthKit store.

[…]

In other words, all third-party apps — including anyone using the Vital Health SDK — would:

  1. not be able to determine if a particular read permission has been granted or denied by the user;

  2. not be able to manage or review read permissions inside their app.

The best course of action out of this is to inform your users of the location where they can review and manage their health data read permissions:

Operating SystemSystem AppLocation
iOS 8.0 and aboveHealth appSharing > Apps and Services
iOS 15.0 and aboveSettings appPrivacy & Security > Health
Android 13 or belowHealth Connect appApps and Permissions
Android 14 and aboveSettings appHealth Connect > Apps and Permissions

When designing your user experience, assume you would have zero knowledge of permission grants and denials after the user has gone through the Ask for Permission flow.

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:

iOS

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.

Android

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.

Sync Progress Debugging UI (iOS only)

Vital Health SDK for iOS includes a ForEachVitalResource — a pre-baked SwiftUI View providing a live-updated sync progress feed of all the VitalResources whose permissions have been asked for.

You can use ForEachVitalResource() in any position which you would use ForEach. For example, you can use it inside a Section of a List:

Native iOS
import VitalHealthKit

struct SyncProgressView: View {
  var view: some View {
    List {
      Section(header: Text("Sync Progress")) {
        ForEachVitalResource()
      }
    }
  }
}

If you are using UIKit, you can still access it through UIHostingController:

Native iOS
let viewController: UIViewController

let hostingController = UIHostingController(rootView: SyncProgressView())
viewController.present(hostingController, animated: true, completion: nil)