Apple Health - Despia Documentation

Access Apple HealthKit from your web app through the Despia native bridge. Despia gives you three ways to work with health data: read historical records on demand, write new samples back to HealthKit, and subscribe to live updates via server webhooks. All three work from JavaScript with no native code required.

HealthKit is iOS only. Always gate calls behind an isDespiaIOS check so your app degrades gracefully in a browser or on Android.

Installation

Bundle
CDN

npm install despia-native

pnpm add despia-native

yarn add despia-native

import despia from 'despia-native';

<script src="https://cdn.jsdelivr.net/npm/despia-native/index.min.js"></script>

<script type="module">
    import despia from 'https://cdn.jsdelivr.net/npm/despia-native/+esm'
</script>

Apple Developer and Despia setup

HealthKit requires the HealthKit capability on your core app bundle ID before any read or write call works. Configure Apple Developer first, then enable Health Data in the Despia Editor and rebuild.

Go to developer.apple.com and sign in with the Apple Developer account that owns your app’s primary bundle ID. Navigate to Certificates, Identifiers & Profiles > Identifiers.

Add HealthKit to your core app bundle ID

Find your core app (e.g. com.despia.myapp), click into it, and check HealthKit under Capabilities. Click Save. Without this, HealthKit reads will return empty arrays and writes will fail silently, since iOS rejects HealthKit access for any app whose bundle ID does not declare the capability.

Enable Health Data in the Despia Editor

Open the Despia Editor and go to App > Addons > Health Data. Toggle the addon on. This signals Despia to compile the HealthKit framework and the matching usage descriptions into your next build.

Rebuild your app

Trigger a fresh build from the Despia Editor. HealthKit linking happens at the binary level, so this cannot be applied over-the-air. After the rebuild, calls to readhealthkit://, writehealthkit://, healthkit://workouts, and healthkit://observe will function in production.

Skipping the HealthKit capability on the core bundle ID, or skipping the rebuild after enabling the Despia addon, leaves the integration inactive even when both toggles read enabled. readhealthkit:// returns empty arrays, healthkit://workouts resolves to [], writehealthkit:// resolves silently without saving, and healthkit://observe never fires a webhook. If health data stops working after editing settings, verify the capability is on in Apple Developer and rebuild before opening a support ticket.

Choosing the right approach

HealthKit data can be accessed in three ways. Which one to use depends on whether you need data right now, want to save data, or need to react to changes continuously.

Approach	Use when	How it works
Read	You need historical data at a specific moment, on page load, on a button tap, or when building a report	Call `readhealthkit://` or `healthkit://workouts` and await the result. Returns records for the last N days
Write	You want to save a value back to HealthKit, for example logging a weight entry or a step count from your own sensor	Call `writehealthkit://` with a value. Adds a new sample without replacing existing data
Observer	You need your server to stay in sync with the user’s health data automatically, without requiring the user to open the app	Register a webhook with `healthkit://observe`. Despia posts new data to your server whenever HealthKit updates, even in the background

A fitness app that shows a weekly steps chart uses read, fetching data when the user opens the dashboard. A coaching platform that tracks whether a user hit their daily goal uses observer, the server receives updates automatically and can send a push notification without any user action. An app that lets users log body weight from a form uses write to save the entry back to Apple Health. You can combine all three. Most apps that use observer also use read to populate the initial UI before the first webhook fires.

How it works

Define the isDespiaIOS check once at the top of your app and reuse it throughout. Pass one or more identifiers as a comma-separated list on the URL host, Despia routes the request through the native bridge in a single dispatch and returns one response keyed by identifier.

const isDespiaIOS = navigator.userAgent.toLowerCase().includes('despia') && (
    navigator.userAgent.toLowerCase().includes('iphone') ||
    navigator.userAgent.toLowerCase().includes('ipad')
)

if (isDespiaIOS) {
    const data  = await despia(
        'readhealthkit://HKQuantityTypeIdentifierStepCount,HKQuantityTypeIdentifierHeartRate?days=7',
        ['healthkitResponse']
    )

    const steps = data.healthkitResponse.HKQuantityTypeIdentifierStepCount
    const hr    = data.healthkitResponse.HKQuantityTypeIdentifierHeartRate
}

Despia requests HealthKit permission on the first call for each identifier, then fetches and returns the data. A single multi-identifier call prompts the user once for the whole set rather than once per type.

Read

Use readhealthkit:// to fetch historical data on demand. This is the right approach when your UI needs to display health data at a point in time, on load, after a user action, or when generating a report. You control exactly when the fetch happens and how many days of history to retrieve. Pass any valid HKQuantityTypeIdentifier, HKCategoryTypeIdentifier, HKWorkoutTypeIdentifier, or HKCharacteristicTypeIdentifier as the URL host, plus an optional days parameter. See Identifier reference for the full list.

Reading multiple identifiers

Most real apps need more than one metric at a time, a dashboard typically wants steps, heart rate, calories, and sleep all at once. Comma-separate the identifiers on the URL host and Despia returns them in a single response, keyed by identifier name.

if (isDespiaIOS) {
    const data = await despia(
        'readhealthkit://HKQuantityTypeIdentifierStepCount,HKQuantityTypeIdentifierActiveEnergyBurned,HKCategoryTypeIdentifierSleepAnalysis?days=7',
        ['healthkitResponse']
    )

    const steps  = data.healthkitResponse.HKQuantityTypeIdentifierStepCount
    const energy = data.healthkitResponse.HKQuantityTypeIdentifierActiveEnergyBurned
    const sleep  = data.healthkitResponse.HKCategoryTypeIdentifierSleepAnalysis
}

Each key on healthkitResponse holds the same array shape that a single-identifier read would return for that type. Quantity types return daily values, sleep returns stage intervals, workouts return session records. The single days parameter applies to every identifier in the call. You can mix categories freely in one call as long as they all accept a days window:

if (isDespiaIOS) {
    const data = await despia(
        'readhealthkit://HKQuantityTypeIdentifierStepCount,HKQuantityTypeIdentifierHeartRate,HKWorkoutTypeIdentifier?days=14',
        ['healthkitResponse']
    )
}

Characteristics (HKCharacteristicTypeIdentifierDateOfBirth, biological sex, blood type, skin type) are static values and do not accept days, so fetch them with their own dedicated call.

Always batch related reads into one comma-separated call. Firing several despia() reads in parallel with Promise.all queues multiple independent requests against the native bridge, which can race during permission prompts and on slower devices, causing one or more reads to return stale or empty arrays without throwing. A single multi-identifier call goes through one native dispatch, hits HealthKit’s authorization layer once, and resolves all identifiers atomically.

Quantity types

Quantity types cover numeric metrics: steps, heart rate, distance, body mass, calories, and more. Each record represents one day’s value for the requested identifier. For individual samples with timestamps instead of a daily value, see Raw samples.

if (isDespiaIOS) {
    const data      = await despia('readhealthkit://HKQuantityTypeIdentifierHeartRate?days=30', ['healthkitResponse'])
    const heartRate = data.healthkitResponse.HKQuantityTypeIdentifierHeartRate
}

[
  { "date": "2025-11-16", "value": 68, "unit": "count/min" },
  { "date": "2025-11-17", "value": 72, "unit": "count/min" },
  { "date": "2025-11-18", "value": 70, "unit": "count/min" }
]

string

Start of day in ISO 8601 format

number

The health metric value for that day

string

Unit of measurement, e.g. count, count/min, kg, m. Determined automatically by the identifier.

Raw samples

By default a quantity read returns one averaged value per day. Add raw=true to get every individual sample with its own timestamp instead. The daily average is computed on-device, so without raw the underlying samples never reach your app. This is the mode to use for intra-day or overnight analysis, for example tracking how HRV moves across a night of sleep.

if (isDespiaIOS) {
    const data    = await despia('readhealthkit://HKQuantityTypeIdentifierHeartRateVariabilitySDNN?days=1&raw=true', ['healthkitResponse'])
    const samples = data.healthkitResponse.HKQuantityTypeIdentifierHeartRateVariabilitySDNN
}

[
  { "startDate": "2026-06-03T01:14:23Z", "endDate": "2026-06-03T01:14:23Z", "value": 52.3, "unit": "ms" },
  { "startDate": "2026-06-03T01:19:41Z", "endDate": "2026-06-03T01:19:41Z", "value": 48.7, "unit": "ms" },
  { "startDate": "2026-06-03T01:24:58Z", "endDate": "2026-06-03T01:24:58Z", "value": 61.2, "unit": "ms" }
]

string

ISO 8601 start time of the sample

string

ISO 8601 end time of the sample

number

The measured value for that sample

string

Unit of measurement, determined automatically by the identifier

raw=true works with comma-separated identifiers and multi-day windows, and applies to quantity types only. Samples come back sorted oldest to newest. It has no effect on HKCategoryTypeIdentifierSleepAnalysis or workout reads, which already return per-sample data. Calls without raw=true return the same daily aggregate as before, so adding it is non-breaking, and on an app build that predates this feature raw=true is ignored and you get the aggregate.

Sleep data

Sleep analysis uses HKCategoryTypeIdentifierSleepAnalysis. Unlike quantity types, sleep returns individual stage intervals rather than daily aggregates, each record covers a contiguous block of one sleep stage with its own start and end time.

if (isDespiaIOS) {
    const data  = await despia('readhealthkit://HKCategoryTypeIdentifierSleepAnalysis?days=7', ['healthkitResponse'])
    const sleep = data.healthkitResponse.HKCategoryTypeIdentifierSleepAnalysis
}

[
  { "startDate": "2025-11-17T22:15:00Z", "endDate": "2025-11-17T22:45:00Z", "value": 0, "label": "inBed" },
  { "startDate": "2025-11-17T22:45:00Z", "endDate": "2025-11-18T00:30:00Z", "value": 3, "label": "core" },
  { "startDate": "2025-11-18T00:30:00Z", "endDate": "2025-11-18T02:15:00Z", "value": 4, "label": "deep" },
  { "startDate": "2025-11-18T02:15:00Z", "endDate": "2025-11-18T03:45:00Z", "value": 5, "label": "rem"  },
  { "startDate": "2025-11-18T03:45:00Z", "endDate": "2025-11-18T06:00:00Z", "value": 3, "label": "core" },
  { "startDate": "2025-11-18T06:00:00Z", "endDate": "2025-11-18T06:20:00Z", "value": 2, "label": "awake" }
]

string

ISO 8601 start time of the sleep stage interval

string

ISO 8601 end time of the sleep stage interval

number

Raw integer from HKCategoryValueSleepAnalysis

string

Human-readable stage: inBed, awake, asleep, core, deep, or rem

Workouts

Use the dedicated healthkit://workouts scheme to fetch workout sessions, optionally enriched with per-workout statistics like average heart rate or summed active energy. The response lands on window.healthkitWorkouts as a flat array, distinct from the multi-type healthkitResponse object used by readhealthkit://.

if (isDespiaIOS) {
    const data     = await despia('healthkit://workouts?days=14', ['healthkitWorkouts'])
    const workouts = data.healthkitWorkouts
}

[
  {
    "date": "2026-05-07T07:32:11Z",
    "activityType": "Running",
    "duration": 1820.4,
    "calories": 312.7,
    "distance": 4521.3,
    "value": 4521.3,
    "unit": "m"
  },
  {
    "date": "2026-05-05T18:02:00Z",
    "activityType": "FunctionalStrengthTraining",
    "duration": 2700,
    "calories": 220.5,
    "distance": 0,
    "value": 220.5,
    "unit": "kcal"
  }
]

number

Number of days back to look. Defaults to 1.

string

Comma-separated list of per-workout quantity statistics. Each entry is a real HKQuantityTypeIdentifier followed by an aggregation suffix. Omit to skip per-workout stats. See Per-workout statistics.

string

ISO 8601 start time of the workout

string

Apple’s activity enum name in PascalCase, for example Running, Cycling, FunctionalStrengthTraining. See HKWorkoutActivityType for the complete list.

number

Duration in seconds

number

Kilocalories burned. 0 if the source did not record this.

number

Distance in meters. 0 if not applicable, for example strength training.

number

Primary metric, picked dynamically: distance if greater than 0, otherwise calories, otherwise duration in seconds

string

Unit of value: m, kcal, or s

array

Per-workout quantity statistics, present only when included= is non-empty. Each entry has key, value, and unit.

Per-workout statistics

Pass included= to compute aggregated quantity values scoped to each workout’s time range. Each entry is an HKQuantityTypeIdentifier plus an aggregation suffix. The native side strips the suffix to request authorization for the underlying type, then runs the aggregation across that workout’s startDate to endDate window. The result is the avg, max, min, or sum of that signal during the workout, not over the whole day.

Suffix	Aggregation	Example
`Average`	Discrete average	`HKQuantityTypeIdentifierHeartRateAverage`
`Max`	Discrete maximum	`HKQuantityTypeIdentifierHeartRateMax`
`Min`	Discrete minimum	`HKQuantityTypeIdentifierHeartRateMin`
`Sum`	Cumulative sum	`HKQuantityTypeIdentifierActiveEnergyBurnedSum`
(none)	Discrete average	`HKQuantityTypeIdentifierHeartRate`

Stack multiple stats for the same identifier by repeating it with different suffixes. The example below pulls average, max, and min heart rate for every workout in the last 14 days.

if (isDespiaIOS) {
    const data     = await despia(
        'healthkit://workouts?days=14&included=HKQuantityTypeIdentifierHeartRateAverage,HKQuantityTypeIdentifierHeartRateMax,HKQuantityTypeIdentifierHeartRateMin',
        ['healthkitWorkouts']
    )
    const workouts = data.healthkitWorkouts
}

[
  {
    "date": "2026-05-07T07:32:11Z",
    "activityType": "Running",
    "duration": 1820.4,
    "calories": 312.7,
    "distance": 4521.3,
    "value": 4521.3,
    "unit": "m",
    "samples": [
      { "key": "HKQuantityTypeIdentifierHeartRateAverage", "value": "148.2", "unit": "count/min" },
      { "key": "HKQuantityTypeIdentifierHeartRateMax",     "value": "176.0", "unit": "count/min" },
      { "key": "HKQuantityTypeIdentifierHeartRateMin",     "value": "62.0",  "unit": "count/min" }
    ]
  }
]

Mix multiple identifiers and aggregations in a single call. Heart rate stats and summed active energy together:

if (isDespiaIOS) {
    const data     = await despia(
        'healthkit://workouts?days=7&included=HKQuantityTypeIdentifierHeartRateAverage,HKQuantityTypeIdentifierHeartRateMax,HKQuantityTypeIdentifierActiveEnergyBurnedSum',
        ['healthkitWorkouts']
    )
    const workouts = data.healthkitWorkouts
}

{
  "date": "2026-05-04T06:10:00Z",
  "activityType": "Cycling",
  "duration": 3600,
  "calories": 540.2,
  "distance": 18234.0,
  "value": 18234.0,
  "unit": "m",
  "samples": [
    { "key": "HKQuantityTypeIdentifierHeartRateAverage",      "value": "138.4", "unit": "count/min" },
    { "key": "HKQuantityTypeIdentifierHeartRateMax",          "value": "171.0", "unit": "count/min" },
    { "key": "HKQuantityTypeIdentifierActiveEnergyBurnedSum", "value": "540.2", "unit": "kcal" }
  ]
}

Common combinations that work well:

Goal	`included=` value
Heart rate range per workout	`HKQuantityTypeIdentifierHeartRateAverage,HKQuantityTypeIdentifierHeartRateMax,HKQuantityTypeIdentifierHeartRateMin`
Total energy per workout	`HKQuantityTypeIdentifierActiveEnergyBurnedSum`
Pace and top speed for runs	`HKQuantityTypeIdentifierRunningSpeedAverage,HKQuantityTypeIdentifierRunningSpeedMax`
Average and peak power for rides	`HKQuantityTypeIdentifierCyclingPowerAverage,HKQuantityTypeIdentifierCyclingPowerMax`

string

Exact identifier you passed in included=, including the aggregation suffix

string

Stringified numeric result. Wrap with Number() before doing math. A value of "0" means the source did not record that signal during the workout, treat as missing rather than literal zero.

string

HealthKit unit string, for example count/min, kcal, m

Authorization for every base quantity type referenced in included= is requested automatically on the first call, the suffix is stripped before the auth request. Invalid identifiers in included= are silently skipped, valid ones in the same call still come through. If the user denies access or the build does not have HealthKit linked, window.healthkitWorkouts resolves to [], so always check Array.isArray() before reading.

The legacy readhealthkit://HKWorkoutTypeIdentifier endpoint continues to work and is the right choice when you need workouts in the same call as other unrelated identifiers, for example pulling steps, heart rate, and workouts together. Its response shape is slightly different: it lands on healthkitResponse.HKWorkoutTypeIdentifier rather than healthkitWorkouts, returns lowercase activityType values, and does not support included=. Use healthkit://workouts for any workouts-only read or any read that needs per-workout statistics.

Characteristics

Characteristics such as date of birth, biological sex, and blood type are static values that do not change over time. They return a plain string or raw integer and do not accept a days parameter, so they cannot be batched into the same call as quantity, category, or workout reads.

if (isDespiaIOS) {
    const data = await despia('readhealthkit://HKCharacteristicTypeIdentifierDateOfBirth', ['healthkitResponse'])
    const dob  = data.healthkitResponse.HKCharacteristicTypeIdentifierDateOfBirth
}

"1990-06-15T00:00:00Z"

Identifier	Returns
`HKCharacteristicTypeIdentifierDateOfBirth`	ISO 8601 date string
`HKCharacteristicTypeIdentifierBiologicalSex`	Raw integer from `HKBiologicalSex`
`HKCharacteristicTypeIdentifierBloodType`	Raw integer from `HKBloodType`
`HKCharacteristicTypeIdentifierFitzpatrickSkinType`	Raw integer from `HKFitzpatrickSkinType`

Write

Use writehealthkit:// to save a value back to HealthKit. This is useful when your app collects health data that should also live in Apple Health, for example a weight logging form, a manual step entry, or a calorie tracker. Writing adds a new sample to HealthKit without removing or replacing any existing records. The URL format is writehealthkit://IdentifierString//Value. The unit is resolved automatically from the identifier.

if (isDespiaIOS) {
    despia('writehealthkit://HKQuantityTypeIdentifierBodyMass//74.5')
    despia('writehealthkit://HKQuantityTypeIdentifierStepCount//10000')
}

string

required

Any writable HKQuantityTypeIdentifier, passed as the URL host (e.g. HKQuantityTypeIdentifierBodyMass)

number

required

Numeric value to write. The unit is determined automatically from the identifier, see the Identifier reference.

Write is one-directional. It adds samples to HealthKit but does not delete or modify existing ones. If you need to correct a previously written value, write a new sample, HealthKit stores the history and surfaces the most recent reading.

Observer

Use observers when you need your server to stay current with a user’s health data automatically, without requiring the user to open your app. Observers register a background listener on the device that watches one or more HealthKit types. When new data arrives, from Apple Watch, a connected sensor, or another app, Despia posts a webhook to your server with the latest records. This is fundamentally different from read. Read is a point-in-time fetch that your code initiates. An observer is a persistent subscription that fires on Despia’s side whenever HealthKit tells it something changed. The user does not need to be in the app for a webhook to fire. Common uses for observers include: tracking whether a user hit a daily step goal, alerting a coach when a client logs a workout, syncing sleep data nightly to a backend, and triggering push notifications based on health events.

Registering an observer

if (isDespiaIOS) {
    despia('healthkit://observe?types=HKQuantityTypeIdentifierStepCount,HKCategoryTypeIdentifierSleepAnalysis&frequency=hourly&server=https://your-server.com/webhook')
}

Observers persist across app restarts automatically. You only need to register them once, typically on app load or after the user enables health tracking in your app.

string

required

Comma-separated list of HealthKit identifiers to observe

string

How often Despia delivers batched updates to your server: immediate, hourly, daily, or weekly. Defaults to immediate. Use hourly or daily for high-volume types like steps to avoid unnecessary webhook traffic.

string

required

Full URL of the endpoint that receives webhook POSTs. Append your own query parameters here to identify the user on your server.

Identifying users in webhooks

Webhooks include a userId field containing the Despia device ID. If you need to map webhook events to your own user records, append your user identifier as a query parameter on the server URL when registering the observer. Your server receives it as part of the request URL.

const myUserId = 'user_abc123'

if (isDespiaIOS) {
    despia(`healthkit://observe?types=HKQuantityTypeIdentifierStepCount&frequency=hourly&server=https://your-server.com/webhook?user=${myUserId}`)
}

Your server receives POST /webhook?user=user_abc123 and can route the event directly to the right user record without any device ID mapping.

Webhook payload

Despia sends a POST with Content-Type: application/json each time an observed type updates. The data object contains one key per observed type, each holding an array of the most recent records (last 1 day).

{
  "event": "update",
  "userId": "abc123-device-id",
  "timestamp": "2025-11-18T08:00:00Z",
  "data": {
    "HKQuantityTypeIdentifierStepCount": [
      { "date": "2025-11-18", "value": 4210, "unit": "count" }
    ]
  }
}

string

Always update

string

Despia device ID, consistent across all events from the same device. For your own user IDs, use a query parameter on the server URL instead.

string

ISO 8601 timestamp of when the webhook was sent

object

One key per observed type, each containing an array of records matching the read response shape for that type

Checking active observers

despia.observingHealthKit holds an array of currently active identifier strings. It is undefined before any observe or unobserve call has been made, and [] once all observers have been stopped. Use this to check whether an observer is already registered before calling observe again.

if (despia.observingHealthKit?.length > 0) {
    console.log('Active observers:', despia.observingHealthKit)
    // ["HKQuantityTypeIdentifierStepCount", "HKCategoryTypeIdentifierSleepAnalysis"]
}

Stopping observers

Pass all to stop every active observer, or a comma-separated list of identifiers to stop specific types. The response contains the updated list of remaining active observers.

if (isDespiaIOS) {
    // Stop all observers
    const data = await despia('healthkit://unobserve?types=all', ['observingHealthKit'])
    console.log(data.observingHealthKit) // []

    // Stop a specific type
    const data = await despia('healthkit://unobserve?types=HKQuantityTypeIdentifierStepCount', ['observingHealthKit'])
    console.log(data.observingHealthKit) // ["HKCategoryTypeIdentifierSleepAnalysis"]
}

Identifier reference

Despia supports all four HealthKit identifier categories. Pass any valid identifier string directly to readhealthkit:// or writehealthkit://, or as part of included= on healthkit://workouts. Despia resolves the type and unit automatically.

Constructing identifiers

Every identifier follows a predictable pattern based on its category:

Type	Prefix	Example
Quantity	`HKQuantityTypeIdentifier`	`HKQuantityTypeIdentifierStepCount`
Category	`HKCategoryTypeIdentifier`	`HKCategoryTypeIdentifierSleepAnalysis`
Workout	`HKWorkoutTypeIdentifier`	`HKWorkoutTypeIdentifier`
Characteristic	`HKCharacteristicTypeIdentifier`	`HKCharacteristicTypeIdentifierDateOfBirth`

Take the type name from Apple’s documentation and prepend the matching prefix. For example, Apple lists StepCount under HKQuantityTypeIdentifier, the full identifier string is HKQuantityTypeIdentifierStepCount. When using a quantity identifier inside included= on healthkit://workouts, append one of the aggregation suffixes (Average, Max, Min, Sum) to control how the value is computed across the workout window. Identifiers used as the URL host on readhealthkit:// never take a suffix.

Apple Documentation

HKQuantityTypeIdentifier

Steps, heart rate, distance, body mass, nutrition, and all other numeric types

HKCategoryTypeIdentifier

Sleep analysis, mindfulness, and other category-based types

HKWorkoutActivityType

All workout activity types returned in the activityType field

HKCharacteristicTypeIdentifier

Date of birth, biological sex, blood type, and skin type

Resources

NPM Package

despia-native

Support

support@despia.com

​Installation

​Apple Developer and Despia setup

​Choosing the right approach

​How it works

​Read

​Reading multiple identifiers

​Quantity types

​Raw samples

​Sleep data

​Workouts

​Per-workout statistics

​Characteristics

​Write

​Observer

​Registering an observer

​Identifying users in webhooks

​Webhook payload

​Checking active observers

​Stopping observers

​Identifier reference

​Constructing identifiers

​Apple Documentation

HKQuantityTypeIdentifier

HKCategoryTypeIdentifier

HKWorkoutActivityType

HKCharacteristicTypeIdentifier

​Resources

NPM Package

Support

Installation

Apple Developer and Despia setup

Choosing the right approach

How it works

Read

Reading multiple identifiers

Quantity types

Raw samples

Sleep data

Workouts

Per-workout statistics

Characteristics

Write

Observer

Registering an observer

Identifying users in webhooks

Webhook payload

Checking active observers

Stopping observers

Identifier reference

Constructing identifiers

Apple Documentation

Resources