Health Bridge

Overview

The Health Bridge plugin allows your Median app to access and sync health data from users' devices using Apple HealthKit (iOS) and Google Health Connect (Android). This plugin provides a unified interface to fetch health metrics such as steps, heart rate, calories, and sleep data - enabling you to build powerful wellness and fitness features in your app.

Health Bridge takes care of handling platform-specific details like permissions, data sources, and user consent, so you can focus on delivering value to your users.

Supported Platforms

• iOS - Apple HealthKit
• Android - Google Health Connect

Typical Use Cases

• Displaying a user's daily or weekly step count
• Creating activity rings or health streaks
• Personalized fitness insights
• Sleep or recovery tracking

👍

Developer Demo

Display our demo page in your app to test during development https://median.dev/health-bridge/

Implementation Guide

Follow these steps to start using the Health Bridge plugin in your app:

Step 1 - Request Permissions

Although not required, we recommend calling requestPermissions() upfront as it improves user transparency and experience. This prompts users to grant access to the specific health data types your app will use.

await median.healthBridge.requestPermissions([
  'steps',
  'sleep',
  'calorieIntake',
]); 

This method accepts an array of data types and returns an object indicating which permissions were granted or declined.

🚧

Platform Caveats

• Android: Returns a list of granted and declined data types.
• iOS: Does not return any information about permission status. The OS will prompt the user when data is first requested, and you won't get confirmation about which permissions were granted.

Supported Data Types:

The following health data types are currently supported by Health Bridge. All values are returned in metric units only. Our team can add support for additional data types if required.

ℹ️

You can optionally skip requestPermissions() and directly call getData() (next step) and the OS will handle permissions automatically.

Step 2 - Fetch Health Data

After permissions are granted (or requested implicitly), use the getData() method to retrieve health data. You can define the following parameters:

• The specific dataTypes to fetch (from the supported list)
• A startDate and endDate in ISO 8601 format
• An optional bucket to group data (e.g., by day or hour)

const result = await median.healthBridge.getData({
  dataTypes: granted, // list of granted permissions from previous step
  startDate: '2025-05-01T00:00:00Z',
  endDate:   '2025-05-08T00:00:00Z',
  bucket:    'day'
});

console.log(result.data.steps);
// [
//   { timestamp: '2025-05-01T00:00:00Z', value: 8123 },
//   { timestamp: '2025-05-02T00:00:00Z', value: 7890 },
//   ...
// ]

Available Data Buckets

Want to show a daily step chart for the past week? Just fetch steps with bucket: 'day' and map the values to your chart component.

✅

Tip

Make sure your date range doesn't exceed platform limitations - some data types (like sleep) may only be available for recent timeframes.

Example JSON response

The following JSON response outlines an example for a grouped data sample where the 'Weight' data was accessible or available.

{
    "data": {
        "height": [
            {
                "start": "2025-12-03T15:30:00.000Z",
                "end": "2025-12-03T15:30:00.000Z",
                "value": 1.87
            }
        ],
        "weight": [],
        "steps": [
            {
                "start": "2025-12-03T15:30:00.000Z",
                "end": "2025-12-03T15:30:00.000Z",
                "value": 5000
            },
            {
                "end": "2025-12-02T15:30:00.000Z",
                "start": "2025-12-02T15:30:00.000Z",
                "value": 4500
            }
        ]
    }
}

Health Bridge Integration Tests

Due to callouts to Apple and Google services, the Health Bridge integration can not be tested in the virtual simulator in the App Studio. Instead, any integration tests have to be performed on a physical device, Xcode or Android Studio simulators.

Testing on iOS

Step 1 - Install your App

Based on your test setup, you can either install the app on a physical device via TestFlight or iOS Binary or build the app locally in Xcode. If you install the app using TestFlight or iOS Binary the app will come fully built including the necessary capabilities.

Local Xcode build

If you want to build and test the app locally on a MacOS system please follow the steps to build your iOS app from source: https://docs.median.co/docs/build-ios-from-source#/ and add the Health Kit capability. You can reference the image below to confirm that the capability has been added as expected.

Step 2 - Add Test Data

Follow the steps below to add test data to your iOS simulator using the Health app.

Step 1	Step 2	Step 3
Suspend the app and find the 'Health' app on your home screen.	Select a metric and manually add test data using the '+' button	Confirm that your test data has been added in the Health app

Step 3 - Access your Data

After adding test data to your account, follow the steps below to access the data through the Health Bridge. Please note that we didn't add any 'Weight' data to the sample to demonstrate the behavior for data that is not available or has not been set.

Step 1	Step 2	Step 3
Select the data points, bucket and date range for the request	Confirm the access	Access the returned data in the JSON object