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

Installation

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>
ParameterDescription
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:

CustomPermissions.WORKOUT_TYPES
CustomPermissions.ACTIVITY_SUMMARY
CustomPermissions.LOCATION
CustomPermissions.CALORIES
CustomPermissions.STEPS
CustomPermissions.HEART_RATE
CustomPermissions.HEART_RATE_VARIABILITY
CustomPermissions.VO2MAX
CustomPermissions.HEIGHT
CustomPermissions.ACTIVE_DURATIONS
CustomPermissions.WEIGHT
CustomPermissions.FLIGHTS_CLIMBED
CustomPermissions.BMI
CustomPermissions.BODY_FAT
CustomPermissions.EXERCISE_DISTANCE
CustomPermissions.GENDER
CustomPermissions.DATE_OF_BIRTH
CustomPermissions.BASAL_ENERGY_BURNED
CustomPermissions.SWIMMING_SUMMARY
CustomPermissions.RESTING_HEART_RATE
CustomPermissions.BLOOD_PRESSURE
CustomPermissions.BLOOD_GLUCOSE
CustomPermissions.BODY_TEMPERATURE
CustomPermissions.LEAN_BODY_MASS
CustomPermissions.OXYGEN_SATURATION
CustomPermissions.SLEEP_ANALYSIS
CustomPermissions.RESPIRATORY_RATE
CustomPermissions.NUTRITION_SODIUM
CustomPermissions.NUTRITION_PROTEIN
CustomPermissions.NUTRITION_CARBOHYDRATES
CustomPermissions.NUTRITION_FIBRE
CustomPermissions.NUTRITION_FAT_TOTAL
CustomPermissions.NUTRITION_SUGAR
CustomPermissions.NUTRITION_VITAMIN_C
CustomPermissions.NUTRITION_VITAMIN_A
CustomPermissions.NUTRITION_CALORIES
CustomPermissions.NUTRITION_WATER
CustomPermissions.NUTRITION_CHOLESTEROL

🚧

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 https://console.cloud.google.com. On project creating, the following scopes should be enabled:

People API

openid
/auth/user.birthday.read
/auth/user.emails.read
/auth/user.gender.read
/auth/userinfo.email
/auth/userinfo.profile

Fitness API

/auth/fitness.activity.read
/auth/fitness.blood_glucose.read
/auth/fitness.blood_pressure.read
/auth/fitness.body.read
/auth/fitness/heart_rate.read
/auth/fitness.body_temperature.read
/auth/fitness.location.read
/auth/fitness.nutrition.read
/auth/fitness.oxygen_saturation.read
/auth/fitness.reproductive_health.read
/auth/fitness.sleep.read

ParameterDescription
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:
    • co.tryterra.data.post.request
  • 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)
ParameterDescription
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:

activateSensor()

❗️

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:

setUpBackgroundDelivery()