Vital Health SDK

​

Overview

This Vital Health SDK guidance page focuses on the inital setup and API usage of the Health SDK that is common to both the Apple HealthKit and Android Health Connect integration.

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

​

Initial Setup

​

iOS apps: Configure your App Delegate

This section applies to:

• 🔘 Native iOS apps
• 🔘 React Native iOS apps

This section does not apply to:

• ❌ Fluter iOS apps (using Vital Flutter SDK 4.3.8 or later).

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

​

Configure the Vital Health SDK

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.

​

Health Data Permissions

​

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.

​

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:

​

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:

• Apple HealthKit guide
• Android Health Connect guide

​

iOS

​

Android

​

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:

• Apple HealthKit: Sync Frequency
• Android Health Connect: Sync Frequency

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:

​

Sync Status

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

​

Sync Progress Debugging UI (iOS only)

import VitalHealthKit

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

let viewController: UIViewController

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