iOS (Swift)

Initialization of Terra manager

Terra.instance

Terra.instance(devId: String, 
               referenceId: String?, 
               completion: @escaping (TerraManager?, TerraError?) -> Void)

• devId: String ➡ The developer identifier given to your after you signed up on Terra

• referenceId: String? ➡ This is used by you to identify a user from your server to a terra user

• completion: @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 a TerraError 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

func initConnection(type: Connections, 
               token: String, 
               customReadTypes: Set<CustomPermissions>, 
               schedulerOn: Bool, 
               completion: @escaping (Bool, TerraError?) -> Void))

• 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 calling initConnection. 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.

func setUpBackgroundDelivery() -> Void

Automatically sends data to Terra to be processed and to be to submitted to your destination.

getUserId

func getUserid(type: Connections) -> String?

• type: Connections ➡ The connection to retrieve the userId for

Data retrieval

getActivity

func getActivity(type: Connections, 
         startDate: Date, 
         endDate: Date, 
         toWebhook: Bool, 
         completion: @escaping (Bool, TerraActivityDataPayloadModel?, TerraError?) -> Void)

• type: Connections ➡ The Connection to get data from

• startDate: Date or startDate: TimeInterval ➡ The beginning of the request in either Date or Unix Timestamp

• endDate: Date or endDate: TimeInterval ➡ The end of the request in either Date or Unix Timestamp

• toWebhook: Bool ➡ Whether or not to send data to your webhook

• completion: (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, the TerraError parameter will be returned

  • TerraDailyDataPayloadModel? -> A payload for each data type. If toWebhook is set to true, this returns a class with a property reference referring to the payload reference sent to your webhook. If toWebhook is set to false, then this returns the entire Terra normalised payload.

  • TerraError? -> Returned if any error occurred while retrieving data

getDaily

func getDaily(type: Connections, 
         startDate: Date, 
         endDate: Date, 
         toWebhook: Bool, 
         completion: @escaping (Bool, TerraDailyDataPayloadModel?, TerraError?) -> Void)

• type: Connections ➡ The Connection to get data from

• startDate: Date or startDate: TimeInterval ➡ The beginning of the request in either Date or Unix Timestamp

• endDate: Date or endDate: TimeInterval ➡ The end of the request in either Date or Unix Timestamp

• toWebhook: Bool ➡ Whether or not to send data to your webhook

• completion: (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, the TerraError parameter will be returned

  • TerraDailyDataPayloadModel? -> A payload for each data type. If toWebhook is set to true, this returns a class with a property reference referring to the payload reference sent to your webhook. If toWebhook is set to false, then this returns the entire Terra normalised payload.

  • TerraError? -> Returned if any error occurred while retrieving data

getSleep

func getSleep(type: Connections, 
         startDate: Date, 
         endDate: Date, 
         toWebhook: Bool, 
         completion: @escaping (Bool, TerraSleepDataPayloadModel?, TerraError?) -> Void)

• type: Connections ➡ The Connection to get data from

• startDate: Date or startDate: TimeInterval ➡ The beginning of the request in either Date or Unix Timestamp

• endDate: Date or endDate: TimeInterval ➡ The end of the request in either Date or Unix Timestamp

• toWebhook: Bool ➡ Whether or not to send data to your webhook

• completion: (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, the TerraError parameter will be returned

  • TerraDailyDataPayloadModel? -> A payload for each data type. If toWebhook is set to true, this returns a class with a property reference referring to the payload reference sent to your webhook. If toWebhook is set to false, then this returns the entire Terra normalised payload.

  • TerraError? -> Returned if any error occurred while retrieving data

getMenstruation

func getMensturation(type: Connections, 
         startDate: Date, 
         endDate: Date, 
         toWebhook: Bool, 
         completion: @escaping (Bool, TerraMenstruationDataPayloadModel?, TerraError?) -> Void)

• type: Connections ➡ The Connection to get data from

• startDate: Date or startDate: TimeInterval ➡ The beginning of the request in either Date or Unix Timestamp

• endDate: Date or endDate: TimeInterval ➡ The end of the request in either Date or Unix Timestamp

• toWebhook: 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 called

  • TerraMenstruationDataPayloadModel? -> A payload for each data type. If toWebhook is set to true, this returns a class with a property reference referring to the payload reference sent to your webhook. If toWebhook is set to false, then this returns the entire Terra normalised payload.

  • TerraError? -> Returned if any error occurred while retrieving data

getAthlete

func getAthlete(type: Connections, 
         toWebhook: Bool, 
         completion: @escaping (Bool, TerraAthleteDataPayloadModel?, TerraError?) -> Void)

• type: Connections ➡ The Connection to get data from

• toWebhook: 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 called

  • TerraAthleteDataPayloadModel? -> A payload for each data type. If toWebhook is set to true, this returns a class with a property reference referring to the payload reference sent to your webhook. If toWebhook is set to false, then this returns the entire Terra normalised payload.

  • TerraError? -> Returned if any error occurred while retrieving data

subscribe

func subscribe(forDataTypes: Set<DataTypes>, 
                completion: @escaping(Bool, TerraError?) -> Void)

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:

Terra.updateHandler = {type: DataTypes, update: Update -> Void in 
  // process updates in here
}

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.

func postActivity(
    type: TerraiOS.Connections,
    payload: TerraiOS.TerraActivityData,
    completion: @escaping (Swift.Bool, TerraiOS.TerraError?) -> Swift.Void = { _, _ in }
)

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 optional TerraiOS.TerraError to indicate any error that occurred.

postNutrition

Write nutrition data into Apple Health

func postNutrition(
    type: TerraiOS.Connections,
    payload: TerraiOS.TerraNutritionData,
    completion: @escaping (Swift.Bool) -> Swift.Void = { _ in }
)

Description: This function allows you to

Parameters:

• type: The connection type (TerraConnections) for which to post the data. E.g., Connections.APPLE.

• payload: A TerraNutritionData object that contains the nutrition data you wish to post.

• completion: A closure that returns a Bool indicating the success or failure of the post operation.

postBody

Write body composition data into Apple Health

final public func postBody(
    type: TerraiOS.Connections,
    payload: TerraiOS.TerraBodyData,
    completion: @escaping (Swift.Bool) -> Swift.Void = { _ in }
)

• type: The connection type (TerraConnections) for which to post the data. E.g., Connections.APPLE.

• payload: A TerraBodyData object that contains the body data (e.g., oxygen, glucose, heart rate) you wish to post.

• completion: A closure that returns a Bool 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.

@available(iOS 17, *)
final public func postPlannedWorkout(
    type: TerraiOS.Connections,
    payload: TerraiOS.TerraPlannedWorkout,
    completion: @escaping (Swift.Bool, TerraiOS.TerraError?) -> Swift.Void
)

Parameters:

• type: The connection type (TerraConnections) for which to post the workout. E.g., Connections.APPLE.

• payload: A TerraPlannedWorkout object containing the workout steps and metadata.

• completion: A closure that returns a Bool indicating the success or failure of the post operation and an optional TerraError if applicable.