Junction Health SDK

Overview

Make sure you have successfully integrated with a Vital Mobile SDK authentication scheme, before you proceed to try out Junction Health SDK.

Mobile SDK Authentication

Learn how to authenticate your mobile app user with Vital Mobile SDK.

This Junction 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:

Apple HealthKit

Learn how to integrate with Apple HealthKit through Vital Mobile SDKs, available in Native iOS, React Native and Flutter.

Android Health Connect

Learn how to integrate with Android Health Connect through Vital Mobile SDKs, available in Native Android, React Native and Flutter.

Initial Setup

Review the Connection Policy options

Junction Health SDK has two Connection Policy options:

The default Auto Connect mode; and
The opt-in Explicit Connect mode.

If your device connection management UX is built upon an explicit notion of connecting and disconnecting Apple HealthKit and Health Connect connections — as if they are like their cloud-based counterparts — you might find the Explicit Connect mode more appealling.

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).

Vital Flutter SDK (4.3.8 and later) automatically integrates with your App Delegate through the Flutter Plugin machinery. You need not manual edit your AppDelegate in Flutter iOS projects.

You must configure your App Delegate as instructed if you use Junction 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 Junction Health SDK automaticConfiguration() synchronously before it returns.

Details

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 apps, the AppDelegate is part of the template Swift or Objective-C code in your generated Xcode project.

import VitalHealthKit

class AppDelegate: NSObject, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
  ) -> Bool {

    VitalHealthKitClient.automaticConfiguration()

    // ...

    return true
  }
}

Configure the Junction Health SDK

The Health SDK must be configured before use. The configuration is persistent, so you typically only need to do this a single time — immediately after a successful authentication with the Core SDK.

import VitalHealthKit

VitalHealthKitClient.configure(
  VitalHealthKitClient.Configuration(
    backgroundDeliveryEnabled: true,

    // Using Auto Connect mode (default)
    connectionPolicy: .autoConnect

    // Using Explicit Connect mode
    connectionPolicy: .explicit
  )
)

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.

import VitalHealthKit

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

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.

import VitalHealthKit

VitalHealthKitClient.shared.hasAskedForPermission(resource: .activity)

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

Junction Health SDK allows you to ask for permission and check if your app has asked for permission before. However, Junction Health SDK cannot tell you:

Whether or not a user has granted or denied a read permission after the Ask for Permission has concluded.
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 Junction Health SDK — would:

not be able to determine if a particular read permission has been granted or denied by the user;
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 System	System App	Location
iOS 8.0 and above	Health app	Sharing > Apps and Services
iOS 15.0 and above	Settings app	Privacy & Security > Health
Android 13 or below	Health Connect app	Apps and Permissions
Android 14 and above	Settings app	Health 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

Junction 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 on	All resource types you have asked permission for.
Triggered by	Two 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 on	All resource types you have asked permission for.
Triggered by	Two mechanisms: Sync On App Launch Background Sync if it is enabled.

Sync On App Launch is an always-on behaviour. Background Sync 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

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

Configured Apple HealthKit Background Delivery as per instruction; and
Configured Health Connect Background Sync 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.

import VitalHealthKit

// Pause Synchronization
VitalHealthKitClient.shared.pauseSynchronization = true

// Unpause Synchronization
VitalHealthKitClient.shared.pauseSynchronization = false

// Check if synchronization is paused
print("Paused? \(VitalHealthKitClient.shared.pauseSynchronization)")

Manually start data sync

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

import VitalHealthKit

VitalHealthKitClient.shared.syncData()

Writing data

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

import VitalHealthKit

try await VitalHealthKitClient.shared.write(
  input: .water(milliliters: 1000),
  startDate: Date(),
  endDate: Date()
)

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.

import VitalHealthKit

VitalHealthKitClient.shared.status.sink { status in
  print("Sync Status: \(status)")
}

Sync Progress Debugging UI (iOS only)

Sync Progress View on Native iOS

Junction 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)

Sync Progress UI on Flutter / React Native

You can open the Apple HealthKit Sync Progress Inspector UI through a simple call:

import 'package:vital_health/vital_health.dart' as vital_health;

unawaited(vital_health.openSyncProgressView());

This Sync Progress Inspector UI provides a live-updated sync progress feed of all the VitalResources whose permissions have been asked for.

Note that it is currently a no-op on Android.

Connecting Providers

Bring Your Own OAuth

Vital iOS App

Providers

Data

Mobile SDKs

Guides

Junction Health SDK

Overview

Mobile SDK Authentication

Apple HealthKit

Android Health Connect

Initial Setup

Review the Connection Policy options

iOS apps: Configure your App Delegate

Configure the Junction Health SDK

Health Data Permissions

Ask user for health data permissions

Check if your app has asked for permissions before

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

Automatic Data Sync

iOS

Android

Background Sync Frequency

Pausing Data Synchronization

Manually start data sync

Writing data

Sync Status

Sync Progress Debugging UI (iOS only)

Connecting Providers

Bring Your Own OAuth

Vital iOS App

Providers

Data

Mobile SDKs

Guides

​Overview

Mobile SDK Authentication

Apple HealthKit

Android Health Connect

​Initial Setup

​Review the Connection Policy options

​iOS apps: Configure your App Delegate

​Configure the Junction Health SDK

​Health Data Permissions

​Ask user for health data permissions

​Check if your app has asked for permissions before

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

​Automatic Data Sync

​iOS

​Android

​Background Sync Frequency

​Pausing Data Synchronization

​Manually start data sync

​Writing data

​Sync Status

​Sync Progress Debugging UI (iOS only)

Overview

Initial Setup

Review the Connection Policy options

iOS apps: Configure your App Delegate

Configure the Junction Health SDK

Health Data Permissions

Ask user for health data permissions

Check if your app has asked for permissions before

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

Automatic Data Sync

iOS

Android

Background Sync Frequency

Pausing Data Synchronization

Manually start data sync

Writing data

Sync Status

Sync Progress Debugging UI (iOS only)