React Native project

If you have a react native application, you can use the terra-react NPM 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:

npm install terra-react
yarn install terra-react

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

import {...} from 'terra-react'


Pod setup

For iOS, when updating to a newer version, you might also have to set up pods! In the iOS directly, run: pod install or pod update

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

function initTerra(
  devID: string,
  referenceId: string,
): Promise<any>
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
promise callbackReturns success

Connect an integration

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

function initConnection(
  connection: Connections,
  token: string,
  schedulerOn: boolean,
  customPermissions: CustomPermissions[] = [],
  startIntent: String | null = null
): Promise<any>


Custom Permissions

We provide a basically one to one mapping to Health Kit permissions enum CustomPermissions so that you do not need to deal with HealthKit whatsoever! The types are:



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 access

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 access

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 On project creating, the following scopes should be enabled:

People API


Fitness API


typeTerra integration connection type. Supports Connections.APPLE_HEALTH, Connections.FREESTYLE_LIBRE, Connections.GOOGLE, Connections.SAMSUNG
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.
schedulerOn (optional)Wether to use or not the terra scheduler to automatically fetch data to webhook. Default value is true.
customPermissions (optional)A more granular set to control which sub-scopes the application would like to access (using HKObjectType types). Default value is empty.
startIntent (optional)This is meant for Freestylelibre users who are planning to implement the "Background scanning" for sensors in Android. This is essentially a string pathway to the Activity you wish to display to the user when they scan an a Freestylelibre tag. For more information please see initConnection from TerraAndroid


Background Delivery for 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:
  • Run Terra.setUpBackgroundDelivery() in your AppDelegate's didFinishLaunchingWithOptions function


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:

getUserId(connection: Connections): Promise<any>

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

getActivity(connection: Connections, startDate: Date, endDate: Date): Promise<any>
getBody(connection: Connections, startDate: Date, endDate: Date): Promise<any>
getDaily(connection: Connections, startDate: Date, endDate: Date): Promise<any>
getNutrition(connection: Connections, startDate: Date, endDate: Date): Promise<any>
getSleep(connection: Connections, startDate: Date, endDate: Date): Promise<any>
getAthlete(connection: Connections)
typeTerra integration connection type. Supports Connections.APPLE_HEALTH, Connections.GOOGLE, Connections.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
callback (optional)Callback containing a success boolean

Freestyle Libre - NFC functions

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

To scan a Freestyle Libre 1 sensor, an NFC scan session has to be started by the app. This can be accomplished using:

readGlucoseData(): Promise<any>

The app can also activate a sensor:



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

Background delivery

To start the background delivery functionality: