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

  1. TerraDevID in Info.plist, plus NSHealthShareUsageDescription (and NSHealthUpdateUsageDescription if you write).

  2. The HealthKit capability with background delivery, fetch in UIBackgroundModes, and co.tryterra.sdk.refresh in BGTaskSchedulerPermittedIdentifiers.

  3. One line in application(_:didFinishLaunchingWithOptions:), before super:

    import terra_flutter_bridge
    
    TerraFlutterBridgePlugin.bootstrap()
    
  4. Health Records (opt-in). Only if the app reads them:

    • add health-records to the com.apple.developer.healthkit.access entitlement;

    • add both NSHealthShareUsageDescription and NSHealthClinicalHealthRecordsShareUsageDescription to Info.plist;

    • enable CLINICAL_RECORD for the Terra client in Terra's dashboard, or Terra refuses every upload with data_type_not_enabled;

    • ask on HealthKit's own sheet. The function is null on Android, and permissions.request ignores clinicalRecord:

      await terra.permissions.requestClinicalRecords?.call();
      

Android

  1. The developer id in AndroidManifest.xml's <application>; the package's startup initializer reads it before Application.onCreate:

    <meta-data android:name="co.tryterra.sdk.DEV_ID" android:value="YOUR_DEV_ID" />
    
  2. MainActivity extends FlutterFragmentActivity, not FlutterActivity: the Health Connect permission sheet is launched through an activity result, which only a ComponentActivity can register for. With a plain FlutterActivity, permissions.request answers bridge.no_activity and the plugin logs why.

  3. minSdk = 28, and the Health Connect permissions your requests expand to, plus the VIEW_PERMISSION_USAGE activity alias Android 14 requires. example/android has both.

  4. Samsung Health is opt-in: terraSamsungHealth=true in android/gradle.properties, and Samsung's samsung-health-data-api.aar in 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.

Libraries

terra_flutter_bridge
Terra's health SDK for Flutter.