Apple Health

With Thryve you can easily integrate your iOS application with Apple Health, Apple's on-device health data store, via the `ThryveAppleHealth` module.

ThryveAppleHealth handles the HealthKit permission flow so your app can easily read health data (steps, vitals, sleep, workouts, nutrition, and more) recorded by the iPhone, Apple Watch, and any other app or device that writes to Apple Health, without having to integrate each source separately.

Apple Health is only available on iOS. Your app must have the HealthKit capability with Background Delivery enabled, and both NSHealthShareUsageDescription and NSHealthUpdateUsageDescription in its Info.plist. A missing description leads to rejection during App Store review. See Setup Thryve SDK → iOS for the full project configuration.

On devices without HealthKit (e.g. iPads before iPadOS 17), start returns error 70004 and Apple Health is not shown in the Thryve Connection Widget.

Data availability

Apple Health only exposes data that has already been written to it on the user's iPhone, by the iPhone itself, a paired Apple Watch, or a third-party app (e.g. a scale, a sleep tracker, a nutrition app). If nothing writes a given data type to Apple Health, Thryve will not receive it either.

• First sync is today only. The first synchronize after connecting (or after stop, reinstall, or a new device) fetches data for the current day only. Use historic data backfill to fetch earlier data.

• Backfill limits. backfillEpoch accepts ranges of up to 30 days and backfillDaily up to 365 days per call. Longer ranges return error 70015; split them into several calls.

• Limited history (iOS 27 and later). After choosing data types, the user picks how much history to share: Past 30 Days and Future Data or All Recorded Data and Future Data. With the 30-day option, Apple Health never returns data recorded before that limit, in backfill or in synchronize, and without an error. New data keeps syncing, but backfill of older data returns nothing, and data that another app or device writes to Apple Health late, dated before the limit, is skipped.

• Denied permissions are invisible. For privacy reasons, iOS never tells an app whether the user denied read access to a data type. A denied type behaves exactly like a type with no data: it syncs successfully and returns nothing.

• Data is locked with the phone. Apple Health data is encrypted while the iPhone is locked. A sync that runs while the device is locked cannot read data and fails with error 70106. The data is picked up by the next sync after the user unlocks the phone.

• Background timing is controlled by iOS. The SDK asks HealthKit to wake the app as soon as new data arrives, but iOS decides when that actually happens based on battery, device usage and system load. We recommend calling synchronize whenever your app comes to the foreground.

• Permissions are per device. HealthKit permissions do not move to a new iPhone. If the user is connected on the Thryve backend but has granted no permissions on the current device, the SDK returns error 70031. Call start again to show the permission sheet.

We recommend asking users to choose All Recorded Data and Future Data on the iOS 27 permission screen, for example in your onboarding before calling start. Apps cannot preselect this option, and iOS only tells an app when access is limited, never when full access was granted.

Calling stop stops data synchronization, but your app will still appear as connected in the Apple Health app. Apple does not allow apps to revoke their own access. Only the user can remove it in Health → Profile → Apps.

Capabilities

• Lifecycle & permissions: Connects and disconnects via start / stop, checks availability and active state, and requests HealthKit read permissions for the data types you configure.

• Incremental sync: synchronize uses HealthKit anchored queries to fetch only new and updated samples since the last sync, plus daily aggregates, and uploads them to the Thryve backend.

• Background sync: Uses HealthKit background delivery to sync when new data is written to Apple Health, even while your app is in the background. Enabled by default via enableBackgroundSync in ThryveAppleHealthConfig.

• Historical backfill: backfillEpoch reads raw samples over a date range (up to 30 days); backfillDaily reads daily aggregates over a date range (up to 365 days).

• Data types & configuration: Maps over 90 HealthKit data types into Thryve's standardised format. You choose which types to request in ThryveAppleHealthConfig.dataTypes.

• Observability: OpenTelemetry-style spans for sync, backfill, permission requests, reads and uploads to aid debugging and monitoring. See Observability.

Supported Data Types

The ThryveAppleHealth module supports over 90 HealthKit data types, including quantity types (e.g. steps, heart rate, body mass), category types (e.g. sleep analysis, mindful sessions), workouts, heartbeat series, ECG and characteristics (e.g. date of birth, biological sex). We map these to Thryve's standard data types. See the full list of supported data types.

How to integrate Thryve SDK Apple Health module

1. Configure your Xcode project for HealthKit: Setup Thryve SDK → iOS. For React Native and Flutter, see React Native and Flutter.

2. Add ThryveAppleHealthConfig to your SDK configuration and connect the user: Connect data sources.

3. Set up background, manual and historic synchronization: Apple Health, Health Connect & Samsung Health.