React Native

SDK Installation

If you have a react native application, you can use the terra-react NPM to access SDK 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 {initTerra, initConnection, Connections, getUserId, <other functions>} from 'terra-react'

📘

Pod setup

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

Apple Health Integration Setup for iOS

If you want to connect to Apple Health, additional steps are required.

1. Using XCode, open the .xcodeproj project for the app. This is typically found at ios/<YOUR PROJECT NAME>.xcodeproj from the root directory of your project.
2. Add Privacy Keys:
   Go to main app folder > Click on the icon below TARGETS on the sidebar > click on Info on menu bar > go to Custom iOS Target Properties > hover over any key and click + button > add Privacy - Health Share Usage Description and set values for each > add key array Permitted background task scheduler identifiers and add item co.tryterra.data.post.request
3. Add HealthKit as a Capability to your project. Enable the Background Delivery option. See the Apple Developer Docs for a detailed walkthrough.

📘

Background Delivery for iOS

Enabling Background Delivery for your app will allow it to send new data to your server backend through Terra even when it is not running in the foreground.

To enable Background Delivery for your app:

• 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
• RunsetUpBackgroundDelivery in your AppDelegate's didFinishLaunchingWithOptions function:

AppDelegate.mm

#import "AppDelegate.h"

#import <React/RCTBundleURLProvider.h>
#import <TerraiOS/TerraiOS-Swift.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  self.moduleName = @"AwesomeProject";
  // You can add your custom initial props in the dictionary below.
  // They will be passed down to the ViewController used by React Native.
  self.initialProps = @{};
  [Terra setUpBackgroundDelivery];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

Samsung/Google Fit Integration Setup for Android

Health Connect Setup

1. The SDK requires Health Connect to function. Make sure it is installed on your user's devices.
2. In the Health Connect app, give all permissions between the app you wish to read from and Health Connect.
3. Navigate to your project's AndroidManifest.xml file. It is typically located at android/app/src/main/AndroidManifest.xml from the root directory of your project.
4. In your AndroidManifest.xml include the following under the Activity you wish to display to the user when user wants to see your app's privacy policy:

<intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
<intent-filter>
  <action android:name="android.intent.action.VIEW_PERMISSION_USAGE"/>
  <category android:name="android.intent.category.HEALTH_PERMISSIONS"/>
</intent-filter>

5. In your AndroidManifest.xml include the following to the Activity you wish to request permissions for Health Connect from:

 <meta-data
     android:name="health_permissions"
     android:resource="@array/health_permissions" />

For example, you could add them to the MainActivity activity so both will run when the user launches your app:

<activity
	android:name=".MainActivity"
  android:exported="true"
  android:label="@string/app_name"
  android:theme="@style/Theme.<YOUR_APP_NAME>">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
  </intent-filter>
  <intent-filter>
    <action android:name="android.intent.action.VIEW_PERMISSION_USAGE"/>
    <category android:name="android.intent.category.HEALTH_PERMISSIONS"/>
  </intent-filter>
</activity>

6. Add wanted permissions on AndroidManifest:

    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_STEPS"/>
    <uses-permission android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_BASAL_METABOLIC_RATE"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE"/>
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE"/>
    <uses-permission android:name="android.permission.health.READ_BODY_FAT"/>
    <uses-permission android:name="android.permission.health.READ_BODY_TEMPERATURE"/>
    <uses-permission android:name="android.permission.health.READ_BODY_WATER_MASS"/>
    <uses-permission android:name="android.permission.health.READ_BONE_MASS"/>
    <uses-permission android:name="android.permission.health.READ_DISTANCE"/>
    <uses-permission android:name="android.permission.health.READ_ELEVATION_GAINED"/>
    <uses-permission android:name="android.permission.health.READ_EXERCISE"/>
    <uses-permission android:name="android.permission.health.READ_FLOORS_CLIMBED"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY"/>
    <uses-permission android:name="android.permission.health.READ_HEIGHT"/>
    <uses-permission android:name="android.permission.health.READ_HYDRATION"/>
    <uses-permission android:name="android.permission.health.READ_LEAN_BODY_MASS"/>
    <uses-permission android:name="android.permission.health.READ_MENSTRUATION"/>
    <uses-permission android:name="android.permission.health.READ_NUTRITION"/>
    <uses-permission android:name="android.permission.health.READ_OXYGEN_SATURATION"/>
    <uses-permission android:name="android.permission.health.READ_POWER"/>
    <uses-permission android:name="android.permission.health.READ_RESPIRATORY_RATE"/>
    <uses-permission android:name="android.permission.health.READ_RESTING_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_SLEEP"/>
    <uses-permission android:name="android.permission.health.READ_SPEED"/>
    <uses-permission android:name="android.permission.health.READ_STEPS_CADENCE"/>
    <uses-permission android:name="android.permission.health.READ_SWIMMING_STROKES"/>
    <uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED"/>
    <uses-permission android:name="android.permission.health.READ_VO2_MAX"/>
    <uses-permission android:name="android.permission.health.READ_WEIGHT"/>

🚧

Going LIVE

Before going LIVE (release), you will need to apply for permissions to access the Health Connect API with Google. Use this application form.

In the form, you will need to specify which data types you intend to read from Health Connect.

For each permission which you are not using, please add the following lines to your AndroidManifest.xml

<uses-permission android:name="android.permission.health.READ_HEART_RATE" tools:node="remove"/>

Initialise Terra

The next 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<SuccessMessage>

Where SuccessMessage is:

export type SuccessMessage = {
  success: Boolean;
  error: String | null;
};

Connect an integration

🚧

Currently only Libre 1, Pro/H and Libre 2 (UK) are supported!

Libre 2 US and Libre14Days US are not supported currently

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

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

Once everything is set with schedulerOn, the SDK will send data to your server automatically without needing you to do anything else!

Test Authentication

To ensure a specific connection is still valid, use the checkAuth() method.

function checkAuth(connection: Connections, devId: string): Promise<Object>
// Object takes the form {success: Boolean;}

In order to check the connection is still valid, you can use the checkAuth() method. You should occasionally use this method to check the connection (only implemented for iOS)

Getting Data

If you have initialised your connection to a provider with schedulerOn as true, you will automatically receive new data from the provider at your webhook when it becomes available. For more information, checkout the Receiving Data guide.

To manually get historical data, you can use a getter function. See the React Native SDK reference for the full list of possible functions.

function getNutrition(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: Boolean = true
): Promise<DataMessage>
    
export type DataMessage = {
  success: Boolean;
  data: Object;
  error: String | null;
};

The data field of the DataMessage will be an object in the form of one of the V2 data models, depending on what data the request was made for.