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()
    

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.

Libraries

terra_flutter_bridge
Terra's health SDK for Flutter.