Skip to main content

Introduction

The Open Wearables Flutter SDK (open_wearables_health_sdk) enables secure background synchronization of health data from Apple HealthKit (iOS), Samsung Health, and Health Connect (Android) to the Open Wearables platform. On iOS, the Flutter SDK is a wrapper around the native iOS SDK (OpenWearablesHealthSDK). On Android, it wraps the native Android SDK (open-wearables-android-sdk). This means all the core sync logic — background execution, streaming uploads, secure storage, and retry mechanisms — is handled by the native implementations under the hood. The Flutter layer provides a convenient Dart API for cross-platform apps.

Flutter SDK Repository

View source code, report issues, and contribute to the Flutter SDK.

Native iOS SDK

See the native iOS SDK documentation for the underlying iOS implementation.

Native Android SDK

See the native Android SDK documentation for the underlying Android implementation.

Features

  • Cross-Platform - Single Dart API for iOS (HealthKit) and Android (Samsung Health, Health Connect)
  • Background Sync - Health data syncs even when your app is in the background
  • Incremental Updates - Only syncs new data using anchored queries
  • Secure Storage - Credentials stored in iOS Keychain / Android EncryptedSharedPreferences
  • Dual Authentication - Token-based auth with auto-refresh or API key authentication
  • Resumable Sessions - Sync sessions survive app restarts
  • Wide Data Support - Steps, heart rate, workouts, sleep, and 40+ data types
  • Provider Selection - Choose between Samsung Health and Health Connect on Android

Requirements

RequirementDetails
iOS VersioniOS 15.0+
XcodeXcode 14+
Apple Developer AccountRequired for HealthKit entitlement
HealthKit CapabilityMust be enabled in Xcode
Physical DeviceHealthKit doesn’t work in iOS Simulator

Installation

1

Add the dependency

Add open_wearables_health_sdk to your pubspec.yaml:
dependencies:
  open_wearables_health_sdk: ^0.0.14
Then run:
flutter pub get
2

iOS Configuration

Add the following to your ios/Runner/Info.plist:
<!-- Health data permission -->
<key>NSHealthShareUsageDescription</key>
<string>This app syncs your health data to your account.</string>

<!-- Background modes for sync -->
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>

<!-- Background task identifiers -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.openwearables.healthsdk.task.refresh</string>
    <string>com.openwearables.healthsdk.task.process</string>
</array>
Then enable HealthKit capability in Xcode:
  1. Open ios/Runner.xcworkspace in Xcode
  2. Select your target → Signing & Capabilities
  3. Click + Capability → Add HealthKit
  4. Check Background Delivery if you want updates while app is closed
3

Android Configuration

The SDK’s Android module handles most configuration automatically. Make sure your android/app/build.gradle has:
android {
    compileSdk 36
    defaultConfig {
        minSdk 29
    }
}
No additional permissions or manifest entries are needed — the SDK’s AndroidManifest.xml merges automatically.

Quick Start

Here’s the minimal code to get health sync working:
import 'package:open_wearables_health_sdk/open_wearables_health_sdk.dart';

class HealthService {
  Future<void> initialize() async {
    // 1. Configure the SDK with your backend host
    await OpenWearablesHealthSdk.configure(
      host: 'https://api.openwearables.io',
    );

    // 2. Check if already signed in (session restored from secure storage)
    if (OpenWearablesHealthSdk.isSignedIn) {
      print('Session restored for ${OpenWearablesHealthSdk.currentUser?.userId}');
      return;
    }

    // 3. Get credentials from YOUR backend
    final credentials = await yourBackend.getHealthCredentials();

    // 4. Sign in with the SDK
    await OpenWearablesHealthSdk.signIn(
      userId: credentials.userId,
      accessToken: credentials.accessToken,
      refreshToken: credentials.refreshToken,
    );

    // 5. Request health permissions
    await OpenWearablesHealthSdk.requestAuthorization(
      types: [
        HealthDataType.steps,
        HealthDataType.heartRate,
        HealthDataType.sleep,
        HealthDataType.workout,
      ],
    );

    // 6. Start background sync (sync last 90 days of data)
    await OpenWearablesHealthSdk.startBackgroundSync(syncDaysBack: 90);
  }
}

Android Provider Selection

On Android, you need to select a health data provider before requesting permissions:
import 'dart:io';

if (Platform.isAndroid) {
  // Check available providers
  final providers = await OpenWearablesHealthSdk.getAvailableProviders();
  for (final p in providers) {
    print('${p.displayName} (${p.id})');
  }

  // Set the provider (samsung or google/Health Connect)
  await OpenWearablesHealthSdk.setProvider(AndroidHealthProvider.healthConnect);
}
AndroidHealthProvider.samsungHealth maps to Samsung Health, and AndroidHealthProvider.healthConnect maps to Google Health Connect. Use getAvailableProviders() to check which are installed on the device.

Log Level

Control SDK log output with setLogLevel. The default is OWLogLevel.debug (logs only in debug builds):
// Always show logs (useful for troubleshooting in production)
await OpenWearablesHealthSdk.setLogLevel(OWLogLevel.always);

// Disable all logs
await OpenWearablesHealthSdk.setLogLevel(OWLogLevel.none);
LevelDescription
OWLogLevel.noneNo logs at all
OWLogLevel.alwaysLogs are always printed regardless of build mode
OWLogLevel.debugLogs are printed only in debug builds (default)

Listening to Events

The SDK exposes streams for logging and auth errors:
import 'package:open_wearables_health_sdk/open_wearables_health_sdk_method_channel.dart';

// Log stream from native SDK
MethodChannelOpenWearablesHealthSdk.logStream.listen((message) {
  print('[HealthSDK] $message');
});

// Auth error stream (e.g. 401 responses)
MethodChannelOpenWearablesHealthSdk.authErrorStream.listen((error) {
  print('Auth error: ${error['statusCode']} - ${error['message']}');
});

Documentation

Integration Guide

Complete guide to integrating the SDK including authentication flow, backend setup, and best practices.

Troubleshooting

Common issues and their solutions for iOS and Android.

Supported Health Data Types

The SDK supports 40+ health data types across multiple categories:
TypeDescription
stepsStep count
distanceWalkingRunningWalking/running distance
distanceCyclingCycling distance
flightsClimbedFloors climbed
walkingSpeedAverage walking speed
walkingStepLengthStep length
walkingAsymmetryPercentageWalking asymmetry percentage
walkingDoubleSupportPercentageWalking double support percentage
sixMinuteWalkTestDistance6-minute walk test
activeEnergyActive energy burned
basalEnergyBasal (resting) energy burned
TypeDescription
heartRateHeart rate measurements
restingHeartRateResting heart rate
heartRateVariabilitySDNNHRV (SDNN)
vo2MaxVO2 max
oxygenSaturationBlood oxygen
respiratoryRateBreathing rate
TypeDescription
bodyMassWeight
heightHeight
bmiBody Mass Index
bodyFatPercentageBody fat %
leanBodyMassLean body mass
waistCircumferenceWaist circumference
bodyTemperatureBody temperature
TypeDescription
bloodGlucoseBlood glucose level
insulinDeliveryInsulin delivery
bloodPressureSystolicSystolic blood pressure
bloodPressureDiastolicDiastolic blood pressure
bloodPressureBlood pressure (correlation type)
TypeDescription
sleepSleep sessions and stages
mindfulSessionMeditation/mindfulness sessions
TypeDescription
menstrualFlowMenstrual flow
cervicalMucusQualityCervical mucus quality
ovulationTestResultOvulation test result
sexualActivitySexual activity
TypeDescription
dietaryEnergyConsumedCalories consumed
dietaryCarbohydratesCarbs
dietaryProteinProtein
dietaryFatTotalTotal fat
dietaryWaterWater intake
TypeDescription
workoutAll workout types with metadata
Not all data types are available on all providers. Samsung Health supports a subset of types compared to Health Connect and HealthKit. See the Android SDK docs for provider-specific availability.

Next Steps

Integration Guide

Complete step-by-step integration guide.

API Reference

Full API documentation on GitHub.