Overview
The Synheart Wear Flutter SDK provides a unified API for streaming biometric data from Apple Health, Health Connect, WHOOP, Garmin, Fitbit, Oura and BLE heart-rate straps in Flutter applications. Key Features:- Cross-platform support (iOS + Android)
- Real-time HR and HRV streaming
- Unified data schema across all devices
- Optional encrypted local cache (AES-256)
- Consent-based permissions
Installation
Add to yourpubspec.yaml:
minSdk 28.
Platform Configuration
iOS Configuration
Add toios/Runner/Info.plist:
NSHealthUpdateUsageDescription
is not needed.
Android Configuration
Add toandroid/app/src/main/AndroidManifest.xml:
MainActivity must extend FlutterFragmentActivity (not FlutterActivity) for Android 14+.
Basic Usage
Recommended Pattern (Explicit Permission Control):initialize() request permissions itself:
initialize() validates that wearable data is available and not stale (>24 hours old). If no data is available or data is too old, it will throw a SynheartWearError with codes NO_WEARABLE_DATA or STALE_DATA.
Real-Time Streaming
Complete Example
Data Schema
Access metrics using theWearMetrics object:
Error Handling
NO_WEARABLE_DATA: No health data available from connected devicesSTALE_DATA: Latest data is older than 24 hoursPERMISSION_DENIED: User denied required permissions (thrown asPermissionDeniedError)
requestPermissions() accepts a reason: argument, but the SDK doesn’t show it
anywhere; explain the request in your own UI before calling it.
BLE Heart Rate Monitor
Connect directly to any standard Bluetooth LE heart rate monitor (WHOOP Broadcast, Polar, Wahoo, Garmin HRM straps) for real-time HR streaming. No cloud backend needed.Platform Setup
Android — Add toAndroidManifest.xml:
BLUETOOTH_SCAN and BLUETOOTH_CONNECT at runtime yourself
(for example with permission_handler). BleHrmProvider.requestPermission() is
iOS-only; on Android it throws MissingPluginException.
iOS — Add to Info.plist:
Usage
enableMotion: true (and optionally motionSampleRateHz, default 50) to
connect() and listen to bleHrm.onMotion. getBondedHrDevices() lists
already-bonded straps without scanning.
HeartRateSample
Each sample from the stream contains:Error Handling
BLE calls throwBleHrmError, whose code is a BleHrmErrorCode. Errors on
the onHeartRate stream use the same type:
Notes
- WHOOP devices require “Broadcast Heart Rate” enabled in the WHOOP app settings
- RR intervals are available on some devices (e.g. Polar chest straps) but not all
- Reconnection is automatic. Android retries 5 times, 3 s apart; iOS waits up to 30 s for CoreBluetooth to reconnect. After that
disconnectedis reported - Only one BLE HRM device can be connected at a time
Cloud Providers
WhoopProvider
GarminProvider (Cloud)
Full Garmin Connect integration via OAuth PKCE. Supports 12 summary types through the Garmin Health API backfill endpoint, plus activities (fetchActivities()): dailies, epochs, sleeps, stressDetails, hrv, userMetrics, bodyComps, pulseox, respiration, healthSnapshot, bloodPressures, and skinTemp.
GarminHealth (Native RTS)
TheGarminHealth facade provides native Garmin device integration for scanning, pairing, and real-time streaming. All method signatures use generic SDK-owned types (ScannedDevice, PairedDevice, WearMetrics), never Garmin-specific types.
Important: The Garmin Health SDK Real-Time Streaming (RTS) capability requires a separate license from Garmin. This facade is available on demand for licensed integrations. The underlying Garmin Health SDK code is proprietary to Garmin and is not distributed as open source.
Platform-Specific Notes
Android
- HRV: Only
HRV_RMSSDis supported by Health Connect - Distance: Uses
DISTANCE_DELTAtype - Requires Health Connect app installed
- MainActivity must extend
FlutterFragmentActivity
iOS
- Requires iOS 16+ and the HealthKit capability enabled in Xcode
- No HealthKit background delivery: reads happen when your app calls the SDK
- Real-time reads look back 2 minutes and run at most every 10 s; calls in between return no new data
API Reference
SynheartWear
Main SDK class for interacting with wearable devices.
Constructor:
SynheartWearConfig
Configuration for the SDK.
Constructor:
WearMetrics
Biometric data container.
Methods:
Properties:
Resources
- Repository: synheart-wear-flutter
- pub.dev: synheart_wear
- API Docs: API Reference
- Issues: GitHub Issues