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
orpod update
Apple Health Integration Setup for iOS
If you want to connect to Apple Health, additional steps are required.
- Using XCode, open the
.xcodeproj
project for the app. This is typically found atios/<YOUR PROJECT NAME>.xcodeproj
from the root directory of your project. - Add Privacy Keys:
Go to main app folder > Click on the icon below TARGETS on the sidebar > click onInfo
on menu bar > go to Custom iOS Target Properties > hover over any key and click+
button > addPrivacy - Health Share Usage Description
and set values for each > add key arrayPermitted background task scheduler identifiers
and add itemco.tryterra.data.post.request
- 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 yourinfo.plist
with one item:
co.tryterra.data.post.request
- Run
setUpBackgroundDelivery
in your AppDelegate'sdidFinishLaunchingWithOptions
function:#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
- The SDK requires Health Connect to function. Make sure it is installed on your user's devices.
- In the Health Connect app, give all permissions between the app you wish to read from and Health Connect.
- Navigate to your project's
AndroidManifest.xml
file. It is typically located atandroid/app/src/main/AndroidManifest.xml
from the root directory of your project. - 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>
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>
- 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"/>
- Update your proguard ules:
-keep class co.tryterra.** {; }
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>
Parameter | Description |
---|---|
devId | Your terra developer ID. You can find it in your terra dashboard (see Customize API settings) |
referenceId | An identifier that allows you to map the terra user id to one of your users |
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>
Parameter | Description |
---|---|
connection | Terra integration connection type. Supports Connections.APPLE_HEALTH , Connections.FREESTYLE_LIBRE , Connections.GOOGLE , Connections.SAMSUNG |
token | Single-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 | Wether to use or not the terra scheduler to automatically fetch data to webhook. |
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 |
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.
Updated 18 days ago