health_connector #

The most complete Flutter health SDK — unified, type-safe access to 100+ health data types across iOS HealthKit and Android Health Connect.

📖 Table of Contents #

• 🎮 See It In Action

• 🚀 Quick Start

  • 📋 Requirements
  • 📦 Installation
  • 🔧 Platform Setup
  • ⚡ Quick Demo

• 📘 Developer Guide

  • 🔐 Permission Management
  • 📖 Reading Health Data
  • ✍️ Writing Health Data
  • 🔄 Updating Health Records
  • 🗑️ Deleting Health Records
  • ➕ Aggregating Health Data
  • ⚙️ Feature Management
  • ⚠️ Error Handling
  • 📝 Logging
  • ❓ Troubleshooting & FAQ
  • 🎯 Real-World Use Cases

• 📚 References

  • 📋 Supported Health Data Types
  • 🔄 Migration Guides
  • 🤝 Contributing
  • 📄 License

🎮 See It In Action — Interactive Toolbox Demo #

See what's possible. The Health Connector Toolbox showcases the full power of the SDK with live, interactive demonstrations running on both iOS and Android.

🔐 Permissions	📖 Read	✍️ Write	🗑️ Delete	📊 Aggregate

🚀 Try It Yourself #

git clone https://github.com/fam-tung-lam/health_connector.git
cd health_connector/examples/health_connector_toolbox
flutter pub get && flutter run

Explore:

• 🔐 Permission flows for HealthKit & Health Connect
• 📊 Real-time health data visualization
• ✍️ CRUD operations with live feedback
• 🧪 Feature detection and platform capabilities

💡 Note: The toolbox is a demonstration tool—perfect for exploring APIs, not for production reference.

🚀 Quick Start #

📋 Requirements #

📦 Installation #

flutter pub add health_connector

Or add manually to pubspec.yaml:

dependencies:
  health_connector: [latest_version]

🔧 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" />
    <!-- Add more read permissions... -->
    
    <!-- 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" />
    <!-- Add more write permissions... -->

    <!-- 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" />
    <!-- Add more feature permissions... -->
</manifest>

package com.example.yourapp

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
    // Your existing code
}

# Your existing configuration

android.enableJetifier=true
android.useAndroidX=true

android {
    // Your existing configuration

    defaultConfig {
        // Your existing configuration

        minSdkVersion 26  // Required for Health Connect
    }
}

<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 Demo #

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(
    const HealthConnectorConfig(isLoggerEnabled: true),
  );

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

  // 4. Verify permissions were granted
  final granted = results.every((r) => r.status != PermissionStatus.denied);
  if (!granted) {
    print('Permissions denied');
    return;
  }

  // 5. Write health data
  final now = DateTime.now();
  final records = [
    _createStepsRecord(now.subtract(Duration(hours: 3)), 1500),
    _createStepsRecord(now.subtract(Duration(hours: 2)), 2000),
    _createStepsRecord(now.subtract(Duration(hours: 1)), 1800),
  ];
  
  final recordIds = await connector.writeRecords(records);
  print('✅ Wrote ${recordIds.length} records');

  // 6. Read health data
  final response = await connector.readRecords(
    HealthDataType.steps.readInTimeRange(
      startTime: now.subtract(Duration(days: 1)),
      endTime: now,
    ),
  );

  print('📊 Found ${response.records.length} records:');
  for (final record in response.records) {
    print('  → ${record.count.value} steps (${record.startTime})');
  }
}

// Helper to create step records
StepsRecord _createStepsRecord(DateTime time, int steps) {
  return StepsRecord(
    startTime: time,
    endTime: time.add(Duration(hours: 1)),
    count: Number(steps),
    metadata: Metadata.automaticallyRecorded(
      dataOrigin: DataOrigin('com.example'),
      device: Device.fromType(DeviceType.phone),
    ),
  );
}

💡 What's Next? Check out the Developer Guide for full API documentation, error handling, and advanced features.

📘 Developer Guide #

🔐 Permission Management #

Request Permissions

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

final results = await connector.requestPermissions(permissions);

// Process results
for (final result in results) {
  if (result.status == PermissionStatus.granted) {
    print('✅ ${result.permission}');
  } else if (result.status == PermissionStatus.unknown) {
    print('❓ ${result.permission} (iOS read permission)');
  }
}

iOS Privacy: Read permissions always return unknown to prevent apps from inferring whether users have health data.

Check Permission Status

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

switch (status) {
  case PermissionStatus.granted:
    // Permission granted
  case PermissionStatus.denied:
    // Permission denied
  case PermissionStatus.unknown:
    // iOS read permission (cannot determine)
}

iOS Read Permission Workaround

Strategy: Attempt a minimal read operation and catch NotAuthorizedException.

Future<bool> hasReadPermission(HealthDataType dataType) async {
  try {
    await connector.readRecords(
      dataType.readInTimeRange(
        startTime: DateTime.now().subtract(Duration(days: 1)),
        endTime: DateTime.now(),
        pageSize: 1,
      ),
    );
    return true;  // Read succeeded = permission granted
  } on NotAuthorizedException {
    return false; // Permission denied
  }
}

Disclaimer: Not officially recommended by Apple. Use only if your app genuinely needs to determine read permission status.

Get All Granted Permissions (Android only)

iOS Privacy: HealthKit doesn't allow apps to enumerate granted permissions.

try {
  final granted = await connector.getGrantedPermissions();
  for (final p in granted) {
    print('${p.dataType} (${p.accessType})');
  }
} on UnsupportedOperationException {
  // iOS doesn't support this API
}

Revoke All Permissions (Android only)

iOS Privacy: Not supported by HealthKit. Users must revoke permissions manually via Settings app.

try {
  await connector.revokeAllPermissions();
} on UnsupportedOperationException {
  // iOS users must revoke via Settings app
}

📖 Reading Health Data #

Read by ID

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

if (record != null) {
  print('✅ Found: ${record.count.value} steps');
}

Read by Time Range

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

print('📊 Found ${response.records.length} records');
for (final record in response.records) {
  print('${record.count.value} steps on ${record.startTime}');
}

Historical Data Access: Android Health Connect defaults to 30 days—request HealthPlatformFeature.readHealthDataHistory permission for older data. iOS HealthKit has no restrictions.

Paginate Through All Records

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

final allRecords = <StepsRecord>[];

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

  // Check if there are more pages
  if (response.nextPageRequest == null) break;
  request = response.nextPageRequest!;
}

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

📤 Back to top

✍️ Writing Health Data #

Write Single Record

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

final recordId = await connector.writeRecord(record);
print('✅ Saved: $recordId');

Batch Write Multiple Records

All records succeed or all fail together:

// Helper to create step records
StepsRecord _createSteps(DateTime time, int steps) => StepsRecord(
  id: HealthRecordId.none,
  startTime: time,
  endTime: time.add(Duration(hours: 1)),
  count: Number(steps),
  metadata: Metadata.automaticallyRecorded(
    device: Device.fromType(DeviceType.phone),
  ),
);

final now = DateTime.now();
final records = [
  _createSteps(now.subtract(Duration(hours: 3)), 1500),
  _createSteps(now.subtract(Duration(hours: 2)), 2000),
  _createSteps(now.subtract(Duration(hours: 1)), 1800),
];

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

📤 Back to top

🔄 Updating Health Records #

iOS Note: HealthKit uses an immutable data model—records cannot be updated, only deleted and recreated.

Update Single Record (Android only)

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

if (record != null) {
  await connector.updateRecord(
    record.copyWith(count: Number(record.count.value + 500)),
  );
  print('✅ Record updated');
}

Batch Update (Android only)

Update multiple records atomically—all succeed or all fail.

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

// Apply updates
final updated = response.records.map((r) => 
  r.copyWith(count: Number(r.count.value + 100))
).toList();

await connector.updateRecords(updated);
print('✅ Updated ${updated.length} records');

iOS Workaround: Delete + Recreate

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

// Write new record with updated values
final newRecord = existingRecord.copyWith(
  id: HealthRecordId.none,
  count: Number(newValue),
);

final newId = await connector.writeRecord(newRecord);
// ⚠️ Note: ID changes after recreation

📤 Back to top

🗑️ Deleting Health Records #

Limitation: Apps can only delete records they created—platform security restriction.

Delete by IDs

try {
  await connector.deleteRecords(
    HealthDataType.steps.deleteByIds([
      HealthRecordId('id-1'),
      HealthRecordId('id-2'),
    ]),
  );
  print('✅ Deleted');
} on NotAuthorizedException {
  print('❌ Cannot delete records from other apps');
}

Delete by Time Range

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

📤 Back to top

📊 Aggregating Health Data #

Example: Sum

final response = await connector.aggregate(
  HealthDataType.steps.aggregateSum(
    startTime: DateTime.now().subtract(Duration(days: 1)),
    endTime: DateTime.now(),
  ),
);

print('📊 Total steps: ${response.value.value}');

Example: Average, Min, Max

final now = DateTime.now();
final thirtyDaysAgo = now.subtract(Duration(days: 30));

// Get average weight
final avg = await connector.aggregate(
  HealthDataType.weight.aggregateAvg(
    startTime: thirtyDaysAgo,
    endTime: now,
  ),
);

// Get min/max weight
final min = await connector.aggregate(
  HealthDataType.weight.aggregateMin(
    startTime: thirtyDaysAgo,
    endTime: now,
  ),
);

// Get min/max weight
final max = await connector.aggregate(
  HealthDataType.weight.aggregateMax(
    startTime: thirtyDaysAgo,
    endTime: now,
  ),
);

print('Avg: ${avg.value.inKilograms} kg');
print('Min: ${min.value.inKilograms} kg');
print('Max: ${max.value.inKilograms} kg');

📤 Back to top

⚙️ Feature Management #

Platform Behavior: iOS HealthKit features are always available (built into iOS). Android Health Connect features depend on app version—check getFeatureStatus() before requesting permissions.

Check Feature Availability

final status = await connector.getFeatureStatus(
  HealthPlatformFeature.readHealthDataInBackground,
);

if (status == HealthPlatformFeatureStatus.available) {
  await connector.requestPermissions([
    HealthPlatformFeature.readHealthDataInBackground.permission,
  ]);
  print('✅ Feature available and requested');
} else {
  print('❌ Feature not available—implement fallback');
}

// Note: iOS always returns 'available', Android returns actual status

📤 Back to top

⚠️ Error Handling #

Exception Quick Reference

Standard Exception Handling

try {
  await connector.writeRecord(record);
} on NotAuthorizedException catch (e) {
  print('❌ Permission denied: ${e.message}');
  // Show UI prompting user to check settings
} on HealthPlatformUnavailableException {
  print('❌ Health API unavailable on this device');
} on HealthConnectorException catch (e) {
  print('❌ Error [${e.code}]: ${e.message}');
}

📤 Back to top

📝 Logging #

Zero-intrusion: Logs are emitted to a stream (HealthConnectorLogger.logs) and never printed automatically. You control the output.

Setup & Subscribing

// 1. Enable logging during initialization
final connector = await HealthConnector.create(
  const HealthConnectorConfig(isLoggerEnabled: true),
);

// 2. Subscribe and filter
HealthConnectorLogger.logs
  .where((log) => log.level == HealthConnectorLogLevel.error) // Optional filter
  .listen((log) {
    print(log.structuredMessage);
    // OR send to Crashlytics:
    // Crashlytics.recordError(log.exception, log.stackTrace, reason: log.message);
  });

Log Structure Example

[HEALTHCONNECTOR] [INFO]:
{
    datetime: 06-01-2026 18:15:32.456,
    message: HealthConnector created successfully,
    operation: create,
    context: { platform: healthConnect },
}

[HEALTHCONNECTOR] [ERROR]:
{
    datetime: 06-01-2026 18:15:34.123,
    message: Failed to read records,
    exception: { cause: NotAuthorizedException... },
}

📤 Back to top

🔧 Troubleshooting & FAQ #

📤 Back to top

🎯 Real-World Use Cases #

🏃 Fitness Dashboard

// Get daily summary: steps & calories
Future<Map<String, double>> getDailySummary(HealthConnector connector) async {
  final now = DateTime.now();
  final today = DateTime(now.year, now.month, now.day);
  final tomorrow = today.add(Duration(days: 1));

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

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

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

❤️ Vitals Monitor

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

  // 1. Get latest weight
  final weight = await connector.readRecords(
    HealthDataType.weight.readInTimeRange(
      startTime: weekAgo, endTime: now, pageSize: 1,
    ),
  );
  if (weight.records.isNotEmpty) {
    print('⚖️ Latest weight: ${(weight.records.first as WeightRecord).weight.inKilograms} kg');
  }

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

🥗 Nutrition Tracker

Future<void> logLunch(HealthConnector connector) async {
  final entry = NutritionRecord(
    id: HealthRecordId.none,
    startTime: DateTime.now().subtract(Duration(minutes: 30)),
    endTime: DateTime.now(),
    name: 'Grilled Chicken Salad',
    energy: Energy.kilocalories(450),
    protein: Mass.grams(40),
    totalCarbohydrate: Mass.grams(12),
    totalFat: Mass.grams(15),
    metadata: Metadata.manual(),
  );

  await connector.writeRecord(entry);
  print('✅ Meal logged');
}

📤 Back to top

📚 References #

📋 Supported Health Data Types #

🏃 Activity

General Activity

Distance Types

Speed Types

Power Types

Exercise Sessions

Exercise Types

📏 Body Measurements

❤️ Vitals

😴 Sleep

😋 Nutrition

Core & Hydration

Macronutrients

Fats

Fiber & Sugar

Minerals

B Vitamins

Other Vitamins

🧘 Wellness

🪷 Cycle Tracking

📤 Back to top

🔄 Migration Guides #

• Migration Guide from v1.x.x to v2.x.x

🤝 Contributing #

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

📄 License #

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