terra_flutter_bridge 2.3.0
terra_flutter_bridge: ^2.3.0 copied to clipboard
Terra's health SDK for Flutter, over the same generated bridge as the React Native package.
terra_flutter_bridge #
Terra's health SDK for Flutter: Apple Health on iOS, Health Connect (and optionally Samsung Health)
on Android. The Dart API is the React Native package's, over the same generated bridge
(hybrid-common), so both wrappers answer every op and stream the same way.
Requires Flutter 3.24 or later, iOS 15, and Android API 28 with Kotlin 2.0 or later and Android Gradle Plugin 8.9.1 or later (the floor of Health Connect's client library).
Host setup #
The native client is built at app launch, before any Dart runs, because a background sync wake never starts a Flutter engine. Each platform needs a few lines of native configuration.
iOS #
-
TerraDevIDinInfo.plist, plusNSHealthShareUsageDescription(andNSHealthUpdateUsageDescriptionif you write). -
The HealthKit capability with background delivery,
fetchinUIBackgroundModes, andco.tryterra.sdk.refreshinBGTaskSchedulerPermittedIdentifiers. -
One line in
application(_:didFinishLaunchingWithOptions:), beforesuper:import terra_flutter_bridge TerraFlutterBridgePlugin.bootstrap() -
Health Records (opt-in). Only if the app reads them:
-
add
health-recordsto thecom.apple.developer.healthkit.accessentitlement; -
add both
NSHealthShareUsageDescriptionandNSHealthClinicalHealthRecordsShareUsageDescriptiontoInfo.plist; -
enable
CLINICAL_RECORDfor the Terra client in Terra's dashboard, or Terra refuses every upload withdata_type_not_enabled; -
ask on HealthKit's own sheet. The function is null on Android, and
permissions.requestignoresclinicalRecord:await terra.permissions.requestClinicalRecords?.call();
-
Android #
-
The developer id in
AndroidManifest.xml's<application>; the package's startup initializer reads it beforeApplication.onCreate:<meta-data android:name="co.tryterra.sdk.DEV_ID" android:value="YOUR_DEV_ID" /> -
MainActivityextendsFlutterFragmentActivity, notFlutterActivity: the Health Connect permission sheet is launched through an activity result, which only aComponentActivitycan register for. With a plainFlutterActivity,permissions.requestanswersbridge.no_activityand the plugin logs why. -
minSdk = 28, and the Health Connect permissions your requests expand to, plus theVIEW_PERMISSION_USAGEactivity alias Android 14 requires.example/androidhas both. -
Samsung Health is opt-in:
terraSamsungHealth=trueinandroid/gradle.properties, and Samsung'ssamsung-health-data-api.aarin your app, which no Terra artifact may carry.
A host that removed WorkManager's default initializer calls TerraFlutter.bootstrap(this) at the
end of Application.onCreate instead of relying on the startup initializer.
Use #
WidgetsFlutterBinding.ensureInitialized();
final terra = createTerra(tokenProvider: fetchTokenFromYourBackend);
await terra.permissions.request(read: [DataCategory.daily]);
await terra.connect(Source.health, const EndUser.reference(id: 'user-123'));
final steps = await terra.daily.steps(const TimeRange.today());
example/ exercises connect, sync status, reads and a stream on both platforms, and its
integration_test/ drives the plugin on a simulator or emulator.
Asking for specific types #
A category asks for everything behind it: body is blood glucose, blood pressure and temperature as
well as weight. An app whose consent screen and NSHealthShareUsageDescription name specific data
asks for exactly that, as Terra Grip does for the 22 types it discloses:
await terra.permissions.request(readTypes: [
HealthDataType.workouts, HealthDataType.steps, HealthDataType.activeEnergy,
HealthDataType.exerciseTime, HealthDataType.distance, HealthDataType.floorsClimbed,
HealthDataType.heartRate, HealthDataType.restingHeartRate,
HealthDataType.heartRateVariability, HealthDataType.vo2Max, HealthDataType.sleepAnalysis,
HealthDataType.weight, HealthDataType.height, HealthDataType.bmi, HealthDataType.bodyFat,
HealthDataType.dietaryEnergyConsumed, HealthDataType.dietaryWater,
HealthDataType.dietaryProtein, HealthDataType.dietaryCarbohydrates,
HealthDataType.dietaryFatTotal, HealthDataType.dietarySugar, HealthDataType.menstrualFlow,
]);
final status = await terra.permissions.typeStatus(HealthDataType.heartRate);
The sheet names exactly those types, and from then on the SDK reads and uploads nothing else. iOS
answers typeStatus with notDisclosed, because HealthKit never reports a read decision; Android
answers granted once any permission behind the type is (workouts once exercise is). exerciseTime and bmi are HealthKit
only, so on Android pass the list less them: a type a platform has no store type for fails with
bridge.unsupported_on_platform and nothing is recorded. docs/sdk-reference.md lists every type
with the HealthKit and Health Connect types behind it.