@capgo/capacitor-health

Read and write health data with Apple HealthKit on iOS and Health Connect on Android through one API. Build fitness, wellness and medical apps once.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-health in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-health to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Read samples: readSamples() for steps, heart rate, sleep and other types over a time range.
• Write samples: saveSample() stores a single sample.
• Workouts and aggregates: queryWorkouts() and queryAggregated() for summaries.
• Authorization: requestAuthorization() and checkAuthorization() per data type.
• Health Connect helpers: openHealthConnectSettings() and showPrivacyPolicy() on Android.
• Platforms: iOS and Android. A few data types and units differ between iOS and Android, see the Supported data types table below. Not available on web.

Why Capacitor Health?

The only free, unified health data plugin for Capacitor supporting the latest native APIs:

• Health Connect (Android) - Uses Google's newest health platform (replaces deprecated Google Fit)
• HealthKit (iOS) - Full integration with Apple's health framework
• Unified API - Same TypeScript interface across platforms with consistent units
• Multiple metrics - Steps, distance, calories, heart rate, weight
• Read & Write - Query historical data and save new health entries
• Modern standards - Supports Android 8.0+ and iOS 14+
• Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)

Perfect for fitness apps, health trackers, wellness platforms, and medical applications.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/health/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-health` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-health
npx cap sync

iOS Setup

1. Open your Capacitor application's Xcode workspace and enable the HealthKit capability.
2. Provide usage descriptions in Info.plist (update the copy for your product):

<key>NSHealthShareUsageDescription</key>
<string>This app reads your health data to personalise your experience.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>This app writes new health entries that you explicitly create.</string>

Android Setup

This plugin now uses Health Connect instead of Google Fit. Make sure your app meets the requirements below:

1. Min SDK 26+. Health Connect is only available on Android 8.0 (API 26) and above. The plugin's Gradle setup already targets this level.
2. Declare Health permissions. The plugin manifest ships with the required <uses-permission> declarations for basic data types (READ_/WRITE_STEPS, READ_/WRITE_DISTANCE, READ_/WRITE_ACTIVE_CALORIES_BURNED, READ_/WRITE_HEART_RATE, READ_/WRITE_WEIGHT, READ_/WRITE_SLEEP, READ_/WRITE_RESPIRATORY_RATE, READ_/WRITE_OXYGEN_SATURATION, READ_/WRITE_RESTING_HEART_RATE, READ_/WRITE_HEART_RATE_VARIABILITY). Your app does not need to duplicate them, but you must surface a user-facing rationale because the permissions are considered health sensitive.
3. Ensure Health Connect is installed. Devices on Android 14+ include it by default. For earlier versions the user must install Health Connect by Android from the Play Store. The Health.isAvailable() helper exposes the current status so you can prompt accordingly.
4. Request runtime access. The plugin opens the Health Connect permission UI when you call requestAuthorization. You should still handle denial flows (e.g., show a message if checkAuthorization reports missing scopes).
5. Provide a Privacy Policy. Health Connect requires apps to display a privacy policy explaining how health data is used. See the Privacy Policy Setup section below.

If you already used Google Fit in your project you can remove the associated dependencies (play-services-fitness, play-services-auth, OAuth configuration, etc.).

Privacy Policy Setup

Health Connect requires your app to provide a privacy policy that explains how you handle health data. When users tap "Privacy policy" in the Health Connect permissions dialog, your app must display this information.

Option 1: HTML file in assets (recommended for simple cases)

Place an HTML file at android/app/src/main/assets/public/privacypolicy.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Privacy Policy</title>
  </head>
  <body>
    <h1>Privacy Policy</h1>
    <p>Your privacy policy content here...</p>
    <h2>Health Data</h2>
    <p>Explain how you collect, use, and protect health data...</p>
  </body>
</html>

Option 2: Custom URL (recommended for hosted privacy policies)

Add a string resource to your app's android/app/src/main/res/values/strings.xml:

<resources>
    <!-- Your other strings... -->
    <string name="health_connect_privacy_policy_url">https://yourapp.com/privacy-policy</string>
</resources>

This URL will be loaded in a WebView when the user requests to see your privacy policy.

Programmatic access:

You can also show the privacy policy or open Health Connect settings from your app:

// Show the privacy policy screen
await Health.showPrivacyPolicy();

// Open Health Connect settings (useful for managing permissions)
await Health.openHealthConnectSettings();

Usage

import { Health } from '@capgo/capacitor-health';

// Verify that the native health SDK is present on this device
const availability = await Health.isAvailable();
if (!availability.available) {
  console.warn('Health access unavailable:', availability.reason);
}

// Ask for separate read/write access scopes
await Health.requestAuthorization({
  read: ['steps', 'heartRate', 'weight'],
  write: ['weight'],
});

// Query the last 50 step samples from the past 24 hours
const { samples } = await Health.readSamples({
  dataType: 'steps',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  limit: 50,
});

// Persist a new body-weight entry (kilograms by default)
await Health.saveSample({
  dataType: 'weight',
  value: 74.3,
});

Supported data types

All write operations expect the default unit shown above. On Android the metadata option is currently ignored by Health Connect.

Blood Pressure: Blood pressure requires both systolic and diastolic values:

await Health.saveSample({
  dataType: 'bloodPressure',
  value: 120, // systolic value (used as main value)
  systolic: 120,
  diastolic: 80,
  startDate: new Date().toISOString(),
});

// Reading blood pressure returns samples with systolic/diastolic fields
const { samples } = await Health.readSamples({
  dataType: 'bloodPressure',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

samples.forEach((sample) => {
  console.log(`BP: ${sample.systolic}/${sample.diastolic} mmHg`);
});

Note about workouts: To query workout data using queryWorkouts(), you need to explicitly request workouts permission:

await Health.requestAuthorization({
  read: ['steps', 'workouts'], // Include 'workouts' to access workout sessions
});

Reading data older than 30 days (Android)

On Android, Health Connect caps reads to roughly the last 30 days unless your app holds the android.permission.health.READ_HEALTH_DATA_HISTORY permission. To read older history, set requestHistoryAccess: true on your normal requestAuthorization() call. The permission then appears in the first-time Health Connect permission sheet alongside your data-type permissions, instead of forcing users to grant it manually in Health Connect settings.

const status = await Health.requestAuthorization({
  read: ['steps', 'heartRate'],
  write: [],
  requestHistoryAccess: true,
});

// On Android, whether the history permission was granted:
console.log(status.historyAccessAuthorized); // true | false
// And whether the provider supports it at all:
console.log(status.historyAccessAvailable); // true | false

The result is reported back as the top-level historyAccessAuthorized boolean (present only when requestHistoryAccess was set). The same option works with checkAuthorization().

The READ_HEALTH_DATA_HISTORY permission only exists on sufficiently new Health Connect providers (Android 14 extension 13+ or Health Connect APK 171302+). On an older but otherwise supported provider the permission can never be granted, so the plugin checks feature availability and silently skips the history permission when it is unavailable, your normal read/write scopes are still requested as usual. In that case the status reports historyAccessAvailable: false (and historyAccessAuthorized: false), which lets you distinguish "the device can't do this" from "the user denied it" and avoid re-prompting. historyAccessAvailable is omitted unless requestHistoryAccess was set, and always omitted on iOS.

You must also declare the permission in your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

Health Connect only shows permissions that are both declared in the manifest and passed to the permission request, so this declaration is required for requestHistoryAccess to take effect. On iOS, HealthKit has no equivalent permission and no 30-day read cap, so requestHistoryAccess is ignored and historyAccessAuthorized is omitted from the returned status.

See Google's documentation on reading historical Health Connect data for more details.

Pagination example: Use the anchor parameter to paginate through workout results:

// First page: get the first 10 workouts
let result = await Health.queryWorkouts({
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), // Last 30 days
  endDate: new Date().toISOString(),
  limit: 10,
});

console.log(`Found ${result.workouts.length} workouts`);

// If there are more results, the anchor will be set
while (result.anchor) {
  // Next page: use the anchor to continue from where we left off
  result = await Health.queryWorkouts({
    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
    limit: 10,
    anchor: result.anchor, // Continue from the last result
  });

  console.log(`Found ${result.workouts.length} more workouts`);
}

New Data Types Examples

Sleep data:

// Request permission for sleep data
await Health.requestAuthorization({
  read: ['sleep'],
});

// Read sleep sessions from the past week
const { samples } = await Health.readSamples({
  dataType: 'sleep',
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

samples.forEach(sample => {
  console.log(`Sleep: ${sample.value} minutes, state: ${sample.sleepState}`);
});

Respiratory rate, oxygen saturation, and HRV:

// Request permission
await Health.requestAuthorization({
  read: ['respiratoryRate', 'oxygenSaturation', 'restingHeartRate', 'heartRateVariability'],
});

// Read respiratory rate
const { samples: respiratoryRate } = await Health.readSamples({
  dataType: 'respiratoryRate',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

// Read oxygen saturation (SpO2)
const { samples: oxygenSat } = await Health.readSamples({
  dataType: 'oxygenSaturation',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

Aggregated Queries

For large date ranges, use queryAggregated() to get aggregated data efficiently instead of fetching individual samples:

// Get daily step totals for the past month
const { samples } = await Health.queryAggregated({
  dataType: 'steps',
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',        // Options: 'hour', 'day', 'week', 'month'
  aggregation: 'sum',   // Options: 'sum', 'average', 'min', 'max'
});

samples.forEach(sample => {
  console.log(`${sample.startDate}: ${sample.value} ${sample.unit}`);
});

// Request several aggregations at once by passing an array. Each result is returned
// in `sample.values`, keyed by aggregation name (`sample.value` holds the first one).
const { samples: hr } = await Health.queryAggregated({
  dataType: 'heartRate',
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',
  aggregation: ['average', 'min', 'max'],
});

hr.forEach(sample => {
  console.log(`${sample.startDate}: avg=${sample.values.average}, min=${sample.values.min}, max=${sample.values.max}`);
});

Note: Aggregated queries are not supported for sleep, respiratory rate, oxygen saturation, heart rate variability, and VO2 max data types. These measurements should use readSamples(), not queryAggregated(). Aggregation is supported for: steps, distance, calories, dietary water, dietary energy consumed, heart rate, weight, and resting heart rate.

API

• isAvailable()
• requestAuthorization(...)
• checkAuthorization(...)
• readSamples(...)
• saveSample(...)
• getPluginVersion()
• openHealthConnectSettings()
• showPrivacyPolicy()
• queryWorkouts(...)
• queryAggregated(...)
• Interfaces
• Type Aliases

isAvailable()

isAvailable() => Promise<AvailabilityResult>

Returns whether the current platform supports the native health SDK.

Returns: Promise<AvailabilityResult>

requestAuthorization(...)

requestAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>

Requests read/write access to the provided data types.

Set requestHistoryAccess: true to additionally request Android's READ_HEALTH_DATA_HISTORY permission in the same Health Connect permission sheet (see {@link AuthorizationOptions.requestHistoryAccess}). The granted/denied status is reported back as historyAccessAuthorized on the result.

Returns: Promise<AuthorizationStatus>

checkAuthorization(...)

checkAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>

Checks authorization status for the provided data types without prompting the user.

Returns: Promise<AuthorizationStatus>

readSamples(...)

readSamples(options: QueryOptions) => Promise<ReadSamplesResult>

Reads samples for the given data type within the specified time frame.

Returns: Promise<ReadSamplesResult>

saveSample(...)

saveSample(options: WriteSampleOptions) => Promise<void>

Writes a single sample to the native health store.

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

openHealthConnectSettings()

openHealthConnectSettings() => Promise<void>

Opens the Health Connect settings screen (Android only). On iOS, this method does nothing.

Use this to direct users to manage their Health Connect permissions or to install Health Connect if not available.

showPrivacyPolicy()

showPrivacyPolicy() => Promise<void>

Shows the app's privacy policy for Health Connect (Android only). On iOS, this method does nothing.

This displays the same privacy policy screen that Health Connect shows when the user taps "Privacy policy" in the permissions dialog.

The privacy policy URL can be configured by adding a string resource named "health_connect_privacy_policy_url" in your app's strings.xml, or by placing an HTML file at www/privacypolicy.html in your assets.

queryWorkouts(...)

queryWorkouts(options: QueryWorkoutsOptions) => Promise<QueryWorkoutsResult>

Queries workout sessions from the native health store. Supported on iOS (HealthKit) and Android (Health Connect).

Returns: Promise<QueryWorkoutsResult>

queryAggregated(...)

queryAggregated(options: QueryAggregatedOptions) => Promise<QueryAggregatedResult>

Queries aggregated health data from the native health store. Aggregates data into time buckets (hour, day, week, month) with operations like sum, average, min, or max. This is more efficient than fetching individual samples for large date ranges.

Supported on iOS (HealthKit) and Android (Health Connect).

Returns: Promise<QueryAggregatedResult>

Interfaces

AvailabilityResult

AuthorizationStatus

AuthorizationOptions

ReadSamplesResult

HealthSample

SleepStage

Stage-level sleep segment emitted for sleep samples when platform data is available.

QueryOptions

WriteSampleOptions

QueryWorkoutsResult

Workout

WorkoutEvent

QueryWorkoutsOptions

QueryAggregatedResult

AggregatedSample

QueryAggregatedOptions

Type Aliases

HealthDataType

'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'sleep' | 'respiratoryRate' | 'oxygenSaturation' | 'restingHeartRate' | 'heartRateVariability' | 'vo2Max' | 'bloodPressure' | 'bloodGlucose' | 'bodyTemperature' | 'height' | 'flightsClimbed' | 'exerciseTime' | 'distanceCycling' | 'bodyFat' | 'basalBodyTemperature' | 'appleSleepingWristTemperature' | 'basalCalories' | 'totalCalories' | 'mindfulness' | 'appleStandHour' | 'dietaryWater' | 'dietaryEnergyConsumed' | 'stateOfMind' | 'workouts'

HealthUnit

'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram' | 'minute' | 'percent' | 'millisecond' | 'mL/min/kg' | 'mmHg' | 'mg/dL' | 'celsius' | 'fahrenheit' | 'centimeter' | 'liter' | 'valence'

SleepState

'inBed' | 'asleep' | 'awake' | 'rem' | 'deep' | 'light'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

WorkoutType

'americanFootball' | 'australianFootball' | 'badminton' | 'baseball' | 'basketball' | 'bowling' | 'boxing' | 'climbing' | 'cricket' | 'crossTraining' | 'curling' | 'cycling' | 'dance' | 'elliptical' | 'fencing' | 'functionalStrengthTraining' | 'golf' | 'gymnastics' | 'handball' | 'hiking' | 'hockey' | 'jumpRope' | 'kickboxing' | 'lacrosse' | 'martialArts' | 'pilates' | 'racquetball' | 'rowing' | 'rugby' | 'running' | 'sailing' | 'skatingSports' | 'skiing' | 'snowboarding' | 'soccer' | 'softball' | 'squash' | 'stairClimbing' | 'strengthTraining' | 'surfing' | 'swimming' | 'swimmingPool' | 'swimmingOpenWater' | 'tableTennis' | 'tennis' | 'trackAndField' | 'traditionalStrengthTraining' | 'volleyball' | 'walking' | 'waterFitness' | 'waterPolo' | 'waterSports' | 'weightlifting' | 'wheelchair' | 'yoga' | 'archery' | 'barre' | 'cooldown' | 'coreTraining' | 'crossCountrySkiing' | 'discSports' | 'downhillSkiing' | 'equestrianSports' | 'fishing' | 'fitnessGaming' | 'flexibility' | 'handCycling' | 'highIntensityIntervalTraining' | 'hunting' | 'mindAndBody' | 'mixedCardio' | 'paddleSports' | 'pickleball' | 'play' | 'preparationAndRecovery' | 'snowSports' | 'stairs' | 'stepTraining' | 'surfingSports' | 'taiChi' | 'transition' | 'underwaterDiving' | 'wheelchairRunPace' | 'wheelchairWalkPace' | 'wrestling' | 'cardioDance' | 'socialDance' | 'backExtension' | 'barbellShoulderPress' | 'benchPress' | 'benchSitUp' | 'bikingStationary' | 'bootCamp' | 'burpee' | 'calisthenics' | 'crunch' | 'dancing' | 'deadlift' | 'dumbbellCurlLeftArm' | 'dumbbellCurlRightArm' | 'dumbbellFrontRaise' | 'dumbbellLateralRaise' | 'dumbbellTricepsExtensionLeftArm' | 'dumbbellTricepsExtensionRightArm' | 'dumbbellTricepsExtensionTwoArm' | 'exerciseClass' | 'forwardTwist' | 'frisbeedisc' | 'guidedBreathing' | 'iceHockey' | 'iceSkating' | 'jumpingJack' | 'latPullDown' | 'lunge' | 'meditation' | 'paddling' | 'paraGliding' | 'plank' | 'rockClimbing' | 'rollerHockey' | 'rowingMachine' | 'runningTreadmill' | 'scubaDiving' | 'skating' | 'snowshoeing' | 'stairClimbingMachine' | 'st