health_connector

Unified, type-safe health data access for Flutter — a single API to read, write, delete, and aggregate health metrics across iOS HealthKit and Android Health Connect.

📖 Table of Contents

Getting Started

• 🎯 Requirements
• 📦 Installation
• ⚡ Quick Start
• 🔍 Exploring SDK using Health Connector Toolbox
• 📚 Core Concepts

Features

• ⚙️ Feature Management
• 🔐 Permission Management
• 📖 Reading Health Data
• ✍️ Writing Health Data
• 🔄 Updating Health Records
• 🗑️ Deleting Health Records
• ➕ Aggregating Health Data

Additional Information

• 🎯 Real-World Use Cases
• ⚠️ Error Handling
• 🔧 Troubleshooting
• ❓ FAQ

Reference

• 📋 Supported Health Data Types
• 📋 API Reference
• 📈 Migration Guides

Resources

• 🤝 Contributing
• 📄 License
• 📝 Changelog

🎯 Requirements

📦 Installation

Step 1: Add the Package

flutter pub add health_connector

Or add manually to pubspec.yaml:

dependencies:
  health_connector: ^1.4.0

Step 2: Platform Setup

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <!-- Your existing configuration -->

        <!-- Health Connect intent filter for showing permissions rationale -->
        <activity-alias
            android:name="ViewPermissionUsageActivity"
            android:exported="true"
            android:targetActivity=".MainActivity"
            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
            <intent-filter>
                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
            </intent-filter>
        </activity-alias>
    </application>

    <!-- Declare Health Connect permissions for each data type you use -->
    <!-- Read permissions -->
    <uses-permission android:name="android.permission.health.READ_STEPS" />
    <uses-permission android:name="android.permission.health.READ_WEIGHT" />
    <uses-permission android:name="android.permission.health.READ_HEART_RATE" />
    
    <!-- Write permissions -->
    <uses-permission android:name="android.permission.health.WRITE_STEPS" />
    <uses-permission android:name="android.permission.health.WRITE_WEIGHT" />
    <uses-permission android:name="android.permission.health.WRITE_HEART_RATE" />

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

<dict>
    <!-- Existing keys -->

    <!-- Required: Describe why your app reads health data -->
    <key>NSHealthShareUsageDescription</key>
    <string>This app needs to read your health data to provide personalized insights.</string>

    <!-- Required: Describe why your app writes health data -->
    <key>NSHealthUpdateUsageDescription</key>
    <string>This app needs to save health data to track your progress.</string>
</dict>

⚡ Quick Start

Get health data flowing in under 5 minutes:

import 'package:health_connector/health_connector.dart';

Future<void> quickStart() async {
  // 1. Check platform availability
  final status = await HealthConnector.getHealthPlatformStatus();
  if (status != HealthPlatformStatus.available) {
    print('Health platform not available: $status');
    return;
  }

  // 2. Create connector instance
  final connector = await HealthConnector.create(
    HealthConnectorConfig(isLoggerEnabled: true),
  );

  // 3. Request permissions for steps
  final results = await connector.requestPermissions([
    HealthDataType.steps.readPermission,
    HealthDataType.steps.writePermission,
  ]);

  // 4. Check if write permission was granted
  final writeGranted = results.any((r) =>
      r.permission == HealthDataType.steps.writePermission &&
      r.status == PermissionStatus.granted);

  if (!writeGranted) {
    print('Write permission not granted');
    return;
  }

  // 5. Read today's step records
  final response = await connector.readRecords(
    HealthDataType.steps.readInTimeRange(
      startTime: DateTime.now().subtract(Duration(days: 1)),
      endTime: DateTime.now(),
    ),
  );

  for (final record in response.records) {
    print('Steps: ${record.count.value} (${record.startTime} - ${record.endTime})');
  }

  // 6. Write a new step record
  final newRecord = StepsRecord(
    id: HealthRecordId.none, // Always use .none for new records
    startTime: DateTime.now().subtract(Duration(hours: 1)),
    endTime: DateTime.now(),
    count: Numeric(1500),
    metadata: Metadata.automaticallyRecorded(
      device: Device.fromType(DeviceType.phone),
    ),
  );

  try {
    final recordId = await connector.writeRecord(newRecord);
    print('Record written with ID: $recordId');
  } on NotAuthorizedException catch (e) {
    print('Permission denied: ${e.message}');
  } on HealthConnectorException catch (e) {
    print('Error: ${e.message}');
  }
}

🔍 Exploring the SDK Features with Health Connector Toolbox

Permission Request	Read Data	Write Data	Delete Data	Aggregate Data

To explore the SDK's capabilities hands-on, you can use the Health Connector Toolbox example app included in the repository. The toolbox app was created to showcase the SDK's features and is used internally for manual testing purposes.

Note: The toolbox is intended as a demonstration and testing tool only. It is not recommended as a reference for building production applications.

What the Toolbox Offers

• Interactive demonstrations of core SDK features
• Permission management UI examples
• Read, write, update, and delete operations
• Data aggregation examples
• Visual representation of health records

Running the Toolbox

# Clone the repository
git clone https://github.com/fam-tung-lam/health_connector.git
cd health_connector

# Navigate to the toolbox app
cd examples/health_connector_toolbox

# Install dependencies
flutter pub get

# Run on your device
flutter run

📚 Core Concepts

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Your Flutter App                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      health_connector                       │
│                (Unified cross-platform API)                 │
└─────────────────────────────────────────────────────────────┘
            │                                  │
            ▼                                  ▼
┌─────────────────────────┐     ┌─────────────────────────────┐
│ health_connector_hk_ios │     │ health_connector_hc_android │
│     (Apple HealthKit)   │     │    (Android Health Connect) │
└─────────────────────────┘     └─────────────────────────────┘

Key Types

Request-Response Pattern

The SDK uses a request-response pattern for read, aggregate, and delete operations. This design abstracts the significant API differences between Health Connect and HealthKit, providing you with a consistent interface regardless of the underlying platform.

How It Works

Instead of calling methods directly with raw parameters, you create strongly-typed request objects through the HealthDataType class:

// Reading records: Create request via HealthDataType
final readRequest = HealthDataType.steps.readInTimeRange(
  startTime: DateTime.now().subtract(Duration(days: 7)),
  endTime: DateTime.now(),
);
final response = await connector.readRecords(readRequest);

// Aggregating data: Create request via HealthDataType
final aggregateRequest = HealthDataType.steps.aggregateSum(
  startTime: DateTime.now().subtract(Duration(days: 1)),
  endTime: DateTime.now(),
);
final aggregateResponse = await connector.aggregate(aggregateRequest);

// Deleting records: Create request via HealthDataType
final deleteRequest = HealthDataType.steps.deleteByIds([recordId]);
await connector.deleteRecords(deleteRequest);

Why This Pattern?

Health Connect and HealthKit have fundamentally different APIs.

The request-response pattern solves this by:

1. Encapsulating platform logic — The SDK translates your request into the appropriate platform-specific API calls
2. Type safety — Each HealthDataType only exposes the operations it supports (e.g., aggregateSum() is only available on types that support sum aggregation)
3. Validation — Requests validate parameters at creation time, catching errors early

Write and Update Operations

Write and update operations do not use the request-response pattern. This is because:

• Write operations have consistent APIs across both platforms — both accept health record objects
• Update operations are only supported on Android Health Connect, because iOS HealthKit uses the immutable data model.

Type-Safe Generics

The SDK leverages Dart generics to provide compile-time type safety. Each HealthDataType is parameterized with its corresponding HealthRecord type and MeasurementUnit, ensuring the correct types flow through all operations automatically.

// HealthDataType.weight is defined as `HealthDataType<WeightRecord, Mass>`
// This means:
//   - Read operations return `WeightRecord` (not a generic `HealthRecord`)
//   - Aggregation returns `Mass` (the measurement unit for weight)

// The compiler automatically infers the correct record type
final request = HealthDataType.weight.readInTimeRange(
  startTime: start,
  endTime: end,
);
// request is `ReadRecordsInTimeRangeRequest<WeightRecord>`

final response = await connector.readRecords(request);
// response.records is `List<WeightRecord>`, not `List<HealthRecord>`

// You can directly access `WeightRecord`-specific properties without casting
for (final record in response.records) {
  print('Steps: ${record.weight.value}'); // ✅ No cast needed
}

// Same for aggregation - the measurement unit is inferred
final avgRequest = HealthDataType.weight.aggregateAvg(
  startTime: start,
  endTime: end,
);
// `avgRequest` is `AggregateRequest<WeightRecord, Mass>`

final avgWeight = await connector.aggregate(avgRequest);
// `avgWeight` is `Mass`, not `MeasurementUnit`
print('Total steps: ${total.value}'); // ✅ Correct type automatically

This generic approach means:

• No runtime type casting — The compiler knows the exact record and unit types
• IDE autocompletion — Your IDE suggests the correct properties for each record type
• Compile-time errors — Type mismatches are caught before your app runs

🧑‍💻 Usage

⚙️ Feature Management

Platform features (such as background health data reading) have different availability characteristics across platforms.

Platform Differences

iOS HealthKit

• All features are available and granted by default
• When checking feature status with getFeatureStatus(), the SDK always returns HealthPlatformFeatureStatus.available
• When requesting feature permissions with requestPermissions(), the SDK always returns PermissionStatus.granted
• No additional user action is required for feature access

Android Health Connect

• Feature availability depends on Android version and Health Connect SDK version
• Some features require specific minimum versions, f.e. background health data reading requires Health Connect SDK v1.1.0-alpha04
• Feature status must be checked before requesting permissions

Checking Feature Availability

// Check if background reading is available
final status = await connector.getFeatureStatus(
  HealthPlatformFeature.readHealthDataInBackground,
);

if (status == HealthPlatformFeatureStatus.available) {
  // Feature is supported - safe to request permission
  await connector.requestPermissions([
    HealthPlatformFeature.readHealthDataInBackground.permission,
  ]);
} else {
  // Feature not available on this device/version
  print('Background reading not available');
  // Implement fallback or disable feature in UI
}

Feature Permission Status

When checking the status of a feature permission:

final permissionStatus = await connector.getPermissionStatus(
  HealthPlatformFeature.readHealthDataInBackground.permission,
);

// On iOS: Always returns PermissionStatus.granted
// On Android: Returns actual status (granted/denied)

🔐 Permission Management

Request Permissions

iOS Privacy Note: Read permissions always return PermissionStatus.unknown on iOS. This is intentional—Apple prevents apps from detecting whether users have health data by checking permission status.

final permissions = [
  // Data permissions
  HealthDataType.steps.readPermission,
  HealthDataType.steps.writePermission,
  HealthDataType.weight.readPermission,
  HealthDataType.weight.writePermission,
  
  // Feature permissions
  HealthPlatformFeature.readHealthDataInBackground.permission,
];

final results = await connector.requestPermissions(permissions);

for (final result in results) {
  print('${result.permission}: ${result.status}');
}

Check Individual Permission Status

final status = await connector.getPermissionStatus(
  HealthDataType.steps.readPermission,
);

switch (status) {
  case PermissionStatus.granted:
    print('Permission granted');
  case PermissionStatus.denied:
    print('Permission denied');
  case PermissionStatus.unknown:
    print('Cannot determine (iOS read permission)');
}

Get All Granted Permissions (Android Health Connect Only)

iOS Privacy Note: This API is not available on iOS. HealthKit does not provide a way to query all granted permissions to protect user privacy. Apps cannot enumerate what health data access they have been granted.

try {
  final grantedPermissions = await connector.getGrantedPermissions();
  for (final permission in grantedPermissions) {
    if (permission is HealthDataPermission) {
      print('${permission.dataType} (${permission.accessType})');
    }
  }
} on UnsupportedOperationException {
  print('Only available on Android');
}

Revoke All Permissions (Android Health Connect Only)

iOS Privacy Note: This API is not available on iOS. HealthKit requires users to manually revoke permissions through the iOS Settings app. This ensures users have full control and visibility over their health data permissions.

try {
  await connector.revokeAllPermissions();
} on UnsupportedOperationException {
  print('Only available on Android');
}

📖 Reading Health Data

Platform Note - Historical Data Access:

Android Health Connect
By default, Health Connect only provides access to the last 30 days of historical health data. To read data older than 30 days, the HealthPlatformFeature.readHealthDataHistory feature must be available and its permission must be granted.

iOS HealthKit
HealthKit has no default limitation on historical data access. Apps can read health data from any time period, subject only to user permission.

Read by ID

final recordId = HealthRecordId('existing-record-id');
final request = HealthDataType.steps.readRecord(recordId);
final record = await connector.readRecord(request);

if (record != null) {
  print('Steps: ${record.count.value}');
} else {
  print('Record not found');
}

Read Multiple Records

final request = HealthDataType.steps.readInTimeRange(
  startTime: DateTime.now().subtract(Duration(days: 7)),
  endTime: DateTime.now(),
  pageSize: 100,
);

final response = await connector.readRecords(request);

for (final record in response.records) {
  print('Steps: ${record.count.value} (${record.startTime} - ${record.endTime})');
}

Pagination

var request = HealthDataType.steps.readInTimeRange(
  startTime: DateTime.now().subtract(Duration(days: 30)),
  endTime: DateTime.now(),
  pageSize: 100,
);

final allRecords = <StepsRecord>[];

while (true) {
  final response = await connector.readRecords(request);
  allRecords.addAll(response.records.cast<StepsRecord>());

  if (response.nextPageRequest == null) break;
  request = response.nextPageRequest!;
}

print('Total records: ${allRecords.length}');

✍️ Writing Health Data

Write Single Record

final stepRecord = StepsRecord(
  id: HealthRecordId.none, // Must be .none for new records
  startTime: DateTime.now().subtract(Duration(hours: 1)),
  endTime: DateTime.now(),
  count: Numeric(5000),
  metadata: Metadata.automaticallyRecorded(
    device: Device.fromType(DeviceType.phone),
  ),
);

final recordId = await connector.writeRecord(stepRecord);
print('Record ID: $recordId');

Atomic Write Multiple Records

All records succeed or all fail together:

final records = [
  StepsRecord(
    id: HealthRecordId.none,
    startTime: DateTime.now().subtract(Duration(hours: 2)),
    endTime: DateTime.now().subtract(Duration(hours: 1)),
    count: Numeric(3000),
    metadata: Metadata.automaticallyRecorded(
      device: Device.fromType(DeviceType.phone),
    ),
  ),
  StepsRecord(
    id: HealthRecordId.none,
    startTime: DateTime.now().subtract(Duration(hours: 1)),
    endTime: DateTime.now(),
    count: Numeric(2000),
    metadata: Metadata.automaticallyRecorded(
      device: Device.fromType(DeviceType.phone),
    ),
  ),
];

final recordIds = await connector.writeRecords(records);
print('Wrote ${recordIds.length} records');

🔄 Updating Health Records

iOS Privacy Note: HealthKit does not provide an update API because it uses an immutable data model. Once a health record is written to HealthKit, it cannot be modified—only deleted.

Update Record (Android Health Connect Only)

final recordId = HealthRecordId('existing-record-id');
final request = HealthDataType.steps.readRecord(recordId);
final existingRecord = await connector.readRecord(request);

if (existingRecord != null) {
  final updatedRecord = existingRecord.copyWith(
    count: Numeric(existingRecord.count.value + 500),
  );

  await connector.updateRecord(updatedRecord);
  print('Record updated');
}

Atomic Update Multiple Records (Android Health Connect Only)

Update multiple records atomically—all succeed or all fail together:

// Read existing records
final readRequest = HealthDataType.steps.readInTimeRange(
  startTime: DateTime.now().subtract(Duration(days: 7)),
  endTime: DateTime.now(),
);
final response = await connector.readRecords(readRequest);

// Update all records by adding 100 steps to each
final updatedRecords = response.records.map((record) {
  return record.copyWith(
    count: Numeric(record.count.value + 100),
  );
}).toList();

// Batch update all records
await connector.updateRecords(updatedRecords);
print('Updated ${updatedRecords.length} records');

iOS HealthKit Update Workaround (Delete + Write)

// 1. Delete existing record
await connector.deleteRecords(
  HealthDataType.steps.deleteByIds([existingRecord.id]),
);

// 2. Write new record with updated values
final newRecord = StepsRecord(
  id: HealthRecordId.none,
  startTime: existingRecord.startTime,
  endTime: existingRecord.endTime,
  count: Numeric(newValue),
  metadata: existingRecord.metadata,
);

final newId = await connector.writeRecord(newRecord);
// Note: newId will be different from the original ID

🗑️ Deleting Health Records

Atomic Delete by IDs

await connector.deleteRecords(
  HealthDataType.steps.deleteByIds([
    HealthRecordId('id-1'),
    HealthRecordId('id-2'),
  ]),
);

Atomic Delete by Time Range

await connector.deleteRecords(
  HealthDataType.steps.deleteInTimeRange(
    startTime: DateTime.now().subtract(Duration(days: 7)),
    endTime: DateTime.now(),
  ),
);

Important: Apps can only delete records they created. Attempting to delete records from other apps will silently fail.

➕ Aggregating Health Data

Sum Aggregation

Get the total value over a period, such as total steps for a day:

final sumRequest = HealthDataType.steps.aggregateSum(
  startTime: DateTime.now().subtract(Duration(days: 1)),
  endTime: DateTime.now(),
);

final sumResponse = await connector.aggregate(sumRequest);
print('Total steps: ${sumResponse.value.value}');

Average Aggregation

Get the average value over 30 days:

final avgRequest = HealthDataType.weight.aggregateAvg(
  startTime: DateTime.now().subtract(Duration(days: 30)),
  endTime: DateTime.now(),
);

final avgResponse = await connector.aggregate(avgRequest);
print('Average weight: ${avgResponse.value.inKilograms} kg');

Minimum Aggregation

Get the minimum recorded value over a period:

final minRequest = HealthDataType.weight.aggregateMin(
  startTime: DateTime.now().subtract(Duration(days: 30)),
  endTime: DateTime.now(),
);

final minResponse = await connector.aggregate(minRequest);
print('Min weight: ${minResponse.value.inKilograms} kg');

Maximum Aggregation

Get the maximum recorded value over a period:

final maxRequest = HealthDataType.weight.aggregateMax(
  startTime: DateTime.now().subtract(Duration(days: 30)),
  endTime: DateTime.now(),
);

final maxResponse = await connector.aggregate(maxRequest);
print('Max weight: ${maxResponse.value.inKilograms} kg');

🎯 Real-World Use Cases

Fitness Tracker

Track daily activity with steps, calories, and distance:

Future<Map<String, double>> getDailyActivitySummary(
  HealthConnector connector,
  DateTime date,
) async {
  final startOfDay = DateTime(date.year, date.month, date.day);
  final endOfDay = startOfDay.add(Duration(days: 1));

  final steps = await connector.aggregate(
    HealthDataType.steps.aggregateSum(
      startTime: startOfDay,
      endTime: endOfDay,
    ),
  );

  final calories = await connector.aggregate(
    HealthDataType.activeCaloriesBurned.aggregateSum(
      startTime: startOfDay,
      endTime: endOfDay,
    ),
  );

  return {
    'steps': steps.value.value,
    'calories': calories.value.inKilocalories,
  };
}

Health Dashboard

Display vital signs with recent measurements:

Future<void> displayVitals(HealthConnector connector) async {
  final now = DateTime.now();
  final weekAgo = now.subtract(Duration(days: 7));

  // Get latest weight
  final weightResponse = await connector.readRecords(
    HealthDataType.weight.readInTimeRange(
      startTime: weekAgo,
      endTime: now,
      pageSize: 1,
    ),
  );

  if (weightResponse.records.isNotEmpty) {
    final latestWeight = weightResponse.records.first as WeightRecord;
    print('Latest weight: ${latestWeight.weight.inKilograms} kg');
  }

  // Get heart rate average
  final heartRateAvg = await connector.aggregate(
    HealthDataType.restingHeartRate.aggregateAvg(
      startTime: weekAgo,
      endTime: now,
    ),
  );
  print('Avg resting HR: ${heartRateAvg.value.inBeatsPerMinute} bpm');
}

Nutrition Logger

Log meals with macronutrients:

Future<void> logMeal({
  required HealthConnector connector,
  required String mealName,
  required double calories,
  required double proteinGrams,
  required double carbsGrams,
  required double fatGrams,
}) async {
  final now = DateTime.now();

  final nutritionRecord = NutritionRecord(
    id: HealthRecordId.none,
    startTime: now.subtract(Duration(minutes: 30)),
    endTime: now,
    mealType: MealType.lunch,
    name: mealName,
    energy: Energy.kilocalories(calories),
    protein: Mass.grams(proteinGrams),
    totalCarbohydrate: Mass.grams(carbsGrams),
    totalFat: Mass.grams(fatGrams),
    metadata: Metadata.manual(),
  );

  await connector.writeRecord(nutritionRecord);
  print('Meal logged: $mealName');
}

📋 API Reference

HealthConnector Methods

⚠️ Error Handling

The plugin provides two approaches for handling errors:

Approach 1: Catching Specific Exceptions

Use Dart's type-based exception handling to catch specific error types.

try {
  await connector.requestPermissions([...]);
  await connector.writeRecord(record);
} on NotAuthorizedException catch (e) {
  // User denied or revoked permissions
  // Recovery: Explain why permission is needed, guide to settings
  print('Permission denied: ${e.message}');
} on InvalidConfigurationException catch (e) {
  // Missing AndroidManifest.xml or Info.plist configuration
  // Recovery: Fix app configuration (development-time error)
  print('Configuration error: ${e.message}');
} on UnsupportedOperationException catch (e) {
  // Platform doesn't support this operation
  // Recovery: Check platform before calling, use alternative approach
  print('Not supported: ${e.message}');
} on InvalidArgumentException catch (e) {
  // Invalid input (e.g., startTime > endTime, negative values)
  // Recovery: Validate inputs before calling
  print('Invalid argument: ${e.message}');
} on HealthPlatformUnavailableException catch (e) {
  // Device doesn't support health API
  // Recovery: Disable health features for this device
  print('Health unavailable: ${e.message}');
} on HealthPlatformNotInstalledOrUpdateRequiredException catch (e) {
  // Health Connect needs installation/update (Android Health Connect Only)
  // Recovery: Prompt user to install/update Health Connect
  print('Health Connect needs update: ${e.message}');
} on RemoteErrorException catch (e) {
  // Transient I/O or communication error
  // Recovery: Retry with exponential backoff
  print('Remote error: ${e.message}');
} on HealthConnectorException catch (e) {
  // Generic fallback for unexpected errors
  print('Unknown error [${e.code}]: ${e.message}');
}

Approach 2: Handling by Error Code

Catch the base HealthConnectorException and switch on HealthConnectorErrorCode.

try {
  await connector.requestPermissions([...]);
  await connector.writeRecord(record);
} on HealthConnectorException catch (e) {
  switch (e.code) {
    case HealthConnectorErrorCode.notAuthorized:
      print('Permission denied: ${e.message}');
    case HealthConnectorErrorCode.invalidConfiguration:
      print('Configuration error: ${e.message}');
    case HealthConnectorErrorCode.unsupportedOperation:
      print('Not supported: ${e.message}');
    case HealthConnectorErrorCode.invalidArgument:
      print('Invalid argument: ${e.message}');
    case HealthConnectorErrorCode.healthPlatformUnavailable:
      print('Health unavailable: ${e.message}');
    case HealthConnectorErrorCode.healthPlatformNotInstalledOrUpdateRequired:
      print('Health Connect needs update: ${e.message}');
    case HealthConnectorErrorCode.remoteError:
      print('Remote error: ${e.message}');
    case HealthConnectorErrorCode.unknown:
      print('Unknown error [${e.code}]: ${e.message}');
  }
}

Exception Quick Reference

🔧 Troubleshooting

Common Issues

Debug Logging

Enable detailed logs to troubleshoot issues:

final connector = await HealthConnector.create(
  HealthConnectorConfig(isLoggerEnabled: true),
);

❓ FAQ

Why do iOS read permissions always return unknown?

Apple intentionally hides read permission status to protect user privacy. This prevents apps from inferring whether a user has any health data by checking if read permission was denied.

How do I handle Health Connect not being installed?

final status = await HealthConnector.getHealthPlatformStatus();
if (status == HealthPlatformStatus.installationOrUpdateRequired) {
  // Show dialog prompting user to install Health Connect
  // Open Play Store: https://play.google.com/store/apps/details?id=com.google.android.apps.healthdata
}

What's the difference between heartRateSeriesRecord and heartRateMeasurementRecord?

• Android Health Connect: Uses heartRateSeriesRecord—a single record with multiple samples over a time interval
• iOS HealthKit: Uses heartRateMeasurementRecord—each measurement is a separate record with its own ID

Can I read health data from other apps?

Yes, with user permission. When granted read access, you can read health data from all sources (other apps, devices, manual entries).

Can I delete health data from other apps?

No. Apps can only delete records they created. This is a platform security restriction.

📋 Supported Health Data Types

🏃 Activity

📏 Distance Types

📏 Body Measurements

❤️ Vitals

😴 Sleep

🏋️ Exercise & Workouts

Supported Exercise Types

The SDK supports 100+ exercise types across both platforms, including:

Cross-Platform Types (~50 types supported on both iOS and Android):

• Cardio: running, walking, cycling, hiking, swimming
• Strength: strength training, calisthenics, weightlifting
• Team Sports: basketball, soccer, tennis, volleyball, baseball, rugby
• Racquet Sports: tennis, badminton, squash, table tennis
• Winter Sports: snowboarding, skating
• Fitness: yoga, pilates, HIIT, elliptical
• Water Sports: surfing, water polo, rowing, sailing, paddling, diving
• And many more: golf, climbing, boxing, martial arts, gymnastics, fencing

iOS-Only Types (annotated with @supportedOnAppleHealth):

• swimming (generic), waterFitness, waterSports
• kickboxing, wrestling, taiChi
• handCycling, trackAndField
• crossCountrySkiing, downhillSkiing, snowSports, curling
• pickleball, lacrosse, hockey, discSports
• archery, bowling, fishing, hunting, equestrianSports
• barre, cardioDance, socialDance, coreTraining
• crossTraining, jumpRope, fitnessGaming, mixedCardio
• stepTraining, mindAndBody, preparationAndRecovery, cooldown
• wheelchairWalkPace, wheelchairRunPace
• transition, swimBikeRun, play

Android-Only Types (annotated with @supportedOnHealthConnect):

• runningTreadmill, cyclingStationary
• swimmingOpenWater, swimmingPool
• weightlifting, calisthenics
• iceHockey, rollerHockey
• skiing, snowshoeing
• dancing, exerciseClass, bootCamp
• guidedBreathing, paragliding, wheelchair

Platform Mapping Details:

• Android Health Connect: Maps to ExerciseSessionRecord.EXERCISE_TYPE_* constants
• iOS HealthKit: Maps to HKWorkoutActivityType enum values

For complete exercise type documentation and platform mappings, see the ExerciseType enum documentation.

🍎 Nutrition

Core & Hydration

Macronutrients

Fats

Fiber & Sugar

Minerals

B Vitamins

Other Vitamins

🏃 Speed

📈 Migration Guides

• migration-guide-v1.x.x-to-v2.x.x.md

🤝 Contributing

Contributions are welcome! See our GitHub Issues to report bugs or request features.

Development Setup

# Clone the repository
git clone https://github.com/fam-tung-lam/health_connector.git
cd health_connector

# Bootstrap the monorepo
melos bootstrap

# Install dependencies
melos get

# Run analysis
melos analyze:dart

Code Style

This project uses health_connector_lint for consistent code style. Run dart analyze before submitting PRs.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

📝 Changelog

See CHANGELOG.md for version history.