iOS (Swift)
Initialization of Terra manager
Terra.instance
devId: String
➡ The developer identifier given to your after you signed up on TerrareferenceId: String?
➡ This is used by you to identify a user from your server to a terra usercompletion: @escaping (TerraManager?, TerraError?) -> Void
➡ A callback function that is called when the TerraManager class is initialised. If an error has occurred in creation, then the completion will return aTerraError
class. Highly recommended to wait for this callback before proceeding
Terra manager Instance methods
All methods below are used on the instance returned by Terra.instance
above.
Connection setup/management
initConnection
Initialises a connection for Apple Health
type: Connections
➡ An ENUM from the Connections class signifying the connection you wish to initiate for.token: String
➡ A token used for authentication. Generate one here: https://docs.tryterra.co/reference/generate-authentication-token(Optional)
customReadTypes: Set<CustomPermissions>
➡ used to customize the permissions list shown in the Apple Health popup when callinginitConnection
. When empty, it defaults to all available permissions.schedulerOn: Bool
➡ A boolean dictating if you wish turn on background delivery. Defaults to true. Please see Background Delivery section for setup.completion: @escaping (Bool, TerraError?) -> Void
➡ A callback with a boolean dictating if the initialisation succeeds.
setUpBackgroundDelivery
This function is expected to be run in your AppDelegate under didFinishLaunchingWithOptions
function.
Automatically sends data to Terra to be processed and to be to submitted to your destination.
getUserId
type: Connections
➡ The connection to retrieve the userId for
Data retrieval
getActivity
type: Connections
➡ The Connection to get data fromstartDate: Date
orstartDate: TimeInterval
➡ The beginning of the request in either Date or Unix TimestampendDate: Date
orendDate: TimeInterval
➡ The end of the request in either Date or Unix TimestamptoWebhook: Bool
➡ Whether or not to send data to your webhookcompletion: (Bool, TerraDailyDataPayloadModel?, TerraError?) -> Void
➡ callback function that runs after the request is completed. It has the following parameters:Bool
-> If the request was successful or not. If not, theTerraError
parameter will be returnedTerraDailyDataPayloadModel?
-> A payload for each data type. IftoWebhook
is set to true, this returns a class with a propertyreference
referring to the payload reference sent to your webhook. IftoWebhook
is set to false, then this returns the entire Terra normalised payload.TerraError?
-> Returned if any error occurred while retrieving data
getDaily
type: Connections
➡ The Connection to get data fromstartDate: Date
orstartDate: TimeInterval
➡ The beginning of the request in either Date or Unix TimestampendDate: Date
orendDate: TimeInterval
➡ The end of the request in either Date or Unix TimestamptoWebhook: Bool
➡ Whether or not to send data to your webhookcompletion: (Bool, TerraDailyDataPayloadModel?, TerraError?) -> Void
➡ callback function that runs after the request is completed. It has the following parameters:Bool
-> If the request was successful or not. If not, theTerraError
parameter will be returnedTerraDailyDataPayloadModel?
-> A payload for each data type. IftoWebhook
is set to true, this returns a class with a propertyreference
referring to the payload reference sent to your webhook. IftoWebhook
is set to false, then this returns the entire Terra normalised payload.TerraError?
-> Returned if any error occurred while retrieving data
getSleep
type: Connections
➡ The Connection to get data fromstartDate: Date
orstartDate: TimeInterval
➡ The beginning of the request in either Date or Unix TimestampendDate: Date
orendDate: TimeInterval
➡ The end of the request in either Date or Unix TimestamptoWebhook: Bool
➡ Whether or not to send data to your webhookcompletion: (Bool, TerraDailyDataPayloadModel?, TerraError?) -> Void
➡ callback function that runs after the request is completed. It has the following parameters:Bool
-> If the request was successful or not. If not, theTerraError
parameter will be returnedTerraDailyDataPayloadModel?
-> A payload for each data type. IftoWebhook
is set to true, this returns a class with a propertyreference
referring to the payload reference sent to your webhook. IftoWebhook
is set to false, then this returns the entire Terra normalised payload.TerraError?
-> Returned if any error occurred while retrieving data
getMenstruation
type: Connections
➡ The Connection to get data fromstartDate: Date
orstartDate: TimeInterval
➡ The beginning of the request in either Date or Unix TimestampendDate: Date
orendDate: TimeInterval
➡ The end of the request in either Date or Unix TimestamptoWebhook: Bool
➡ Whether or not to send data to your webhook`completion: (Bool, TerraMenstruationDataPayloadModel?, TerraError?) -> Void ➡ callback function that runs after the request is completed. It has the following parameters:
Bool
-> If the request was successful or not. If not, a TerraError instance will also be calledTerraMenstruationDataPayloadModel?
-> A payload for each data type. IftoWebhook
is set to true, this returns a class with a propertyreference
referring to the payload reference sent to your webhook. IftoWebhook
is set to false, then this returns the entire Terra normalised payload.TerraError?
-> Returned if any error occurred while retrieving data
getAthlete
type: Connections
➡ The Connection to get data fromtoWebhook: Bool
➡ Whether or not to send data to your webhook`completion: (Bool, TerraAthleteDataPayloadModel?, TerraError?) -> Void ➡
Bool
-> If the request was successful or not. If not, a TerraError instance will also be calledTerraAthleteDataPayloadModel?
-> A payload for each data type. IftoWebhook
is set to true, this returns a class with a propertyreference
referring to the payload reference sent to your webhook. IftoWebhook
is set to false, then this returns the entire Terra normalised payload.TerraError?
-> Returned if any error occurred while retrieving data
subscribe
You can subscribe for individual datatypes as follows (only needs to be done once).
After you have confirmed a connection with Apple Health, you can pass us an update handler ideally in your app delegate's didFinishLaunchingWithOptions function, so it is set everytime the app launches. This can be done as such:
After the call, your update handler will be called with the corresponding datatypes whenever new ones are available. This includes the next time you open your app.
Scenario: You subscribed for steps data. You close your app and do not go back for 5 days. The next time you open it, your update handler will be called with all 5 days worth of steps, without you needing to query for it and would execute a lot faster as it is only steps.
Writing data
postActivity
Write activity data into Apple Health or other supported connections.
Description: This function allows you to write activity data into Apple Health. Internally uses HKWorkout
Parameters:
type: The connection type (
TerraiOS.Connections
) for which to post the data. For example, use.APPLE_HEALTH
to write data to Apple Health.payload: A
TerraiOS.TerraActivityData
object that contains the activity data you wish to post. This can include details such as activity type, heart rate, distance, calories, and other relevant activity metrics.completion: A closure that returns a
Bool
indicating the success (true
) or failure (false
) of the post operation, along with an optionalTerraiOS.TerraError
to indicate any error that occurred.
postNutrition
Write nutrition data into Apple Health
Description: This function allows you to
Parameters:
type
: The connection type (TerraConnections
) for which to post the data. E.g.,Connections.APPLE
.payload
: ATerraNutritionData
object that contains the nutrition data you wish to post.completion
: A closure that returns aBool
indicating the success or failure of the post operation.
postBody
Write body composition data into Apple Health
type
: The connection type (TerraConnections
) for which to post the data. E.g.,Connections.APPLE
.payload
: ATerraBodyData
object that contains the body data (e.g., oxygen, glucose, heart rate) you wish to post.completion
: A closure that returns aBool
indicating whether the post operation was successful.
postPlannedWorkout
Write planned workouts to Apple Health, for syncing scheduled workouts to the Workout app on Apple Watch.
Parameters:
type
: The connection type (TerraConnections
) for which to post the workout. E.g.,Connections.APPLE
.payload
: ATerraPlannedWorkout
object containing the workout steps and metadata.completion
: A closure that returns aBool
indicating the success or failure of the post operation and an optionalTerraError
if applicable.
Was this helpful?