eitri-android-health

Health module for the Eitri Android framework. Provides a standardized bridge over Android Health Connect (androidx.health.connect) for consuming health & fitness data from eitri-apps.

Requirements

• Android 9 (API level 28) or later
• Health Connect provider available on the device:
  • Android 14+: built into the system
  • Android 13 and below: user must install the Health Connect by Android app from the Play Store (com.google.android.apps.healthdata)

Installation

The eitri-android-health artifact is available on Maven Central.

Gradle Kotlin DSL (build.gradle.kts)

dependencies {
    implementation("tech.eitri:eitri-android-health:$version")
}

Replace $version with the desired version. You can find the latest on Maven Central.

Registering the health module

import tech.eitri.android.health.HealthModule

// [...]

val machineContext = EitriMachineInstanceManager.start()
val mainEitriMachine = machineContext.mainMachine

// configure eitri-machine [...]

// register modules
mainEitriMachine.modules.register(HealthModule())

Required host-app configuration

Health Connect permissions are declared by the host app, not by this module. The runtime can only return data for types that were declared at install time. The full list of permissions and corresponding Record classes is at https://developer.android.com/health-and-fitness/health-connect/data-types.

1. Declare the data types you need in AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required: provider package visibility (also declared by this module, listed here for reference) -->
    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>

    <!-- Activity (steps / distance / calories / exercise) -->
    <uses-permission android:name="android.permission.health.READ_STEPS" />
    <uses-permission android:name="android.permission.health.READ_DISTANCE" />
    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED" />
    <uses-permission android:name="android.permission.health.READ_EXERCISE" />

    <!-- Vitals -->
    <uses-permission android:name="android.permission.health.READ_HEART_RATE" />
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE" />

    <!-- Body -->
    <uses-permission android:name="android.permission.health.READ_WEIGHT" />

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

    <!-- ... application ... -->
</manifest>

Permissions must also be listed in the Play Console under "App content > Health Connect" before the app is published.

2. Declare the permissions rationale activity

Health Connect launches the host app when the user taps the privacy policy link inside the permissions screen. The host app must declare an activity (or activity-alias) to render that screen.

For Android 13 and below:

<activity
    android:name=".PermissionsRationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

For Android 14 and above:

<activity-alias
    android:name="ViewPermissionUsageActivity"
    android:exported="true"
    android:targetActivity=".PermissionsRationaleActivity"
    android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
</activity-alias>

The activity itself can be a simple screen rendering the host app's privacy policy.

Core Concepts

• HealthModule: entry point implementing EitriModule. Exposes the methods consumed by the Bifrost Health service.
• HealthDataType: neutral identifiers (steps, heartRate, weight, ...)
• HealthService: low-level wrapper over androidx.health.connect.client.HealthConnectClient.

Methods

Exposed under the health namespace. Bifrost-side API and platform notes (units, unsupported data types, etc.) are documented at the Eitri Bifrost documentation page.

Method	Description
isAvailable	Returns { available, reason? } based on HealthConnectClient.getSdkStatus.
getSupportedDataTypes	Returns the intersection of the types this module supports and the host-declared <uses-permission android:name="android.permission.health.READ_*" /> entries.
requestPermissions	Launches the Health Connect permissions UI for the requested data types. Accepts samples, characteristics and exercise in the same read array; characteristic types are silently skipped on Android (no Health Connect equivalent). Resolves with no payload — apps detect access by calling the relevant read method and checking the result.
readSamples	Reads one page of raw samples for a single data type via readRecords. limit is the per-page sample cap, clamped to 1..500, default 100. Paginate with cursor: pass the previous page's opaque nextCursor to fetch the next page; drive the loop on nextCursor (absent ⇒ exhausted), not on page size. Returns samples: [] when the user has not granted the corresponding permission.
readExercises	Reads one page of exercises — every ExerciseSessionRecord whose start instant falls in [startDate, endDate). No type filter — caller narrows by inspecting exercise.exerciseType. Same pagination contract as readSamples (per-page limit clamped to 1..500, default 100, paginate via cursor/nextCursor). Requires the android.permission.health.READ_EXERCISE manifest entry and the "exercise" runtime permission. Returns exercises: [] when permission is missing.
getCharacteristics	Always returns an object with every requested field as null — Health Connect does not expose user characteristics. Kept for cross-platform parity.

HealthExercise.exerciseType values

Reference of values Android may emit: Health Connect ExerciseSessionType. Read sample values yourself by calling readSamples for "distance" / "activeEnergyBurned" / "heartRate" scoped to the exercise's startDate/endDate.