Junction Health SDK

Overview of the Junction Health SDK for integrating with Apple HealthKit and Android Health Connect, including setup and common API usage.

Overview

Make sure you have successfully integrated with a Junction 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 Junction Mobile SDK.

This Junction Health SDK guidance page focuses on the initial setup and API usage of the Health SDK that is common to Apple HealthKit, Android Health Connect, and Samsung Health integrations, where supported.

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

Apple HealthKit

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

Android Health Connect

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

Samsung Health

Learn how to integrate with Samsung Health through Junction Mobile SDKs, available in Native Android and React Native.

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, Health Connect and Samsung Health connections — as if they are like their cloud-based counterparts — you might find the Explicit Connect mode more appealing.

iOS apps: Configure your App Delegate

This section applies to:

• 🔘 Native iOS apps
• 🔘 React Native iOS apps

This section does not apply to:

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

Junction Flutter SDK (4.3.8 and later) automatically integrates with your App Delegate through the Flutter Plugin machinery. You need not manually 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

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

Swift

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.

Health Connect and Samsung Health are two independent SDK integrations on Android, despite sharing the same Health SDK API. If you intend to use both integrations, you must configure both of them explicitly.

For Android via Expo and React Native, the Health SDK API assumes Health Connect by default. To target Samsung Health, you must pass "samsung_health" to the provider argument when calling the API.

Native iOS

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.

For Android via Expo and React Native, the Health SDK API assumes Health Connect by default. To target Samsung Health, you must pass "samsung_health" to the provider argument when calling the API.

Native iOS

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 prompt is managed by the operating system. Junction 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 make 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 an 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.

For Android via Expo and React Native, the Health SDK API assumes Health Connect by default. To target Samsung Health, you must pass "samsung_health" to the provider argument when calling the API.

Native iOS

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:

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

• Apple HealthKit guide
• Android Health Connect guide
• Samsung Health guide

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 or the Samsung Health guide for the full context and required configuration of these two behaviours.

Background Sync Frequency

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

1. Configured Apple HealthKit Background Delivery as per instruction; and
2. Configured Android Background Sync for the provider you are using — Health Connect or Samsung Health — 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
• Samsung Health: Background Sync

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

For Android via Expo and React Native, the Health SDK API assumes Health Connect by default. To target Samsung Health, you must pass "samsung_health" to the provider argument when calling the API.

Native iOS

import VitalHealthKit

// Pause Synchronization
VitalHealthKitClient.shared.pauseSynchronization = true

// Unpause Synchronization
VitalHealthKitClient.shared.pauseSynchronization = false

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

Sync Status

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

Native iOS

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:

Flutter

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.

Persistent Logging (iOS only)

While Junction Dashboard provides a fairly comprehensive Mobile SDK Sync Progress view, the reporting mechanism can only include condensed and headline information in order to conserve network bandwidth usage.

In order to troubleshoot data sync issues that are non-reproducible in controlled environments, the Health SDK supports opt-in Persistent Logging which would keep logs on disk across application launches.

The archive file is simply an Apple Archive (aar) containing various JSON files and plain text logs. Your app developers are welcomed to dig into it for a self-troubleshooting attempt.

iOS

import VitalCore
import VitalHealthKit

// Toggle Persistent Logging
// ℹ️ Note that this persists across application launches.
VitalPersistentLogger.isEnabled = true

// Generate the archive file, and open the system Share Sheet.
VitalHealthKitClient.createAndShareLogArchive()

You can introduce a couple of simple UI controls in a non-prominent location in your user experience, e.g., the app settings screen:

• A “Capture Sync Issues” switch, which toggles the SDK Persistent Logging.
• A “Share the Capture” button, which triggers the archive file generate-and-share flow.

Then on an as-needed basis, your support team can:

1. Instruct users to enable capturing; and
2. In a few days time, share the capture (archive file) with you.

Junction may also require your support team’s help to obtain an archive file, in order to make progress on any non-reproducible issue reports.