Flutter project

If you have a flutter application, you can use the terra_flutter_bridge package to access SDK integrations. For details about the difference between API and SDK integrations, see Integrations.

Simple Integration Steps


Start off by installing the terra-react package:

flutter pub add terra_flutter_bridge

Then you can import the package in your code as such:

import 'package:terra_flutter_bridge/terra_flutter_bridge.dart';

Initialise Terra

The first step is to initialise Terra on the device. This allows the SDK to connect to the Terra service and handle any necessary setups on the device while the app is running. The following function should be called before usage of the SDK once when the app opens up

static Future<bool?> initTerra(
      String devID,
      String referenceID) async

It is recommended to run this function with await before proceeding!

devIdYour terra developer ID. You can find it in your terra dashboard (see Customize API settings)
referenceIdAn identifier that allows you to map the terra user id to one of your users

Connect an integration

After initialising Terra, you can initialise a device connection. This function needs to be called once only.

static Future<bool?> initConnection(
      Connection connection,
      String token,
      bool schedulerOn,
      List<CustomPermission> customPermissions) async

The function completes when the connection is done initiating!


How to choose which integration to connect?

You can have in your application a button for each integration name, allowing the user to select which integrations they'd like to link. You can also use the Terra widget in your application and trigger the connection initialisation based on the resource in the redirect URL.

In either case, TerraiOS provides further functions to simplify the application state so you don't have to store any of the connection states. See further below under the "Advanced Usage" section.


HealthKit access

To use the Apple Health integration, the following keys must be included in the Info.plist file: Privacy - Health Share Usage Description and Privacy - Health Records Usage Description


Samsung / Google Fit Access for versions (0.3.x +)

You will need to install Health Connect.

Then for Samsung Health:
Settings -> Health Connect -> Enable permissions for Samsung Health to Write/Read from Health Connect

For Google Fit:
Settings -> Health Connect -> Enable permissions for Google Fit to Write/Read from Health Connect

You will also need to include the following in your AndroidManifest:

    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />

To the Activity you wish to show when the user checks on your privacy policy page for Health Connect.

     android:resource="@array/health_permissions" />

To the activity you wish to request permissions and use Health Connect from


Samsung and Google Fit Access Pre 0.3.x

To use the Samsung integration, the user needs Health Platform downloaded on their device and their Samsung Health Account linked to Health Platform. This can be done by going on Samsung Health -> Profile -> Settings -> Connected Services -> Health Platform and giving Health Platform access to their data.

Google Fit
For Google Fit, the project's package name has to be registered your AndroidManifest.xml file with Google API. This requires creating a new project and a new set of Oauth credentials within on https://console.cloud.google.com. On project creating, the following scopes should be enabled:

People API


Fitness API


typeTerra integration connection type. Supports Connection.appleHealth , Connection.googleFit , Connection.samsung , Connection.freestyleLibre
tokenSingle-use authentication token generated from Generate Authentication Token. This ensures that terra credentials are not sitting on the client-side. *It is advised you securely generate the token from a backend.
customReadTypes (optional)A more granular set to control which sub-scopes the application would like to access (using HKObjectType types). Default value is empty.
schedulerOn (optional)Wether to use or not the terra scheduler to automatically fetch data to webhook. Default value is true.


Background Delivery on iOS

For iOS, you will need to do a few extra things:

  • Enable Background Delivery in HealthKit Entitlements
  • Add Background Modes as a Capability to your project and enable Background Fetch and Background Processing
  • Add the Permitted background task scheduler identifiers key to your info.plist with one item:
    • co.tryterra.data.post.request
  • Add Terra.setUpBackgroundDelivery() in your app delegate's didFinishLaunchingWithOptions delegate function, i.e:
 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        return true


That's all that's needed!

With these two functions, and the scheduler set to true, the application now automatically fetches data following the timers and sends it to your webhook!

Advanced Usage

TerraiOS provides a few other functions that enable further control of the application flow.

Get user id

To get the userId for a specific connection:

static Future<String?> getUserId(Connection connection) async

Getting Data

Instead of using the scheduler, it is possible to query data manually using the data getters. Five scopes are available: Athlete, Body, Daily, Sleep, and Nutrition

static Future<bool?> getActivity(Connection connection, DateTime startDate, DateTime endDate) async
static Future<bool?> getBody(Connection connection, DateTime startDate, DateTime endDate) async
static Future<bool?> getDaily(Connection connection, DateTime startDate, DateTime endDate) async
static Future<bool?> getNutrition(Connection connection, DateTime startDate, DateTime endDate) async
static Future<bool?> getSleep(Connection connection, DateTime startDate, DateTime endDate) async
static Future<bool?> getAthlete(Connection connection) async
typeTerra integration connection type. Supports Connection.appleHealth , Connection.googleFit , Connection.samsung ,
startDateDate object for start date of the data query
endDate (optional)Date object for end date of the data query. Default value is one day after startDate

Freestyle Libre - NFC functions

To use Freestyle Libre, additional functions are introduced for NFC control and sensor initialisation.

To read the sensor:

static Future<String?> readGlucoseData() async

To activate the sensor:

static Future<bool?> activateGlucoseSensor() async


Freestyle Libre - NFC access

To scan a freestyle sensor, the following keys must be included in the Info.plist file to enable NFC: Privacy-NFC Scan Usage Description