Platform Notes

iOS

• HealthKit requires a real device (not simulator) for most data types
• RequestPermissions on iOS does NOT tell you if the user denied access (Apple privacy policy) — it may return true even when denied
• Percentage values (body fat, O2 saturation) are returned as 0–100, not 0–1
• Your app requires a provisioning profile with HealthKit capabilities enabled
• Observe uses HKAnchoredObjectQuery for push-based real-time delivery — no polling needed
• Menstruation flow uses HKCategoryType.MenstrualFlow; the MenstruationFlowResult.IsCycleStart flag maps to the HKMetadataKeyMenstrualCycleStart sample metadata, and the MenstrualFlow.None level is supported
• Heart rate variability uses HKQuantityTypeIdentifier.HeartRateVariabilitySDNN (SDNN, in ms)
• Speed maps to WalkingSpeed and Power maps to CyclingPower (HealthKit has no generic speed/power types)
• Workouts use HKWorkout with WorkoutType mapped to HKWorkoutActivityType; nutrition is written as an HKCorrelation of type Food containing the individual dietary quantity samples
• Sexual activity protection is stored via the HKMetadataKeySexualActivityProtectionUsed metadata key

Android

• The Health Connect app must be installed on the device
• Minimum SDK version must be 28 (Android 9) or higher
• Body fat percentage and oxygen saturation use individual record queries (Health Connect does not provide aggregate metrics for these types)
• Observe uses Health Connect change tokens with polling (default 5 seconds) — Health Connect does not support push-based observation
• Menstruation flow uses the MenstruationFlowRecord with the android.permission.health.READ_MENSTRUATION / WRITE_MENSTRUATION permissions. There is no None flow value (written as Unspecified), and IsCycleStart is ignored — Health Connect models the period span as a separate MenstruationPeriodRecord
• Heart rate variability uses HeartRateVariabilityRmssdRecord (RMSSD, in ms) — a different computation than iOS’s SDNN, so the values are not directly comparable
• Each new type needs its own permission, e.g. READ_BLOOD_GLUCOSE, READ_VO2_MAX, READ_EXERCISE (workouts), READ_NUTRITION, READ_SEXUAL_ACTIVITY (and the WRITE_… equivalents) — declare them in AndroidManifest.xml
• Instantaneous records without aggregate metrics (blood glucose, body/basal temperature, respiratory rate, VO2 max, HRV, lean body mass) are read with ReadRecords and bucketed in-memory, like body fat and oxygen saturation
• Workouts use ExerciseSessionRecord; its WorkoutResult energy and distance are null on read because Health Connect stores those as separate ActiveCaloriesBurnedRecord / DistanceRecord entries
• BasalEnergyBurned is derived from BasalMetabolicRateRecord (a rate); on write the value is treated as kcal/day