Apple Health and Health Connect

The app reads the trainee’s daily step count from the phone and sends it to the server. It reads steps only and writes nothing back to the health store. iOS uses HealthKit. Android uses Health Connect. The code is src/features/health.

File	Role
`lib/types.ts`	`HealthProvider`, `HealthDayTotal`, `HealthCursor`
`lib/provider.ts`	`getHealthProvider()` picks by platform
`lib/healthKit.ts`	iOS provider
`lib/healthConnect.ts`	Android provider
`lib/sync.ts`	`syncHealthData()` and the result type
`lib/connect.ts`	`connectHealth()` and `promptForHealthAccessOnce()`
`lib/backgroundTask.ts`	Background task definition and registration
`lib/sources.ts`	`highestSourcePerDay()`
`lib/installPrompt.ts`	The install alert and `whenAppReturns()`
`lib/runtime.ts`	`isVersionAtLeast()`, `runtimeIsAtLeast()`
`lib/constants.ts`	Identifiers, windows and version gates
`data/healthApi.ts`	The two API calls
`hooks/useHealthSync.ts`	Connection state for the profile card
`hooks/useForegroundHealthSync.ts`	Sync on launch and on foreground
`hooks/useHealthSummary.ts`	Query for the server summary
`presentation/HealthConnectCard.tsx`	The card on the profile tab

Endpoints

Call	Body	Returns
`POST /v1/trainee/health/days`	`{ days: [{ date, steps }] }`	`{ days }`, the number of days updated
`GET /v1/trainee/health/summary`		`{ range: { from, to }, days: [{ date, steps }] }`

date is a local calendar date, YYYY-MM-DD.

Provider interface

Both platforms implement the same contract, so everything above it is platform neutral.

export interface HealthProvider {
  source: 'HEALTHKIT' | 'HEALTH_CONNECT';
  isAvailable(): Promise<boolean>;
  hasPermissions(): Promise<boolean>;
  requestPermissions(): Promise<boolean>;
  canPromptAutomatically(): boolean;
  shouldPromptForAccess(): Promise<boolean>;
  needsInstall(): Promise<boolean>;
  openInstall(): Promise<boolean>;
  collect(cursor: HealthCursor): Promise<HealthCollectResult>;
  enableBackground(): Promise<boolean>;
}

getHealthProvider() returns null on web. Both native libraries are loaded with a guarded dynamic import() inside loadHealthKit() and loadHealthConnect(). If the module is missing, every provider method returns a safe default and the feature reports itself unavailable.

Collecting steps

Each sync re-reads a full window and sends daily totals. There is no incremental cursor.

Constant	Value
`HEALTH_SYNC_LOOKBACK_DAYS`	`30`
`HEALTH_CURSOR_VERSION`	`3`

The stored cursor only records version and lastSyncAt. Re-sending 30 days each time means late-arriving data, such as a watch that syncs hours later, corrects earlier days. The server upserts by day.

Never sum raw samples

A phone and a watch both record the same walk. Adding raw samples counts those steps twice. Both providers avoid that in two ways:

They ask the health store for a statistics aggregate per day instead of reading samples.
When more than one source contributed, they take the highest single source for each day with highestSourcePerDay().

export function highestSourcePerDay(entries: readonly HealthSourceDayTotal[]): HealthDayTotal[] {
  const best = new Map<string, number>();
  for (const entry of entries) {
    if (entry.steps <= 0) continue;
    const current = best.get(entry.date);
    if (current === undefined || entry.steps > current) {
      best.set(entry.date, entry.steps);
    }
  }
  return [...best].map(([date, steps]) => ({ date, steps }));
}

iOS

healthKit.ts queries HKQuantityTypeIdentifierStepCount with the cumulativeSum statistic in one-day intervals, anchored at the start of the window.

If queryStatisticsCollectionForQuantitySeparateBySource exists, it is used and reduced with highestSourcePerDay. The source key is the bundle identifier.
Otherwise it falls back to queryStatisticsCollectionForQuantity.
If neither function exists it returns no days.

The bucket date is converted with localIsoDate, so days follow the device’s local calendar.

Android

healthConnect.ts calls aggregateGroupByPeriod for the Steps record with a one-day slicer.

With fewer than two data origins in the result, the combined totals are used.
With two or more, it runs one aggregate per origin with dataOriginFilter and reduces with highestSourcePerDay.

Sync

syncHealthData() in sync.ts is the single entry point. It never throws for expected conditions. It returns a HealthSyncResult:

export interface HealthSyncResult {
  reason: 'ok' | 'unavailable' | 'not-connected' | 'permission' | 'auth' | 'network' | 'error';
  days: number;
  updated: number;
  detail?: string;
}

Steps, in order:

No provider, or the provider is unavailable: unavailable.
healthStorage.isConnected() is false: not-connected.
provider.hasPermissions() is false: permission.
ensureAuthToken() loads the bearer token from SecureStore if memory is empty. No token: auth.
Read the cursor. A cursor with a different version is treated as empty.
provider.collect(cursor).
If there are days, POST /v1/trainee/health/days.
Save the new cursor.

A failure at any stage goes through healthSyncFailure(stage, error), which returns network when the error is an ApiError with status 0 and error otherwise, and logs the stage in development. Step 4 is why the token is stored with the after-first-unlock keychain class on iOS. A background run starts a fresh JS context with nothing in memory, possibly while the phone is locked. See Authentication.

When sync runs

Trigger	Where
Launch, once signed in	`useForegroundHealthSync()` in the root layout
Every return from background or inactive to active	Same hook
Background task	`backgroundTask.ts`
The profile card mounting while connected	`useHealthSync()`
The Sync now button	`useHealthSync().syncNow()`

Background sync

backgroundTask.ts defines the task at module scope:

TaskManager.defineTask(HEALTH_BACKGROUND_TASK, async () => {
  await syncHealthData();
  return RESULT_SUCCESS;
});

The root layout imports the file for its side effect, because a task must be defined every time the JS bundle loads, including headless background launches. The definition is wrapped in try/catch so a runtime without TaskManager, such as Expo Go, simply has no background sync.

Constant	Value
`HEALTH_BACKGROUND_TASK`	`'perform-health-sync'`
`HEALTH_BACKGROUND_INTERVAL_MINUTES`	`15`

registerHealthBackgroundTask() loads expo-background-task dynamically and registers with that minimum interval. The operating system decides the real schedule. Registration happens only after provider.enableBackground() returns true:

iOS calls enableBackgroundDelivery for step count with the immediate frequency. The entitlements com.apple.developer.healthkit and com.apple.developer.healthkit.background-delivery are in app.json.
Android needs the Health Connect background read permission. If it is not granted, the app asks once, records that in perform_health_background_prompted_v1, and never asks again after a refusal.

Connecting

Two paths lead to the same state. HealthConnectCard uses useHealthSync(), which exposes a status:

Status	Card shows
`unavailable`	The `healthUnavailable` text
`install`	An install prompt for Health Connect (Android)
`disconnected`	The Connect button
`connected`	Today’s steps, last sync time, Sync now and Disconnect

connectHealth() requests permission, sets perform_health_connected, enables background delivery and waits for the first sync so the card can report the result. The card maps reason to a toast: permission, unavailable, network, and a generic error for auth and error. Disconnect clears the connected flag, the cursor and the background prompt flag, and unregisters the task. It cannot revoke the OS permission. The trainee does that in system settings. While the status is install, the hook re-checks availability each time the app becomes active, so returning from the Play Store updates the card.

First-launch prompt

promptForHealthAccessOnce() is the second of the three startup prompts, after push permission and before the app update check. See Route tree. Rules encoded here, each covered by scripts/test-health-first-launch-prompt.cjs:

The prompt is marked as shown before the permission request, so a crash or a kill during the sheet does not cause a second prompt.
The first-launch path does not wait for the sync. The profile button does.
A trainee who declines is not asked again. They can still connect from the profile.
The whole function is wrapped in try/catch. The prompt must never break a launch.

iOS

shouldPromptForAccess() asks HealthKit with getRequestStatusForAuthorization. It prompts only while the status is shouldRequest, meaning the system sheet would still appear. canPromptAutomatically() is always true and there is never anything to install.

Android

The app allows one automatic prompt per install, tracked by perform_health_connect_prompted, and skips it when steps access is already granted. canPromptAutomatically() is gated on the installed app version, because the permission screen depends on native setup that older binaries lack:

Android API level	Minimum app version	Constant
34 and newer	`1.0.6`	`HEALTH_CONNECT_PROMPT_MIN_RUNTIME`
33 and older	`1.0.5`	`HEALTH_CONNECT_LEGACY_PROMPT_MIN_RUNTIME`

The version comes from Constants.expoConfig.version through runtimeIsAtLeast(). This gate matters because a JS update can reach an older binary. See OTA updates. needsInstall() is true only when the SDK status is SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED. The install offer is shown once (perform_health_connect_install_offered). openInstall() tries the Play Store deep link, then the web listing.

Native setup

iOS

app.json declares the HealthKit entitlements and NSHealthShareUsageDescription, and configures the @kingstinct/react-native-healthkit plugin with background: true.

Android

Piece	Where	Why
Permissions `android.permission.health.READ_STEPS` and `READ_HEALTH_DATA_IN_BACKGROUND`	`app.json`	Declared permissions
`minSdkVersion: 26`	`expo-build-properties` in `app.json`	The Health Connect client library requires it
`react-native-health-connect` plugin	`app.json`	Library setup
`plugins/withHealthConnectPermissionDelegate.js`	Local config plugin	Registers the permission delegate in `MainActivity.onCreate`
`plugins/withHealthConnectPermissionsRationale.js`	Local config plugin	Adds the activity alias Android 14 uses to show the permissions rationale
`patches/react-native-health-connect@3.5.3.patch`	pnpm patch	Turns an uncaught exception in the permission dialog into a rejected promise

Details of the plugins and the patch are in Native modules and config plugins.

Stored state

Key	Meaning	Cleared on sign out
`perform_health_connected`	The trainee connected	No
`perform_health_state`	The cursor: `{ version, lastSyncAt }`	Yes
`perform_health_connect_prompted`	The first-launch prompt has run	No
`perform_health_connect_install_offered`	The install offer has been shown	No
`perform_health_background_prompted_v1`	Background access was asked for	Yes

Manual steps

/track/steps renders StepsScreen in the tracking feature, where a trainee types a step count by hand. It is separate from this sync. See Tracking and uploads.

​Endpoints

​Provider interface

​Collecting steps

​Never sum raw samples

​iOS

​Android

​Sync

​When sync runs

​Background sync

​Connecting

​Profile card

​First-launch prompt

​iOS

​Android

​Native setup

​iOS

​Android

​Stored state

​Manual steps

Endpoints

Provider interface

Collecting steps

Never sum raw samples

iOS

Android

Sync

When sync runs

Background sync

Connecting

Profile card

First-launch prompt

iOS

Android

Native setup

iOS

Android

Stored state

Manual steps