React Native
Last updated
Was this helpful?
Last updated
Was this helpful?
Install the using npm (npm install terra-react
).
Complete the following iOS and/or Android setup.
The first step is to initialize the Terra SDK.
The initialization only needs to be done once on app start, (e.g. in your app.tsx
or an equivalent file), and ideally, and everytime the app is brought into the foreground. This ensures that the SDK is properly set up and ready to be used.
The SDK should be initialized every time your app is opened.
This is a necessary prerequisite for other SDK functions to run as expected
In your project, you should now be able to import function from the Terra Plugin. Here is an example:
In order to interact with the SDK, you need to call initTerra
first.
Call initTerra()
with the following arguments:
devId
: Your Developer ID provided by Terra.
referenceId
: An ID of your choice to identify your app user.
Find more details in the SDK Reference: Terra manager initialization function
(N.B This call is asynchronous, please ensure this is complete before using other SDK functions).
Once Terra is initialized, you can create a connection by calling the function initConnection()
to trigger a permission screen pop up.
From terra-react
, import initConnection
and call the function with the following arguments:
type
: Specify the connection type (e.g. Connections.APPLE_HEALTH
, Connections.SAMSUNG
, Connections.HEALTH_CONNECT
)
token
: A one-time authentication token generated from your backend server. This ensures secure communication between your app and the Terra servers.
customPermissions
: A set of permissions that define what data you want to request from Apple Health (e.g., heart rate, steps). If empty, it defaults to all available permissions.
schedulerOn
:
iOS: Defaults the Background Delivery option to true. This will make Terra send new data from the provider to your webhook automatically.
Android: To allow Terra to make scheduled requests whenever the app is in the foreground.
initConnection()
Apple Health only shows the permission popup once, so calling initConnection()
multiple times won’t trigger the popup again unless:
a. you call initConnection with an expanded set of customPermissions
b. the app is deleted & reinstalled.
initConnection
only needs to be called a single time.Health Connect prohibits the permission popup to appear more than once for any given permission, so calling initConnection
more than once will result in no action at all
The only case where it would re-appear is if:
you call initConnection with an expanded set of customPermissions
the app is deleted & reinstalled.
A permission that was not granted to use on release by Google has been requested by the app
Apple HealthKit implements the permissions popup as a WebView.
If your app is also based on a WebView, you will need to interrupt your WebView, call initConnection
, then upon completion re-open your WebView.
For Apple apps, you can enable background delivery settings to allow data to be synced even when your app is not brought to the foreground.
Go to your /ios
folder in the React Native project
Call the function setUpBackgroundDelivery
in your AppDelegate's didFinishLaunchingWithOptions
function
This will ensure you get updates for the user's Apple Health data automatically sent to your destination.
Now you'll start receiving health data events automatically to your Data Destination (e.g. webhook)!
You can also request historical data to backfill, to verify that data exists, or as a fallback.
You may set toWebhook
to false if you wish for the callback function to return the data payload on the client side.
You may write data into Apple Health (Health Connect not yet supported) through one of the helper functions in the SDK
device_data
must be passed in for postActivity to succeed.
To ensure a connection is still valid on the client side, use the method. This function returns the user_id
for the connection or null if none exists.
Check out the for details about all the functions in the SDK.
In order to disconnect an Apple Health user, you may use, called from your backend.
You can request for historical data using one of the
Check out the for details about all the functions in the SDK
In your terminal, cd to your /ios
folder, and run pod install
to install all the dependencies.
Add Capabilities:
Healthkit > Healthkit Background Delivery
Background Modes > Background processing
Background modes > Background fetch
Add the following keys to your info.plist:
1) Go to the /ios
directory of your project, open the .xcworkspace
in XCode.
2) Go to info.plist, and add the following keys and values:
Privacy - Health Share Usage Description
Description of how Health data is used
(Min 3 words)
Privacy - Health Records Usage Description
Description of how Health data is used
(Min 3 words)
Privacy - Health Update Usage Description
Description of how Health data is used
(Min 3 words)
Permitted background task scheduler
co.tryterra.data.post.request
1) In your RN app project, go to your /ios
folder
2) Go to info.plist, and add the following tags:
The Mobile SDK is ONLY used to connect to the following integrations:
Apple Health - iOS
Samsung Health - Android
Google Fit - Android. Note: the is the preferred way to connect to Google Fit until its sunsetting on June 30, 2025 due to better reliability
For ALL other integrations, please refer to the
Use this .
Check if a user_id
exists right after initializing the Terra SDK to see if the connection still exists.
Check if the User is Connected
If the function returns a user ID, the user is still connected, 🎉 keep vibing along!
If the function returns nil
, the user needs to reconnect.
Re-connect if Needed
If the connection is lost, you can call terra.initConnection()
again to re-establish the connection.
Calling terra.initConnection()
when the user is already connected or just needs a reconnection will not trigger any permission screens from Apple Health, and the user flow will remain uninterrupted. The connection will be re-established if necessary.
To be able to call the initConnection()
method, you need to pass a token
as an argument.
This token
is a single-use token created to ensure the authentication endpoint for creating a connection (and connecting the SDK to Terra's servers) does not get abused.
Generate the token with this endpoint POST
https://api.tryterra.co/v2/auth/generateAuthToken
. Make sure to call it with your Terra x-api-key
and dev-id
in the headers from your backend server. After you generate the token, provide the response to your client side using your own logic.
Go to the SDK Reference to find more details on the .
During the development phase, it it acceptable to place this call on the client side, exposing your API key in your mobile app.
For a production implementation, DO NOT expose your API key this way, and make sure to only make this call from your backend.