Skip to content
shubhamsinghshubham777Public

About

A Kotlin Multiplatform wrapper for Android's Health Connect and Apple's HealthKit πŸ₯

Topics

Resources

Stars

85 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

91 Commits

Folders and files

Repository files navigation

πŸ₯ KHealth πŸ₯

KHealth Logo

KHealth (Kotlin Health) is a modern Kotlin Multiplatform library providing a unified, type-safe API over Android's Health Connect and Apple's HealthKit (iOS and watchOS). It is designed from the ground up for seamless use in Kotlin Multiplatform (KMP) and Compose Multiplatform projects.


✨ Features

  • πŸš€ Zero-Boilerplate Instantiation: Call val kHealth = KHealth() directly in commonMain across Android, iOS, and watchOS.
  • πŸ€– Android Auto-Initialization: Automatically initializes Health Connect via ContentProvider. No manual initialise() call or Android Context required in shared code.
  • 🎯 Type-Safe Generic Reads: readRecords(KHReadRequest.HeartRate(...)) directly returns List<KHRecord.HeartRate> without type casting or runtime checks.
  • πŸ›‘οΈ Ergonomic Permissions API: Check, request, and verify permissions with expressive extensions like perms.isGranted(...), perms.allGranted(), and kHealth.hasPermission(...).
  • ⚑ Flexible API: Vararg and collection overloads for reading, writing, and permission management.
  • πŸ“± Multiplatform Sample Apps: Clean architectural separation with shared business logic and native UIs (Jetpack Compose on Android, SwiftUI on iOS & watchOS).

πŸ“± Sample Apps

Note

Sample apps showcasing integration can be found in the sampleApps directory:

  • sampleApps/shared: Shared KMP logic, repository layer, and sample health interactions.
  • sampleApps/android: Android Jetpack Compose app with Health Connect permission rationale.
  • sampleApps/apple: SwiftUI iOS and watchOS applications.

πŸš€ Getting Started

Maven Central Version

Add the dependency to your shared module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.shubhamsinghshubham777:khealth:2.1.0")
        }
    }
}

Or using Gradle version catalogs:

[versions]
khealth = "2.1.0"

[libraries]
khealth = { module = "io.github.shubhamsinghshubham777:khealth", version.ref = "khealth" }
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.khealth)
        }
    }
}

βš™οΈ Platform Setup

1. Apple (iOS & watchOS)

Add HealthKit usage descriptions to your Info.plist:

<plist version="1.0">
<dict>
    <!-- ... -->
    <key>NSHealthUpdateUsageDescription</key>
    <string>We need permission to save health records to Apple Health.</string>
    <key>NSHealthShareUsageDescription</key>
    <string>We need permission to read your health records from Apple Health.</string>
</dict>
</plist>

In Xcode, ensure the HealthKit capability is enabled in your application target's Signing & Capabilities tab (with Clinical Health Records if applicable).


2. Android (Health Connect)

A. Query Declaration & Permissions Rationale

Add the following to your AndroidManifest.xml:

<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

<application ...>
    <!-- Android 13 and below: Rationale activity for Health Connect -->
    <activity
        android:name=".PermissionsRationaleActivity"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
        </intent-filter>
    </activity>

    <!-- Android 14+: Rationale activity alias for Health Connect -->
    <activity-alias
        android:name="ViewPermissionUsageActivity"
        android:exported="true"
        android:permission="android.permission.START_VIEW_PERMISSION_USAGE"
        android:targetActivity=".PermissionsRationaleActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
            <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
        </intent-filter>
    </activity-alias>
</application>

Tip

KHealth automatically initializes its Android context via a built-in ContentProvider. No manual context passing or initialise() calls are needed!

B. Declare Required Health Connect Permissions

Add the permissions matching the data types your app accesses:

Type Manifest Permissions
ACTIVE_CALORIES_BURNED android.permission.health.READ_ACTIVE_CALORIES_BURNED
android.permission.health.WRITE_ACTIVE_CALORIES_BURNED
BASAL_METABOLIC_RATE android.permission.health.READ_BASAL_METABOLIC_RATE
android.permission.health.WRITE_BASAL_METABOLIC_RATE
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
android.permission.health.WRITE_BODY_FAT
BODY_TEMPERATURE android.permission.health.READ_BODY_TEMPERATURE
android.permission.health.WRITE_BODY_TEMPERATURE
BODY_WATER_MASS android.permission.health.READ_BODY_WATER_MASS
android.permission.health.WRITE_BODY_WATER_MASS
BONE_MASS android.permission.health.READ_BONE_MASS
android.permission.health.WRITE_BONE_MASS
CERVICAL_MUCUS android.permission.health.READ_CERVICAL_MUCUS
android.permission.health.WRITE_CERVICAL_MUCUS
DISTANCE android.permission.health.READ_DISTANCE
android.permission.health.WRITE_DISTANCE
ELEVATION_GAINED android.permission.health.READ_ELEVATION_GAINED
android.permission.health.WRITE_ELEVATION_GAINED
EXERCISE android.permission.health.READ_EXERCISE
android.permission.health.WRITE_EXERCISE
FLOORS_CLIMBED android.permission.health.READ_FLOORS_CLIMBED
android.permission.health.WRITE_FLOORS_CLIMBED
HEART_RATE android.permission.health.READ_HEART_RATE
android.permission.health.WRITE_HEART_RATE
HEART_RATE_VARIABILITY android.permission.health.READ_HEART_RATE_VARIABILITY
android.permission.health.WRITE_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
INTERMENSTRUAL_BLEEDING android.permission.health.READ_INTERMENSTRUAL_BLEEDING
android.permission.health.WRITE_INTERMENSTRUAL_BLEEDING
LEAN_BODY_MASS android.permission.health.READ_LEAN_BODY_MASS
android.permission.health.WRITE_LEAN_BODY_MASS
MENSTRUATION android.permission.health.READ_MENSTRUATION
android.permission.health.WRITE_MENSTRUATION
NUTRITION android.permission.health.READ_NUTRITION
android.permission.health.WRITE_NUTRITION
OVULATION_TEST android.permission.health.READ_OVULATION_TEST
android.permission.health.WRITE_OVULATION_TEST
OXYGEN_SATURATION android.permission.health.READ_OXYGEN_SATURATION
android.permission.health.WRITE_OXYGEN_SATURATION
POWER android.permission.health.READ_POWER
android.permission.health.WRITE_POWER
RESPIRATORY_RATE android.permission.health.READ_RESPIRATORY_RATE
android.permission.health.WRITE_RESPIRATORY_RATE
RESTING_HEART_RATE android.permission.health.READ_RESTING_HEART_RATE
android.permission.health.WRITE_RESTING_HEART_RATE
SEXUAL_ACTIVITY android.permission.health.READ_SEXUAL_ACTIVITY
android.permission.health.WRITE_SEXUAL_ACTIVITY
SLEEP android.permission.health.READ_SLEEP
android.permission.health.WRITE_SLEEP
SPEED android.permission.health.READ_SPEED
android.permission.health.WRITE_SPEED
STEPS android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS
VO2_MAX android.permission.health.READ_VO2_MAX
android.permission.health.WRITE_VO2_MAX
WEIGHT android.permission.health.READ_WEIGHT
android.permission.health.WRITE_WEIGHT
WHEELCHAIR_PUSHES android.permission.health.READ_WHEELCHAIR_PUSHES
android.permission.health.WRITE_WHEELCHAIR_PUSHES

πŸ“– Usage Guide

1. Instantiate

Instantiate KHealth directly in your shared multiplatform code (e.g., in a ViewModel, Repository, or Dependency Injection module):

// In commonMain (KMP / Compose Multiplatform)
val kHealth = KHealth()

Note

On Android, if your application needs to prompt the user with permission dialogs via requestPermissions(), bind your active ComponentActivity:

// Option A: Bind activity to an existing instance
kHealth.bindActivity(activity)

// Option B: Construct with activity in Android source set
val kHealth = KHealth(activity)

2. Check Permissions

Check current permission states without prompting the user:

val permissions: Set<KHPermission> = kHealth.checkPermissions(
    KHPermission.ActiveCaloriesBurned(read = true, write = true),
    KHPermission.HeartRate(read = true, write = false),
)

You can also pass an Iterable<KHPermission>:

val permissionList = listOf(
    KHPermission.StepCount(read = true, write = false),
    KHPermission.Weight(read = true, write = true),
)
val permissions = kHealth.checkPermissions(permissionList)

3. Request Permissions

Request access from the user:

val permissions: Set<KHPermission> = kHealth.requestPermissions(
    KHPermission.ActiveCaloriesBurned(read = true, write = true),
    KHPermission.HeartRate(read = true, write = false),
)

4. Verify Permission Status

KHealth provides intuitive extension functions to verify granted permissions:

// Check if a specific permission is granted with the requested read/write access
val canWriteCalories: Boolean = permissions.isGranted(
    KHPermission.ActiveCaloriesBurned(read = false, write = true)
)

// Check if all requested permissions in the response are granted
val allGranted: Boolean = permissions.allGranted()

// Query KHealth directly at any time
val canReadHeartRate: Boolean = kHealth.hasPermission(
    KHPermission.HeartRate(read = true, write = false)
)

5. Write Records

Write one or more health records using type-safe constructors:

import kotlinx.datetime.Clock
import kotlin.time.Duration.Companion.minutes

val response: KHWriteResponse = kHealth.writeRecords(
    KHRecord.ActiveCaloriesBurned(
        unit = KHUnit.Energy.KiloCalorie,
        value = 145.0,
        startTime = Clock.System.now().minus(30.minutes),
        endTime = Clock.System.now(),
    ),
    KHRecord.HeartRate(
        samples = listOf(
            KHHeartRateSample(
                beatsPerMinute = 126,
                time = Clock.System.now().minus(10.minutes),
            ),
            KHHeartRateSample(
                beatsPerMinute = 132,
                time = Clock.System.now().minus(5.minutes),
            ),
        ),
    ),
    KHRecord.BasalMetabolicRate(
        unit = KHUnit.Energy.KiloCalorie,
        value = 1600.0,
        time = Clock.System.now(),
    ),
)

when (response) {
    is KHWriteResponse.Success -> println("All records written successfully βœ…")
    is KHWriteResponse.SomeFailed -> println("Some records failed to write ⚠️")
    is KHWriteResponse.Failed -> println("Write failed: ${response.throwable} ❌")
}

6. Read Records (Type-Safe Generics)

Reading records is fully generic and type-safe. The returned list matches the exact record type requestedβ€”no manual casting needed!

import kotlinx.datetime.Clock
import kotlin.time.Duration.Companion.days

// Returns List<KHRecord.HeartRate>
val heartRateRecords = kHealth.readRecords(
    KHReadRequest.HeartRate(
        startTime = Clock.System.now().minus(7.days),
        endTime = Clock.System.now(),
    )
)

heartRateRecords.forEach { record ->
    record.samples.forEach { sample ->
        println("BPM: ${sample.beatsPerMinute} at ${sample.time}")
    }
}

// Returns List<KHRecord.StepCount>
val stepRecords = kHealth.readRecords(
    KHReadRequest.StepCount(
        startTime = Clock.System.now().minus(1.days),
        endTime = Clock.System.now(),
    )
)

val totalSteps = stepRecords.sumOf { it.count }
println("Total steps today: $totalSteps")

πŸ“Š Supported Data Types

Type Android Apple (iOS & watchOS) Notes / Units
ActiveCaloriesBurned βœ… βœ… Energy (Calorie, KiloCalorie, Joule, KiloJoule)
BasalMetabolicRate βœ… βœ… Energy per day (Calorie, KiloCalorie, Joule, KiloJoule)
BloodGlucose βœ… βœ… MilliMolesPerLiter, MilliGramsPerDeciLiter
BloodPressure βœ… βœ… MillimetersOfMercury (Systolic & Diastolic)
BodyFat βœ… βœ… Percentage
BodyTemperature βœ… βœ… Celsius, Fahrenheit
BodyWaterMass βœ… Kilogram, Gram, Milligram, Pound, Ounce
BoneMass βœ… Kilogram, Gram, Milligram, Pound, Ounce
CervicalMucus βœ… βœ… Sensation & appearance states
CyclingPedalingCadence βœ… Revolutions per minute
Distance βœ… βœ… Meter, Kilometer, Mile, Foot, Inch
ElevationGained βœ… Meter, Kilometer, Mile, Foot, Inch
Exercise βœ… βœ… Supports 70+ exercise/workout categories
FloorsClimbed βœ… βœ… Floor count
HeartRate βœ… βœ… Samples with BPM and timestamps
HeartRateVariability βœ… βœ… RMSSD in milliseconds
Height βœ… βœ… Meter, Kilometer, Mile, Foot, Inch
Hydration βœ… βœ… Liter, MilliLiter, FluidOunceUs
IntermenstrualBleeding βœ… βœ… Spotting records
LeanBodyMass βœ… βœ… Kilogram, Gram, Milligram, Pound, Ounce
MenstruationPeriod βœ… Menstruation period sessions
MenstruationFlow βœ… βœ… Light, Medium, Heavy, Unspecified
Nutrition βœ… βœ… Macros (Protein, Carbs, Fat) & Micronutrients
OvulationTest βœ… βœ… Inconclusive, Negative, Positive, High, etc.
OxygenSaturation βœ… βœ… Blood oxygen percentage
Power βœ… βœ… Watt, KiloWatt
RespiratoryRate βœ… βœ… Breaths per minute
RestingHeartRate βœ… βœ… Beats per minute
SexualActivity βœ… βœ… Protection used / unspecified
SleepSession βœ… βœ… Sleep stages (Awake, Light, Deep, REM, etc.)
Speed βœ… MetersPerSecond, KilometersPerHour, MilesPerHour
RunningSpeed βœ… MetersPerSecond, KilometersPerHour, MilesPerHour
CyclingSpeed βœ… MetersPerSecond, KilometersPerHour, MilesPerHour
StepCount βœ… βœ… Step counts over time ranges
Vo2Max βœ… βœ… MillilitersPerMinutePerKilogram
Weight βœ… βœ… Kilogram, Gram, Milligram, Pound, Ounce
WheelchairPushes βœ… βœ… Wheelchair push counts

πŸƒ Supported Exercise Types

KHealth supports reading and writing extensive exercise and workout types:

Type Android Apple (iOS & watchOS) Type Android Apple (iOS & watchOS)
AmericanFootball βœ… βœ… MartialArts βœ… βœ…
Archery βœ… MindAndBody βœ…
AustralianFootball βœ… βœ… MixedCardio βœ…
Badminton βœ… βœ… MixedMetabolicCardioTraining βœ…
Barre βœ… Other βœ… βœ…
Baseball βœ… βœ… PaddleSports βœ…
Basketball βœ… βœ… Paddling βœ… βœ…
Biking βœ… βœ… Paragliding βœ… βœ…
BikingStationary βœ… βœ… Pickleball βœ…
BootCamp βœ… βœ… Pilates βœ… βœ…
Bowling βœ… Play βœ…
Boxing βœ… βœ… PreparationAndRecovery βœ…
Calisthenics βœ… βœ… Racquetball βœ… βœ…
CardioDance βœ… RockClimbing βœ… βœ…
Climbing βœ… RollerHockey βœ… βœ…
Cooldown βœ… Rowing βœ… βœ…
CoreTraining βœ… RowingMachine βœ… βœ…
Cricket βœ… βœ… Rugby βœ… βœ…
CrossCountrySkiing βœ… Running βœ… βœ…
CrossTraining βœ… RunningTreadmill βœ… βœ…
Curling βœ… Sailing βœ… βœ…
Cycling βœ… ScubaDiving βœ… βœ…
Dance βœ… Skating βœ… βœ…
DanceInspiredTraining βœ… SkatingSports βœ…
Dancing βœ… βœ… Skiing βœ… βœ…
DiscSports βœ… SnowSports βœ…
DownhillSkiing βœ… Snowboarding βœ… βœ…
Elliptical βœ… βœ… Snowshoeing βœ… βœ…
EquestrianSports βœ… Soccer βœ… βœ…
ExerciseClass βœ… βœ… SocialDance βœ…
Fencing βœ… βœ… Softball βœ… βœ…
Fishing βœ… Squash βœ… βœ…
FitnessGaming βœ… StairClimbing βœ… βœ…
Flexibility βœ… StairClimbingMachine βœ… βœ…
FrisbeeDisc βœ… Stairs βœ…
FunctionalStrengthTraining βœ… StepTraining βœ…
Golf βœ… βœ… StrengthTraining βœ… βœ…
GuidedBreathing βœ… βœ… Stretching βœ… βœ…
Gymnastics βœ… βœ… Surfing βœ… βœ…
HandCycling βœ… SurfingSports βœ…
Handball βœ… βœ… SwimBikeRun βœ…
HighIntensityIntervalTraining βœ… βœ… Swimming βœ…
Hiking βœ… βœ… SwimmingOpenWater βœ…
Hockey βœ… SwimmingPool βœ…
Hunting βœ… TableTennis βœ… βœ…
IceHockey βœ… βœ… TaiChi βœ…
IceSkating βœ… βœ… Tennis βœ… βœ…
JumpRope βœ… TrackAndField βœ…
Kickboxing βœ… TraditionalStrengthTraining βœ…
Lacrosse βœ… Transition βœ…
UnderwaterDiving βœ… Volleyball βœ… βœ…
Walking βœ… βœ… WaterFitness βœ…
WaterPolo βœ… βœ… WaterSports βœ…
Weightlifting βœ… βœ… Wheelchair βœ… βœ…
WheelchairRunPace βœ… WheelchairWalkPace βœ…
Wrestling βœ… Yoga βœ… βœ…

Note

Types unsupported by a specific platform are safely ignored.


πŸ—οΈ Project Architecture

KHealth/
β”œβ”€β”€ khealth/                  # Core KMP library module
β”‚   β”œβ”€β”€ commonMain/           # Interfaces (KHealth), data models, permissions, requests
β”‚   β”œβ”€β”€ androidMain/          # Health Connect integration, auto-init provider, mappers
β”‚   └── appleMain/            # HealthKit integration (iOS & watchOS), mappers, readers, writers
└── sampleApps/               # Sample demonstration apps
    β”œβ”€β”€ shared/               # Shared KMP module with health repository & operations
    β”œβ”€β”€ android/              # Native Android app (Jetpack Compose)
    └── apple/                # Native Apple apps (SwiftUI iOS & watchOS)

🀝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a Pull Request.


πŸ“„ License

This library is licensed under the Apache 2.0 License. See the LICENSE file for details.

About

A Kotlin Multiplatform wrapper for Android's Health Connect and Apple's HealthKit πŸ₯

Topics

Resources

Stars

85 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages