iOS (Swift)
The iOS SDK allows you to seamlessly send data from iOS to your backend or to your app directly!
Last updated
Was this helpful?
The iOS SDK allows you to seamlessly send data from iOS to your backend or to your app directly!
Last updated
Was this helpful?
This guide will walk you through the necessary steps to integrate the Terra Mobile SDK with Apple Health in your iOS app. It covers everything from SDK initialization, user connection, permission handling, and background data updates.
The TerraiOS
SDK supports the following integrations:
Apple Health
Add https://github.com/tryterra/TerraiOS
as a package dependency to your Xcode project.
Add Capabilities:
Healthkit > Healthkit Background Delivery
Background Modes > Background processing
Background modes > Background fetch
In your info.plist, add the following:
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
The first step is to initialize the Terra SDK. This is done by creating a TerraManager
instance which allows you to interact with the Terra SDK.
The initialization only needs to be done once on app start, (e.g. in your ContentView.swift
or an equivalent file), and ideally, whenever the app is brought into the foreground. This ensures that the SDK is properly set up and ready to be used.
In your Xcode project, you should now be able to import Terra SDK
TerraManager
InstanceIn order to interact with the SDK, you need a TerraManager
instance.
Call Terra.instance()
with the following arguments:
devId
: Your Developer ID provided by Terra.
referenceId
: An ID of your choice to identify your app user.
completion
: Callback with a TerraManager
or an instance TerraError
The TerraManager
instance is thereafter ready to be used to call SDK functions!
(N.B This call is asynchronous, please ensure this is complete before using the manager).
This method triggers the Apple Health permission popup and establishes the connection.
type
: Specify the connection type as .APPLE_HEALTH
to connect the Apple Health account.
token
: A one-time authentication token generated from your backend server using the /auth/generateAuthToken endpoint. This ensures secure communication between your app and the Terra servers.
customReadTypes
: 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
: Defaults the Background Delivery option to true. This will make Terra send new data from the provider to your data destination (e.g. webhook) automatically.
After a successful call of initConnection()
with a valid token, an Apple Permission screen will pop up!
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.
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.
Go to 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.
Go to the main entry point of your app, and initialize the TerraiOS SDK.
Define the core functions of the SDK that you need to use, e.g. getUserId()
, intiConnection()
The getter functions are asynchronous, so include a callback as in the example above.
You may write other types of data into Apple Health through one of the helper functions in the SDK
device_data
must be passed in for postActivity to succeed.
Find more details in the SDK Reference:
Once you’ve initialized the SDK, you can connect the Apple Health user. This is done by calling the method provided by the TerraManager
instance that you created above.
From TerraManager
, 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, make sure to use the from TerraManager
every time you reinitialize the SDK. This function is synchronous and returns a user_id
right away if a user is connected or nil if none exists.
Add
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 . You may set toWebhook
to false if you wish for the callback function to return the data payload on the client side.
: allows you to write a completed activity to a user's Apple Health
: allows you to write a nutrition log to a user's Apple Health
: allows you to write a body measurement to a user's Apple Health
: allows you to write a workout plan to a user's Apple Health
In order to write a completed activity to a user's Apple Health, use the function as below, with the .
In order to write Body Measurement data to a user's Apple Health, use the function as below, with the .
In order to write Nutrition log to a user's Apple Health, use the function as below, with the
In order to write a planned workout for the user to follow on their Apple Watch, use the function as below, with the .
Writing planned workouts allows you to create a workout plan for the user (such as those ).
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
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.
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.