Installation

This page covers the dependency, initialization and permission requests. Platform-specific configuration is described in Android setup and iOS setup.

1. Add the dependency

   pub.devLocal path

   flutter pub add health

   # pubspec.yaml
   dependencies:
     health:
       path: ../carp-health-flutter  # or use your published package source

   If you use a published version instead of the local path, replace the path with the appropriate version constraint.

2. Initialize the plugin

   Call configure() once, before you use any other method:

   import 'package:health/health.dart';
   
   final health = Health();
   
   Future<void> bootstrap() async {
     // Must be called once before using any methods
     await health.configure();
   }

   configure() resolves a stable device identifier and registers JSON factories. For testing, you can pass a custom DeviceInfoPlugin to Health().

3. Request permissions when needed

   Check which permissions are granted and request the missing ones:

   final types = [
     HealthDataType.STEPS,
     HealthDataType.HEART_RATE,
     HealthDataType.WEIGHT,
   ];
   
   final permissions = types.map((t) => HealthDataAccess.READ_WRITE).toList();
   
   final hasPerms = await health.hasPermissions(types, permissions: permissions);
   if (hasPerms != true) {
     final ok = await health.requestAuthorization(types, permissions: permissions);
     if (!ok) {
       // Show guidance to user
     }
   }

   The plugin validates each type and access combination and throws an ArgumentError for illegal combinations:

   • On iOS, some types support READ only.
   • On Android, WRITE is not allowed for certain ECG-related event types.

   See Permissions for the full permission model.

4. Configure each platform

   • Android: declare Health Connect permissions in AndroidManifest.xml, request activity recognition, optionally enable history and background access, and handle the Health Connect install flow.
   • iOS: enable the HealthKit capability and add NSHealthShareUsageDescription and NSHealthUpdateUsageDescription to Info.plist.

Next steps