Android (Kotlin)
Last updated
Was this helpful?
Last updated
Was this helpful?
This guide will walk you through the necessary steps to use the Terra SDK with Android-based integrations in your Android app. It covers everything from SDK initialization, user connection, permission handling, and background data updates.
The TerraAndroid SDK supports the following integrations:
Samsung Health
Health Connect
build.gradle
Inside the dependencies section of your build.gradle
file, add the following line of code.
You can find the latest version number on .
build.gradle
Sync your project with Gradle by clicking on the "Sync Project with Gradle Files" button in the toolbar. This will download the TerraAndroid SDK and make it available to your project.
Your app build config must be for Android 28 (minSDK 28) and above.
The device must have the required app installed, e.g. Health Connect or Samsung Health
Terra API provides direct access to the Samsung Health SDK via our privileged partnership with Samsung.
If you'd like to apply for Samsung Health access, please reach out to us by submitting a ticket on the Terra Support page. You can find this in your Terra Dashboard!
The initialization only needs to be done once on app start, (e.g. in your MainActivity
file or equivalent), and every time 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 started.
This is a necessary prerequisite for other SDK functions to run as expected
Terra
and TerraManager
In your Android Studio project, you should now be able to import classes from the Terra SDK.
TerraManager
Instance(N.B This call is asynchronous, please ensure this is complete before using the manager).
Once Terra is initialized, you can create a connection (e.g. Samsung Health or Health Connect).
This method triggers the a permission popup and establishes the connection.
type
: Specify the connection type (e.g. Connections.SAMSUNG
or Connections.HEALTH_CONNECT
)
token
: A one-time authentication token generated from your backend server using Terra API. 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 the Android SDKs (e.g., heart rate, steps). If empty, it defaults to all available permissions.
schedulerOn
: To allow Terra to make scheduled requests whenever the app is in the foreground.
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:
a. you call initConnection with an expanded set of customPermissions
b. the app is deleted & reinstalled.
c. a permission that was not granted to use on release by Google has been requested by the app
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.
Use this .
To do this, run the as below:
Call from the TerraManager
instance you've created above to have the corresponding permission screen pop up.
From the TerraManager
instance, call with the following arguments:
To learn more about these parameters and their different options, check the
To ensure a connection is still valid on the client side, use the method. This function is synchronous and returns the user_id
right away or null if none exists.
Check out the for details about all the functions in the SDK.
In order to disconnect an SDK user, you may use , called from your backend.
You can request for historical data using one of the .
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.
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
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.