--- description: Capacitor Health plugin to read and write health and workout data on Android and iOS via Health Connect and Apple HealthKit. title: Capacitor Health Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/health.png --- [Skip to content ](#capacitor-health-plugin) [📲 Introducing **Build Sharing** — get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Geofences ](/docs/sdks/capacitor/geofences/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * Health [ Health ](/docs/sdks/capacitor/health/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Platform Behavior ](#platform-behavior) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ LLM ](/docs/sdks/capacitor/llm/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ MapLibre ](/docs/sdks/capacitor/maplibre/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Watch ](/docs/sdks/capacitor/watch/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Set Up Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Network Restrictions ](/docs/cloud/organizations/network-restrictions/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Platform Behavior ](#platform-behavior) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) Build and Ship Mobile Apps Faster Cloud builds, OTA live updates, and automated store releases — everything your mobile team needs in one platform. [Start for free ](https://console.cloud.capawesome.io/?utm%5Fsource=docs&utm%5Fmedium=sidebar%5Fcta&utm%5Fcampaign=docs%5Fcta) [See our plans ](https://capawesome.io/pricing/?utm%5Fsource=docs&utm%5Fmedium=sidebar%5Fcta&utm%5Fcampaign=docs%5Fcta) # Capacitor Health Plugin[¶](#capacitor-health-plugin "Permanent link") Capacitor plugin to read, write and aggregate health data via Apple HealthKit and Android Health Connect with a single, strictly typed API. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[¶](#features "Permanent link") The Capacitor Health plugin connects your app to Apple Health (HealthKit) on iOS and Health Connect on Android. Here are some of the key features: * 🏥 **Cross-Platform**: One API for Apple HealthKit and Android Health Connect. * 📖 **\~20 Data Types**: Steps, distance, calories, heart rate, sleep, blood pressure, blood glucose, workouts and more. * 📊 **Aggregation-First**: Query sums, averages, minimums and maximums grouped by hour, day, week or month — with multi-source deduplication handled by the platform. * ✍️ **Writing**: Log the record types apps commonly write, such as weight, hydration, blood pressure and workouts. * 🔒 **Honest Permission Model**: Faithfully models what each platform actually reveals about permissions instead of pretending (see the FAQ). * 🧭 **Availability Handling**: Explicitly models the Health Connect installation states and provides an install helper. * 📋 **Policy Documentation**: Detailed guidance for the Google Play Health apps declaration and Apple's App Review Guideline 5.1.3. * 🛡️ **Typed Errors**: Invalid queries reject with clear error codes instead of resolving with silently empty results. * 🤝 **Compatibility**: Works hand in hand with the [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/), [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/) and [Local Notifications](https://capawesome.io/docs/sdks/capacitor/local-notifications/) plugins. * 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * 🔁 **Up-to-date**: Always supports the latest Capacitor version. * ⭐️ **Support**: Priority support from the Capawesome Team. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[¶](#use-cases "Permanent link") The Health plugin is typically used whenever an app works with health and fitness data, for example: * **Fitness dashboards**: Show daily steps, distance and calories with hourly or daily breakdowns. * **Workout tracking**: Read workouts from other apps or log your own workout sessions. * **Health logging**: Let users log weight, hydration, blood pressure or blood glucose. * **Sleep insights**: Analyze sleep sessions and sleep stages. * **Coaching and habit apps**: Reward users based on their real activity data. ## Compatibility[¶](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Installation[¶](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/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: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-health [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[¶](#android "Permanent link") The plugin uses [Health Connect](https://health.google/health-connect-android/), Google's platform for health data on Android. Health data is available on devices running Android 9 (API level 28) or higher. On Android 9 to 13, the user may need to install the Health Connect app first (see `isAvailable()` and `installHealthConnect()`). On Android 14 and higher, Health Connect is part of the operating system. #### Minimum SDK Version[¶](#minimum-sdk-version "Permanent link") The Health Connect SDK requires a minimum SDK version of `26`. Make sure that the `minSdkVersion` in your `android/variables.gradle` file is set to at least `26`: `[](#%5F%5Fcodelineno-4-1)ext { [](#%5F%5Fcodelineno-4-2) minSdkVersion = 26 [](#%5F%5Fcodelineno-4-3)} ` On devices below Android 9, `isAvailable()` resolves with the reason `not-supported` and all other methods reject as unavailable. #### Permissions[¶](#permissions "Permanent link") Health Connect permissions are declared **in your app**, not by the plugin. This is intentional: Google Play reviews every declared health permission, so your app must only declare the permissions for the data types it actually uses. Add the permissions for the data types you use to your `AndroidManifest.xml` file before or after the `application` tag: `[](#%5F%5Fcodelineno-5-1) [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3) [](#%5F%5Fcodelineno-5-4) ` The following table lists the permission for each data type supported by this plugin: | Data Type | Read Permission | Write Permission (only if you write) | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | ACTIVE\_CALORIES | android.permission.health.READ\_ACTIVE\_CALORIES\_BURNED | \- | | BLOOD\_GLUCOSE | android.permission.health.READ\_BLOOD\_GLUCOSE | android.permission.health.WRITE\_BLOOD\_GLUCOSE | | BLOOD\_PRESSURE | android.permission.health.READ\_BLOOD\_PRESSURE | android.permission.health.WRITE\_BLOOD\_PRESSURE | | BODY\_FAT | android.permission.health.READ\_BODY\_FAT | \- | | BODY\_TEMPERATURE | android.permission.health.READ\_BODY\_TEMPERATURE | \- | | DISTANCE | android.permission.health.READ\_DISTANCE | \- | | FLOORS\_CLIMBED | android.permission.health.READ\_FLOORS\_CLIMBED | \- | | HEART\_RATE | android.permission.health.READ\_HEART\_RATE | \- | | HEART\_RATE\_VARIABILITY | android.permission.health.READ\_HEART\_RATE\_VARIABILITY | \- | | HEIGHT | android.permission.health.READ\_HEIGHT | android.permission.health.WRITE\_HEIGHT | | HYDRATION | android.permission.health.READ\_HYDRATION | android.permission.health.WRITE\_HYDRATION | | OXYGEN\_SATURATION | android.permission.health.READ\_OXYGEN\_SATURATION | \- | | RESPIRATORY\_RATE | android.permission.health.READ\_RESPIRATORY\_RATE | \- | | RESTING\_HEART\_RATE | android.permission.health.READ\_RESTING\_HEART\_RATE | \- | | SLEEP | android.permission.health.READ\_SLEEP | \- | | STEPS | android.permission.health.READ\_STEPS | android.permission.health.WRITE\_STEPS | | TOTAL\_CALORIES | android.permission.health.READ\_TOTAL\_CALORIES\_BURNED | \- | | VO2\_MAX | android.permission.health.READ\_VO2\_MAX | \- | | WEIGHT | android.permission.health.READ\_WEIGHT | android.permission.health.WRITE\_WEIGHT | | WORKOUT | android.permission.health.READ\_EXERCISE (optionally android.permission.health.READ\_ACTIVE\_CALORIES\_BURNED and android.permission.health.READ\_DISTANCE) | android.permission.health.WRITE\_EXERCISE, android.permission.health.WRITE\_DISTANCE, android.permission.health.WRITE\_ACTIVE\_CALORIES\_BURNED | **Note**: Writing a workout requires three permissions because the plugin writes the optional workout totals (`totalDistance`, `totalCalories`) as separate distance and active calories records, which is how Health Connect models workout totals. For the same reason, `readWorkouts(...)` only returns the workout totals if the read permissions for active calories and distance are granted. Without them, the totals are `null`. #### Privacy Policy[¶](#privacy-policy "Permanent link") Health Connect **requires** every app to explain how it uses health data. The plugin already ships the required activity that handles the privacy policy intents of Health Connect. You only need to configure the URL of your privacy policy by adding the following `meta-data` element inside the `application` tag of your `AndroidManifest.xml` file: `[](#%5F%5Fcodelineno-6-1) ` When the user taps the privacy policy link in the Health Connect permission dialog or in the Health Connect settings, this URL is opened in the browser. #### Google Play Health Apps Declaration[¶](#google-play-health-apps-declaration "Permanent link") Google Play requires **every** app that integrates with Health Connect to be approved for access. Without this approval, your app **will be rejected** during Google Play review. Follow these steps before you submit your app: 1. Open the [Google Play Console](https://play.google.com/console/) and select your app. 2. Go to **Monitor and improve** → **Policy and programs** → **App content**. 3. Complete the **Health apps** declaration form: declare that your app integrates with Health Connect, select the requested permission types and describe your use case. 4. Make sure your app provides a **privacy policy** that explains how health data is used (see above). 5. Wait for the approval before rolling out your release. Health Connect data may only be used for the permitted health use cases described in the [Health Connect policy](https://support.google.com/googleplay/android-developer/answer/12991134). Using health data for advertising or undisclosed data-mining purposes is prohibited and will get your app rejected or removed. #### Variables[¶](#variables "Permanent link") If needed, you can define the following project variables in your app’s `variables.gradle` file to change the default versions of the dependencies: * `$healthConnectVersion` version of `androidx.health.connect:connect-client` (default: `1.1.0`) * `$kotlinVersion` version of `org.jetbrains.kotlin:kotlin-gradle-plugin` (default: `2.1.20`) * `$kotlinxCoroutinesVersion` version of `org.jetbrains.kotlinx:kotlinx-coroutines-android` (default: `1.10.2`) This can be useful if you encounter dependency conflicts with other plugins in your project. The Health Connect SDK is a lightweight client library. The actual health data store is provided by the Health Connect app (Android 9 to 13) or the operating system (Android 14+) and is **not** bundled with your app. #### Proguard[¶](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-7-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` ### iOS[¶](#ios "Permanent link") The plugin uses [HealthKit](https://developer.apple.com/documentation/healthkit), Apple's framework for health data on iOS. Health data is not available on iPadOS versions before 17 and in visionOS; use `isAvailable()` to check at runtime. #### Capability[¶](#capability "Permanent link") Add the **HealthKit** capability to your app in Xcode: select your app target, open the **Signing & Capabilities** tab and add the **HealthKit** capability. This adds the `com.apple.developer.healthkit` entitlement to your app. #### Privacy Descriptions[¶](#privacy-descriptions "Permanent link") Add the following keys to the `Info.plist` file of your app to explain why your app needs access to health data: `[](#%5F%5Fcodelineno-8-1)NSHealthShareUsageDescription [](#%5F%5Fcodelineno-8-2)The app needs access to your health data to show your activity and progress. [](#%5F%5Fcodelineno-8-3)NSHealthUpdateUsageDescription [](#%5F%5Fcodelineno-8-4)The app writes the health data you log back to Apple Health. ` `NSHealthShareUsageDescription` is required for reading and `NSHealthUpdateUsageDescription` is required for writing. **Attention**: If a required key is missing, requesting authorization would crash your app. The plugin therefore pre-checks the `Info.plist` file and rejects `requestPermissions(...)` with a clear error message instead. #### App Review Guideline 5.1.3[¶](#app-review-guideline-513 "Permanent link") Apple reviews health apps against [App Review Guideline 5.1.3 (Health and Health Research)](https://developer.apple.com/app-store/review/guidelines/#health-and-health-research). The most important rules: * Your app must provide a **genuine health or fitness feature** that justifies the HealthKit integration. Requesting health permissions without a visible feature is a common rejection reason. * Health data may **not** be used for advertising, marketing or other use-based data mining. Serving ads based on health data will get your app rejected. * Health data may **not** be shared with third parties without explicit user consent, and never for advertising purposes. * Apps that write data to HealthKit must ensure the data is **accurate** and clearly attributed. * Provide a **privacy policy** that explains how health data is collected and used. ## Configuration[¶](#configuration "Permanent link") No configuration required for this plugin. ## Platform Behavior[¶](#platform-behavior "Permanent link") The two platforms model health data differently. The plugin exposes these differences honestly instead of hiding them: | Behavior | Android (Health Connect) | iOS (HealthKit) | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Availability | Three states: available, Health Connect not installed (installable via installHealthConnect()) or unsupported device. | Available on devices with health data support (HKHealthStore.isHealthDataAvailable()). | | Read permissions | Reported as granted or prompt (denied after a rejected request). checkPermissions(...) never reports denied since Health Connect does not reveal it. | Reported as prompt before the first request and unknown afterwards. HealthKit deliberately hides read permission status (see FAQ). Never granted. | | Write permissions | Reported as granted or prompt (denied after a rejected request). | Reported as granted, denied or prompt. | | Historical reads | Limited to 30 days before the permission was first granted. | No time limit. | | SLEEP records | Sleep sessions containing all sleep stages. | Individual sleep analysis samples, each with exactly one stage (HealthKit has no session concept). | | TOTAL\_CALORIES | Dedicated total calories record type. | Only available via aggregate(...), computed as active + basal energy burned. | | HEART\_RATE\_VARIABILITY | RMSSD metric. | SDNN metric. **The values are not comparable across platforms!** | | Workout totals | Aggregated from the records the workout app wrote for the workout time range. | Read from the workout statistics (iOS 16+; null on earlier versions). | | sourceName | Not provided by Health Connect (always null). Use sourceBundleId. | The display name of the source (e.g. "Apple Watch"). | ## Usage[¶](#usage "Permanent link") `[](#%5F%5Fcodelineno-9-1)import { DataType, Health } from '@capawesome-team/capacitor-health'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const checkAvailability = async () => { [](#%5F%5Fcodelineno-9-4) const { available, reason } = await Health.isAvailable(); [](#%5F%5Fcodelineno-9-5) if (!available && reason === 'health-connect-not-installed') { [](#%5F%5Fcodelineno-9-6) // Prompt the user to install Health Connect (Android 9 to 13) [](#%5F%5Fcodelineno-9-7) await Health.installHealthConnect(); [](#%5F%5Fcodelineno-9-8) } [](#%5F%5Fcodelineno-9-9) return available; [](#%5F%5Fcodelineno-9-10)}; [](#%5F%5Fcodelineno-9-11) [](#%5F%5Fcodelineno-9-12)const requestPermissions = async () => { [](#%5F%5Fcodelineno-9-13) const { permissions } = await Health.requestPermissions({ [](#%5F%5Fcodelineno-9-14) read: [DataType.Steps, DataType.HeartRate, DataType.Sleep], [](#%5F%5Fcodelineno-9-15) write: [DataType.Weight], [](#%5F%5Fcodelineno-9-16) }); [](#%5F%5Fcodelineno-9-17) return permissions; [](#%5F%5Fcodelineno-9-18)}; [](#%5F%5Fcodelineno-9-19) [](#%5F%5Fcodelineno-9-20)const readSteps = async () => { [](#%5F%5Fcodelineno-9-21) const { records } = await Health.readRecords({ [](#%5F%5Fcodelineno-9-22) dataType: DataType.Steps, [](#%5F%5Fcodelineno-9-23) startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), [](#%5F%5Fcodelineno-9-24) endDate: new Date().toISOString(), [](#%5F%5Fcodelineno-9-25) }); [](#%5F%5Fcodelineno-9-26) return records; [](#%5F%5Fcodelineno-9-27)}; [](#%5F%5Fcodelineno-9-28) [](#%5F%5Fcodelineno-9-29)const aggregateDailySteps = async () => { [](#%5F%5Fcodelineno-9-30) const { buckets } = await Health.aggregate({ [](#%5F%5Fcodelineno-9-31) dataType: DataType.Steps, [](#%5F%5Fcodelineno-9-32) startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), [](#%5F%5Fcodelineno-9-33) endDate: new Date().toISOString(), [](#%5F%5Fcodelineno-9-34) bucket: 'day', [](#%5F%5Fcodelineno-9-35) operations: ['sum'], [](#%5F%5Fcodelineno-9-36) }); [](#%5F%5Fcodelineno-9-37) return buckets; [](#%5F%5Fcodelineno-9-38)}; [](#%5F%5Fcodelineno-9-39) [](#%5F%5Fcodelineno-9-40)const readWorkouts = async () => { [](#%5F%5Fcodelineno-9-41) const { workouts } = await Health.readWorkouts({ [](#%5F%5Fcodelineno-9-42) startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), [](#%5F%5Fcodelineno-9-43) endDate: new Date().toISOString(), [](#%5F%5Fcodelineno-9-44) limit: 10, [](#%5F%5Fcodelineno-9-45) }); [](#%5F%5Fcodelineno-9-46) return workouts; [](#%5F%5Fcodelineno-9-47)}; [](#%5F%5Fcodelineno-9-48) [](#%5F%5Fcodelineno-9-49)const writeWeight = async () => { [](#%5F%5Fcodelineno-9-50) await Health.writeRecord({ [](#%5F%5Fcodelineno-9-51) dataType: DataType.Weight, [](#%5F%5Fcodelineno-9-52) startDate: new Date().toISOString(), [](#%5F%5Fcodelineno-9-53) value: 71.5, [](#%5F%5Fcodelineno-9-54) }); [](#%5F%5Fcodelineno-9-55)}; [](#%5F%5Fcodelineno-9-56) [](#%5F%5Fcodelineno-9-57)const openSettings = async () => { [](#%5F%5Fcodelineno-9-58) await Health.openSettings(); [](#%5F%5Fcodelineno-9-59)}; ` ## API[¶](#api "Permanent link") * [aggregate(...)](#aggregate) * [checkPermissions(...)](#checkpermissions) * [installHealthConnect()](#installhealthconnect) * [isAvailable()](#isavailable) * [openSettings()](#opensettings) * [readRecords(...)](#readrecords) * [readWorkouts(...)](#readworkouts) * [requestPermissions(...)](#requestpermissions) * [writeRecord(...)](#writerecord) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### aggregate(...)[¶](#aggregate "Permanent link") `[](#%5F%5Fcodelineno-10-1)aggregate(options: AggregateOptions) => Promise ` Aggregate health data over a time range, optionally grouped into buckets. The aggregation is performed by the platform's health store, which deduplicates overlapping data from multiple sources (e.g. a phone and a smartwatch) automatically. Only the following combinations of data type and operation are supported: | Data Type | sum | average, maximum, minimum | | -------------------- | --- | ------------------------- | | ACTIVE\_CALORIES | ✅ | ❌ | | DISTANCE | ✅ | ❌ | | FLOORS\_CLIMBED | ✅ | ❌ | | HEART\_RATE | ❌ | ✅ | | HEIGHT | ❌ | ✅ | | HYDRATION | ✅ | ❌ | | RESTING\_HEART\_RATE | ❌ | ✅ | | STEPS | ✅ | ❌ | | TOTAL\_CALORIES | ✅ | ❌ | | WEIGHT | ❌ | ✅ | Any other combination rejects with the `INVALID_AGGREGATION` error code. It never resolves with silently empty results. On **iOS**, `TOTAL_CALORIES` is computed as the sum of active and basal energy burned since HealthKit has no total energy type. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------- | | **options** | [AggregateOptions](#aggregateoptions) | **Returns:** `Promise<[AggregateResult](#aggregateresult)>` **Since:** 0.0.1 --- ### checkPermissions(...)[¶](#checkpermissions "Permanent link") `[](#%5F%5Fcodelineno-11-1)checkPermissions(options: CheckPermissionsOptions) => Promise ` Check the permission status for the given data types. On **Android**, Health Connect only reports whether a permission is currently granted. A permission that has never been requested and a permission that has been denied are both reported as `prompt`. On **iOS**, HealthKit deliberately hides the read permission status to prevent apps from inferring sensitive information (a denied read permission is indistinguishable from the absence of data). Read permissions are therefore reported as `prompt` before the first request and as `unknown` afterwards. They are **never** reported as `granted`. Design your app around the presence of data, not around the read permission status. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------------- | | **options** | [CheckPermissionsOptions](#checkpermissionsoptions) | **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 0.0.1 --- ### installHealthConnect()[¶](#installhealthconnect "Permanent link") `[](#%5F%5Fcodelineno-12-1)installHealthConnect() => Promise ` Open the Play Store to install or update the Health Connect app. On Android 9 to 13, Health Connect must be installed as a separate app. On Android 14 and later, Health Connect is part of the operating system but may still require an update. Call this method if `isAvailable()` returns the reason `health-connect-not-installed` or `health-connect-update-required`. Only available on Android. **Since:** 0.0.1 --- ### isAvailable()[¶](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-13-1)isAvailable() => Promise ` Check whether health data is available on the device. On **Android**, this checks the Health Connect SDK status and reports one of three states: available, not installed (but supported) or unsupported. If Health Connect is not installed, you can prompt the user to install it with `installHealthConnect()`. On **iOS**, this checks `HKHealthStore.isHealthDataAvailable()`, which returns `false` on devices without health data support (e.g. some iPads). Only available on Android and iOS. **Returns:** `Promise<[IsAvailableResult](#isavailableresult)>` **Since:** 0.0.1 --- ### openSettings()[¶](#opensettings "Permanent link") `[](#%5F%5Fcodelineno-14-1)openSettings() => Promise ` Open the platform's health settings. On **Android**, this opens the Health Connect settings where the user can manage app permissions and data. On **iOS**, this opens the Apple Health app. Apple does not provide a way to open the privacy settings of your app directly. The user can manage permissions in the Health app under `Profile → Privacy → Apps`. Only available on Android and iOS. **Since:** 0.0.1 --- ### readRecords(...)[¶](#readrecords "Permanent link") `[](#%5F%5Fcodelineno-15-1)readRecords(options: ReadRecordsOptions) => Promise ` Read individual health records of a single data type. On **Android**, reads are limited to the last 30 days before the permission was first granted. On **iOS**, the `TOTAL_CALORIES` data type is not supported by this method since HealthKit has no total energy type. Use `aggregate(...)`instead. To read workouts, use `readWorkouts(...)`. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [ReadRecordsOptions](#readrecordsoptions) | **Returns:** `Promise<[ReadRecordsResult](#readrecordsresult)>` **Since:** 0.0.1 --- ### readWorkouts(...)[¶](#readworkouts "Permanent link") `[](#%5F%5Fcodelineno-16-1)readWorkouts(options: ReadWorkoutsOptions) => Promise ` Read workouts. Requires the read permission for the `WORKOUT` data type. On **Android**, the `totalCalories` and `totalDistance` values additionally require the read permissions for the `ACTIVE_CALORIES` and `DISTANCE` data types. Without them, both values are `null`. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------- | | **options** | [ReadWorkoutsOptions](#readworkoutsoptions) | **Returns:** `Promise<[ReadWorkoutsResult](#readworkoutsresult)>` **Since:** 0.0.1 --- ### requestPermissions(...)[¶](#requestpermissions "Permanent link") `[](#%5F%5Fcodelineno-17-1)requestPermissions(options: RequestPermissionsOptions) => Promise ` Request permissions for the given data types. On **Android**, the Health Connect permission screen is shown. If the user denies the request twice, Health Connect permanently ignores further requests and the permissions can only be granted via `openSettings()`. On **iOS**, the HealthKit authorization sheet is shown once per data type. After the request, read permissions are reported as `unknown` since HealthKit hides the read permission status (see `checkPermissions(...)`). On **iOS**, this method rejects with a clear error message if the required usage descriptions are missing in the `Info.plist` file (see the installation instructions). Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [RequestPermissionsOptions](#requestpermissionsoptions) | **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 0.0.1 --- ### writeRecord(...)[¶](#writerecord "Permanent link") `[](#%5F%5Fcodelineno-18-1)writeRecord(options: WriteRecordOptions) => Promise ` Write a single health record. Requires the write permission for the given data type. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [WriteRecordOptions](#writerecordoptions) | **Since:** 0.0.1 --- ### Interfaces[¶](#interfaces "Permanent link") #### AggregateResult[¶](#aggregateresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ------------------------- | ---------------------------------------------- | ----- | | **buckets** | AggregateResultBucket\[\] | The aggregated buckets in chronological order. | 0.0.1 | #### AggregateResultBucket[¶](#aggregateresultbucket "Permanent link") | Prop | Type | Description | Since | | ------------- | ------------------------ | --------------------------------------------------- | ----- | | **endDate** | string | The end of the bucket as ISO 8601 string. | 0.0.1 | | **startDate** | string | The start of the bucket as ISO 8601 string. | 0.0.1 | | **values** | AggregateResultValue\[\] | The aggregated values for each requested operation. | 0.0.1 | #### AggregateResultValue[¶](#aggregateresultvalue "Permanent link") | Prop | Type | Description | Since | | ------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **operation** | [AggregationOperation](#aggregationoperation) | The operation that produced this value. | 0.0.1 | | **value** | number \| null | The aggregated value in the fixed unit of the data type (see [DataType](#datatype)). If no data is available in the bucket, the value is null. | 0.0.1 | #### AggregateOptions[¶](#aggregateoptions "Permanent link") | Prop | Type | Description | Since | | -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **bucket** | [AggregationBucket](#aggregationbucket) | The bucket size to group the results by. The buckets are aligned to startDate. The day, week and month buckets are calendar-aware (e.g. months have different lengths) and are based on the device's time zone. If none, a single bucket spanning the entire time range is returned. | 0.0.1 | | **dataType** | [DataType](#datatype) | The data type to aggregate. | 0.0.1 | | **endDate** | string | The end of the time range (exclusive) as ISO 8601 string. | 0.0.1 | | **operations** | AggregationOperation\[\] | The operations to perform on the data in each bucket. See aggregate(...) for the supported combinations of data type and operation. | 0.0.1 | | **startDate** | string | The start of the time range (inclusive) as ISO 8601 string. | 0.0.1 | #### PermissionStatus[¶](#permissionstatus "Permanent link") | Prop | Type | Description | Since | | --------------- | -------------------------- | --------------------------------------------------- | ----- | | **permissions** | HealthPermissionStatus\[\] | The permission status for each requested data type. | 0.0.1 | #### HealthPermissionStatus[¶](#healthpermissionstatus "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | **dataType** | [DataType](#datatype) | The data type this status belongs to. | 0.0.1 | | **read** | [HealthPermissionState](#healthpermissionstate) | The read permission status. Only set if the data type was included in the read option. | 0.0.1 | | **write** | [HealthPermissionState](#healthpermissionstate) | The write permission status. Only set if the data type was included in the write option. | 0.0.1 | #### CheckPermissionsOptions[¶](#checkpermissionsoptions "Permanent link") | Prop | Type | Description | Since | | --------- | -------------------- | -------------------------------------------------------- | ----- | | **read** | DataType\[\] | The data types to check the read permission status for. | 0.0.1 | | **write** | WritableDataType\[\] | The data types to check the write permission status for. | 0.0.1 | #### IsAvailableResult[¶](#isavailableresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **available** | boolean | Whether or not health data is available on the device. | 0.0.1 | | **reason** | [IsAvailableReason](#isavailablereason) \| null | The reason why health data is not available on the device. If health data is available, the value is null. On **Android**, the reason health-connect-not-installed means that the device is supported but the Health Connect app is not installed. Call installHealthConnect() to prompt the user to install it. The reason health-connect-update-required means that the installed Health Connect app is too old. | 0.0.1 | #### ReadRecordsResult[¶](#readrecordsresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ---------------- | --------------------------- | ----- | | **records** | HealthRecord\[\] | The records that were read. | 0.0.1 | #### HealthRecord[¶](#healthrecord "Permanent link") A single health record. | Prop | Type | Description | Since | | ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **dataType** | [DataType](#datatype) | The data type of the record. | 0.0.1 | | **diastolic** | number | The diastolic blood pressure in millimeters of mercury. Only set for the BLOOD\_PRESSURE data type. | 0.0.1 | | **endDate** | string | The end of the record as ISO 8601 string. For instantaneous records (e.g. weight), this is the same as startDate. | 0.0.1 | | **id** | string \| null | The unique identifier of the record. If the platform does not provide an identifier, the value is null. | 0.0.1 | | **sourceBundleId** | string \| null | The bundle identifier (iOS) or package name (Android) of the app that wrote the record. | 0.0.1 | | **sourceName** | string \| null | The display name of the source that wrote the record. On **Android**, Health Connect does not provide a display name, so the value is always null. | 0.0.1 | | **stages** | SleepStageSample\[\] | The sleep stages of the record. Only set for the SLEEP data type. On **Android**, a record is a sleep session that contains all its stages. On **iOS**, HealthKit has no session concept. Each record is a single sleep analysis sample with exactly one stage. | 0.0.1 | | **startDate** | string | The start of the record as ISO 8601 string. | 0.0.1 | | **systolic** | number | The systolic blood pressure in millimeters of mercury. Only set for the BLOOD\_PRESSURE data type. | 0.0.1 | | **unit** | string | The fixed unit of the value (see [DataType](#datatype)). | 0.0.1 | | **value** | number \| null | The value of the record in the fixed unit of the data type (see DataType). For the BLOOD\_PRESSURE data type, the value is null (see systolic and diastolic). For the SLEEP data type, the value is the duration in minutes. Non-finite values reported by third-party data sources are also normalized to null. | 0.0.1 | #### SleepStageSample[¶](#sleepstagesample "Permanent link") A single sleep stage within a sleep record. | Prop | Type | Description | Since | | ------------- | ------------------------- | ------------------------------------------------ | ----- | | **endDate** | string | The end of the sleep stage as ISO 8601 string. | 0.0.1 | | **stage** | [SleepStage](#sleepstage) | The sleep stage. | 0.0.1 | | **startDate** | string | The start of the sleep stage as ISO 8601 string. | 0.0.1 | #### ReadRecordsOptions[¶](#readrecordsoptions "Permanent link") | Prop | Type | Description | Default | Since | | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- | | **ascending** | boolean | Whether to return the records in ascending order by start date. | true | 0.0.1 | | **dataOrigins** | string\[\] | Filter the records by the apps that wrote them, identified by bundle identifier (iOS) or package name (Android). An empty array is treated like an omitted filter. | | 0.0.1 | | **dataType** | [DataType](#datatype) | The data type to read. The WORKOUT data type is not supported by this method. Use readWorkouts(...) instead. | | 0.0.1 | | **endDate** | string | The end of the time range (exclusive) as ISO 8601 string. | | 0.0.1 | | **limit** | number | The maximum number of records to return. If not set, all records in the time range are returned. | | 0.0.1 | | **startDate** | string | The start of the time range (inclusive) as ISO 8601 string. | | 0.0.1 | #### ReadWorkoutsResult[¶](#readworkoutsresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------- | ---------------------------- | ----- | | **workouts** | Workout\[\] | The workouts that were read. | 0.0.1 | #### Workout[¶](#workout "Permanent link") A single workout. | Prop | Type | Description | Since | | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **duration** | number | The duration of the workout in seconds. On **Android**, this is the wall-clock time between startDate and endDate. On **iOS**, paused intervals are excluded. | 0.0.1 | | **endDate** | string | The end of the workout as ISO 8601 string. | 0.0.1 | | **id** | string \| null | The unique identifier of the workout. If the platform does not provide an identifier, the value is null. | 0.0.1 | | **rawWorkoutType** | string \| null | The platform-specific raw workout type. On **Android**, this is the numeric Health Connect exercise type. On **iOS**, this is the numeric HKWorkoutActivityType raw value. Use this value to distinguish workout types that are mapped to OTHER. | 0.0.1 | | **sourceBundleId** | string \| null | The bundle identifier (iOS) or package name (Android) of the app that wrote the workout. | 0.0.1 | | **sourceName** | string \| null | The display name of the source that wrote the workout. On **Android**, Health Connect does not provide a display name, so the value is always null. | 0.0.1 | | **startDate** | string | The start of the workout as ISO 8601 string. | 0.0.1 | | **totalCalories** | number \| null | The total energy burned during the workout in kilocalories. If the platform does not provide a value, the value is null. On **iOS**, the value is only available on iOS 16 and later. | 0.0.1 | | **totalDistance** | number \| null | The total distance covered during the workout in meters. If the platform does not provide a value, the value is null. On **iOS**, the value is only available on iOS 16 and later. | 0.0.1 | | **workoutType** | [WorkoutType](#workouttype) | The type of the workout. If the platform-specific workout type has no equivalent in [WorkoutType](#workouttype), the value is OTHER and the platform-specific value is available in rawWorkoutType. | 0.0.1 | #### ReadWorkoutsOptions[¶](#readworkoutsoptions "Permanent link") | Prop | Type | Description | Since | | --------------- | --------------------------- | -------------------------------------------------------------------------------------------------- | ----- | | **endDate** | string | The end of the time range (exclusive) as ISO 8601 string. | 0.0.1 | | **limit** | number | The maximum number of workouts to return. If not set, all workouts in the time range are returned. | 0.0.1 | | **startDate** | string | The start of the time range (inclusive) as ISO 8601 string. | 0.0.1 | | **workoutType** | [WorkoutType](#workouttype) | Filter the workouts by workout type. | 0.0.1 | #### RequestPermissionsOptions[¶](#requestpermissionsoptions "Permanent link") | Prop | Type | Description | Since | | --------- | -------------------- | --------------------------------------------------- | ----- | | **read** | DataType\[\] | The data types to request the read permission for. | 0.0.1 | | **write** | WritableDataType\[\] | The data types to request the write permission for. | 0.0.1 | #### WriteRecordOptions[¶](#writerecordoptions "Permanent link") | Prop | Type | Description | Since | | ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **dataType** | [WritableDataType](#writabledatatype) | The data type to write. | 0.0.1 | | **diastolic** | number | The diastolic blood pressure in millimeters of mercury. Required for the BLOOD\_PRESSURE data type. | 0.0.1 | | **endDate** | string | The end of the record as ISO 8601 string. Required for the HYDRATION, STEPS and WORKOUT data types. Ignored for instantaneous data types (e.g. WEIGHT). | 0.0.1 | | **startDate** | string | The start of the record as ISO 8601 string. | 0.0.1 | | **systolic** | number | The systolic blood pressure in millimeters of mercury. Required for the BLOOD\_PRESSURE data type. | 0.0.1 | | **value** | number | The value of the record in the fixed unit of the data type (see DataType). Required for the BLOOD\_GLUCOSE, HEIGHT, HYDRATION, STEPS and WEIGHT data types. Must be a finite number. | 0.0.1 | | **workout** | [WriteRecordWorkout](#writerecordworkout) | The workout to write. Required for the WORKOUT data type. | 0.0.1 | #### WriteRecordWorkout[¶](#writerecordworkout "Permanent link") | Prop | Type | Description | Since | | ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **totalCalories** | number | The total energy burned during the workout in kilocalories. On **Android**, this additionally writes an active calories record for the workout time range, which requires the write permission for the ACTIVE\_CALORIES data type. | 0.0.1 | | **totalDistance** | number | The total distance covered during the workout in meters. On **Android**, this additionally writes a distance record for the workout time range, which requires the write permission for the DISTANCE data type. | 0.0.1 | | **workoutType** | [WorkoutType](#workouttype) | The type of the workout. If the platform has no equivalent for the given workout type, it is written as the platform's generic workout type. | 0.0.1 | ### Type Aliases[¶](#type-aliases "Permanent link") #### AggregationOperation[¶](#aggregationoperation "Permanent link") The operation to perform when aggregating data. `'average' | 'maximum' | 'minimum' | 'sum'` #### AggregationBucket[¶](#aggregationbucket "Permanent link") The bucket size to group aggregation results by. `'day' | 'hour' | 'month' | 'none' | 'week'` #### HealthPermissionState[¶](#healthpermissionstate "Permanent link") The status of a single health permission. The value `unknown` is used on iOS for read permissions after the first request since HealthKit deliberately hides whether a read permission was granted or denied. `'denied' | 'granted' | 'prompt' | 'unknown'` #### WritableDataType[¶](#writabledatatype "Permanent link") The data types that can be written with `writeRecord(...)`. `[DataType.BloodGlucose](#datatype) | [DataType.BloodPressure](#datatype) | [DataType.Height](#datatype) | [DataType.Hydration](#datatype) | [DataType.Steps](#datatype) | [DataType.Weight](#datatype) | [DataType.Workout](#datatype)` #### IsAvailableReason[¶](#isavailablereason "Permanent link") The reason why health data is not available on the device. `'health-connect-not-installed' | 'health-connect-update-required' | 'not-supported'` ### Enums[¶](#enums "Permanent link") #### DataType[¶](#datatype "Permanent link") | Members | Value | Description | Since | | ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **ActiveCalories** | 'ACTIVE\_CALORIES' | Active energy burned in kilocalories (kcal). | 0.0.1 | | **BloodGlucose** | 'BLOOD\_GLUCOSE' | Blood glucose level in millimoles per liter (mmol/L). | 0.0.1 | | **BloodPressure** | 'BLOOD\_PRESSURE' | Blood pressure in millimeters of mercury (mmHg). Records of this data type use the systolic and diastolic properties instead of value. | 0.0.1 | | **BodyFat** | 'BODY\_FAT' | Body fat percentage (percent, 0 to 100). | 0.0.1 | | **BodyTemperature** | 'BODY\_TEMPERATURE' | Body temperature in degrees Celsius (celsius). | 0.0.1 | | **Distance** | 'DISTANCE' | Distance covered in meters (m). On **iOS**, this maps to walking and running distance. | 0.0.1 | | **FloorsClimbed** | 'FLOORS\_CLIMBED' | Floors climbed (count). | 0.0.1 | | **HeartRate** | 'HEART\_RATE' | Heart rate in beats per minute (bpm). | 0.0.1 | | **HeartRateVariability** | 'HEART\_RATE\_VARIABILITY' | Heart rate variability in milliseconds (ms). **Attention**: The platforms measure different metrics! Android (Health Connect) provides RMSSD values while iOS (HealthKit) provides SDNN values. The values are exposed as-is and are **not** comparable across platforms. | 0.0.1 | | **Height** | 'HEIGHT' | Height in meters (m). | 0.0.1 | | **Hydration** | 'HYDRATION' | Water intake in liters (L). | 0.0.1 | | **OxygenSaturation** | 'OXYGEN\_SATURATION' | Blood oxygen saturation percentage (percent, 0 to 100). | 0.0.1 | | **RespiratoryRate** | 'RESPIRATORY\_RATE' | Respiratory rate in breaths per minute (breaths/min). | 0.0.1 | | **RestingHeartRate** | 'RESTING\_HEART\_RATE' | Resting heart rate in beats per minute (bpm). | 0.0.1 | | **Sleep** | 'SLEEP' | Sleep sessions with sleep stages. The record value is the duration in minutes (min). | 0.0.1 | | **Steps** | 'STEPS' | Steps taken (count). | 0.0.1 | | **TotalCalories** | 'TOTAL\_CALORIES' | Total energy burned in kilocalories (kcal). **Attention**: The platforms compose this value differently! Android (Health Connect) has a dedicated total calories record type while on iOS (HealthKit) the value is computed as the sum of active and basal energy burned. On iOS, this data type is only supported by aggregate(...). | 0.0.1 | | **Vo2Max** | 'VO2\_MAX' | Maximal oxygen consumption in milliliters per kilogram of body weight per minute (mL/kg/min). | 0.0.1 | | **Weight** | 'WEIGHT' | Body weight in kilograms (kg). | 0.0.1 | | **Workout** | 'WORKOUT' | Workouts (exercise sessions). This data type is used for permission requests, readWorkouts(...) and writeRecord(...). It is not supported by readRecords(...). | 0.0.1 | #### SleepStage[¶](#sleepstage "Permanent link") | Members | Value | Description | Since | | ----------- | --------- | ------------------------------------------------ | ----- | | **Awake** | 'AWAKE' | The user is awake. | 0.0.1 | | **Deep** | 'DEEP' | The user is in deep sleep. | 0.0.1 | | **InBed** | 'IN\_BED' | The user is in bed but not necessarily sleeping. | 0.0.1 | | **Light** | 'LIGHT' | The user is in light sleep. | 0.0.1 | | **Rem** | 'REM' | The user is in REM sleep. | 0.0.1 | | **Unknown** | 'UNKNOWN' | The sleep stage is unknown. | 0.0.1 | #### WorkoutType[¶](#workouttype "Permanent link") | Members | Value | Description | Since | | --------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **AmericanFootball** | 'AMERICAN\_FOOTBALL' | | 0.0.1 | | **AustralianFootball** | 'AUSTRALIAN\_FOOTBALL' | | 0.0.1 | | **Badminton** | 'BADMINTON' | | 0.0.1 | | **Baseball** | 'BASEBALL' | | 0.0.1 | | **Basketball** | 'BASKETBALL' | | 0.0.1 | | **Biking** | 'BIKING' | | 0.0.1 | | **Boxing** | 'BOXING' | | 0.0.1 | | **Calisthenics** | 'CALISTHENICS' | On **iOS**, this is written as functional strength training and read as STRENGTH\_TRAINING. | 0.0.1 | | **Cricket** | 'CRICKET' | | 0.0.1 | | **Dancing** | 'DANCING' | | 0.0.1 | | **Elliptical** | 'ELLIPTICAL' | | 0.0.1 | | **Fencing** | 'FENCING' | | 0.0.1 | | **Golf** | 'GOLF' | | 0.0.1 | | **Gymnastics** | 'GYMNASTICS' | | 0.0.1 | | **Handball** | 'HANDBALL' | | 0.0.1 | | **HighIntensityIntervalTraining** | 'HIGH\_INTENSITY\_INTERVAL\_TRAINING' | | 0.0.1 | | **Hiking** | 'HIKING' | | 0.0.1 | | **IceHockey** | 'ICE\_HOCKEY' | | 0.0.1 | | **IceSkating** | 'ICE\_SKATING' | | 0.0.1 | | **MartialArts** | 'MARTIAL\_ARTS' | | 0.0.1 | | **Other** | 'OTHER' | | 0.0.1 | | **Paddling** | 'PADDLING' | | 0.0.1 | | **Pilates** | 'PILATES' | | 0.0.1 | | **Racquetball** | 'RACQUETBALL' | | 0.0.1 | | **RockClimbing** | 'ROCK\_CLIMBING' | | 0.0.1 | | **Rowing** | 'ROWING' | | 0.0.1 | | **RowingMachine** | 'ROWING\_MACHINE' | On **iOS**, this is written and read as ROWING. | 0.0.1 | | **Rugby** | 'RUGBY' | | 0.0.1 | | **Running** | 'RUNNING' | | 0.0.1 | | **RunningTreadmill** | 'RUNNING\_TREADMILL' | On **iOS**, this is written and read as RUNNING. | 0.0.1 | | **Sailing** | 'SAILING' | | 0.0.1 | | **ScubaDiving** | 'SCUBA\_DIVING' | | 0.0.1 | | **Skiing** | 'SKIING' | | 0.0.1 | | **Snowboarding** | 'SNOWBOARDING' | | 0.0.1 | | **Soccer** | 'SOCCER' | | 0.0.1 | | **Softball** | 'SOFTBALL' | | 0.0.1 | | **Squash** | 'SQUASH' | | 0.0.1 | | **StairClimbing** | 'STAIR\_CLIMBING' | | 0.0.1 | | **StrengthTraining** | 'STRENGTH\_TRAINING' | | 0.0.1 | | **Stretching** | 'STRETCHING' | | 0.0.1 | | **Surfing** | 'SURFING' | | 0.0.1 | | **Swimming** | 'SWIMMING' | Generic swimming (iOS only). On **Android**, this is written as the generic workout type. Use SWIMMING\_POOL or SWIMMING\_OPEN\_WATER for cross-platform swimming workouts. | 0.0.1 | | **SwimmingOpenWater** | 'SWIMMING\_OPEN\_WATER' | On **iOS**, this is written and read as SWIMMING. | 0.0.1 | | **SwimmingPool** | 'SWIMMING\_POOL' | On **iOS**, this is written and read as SWIMMING. | 0.0.1 | | **TableTennis** | 'TABLE\_TENNIS' | | 0.0.1 | | **Tennis** | 'TENNIS' | | 0.0.1 | | **Volleyball** | 'VOLLEYBALL' | | 0.0.1 | | **Walking** | 'WALKING' | | 0.0.1 | | **WaterPolo** | 'WATER\_POLO' | | 0.0.1 | | **Wheelchair** | 'WHEELCHAIR' | | 0.0.1 | | **Yoga** | 'YOGA' | | 0.0.1 | ## FAQ[¶](#faq "Permanent link") ### How is this plugin different from other similar plugins?[¶](#how-is-this-plugin-different-from-other-similar-plugins "Permanent link") It is built for correctness and honesty with health data: it reports iOS permission states accurately, surfaces the real availability states on Android, and returns strongly-typed, aggregation-first results. It also ships the setup and policy documentation you need to pass App Review and the required Google Play health-data declaration — the steps that most often decide whether a health app ships — and it's backed by dedicated support. ### Why are read permissions reported as `unknown` on iOS?[¶](#why-are-read-permissions-reported-as-unknown-on-ios "Permanent link") HealthKit deliberately hides whether a read permission was granted or denied to prevent apps from inferring sensitive information (an app that knows it was denied access to, say, blood glucose data could conclude the user is likely diabetic). A denied read permission behaves exactly like the absence of data. Some plugins pretend read permissions are `granted` after a request — this plugin does not, because it would simply be wrong. Design your app around the **presence of data**, not around the read permission status: request the permissions, query the data and show an appropriate empty state (e.g. "No data available. Check the Health app if you expected data here.") when nothing is returned. ### Why does my app get rejected by Google Play?[¶](#why-does-my-app-get-rejected-by-google-play "Permanent link") Every app that integrates with Health Connect must complete the **Health apps declaration** in the Google Play Console and be approved for the requested permission types (see the installation instructions above). Also make sure your app only declares the health permissions it actually uses and provides a privacy policy. ### Why can't I read data older than 30 days on Android?[¶](#why-cant-i-read-data-older-than-30-days-on-android "Permanent link") Health Connect only allows apps to read data from up to 30 days before the moment the permission was first granted. If the permission is revoked and granted again, the 30-day window is calculated from the new grant. Support for the `READ_HEALTH_DATA_HISTORY` permission is planned as a fast-follow feature. ### Is health data available on the web?[¶](#is-health-data-available-on-the-web "Permanent link") No. There is no web API for health data. All methods reject with an unimplemented error on the web. ### Why do steps from my phone and smartwatch not add up?[¶](#why-do-steps-from-my-phone-and-smartwatch-not-add-up "Permanent link") They do — that's the point of `aggregate(...)`. The platform deduplicates overlapping data from multiple sources automatically. If you sum up the individual records from `readRecords(...)` yourself, you will count overlapping data twice. Use `aggregate(...)` for totals. ### Can I use this plugin with Ionic, React, Vue or Angular?[¶](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[¶](#related-plugins "Permanent link") * [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/): Live step counting from the device's motion sensors. * [Background Geolocation](https://capawesome.io/docs/sdks/capacitor/background-geolocation/): Track workout routes in the background. * [Local Notifications](https://capawesome.io/docs/sdks/capacitor/local-notifications/): Remind users to log their health data. ## Newsletter[¶](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[¶](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/CHANGELOG.md). ## Breaking Changes[¶](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/BREAKING.md). ## License[¶](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/health/LICENSE). August 15, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/health/#article", "headline": "Capacitor Health Plugin for Android & iOS", "name": "Capacitor Health Plugin for Android & iOS", "description": "Capacitor Health plugin to read and write health and workout data on Android and iOS via Health Connect and Apple HealthKit.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/health/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/health/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/health/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/health/#software", "name": "Capacitor Health Plugin for Android & iOS", "description": "Capacitor Health plugin to read and write health and workout data on Android and iOS via Health Connect and Apple HealthKit.", "url": "https://capawesome.io/docs/sdks/capacitor/health/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How is this plugin different from other similar plugins?", "acceptedAnswer": {"@type": "Answer", "text": "It is built for correctness and honesty with health data: it reports iOS permission states accurately, surfaces the real availability states on Android, and returns strongly-typed, aggregation-first results. It also ships the setup and policy documentation you need to pass App Review and the required Google Play health-data declaration — the steps that most often decide whether a health app ships — and it's backed by dedicated support."}}, {"@type": "Question", "name": "Why are read permissions reported as unknown on iOS?", "acceptedAnswer": {"@type": "Answer", "text": "HealthKit deliberately hides whether a read permission was granted or denied to prevent apps from inferring sensitive information (an app that knows it was denied access to, say, blood glucose data could conclude the user is likely diabetic). A denied read permission behaves exactly like the absence of data. Some plugins pretend read permissions are granted after a request — this plugin does not, because it would simply be wrong. Design your app around the presence of data, not around the read permission status: request the permissions, query the data and show an appropriate empty state (e.g. \"No data available. Check the Health app if you expected data here.\") when nothing is returned."}}, {"@type": "Question", "name": "Why does my app get rejected by Google Play?", "acceptedAnswer": {"@type": "Answer", "text": "Every app that integrates with Health Connect must complete the Health apps declaration in the Google Play Console and be approved for the requested permission types (see the installation instructions above). Also make sure your app only declares the health permissions it actually uses and provides a privacy policy."}}, {"@type": "Question", "name": "Why can't I read data older than 30 days on Android?", "acceptedAnswer": {"@type": "Answer", "text": "Health Connect only allows apps to read data from up to 30 days before the moment the permission was first granted. If the permission is revoked and granted again, the 30-day window is calculated from the new grant. Support for the READ_HEALTH_DATA_HISTORY permission is planned as a fast-follow feature."}}, {"@type": "Question", "name": "Is health data available on the web?", "acceptedAnswer": {"@type": "Answer", "text": "No. There is no web API for health data. All methods reject with an unimplemented error on the web."}}, {"@type": "Question", "name": "Why do steps from my phone and smartwatch not add up?", "acceptedAnswer": {"@type": "Answer", "text": "They do — that's the point of aggregate(...). The platform deduplicates overlapping data from multiple sources automatically. If you sum up the individual records from readRecords(...) yourself, you will count overlapping data twice. Use aggregate(...) for totals."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/health/"} ```