@devmaxime/capacitor-health-connect

Capacitor plugin to interact with Android Health Connect.

Install

npm install @devmaxime/capacitor-health-connect
npx cap sync

Add the following to your app's AndroidManifest.xml:

<queries>
   <package android:name="com.google.android.apps.healthdata" />
</queries>

Also add this to your AndroidManifest.xml:

<application>
...
    <activity>
    ...

        <!-- Permission handling for Android 13 and before -->
        <intent-filter>
            <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
        </intent-filter>

        <!-- Permission handling for Android 14 and later -->
        <intent-filter>
            <action android:name="android.intent.action.VIEW_PERMISSION_USAGE"/>
            <category android:name="android.intent.category.HEALTH_PERMISSIONS"/>
        </intent-filter>

    ...
    </activity>
</application>

Permissions

You also need to add permissions for the records you want to read and/or write to the AndroidManifest.xml. A complete list of available records and the corresponding permissions can be found here.

<!-- Example permissions -->
<uses-permission android:name="android.permission.health.READ_STEPS"/>
<uses-permission android:name="android.permission.health.WRITE_STEPS"/>
<uses-permission android:name="android.permission.health.READ_EXERCISE"/>
<uses-permission android:name="android.permission.health.WRITE_EXERCISE"/>

API

• checkAvailability()
• requestPermissions(...)
• getGrantedPermissions()
• revokePermissions()
• readRecords(...)
• aggregateRecords(...)
• Interfaces
• Type Aliases

checkAvailability()

checkAvailability() => Promise<{ availability: HealthConnectAvailability; }>

Returns: Promise<{ availability: HealthConnectAvailability; }>

requestPermissions(...)

requestPermissions(options: { read: RecordType[]; write: RecordType[]; }) => Promise<PermissionsResponse>

Returns: Promise<PermissionsResponse>

getGrantedPermissions()

getGrantedPermissions() => Promise<PermissionsResponse>

Returns: Promise<PermissionsResponse>

revokePermissions()

revokePermissions() => Promise<void>

readRecords(...)

readRecords(options: { start: string; end: string; type: RecordType; pageSize?: number; pageToken?: string; }) => Promise<ReadRecordsResponse>

Reads records of the specified type within a time range.

When pageToken is not provided, automatic pagination is used to retrieve ALL records within the specified time range. This may take longer for large datasets but ensures complete data retrieval.

When pageToken is provided, manual pagination is used and only a single page of results is returned along with a nextPageToken for retrieving subsequent pages.

Returns: Promise<ReadRecordsResponse>

aggregateRecords(...)

aggregateRecords(options: { start: string; end: string; type: AggregateRecordType; groupBy?: AggregateGroupBy; }) => Promise<AggregateResponse>

Aggregates records of the specified type within a time range. Returns aggregated data grouped by the specified time period (e.g., daily totals).

Returns: Promise<AggregateResponse>

Interfaces

PermissionsResponse

ReadRecordsResponse

Response from reading health records.

When using automatic pagination (no pageToken provided), all records are returned and nextPageToken will be undefined.

When using manual pagination (pageToken provided), nextPageToken will contain the token for the next page, or undefined if this is the last page.

AggregateResponse

Response from aggregating health records. Contains aggregated data grouped by time periods.

AggregateData

Aggregated data for a specific time period.

Type Aliases

HealthConnectAvailability

'Available' | 'NotSupported' | 'NotInstalled'

RecordType

'Steps' | 'Weight' | 'ActivitySession' | 'SleepSession' | 'RestingHeartRate'

AggregateRecordType

'Steps' | 'Distance' | 'TotalCaloriesBurned' | 'ActiveCaloriesBurned' | 'HeartRate'

AggregateGroupBy

'day' | 'hour' | 'week' | 'month'

Available records in Android Health Connect TODO: add this to the docs.

ActiveCaloriesBurned -> class androidx.health.connect.client.records.ActiveCaloriesBurnedRecord ActivitySession -> class androidx.health.connect.client.records.ExerciseSessionRecord BasalBodyTemperature -> class androidx.health.connect.client.records.BasalBodyTemperatureRecord BasalMetabolicRate -> class androidx.health.connect.client.records.BasalMetabolicRateRecord BloodGlucose -> class androidx.health.connect.client.records.BloodGlucoseRecord BloodPressure -> class androidx.health.connect.client.records.BloodPressureRecord BodyFat -> class androidx.health.connect.client.records.BodyFatRecord BodyTemperature -> class androidx.health.connect.client.records.BodyTemperatureRecord BodyWaterMass -> class androidx.health.connect.client.records.BodyWaterMassRecord BoneMass -> class androidx.health.connect.client.records.BoneMassRecord CervicalMucus -> class androidx.health.connect.client.records.CervicalMucusRecord CyclingPedalingCadenceSeries -> class androidx.health.connect.client.records.CyclingPedalingCadenceRecord Distance -> class androidx.health.connect.client.records.DistanceRecord ElevationGained -> class androidx.health.connect.client.records.ElevationGainedRecord FloorsClimbed -> class androidx.health.connect.client.records.FloorsClimbedRecord HeartRateSeries -> class androidx.health.connect.client.records.HeartRateRecord HeartRateVariabilityRmssd -> class androidx.health.connect.client.records.HeartRateVariabilityRmssdRecord Height -> class androidx.health.connect.client.records.HeightRecord Hydration -> class androidx.health.connect.client.records.HydrationRecord LeanBodyMass -> class androidx.health.connect.client.records.LeanBodyMassRecord Menstruation -> class androidx.health.connect.client.records.MenstruationFlowRecord MenstruationPeriod -> class androidx.health.connect.client.records.MenstruationPeriodRecord Nutrition -> class androidx.health.connect.client.records.NutritionRecord OvulationTest -> class androidx.health.connect.client.records.OvulationTestRecord OxygenSaturation -> class androidx.health.connect.client.records.OxygenSaturationRecord PowerSeries -> class androidx.health.connect.client.records.PowerRecord RespiratoryRate -> class androidx.health.connect.client.records.RespiratoryRateRecord RestingHeartRate -> class androidx.health.connect.client.records.RestingHeartRateRecord SexualActivity -> class androidx.health.connect.client.records.SexualActivityRecord SkinTemperature -> class androidx.health.connect.client.records.SkinTemperatureRecord SleepSession -> class androidx.health.connect.client.records.SleepSessionRecord SpeedSeries -> class androidx.health.connect.client.records.SpeedRecord IntermenstrualBleeding -> class androidx.health.connect.client.records.IntermenstrualBleedingRecord Steps -> class androidx.health.connect.client.records.StepsRecord StepsCadenceSeries -> class androidx.health.connect.client.records.StepsCadenceRecord TotalCaloriesBurned -> class androidx.health.connect.client.records.TotalCaloriesBurnedRecord Vo2Max -> class androidx.health.connect.client.records.Vo2MaxRecord WheelchairPushes -> class androidx.health.connect.client.records.WheelchairPushesRecord Weight -> class androidx.health.connect.client.records.WeightRecord

Initially forked from @sprintwerk/capacitor-android-health-connect