HealthKit (Legacy)

The Despia native bridge gives your web app direct access to Apple HealthKit, covering quantity types, category types (including sleep), workouts, and characteristics. Data is returned as JSON via the despia() call.

HealthKit is iOS only. Always gate calls behind an isDespiaIOS check so the feature 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>

How it works

Pass a readhealthkit:// URL with an identifier and optional days parameter. Despia requests permission, fetches the data, and returns it via healthkitResponse.

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?days=7', ['healthkitResponse'])
    const steps = data.healthkitResponse
    // [{ "date": "2025-11-17", "value": 9820, "unit": "count" }, ...]
}

Read

Quantity types

Use any valid HKQuantityTypeIdentifier to read numeric health metrics such as steps, heart rate, distance, or body mass.

if (isDespiaIOS) {
    const data      = await despia('readhealthkit://HKQuantityTypeIdentifierHeartRate?days=30', ['healthkitResponse'])
    const heartRate = data.healthkitResponse
    // [{ "date": "2025-11-17", "value": 72, "unit": "count/min" }, ...]
}

For a full list of supported identifiers, see Apple’s HKQuantityTypeIdentifier documentation.

Sleep data

Sleep analysis uses HKCategoryTypeIdentifierSleepAnalysis. Each record includes a label with the sleep stage (inBed, awake, core, deep, rem, or asleep) alongside startDate and endDate.

if (isDespiaIOS) {
    const data  = await despia('readhealthkit://HKCategoryTypeIdentifierSleepAnalysis?days=7', ['healthkitResponse'])
    const sleep = data.healthkitResponse
    // [
    //   { "startDate": "2025-11-17T22:30:00Z", "endDate": "2025-11-18T06:00:00Z", "value": 3, "label": "deep" },
    //   { "startDate": "2025-11-18T06:00:00Z", "endDate": "2025-11-18T06:45:00Z", "value": 4, "label": "rem" }
    // ]
}

Workouts

Use HKWorkoutTypeIdentifier to fetch workout sessions. Each record includes activityType (e.g. running, yoga, hiit), duration in seconds, calories, and distance in meters.

if (isDespiaIOS) {
    const data     = await despia('readhealthkit://HKWorkoutTypeIdentifier?days=14', ['healthkitResponse'])
    const workouts = data.healthkitResponse
    // [
    //   { "date": "2025-11-16T08:00:00Z", "activityType": "running", "duration": 1820, "calories": 310, "distance": 5200 },
    //   { "date": "2025-11-17T07:30:00Z", "activityType": "hiit",    "duration": 2400, "calories": 420, "distance": 0    }
    // ]
}

Characteristics

Characteristics such as date of birth, biological sex, and blood type are static values. They are returned as a plain string rather than an array.

if (isDespiaIOS) {
    const data = await despia('readhealthkit://HKCharacteristicTypeIdentifierDateOfBirth', ['healthkitResponse'])
    const dob  = data.healthkitResponse
    // "1990-06-15T00:00:00Z"
}

Supported identifiers: HKCharacteristicTypeIdentifierDateOfBirth, HKCharacteristicTypeIdentifierBiologicalSex, HKCharacteristicTypeIdentifierBloodType, HKCharacteristicTypeIdentifierFitzpatrickSkinType.

Write

Use writehealthkit:// to save a numeric value to HealthKit. The format is writehealthkit://IdentifierString//Value. Writing adds to existing data rather than replacing it.

if (isDespiaIOS) {
    // Write body mass in kg
    despia('writehealthkit://HKQuantityTypeIdentifierBodyMass//74.5')

    // Write step count
    despia('writehealthkit://HKQuantityTypeIdentifierStepCount//10000')
}

Realtime updates

The observer system fires a webhook POST to your server whenever HealthKit data changes. Pass a comma-separated list of identifiers, a delivery frequency, and your server URL.

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

Parameters

Parameter	Required	Description
`types`	Yes	Comma-separated list of HealthKit identifiers to observe
`frequency`	No	One of `immediate`, `hourly`, `daily`, `weekly`. Defaults to `immediate`
`server`	Yes	Full URL of the endpoint to receive webhook POSTs

Webhook payload

Your server receives a POST with Content-Type: application/json on every update. The data object contains one key per observed type, each holding an array of the most recent records (last 1 day).

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

Payload fields

Field	Type	Description
`event`	string	Always `healthkit:update`
`userId`	string	Device ID, consistent across all events from the same device
`timestamp`	string	ISO 8601 timestamp of when the webhook was sent
`data`	object	One key per observed type, each containing an array of records

Each record in data follows the same shape as a standard read response for that type. Quantity types include date, value, and unit. Category types include startDate, endDate, value, and label. Workout records include date, activityType, duration, calories, and distance.

Stopping observers

Pass all to stop every active observer or a comma-separated list for specific types. Awaiting with ["observingHealthKit"] returns the updated active types after the call resolves.

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"]
}

Resources

NPM Package

despia-native

Support

support@despia.com

Deployment

Best Practices

Local Ecosystem

Authentication

Payments

Analytics

Connectivity

Machine Learning

Wallets

Native Features

Editor

Roadblocks

Store Rejections

Platform Support

Installation

How it works

Read

Quantity types

Sleep data

Workouts

Characteristics

Write

Realtime updates

Parameters

Webhook payload

Payload fields

Stopping observers

Resources

NPM Package

Support

​Installation

​How it works

​Read

​Quantity types

​Sleep data

​Workouts

​Characteristics

​Write

​Realtime updates

​Parameters

​Webhook payload

​Payload fields

​Stopping observers

​Resources

NPM Package

Support

Installation

How it works

Read

Quantity types

Sleep data

Workouts

Characteristics

Write

Realtime updates

Parameters

Webhook payload

Payload fields

Stopping observers

Resources