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.
- π Zero-Boilerplate Instantiation: Call
val kHealth = KHealth()directly incommonMainacross Android, iOS, and watchOS. - π€ Android Auto-Initialization: Automatically initializes Health Connect via
ContentProvider. No manualinitialise()call or AndroidContextrequired in shared code. - π― Type-Safe Generic Reads:
readRecords(KHReadRequest.HeartRate(...))directly returnsList<KHRecord.HeartRate>without type casting or runtime checks. - π‘οΈ Ergonomic Permissions API: Check, request, and verify permissions with expressive extensions like
perms.isGranted(...),perms.allGranted(), andkHealth.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).
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.
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)
}
}
}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).
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!
Add the permissions matching the data types your app accesses:
| Type | Manifest Permissions |
|---|---|
| ACTIVE_CALORIES_BURNED | android.permission.health.READ_ACTIVE_CALORIES_BURNEDandroid.permission.health.WRITE_ACTIVE_CALORIES_BURNED |
| BASAL_METABOLIC_RATE | android.permission.health.READ_BASAL_METABOLIC_RATEandroid.permission.health.WRITE_BASAL_METABOLIC_RATE |
| BLOOD_GLUCOSE | android.permission.health.READ_BLOOD_GLUCOSEandroid.permission.health.WRITE_BLOOD_GLUCOSE |
| BLOOD_PRESSURE | android.permission.health.READ_BLOOD_PRESSUREandroid.permission.health.WRITE_BLOOD_PRESSURE |
| BODY_FAT | android.permission.health.READ_BODY_FATandroid.permission.health.WRITE_BODY_FAT |
| BODY_TEMPERATURE | android.permission.health.READ_BODY_TEMPERATUREandroid.permission.health.WRITE_BODY_TEMPERATURE |
| BODY_WATER_MASS | android.permission.health.READ_BODY_WATER_MASSandroid.permission.health.WRITE_BODY_WATER_MASS |
| BONE_MASS | android.permission.health.READ_BONE_MASSandroid.permission.health.WRITE_BONE_MASS |
| CERVICAL_MUCUS | android.permission.health.READ_CERVICAL_MUCUSandroid.permission.health.WRITE_CERVICAL_MUCUS |
| DISTANCE | android.permission.health.READ_DISTANCEandroid.permission.health.WRITE_DISTANCE |
| ELEVATION_GAINED | android.permission.health.READ_ELEVATION_GAINEDandroid.permission.health.WRITE_ELEVATION_GAINED |
| EXERCISE | android.permission.health.READ_EXERCISEandroid.permission.health.WRITE_EXERCISE |
| FLOORS_CLIMBED | android.permission.health.READ_FLOORS_CLIMBEDandroid.permission.health.WRITE_FLOORS_CLIMBED |
| HEART_RATE | android.permission.health.READ_HEART_RATEandroid.permission.health.WRITE_HEART_RATE |
| HEART_RATE_VARIABILITY | android.permission.health.READ_HEART_RATE_VARIABILITYandroid.permission.health.WRITE_HEART_RATE_VARIABILITY |
| HEIGHT | android.permission.health.READ_HEIGHTandroid.permission.health.WRITE_HEIGHT |
| HYDRATION | android.permission.health.READ_HYDRATIONandroid.permission.health.WRITE_HYDRATION |
| INTERMENSTRUAL_BLEEDING | android.permission.health.READ_INTERMENSTRUAL_BLEEDINGandroid.permission.health.WRITE_INTERMENSTRUAL_BLEEDING |
| LEAN_BODY_MASS | android.permission.health.READ_LEAN_BODY_MASSandroid.permission.health.WRITE_LEAN_BODY_MASS |
| MENSTRUATION | android.permission.health.READ_MENSTRUATIONandroid.permission.health.WRITE_MENSTRUATION |
| NUTRITION | android.permission.health.READ_NUTRITIONandroid.permission.health.WRITE_NUTRITION |
| OVULATION_TEST | android.permission.health.READ_OVULATION_TESTandroid.permission.health.WRITE_OVULATION_TEST |
| OXYGEN_SATURATION | android.permission.health.READ_OXYGEN_SATURATIONandroid.permission.health.WRITE_OXYGEN_SATURATION |
| POWER | android.permission.health.READ_POWERandroid.permission.health.WRITE_POWER |
| RESPIRATORY_RATE | android.permission.health.READ_RESPIRATORY_RATEandroid.permission.health.WRITE_RESPIRATORY_RATE |
| RESTING_HEART_RATE | android.permission.health.READ_RESTING_HEART_RATEandroid.permission.health.WRITE_RESTING_HEART_RATE |
| SEXUAL_ACTIVITY | android.permission.health.READ_SEXUAL_ACTIVITYandroid.permission.health.WRITE_SEXUAL_ACTIVITY |
| SLEEP | android.permission.health.READ_SLEEPandroid.permission.health.WRITE_SLEEP |
| SPEED | android.permission.health.READ_SPEEDandroid.permission.health.WRITE_SPEED |
| STEPS | android.permission.health.READ_STEPSandroid.permission.health.WRITE_STEPS |
| VO2_MAX | android.permission.health.READ_VO2_MAXandroid.permission.health.WRITE_VO2_MAX |
| WEIGHT | android.permission.health.READ_WEIGHTandroid.permission.health.WRITE_WEIGHT |
| WHEELCHAIR_PUSHES | android.permission.health.READ_WHEELCHAIR_PUSHESandroid.permission.health.WRITE_WHEELCHAIR_PUSHES |
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)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)Request access from the user:
val permissions: Set<KHPermission> = kHealth.requestPermissions(
KHPermission.ActiveCaloriesBurned(read = true, write = true),
KHPermission.HeartRate(read = true, write = false),
)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)
)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} β")
}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")| 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 |
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.
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)
Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
This library is licensed under the Apache 2.0 License. See the LICENSE file for details.
