iOS (Swift)

iOS Functions

Initialization of Terra manager

TerraRT

Initializes the TerraRT instance with the provided developer ID and an optional reference ID.

init(devId: Swift.String, referenceId: Swift.String?, completion: @escaping (Swift.Bool) -> Swift.Void)

• devId: The developer ID used to authenticate and initialize TerraRT.

• referenceId: An optional reference ID for the initialization. Can be nil if not needed.

• completion: A closure that returns a Bool, indicating success (true) or failure (false) of the initialization.

Returns: An instance of TerraRT and executes the completion handler with the result of the initialization (success/failure).

Connection Setup

connectDevice

Connects to a Device.

func connectDevice(_ device: Device, _ connectionCallback: @escaping(Bool) -> Void)

• device: A device object returned from startBluetoothScan.

• connectionCallback: A completion function called when the connection is completed.

initConnection

Initialises a user with the Terra backend

func initConnection(token: String, completion: @escaping (Bool) -> Void = {(success) -> Void in})

• token: An authentication token.

• completion: A completion function called when the initialisation is complete.

disconnect

Disconnects from a connection.

func disconnect(type: Connections)

• type: Enum representing the connection to disconnect from.

startBluetoothScan

Starts a Bluetooth scan session

func startBluetoothScan(type: Connections, deviceCallback: @escaping (Device) -> Void)

Data Streaming

startRealtime

Starts streaming data for a given Connection type

func startRealtime(
    type: Connections, 
    dataType: Set<DataTypes>, 
    token: String, 
    callback: @escaping(Update) -> Void,
    connectionCallback: @escaping(Bool) -> Void
)
// alternative signature, used for streaming data locally without 
// sending data to Terra Websocket API
func startRealtime(
    type: Connections, 
    dataType: Set<DataTypes>, 
    callback: @escaping (Update) -> Swift.Void
)

• type: Enum representing the connection to make.

• dataType: Enum set of the data types to stream.

• token: A user token for authentication.

• callback: A callback for data reception.

• connectionCallback: A callback for connection success.

stopRealtime

Stops streaming for a given connection type

func stopRealtime(type: Connections)

---

iOS -> WatchOS Functions

The functions outlined in this section are only to be used in conjunction with an app running on watchOS, which uses the WatchOS Functions

Connection management

connectWithWatchOS

Initialise a connection with an Apple Watch

func connectWithWatchOS() throws

throws TerraError.FeatureNotSupported

setWatchOSConnectionStateListener

Sets a listener for changes in ConnectionState

func setWatchOSConnectionStateListener(listener: @escaping (ConnectionState) -> Void)

• listener: A listener function called depending on the state of the watch connection.

setWatchStateChangeListeners

Set watch state change listeners (for isPaired, isWatchAppInstalled, and isComplicationEnabled fields)

public func setWatchStateChangeListeners(isPairedListener: ((Bool) -> Void)?, isAppInstalledListener: ((Bool) -> Void)?, isComplicationEnabledListener: ((Bool) -> Void)?)

• isPairedListener: callback function for isPaired state changes.

• isAppInstalledListener: callback function for isWatchAppInstalled state changes.

• isComplicationEnabledListener: callback function for isComplicationEnabled state changes.

Recording session management

The functions below are to be used to manage sessions started on the WatchOS app, using startExercise

resumeWatchOSWorkout

Resume a workout if it is going on

public func resumeWatchOSWorkout(completion: @escaping (Bool) -> Void)

pauseWatchOSWorkout

Pauses a workout if it is going on

public func pauseWatchOSWorkout(completion: @escaping (Bool) -> Void)

stopWatchOSWorkout

Stops a workout if it is going on

public func stopWatchOSWorkout(completion: @escaping (Bool) -> Void)

Messaging

setMessageHandler

Set a message handler to handle the custom message sent from sendMessage function

public func setMessageHandler(_ messageHandler: @escaping([String: Any]) -> Void)

sendMessage

Send a message to the iOS Companion App

public func sendMessage(_ data: [String: Any])

• data: A dictionary of data to send to iOS Companion app.

---

WatchOS Functions

Initialization

Terra()

All functions below are to be called on an instance of the Terra class after it has been initialized (no input parameters)

Connection Setup

sharingDataAuthorised

func sharingDataAuthorised() -> Bool

Returns Bool depicting if user has granted writing Workout information to HealthKit.

connect

Connect to iOS companion app

func connect()

setWatchOSConnectionStateListener

Set a listener for changes in ConnectionState

func setWatchOSConnectionStateListener(listener: @escaping (ConnectionState) -> Void)

• listener: A listener function called depending on the state of the watch connection.

Data Streaming

startStream

Start observing for different data types and stream it to the iOS companion app

func startStream(forDataTypes dTypes: Set<ReadTypes>, completion: @escaping(Bool, TerraWatchOSError?) -> Void)

• dTypes: A set of all the types to start observing for.

• completion: Completion function indicating if the stream started successfully.

stopStream

Stop streaming to the iOS Companion app

func stopStream()

setUpdateHandler (WatchOS)

Set an update handler to receive data on the Watch App. Will only be triggered if startStream has been called

func setUpdateHandler(_ updateHandler: @escaping(Update) -> Void)

Recording Session Management

startExercise

Starts an exercise (HKWorkout) and streams to iOS Companion

func startExercise(forType workoutType: WorkoutTypes, completion: @escaping(Bool, TerraWatchOSError?) -> Void)

• workoutType: The workout type Enum to start exercise for.

• completion: Completion function indicating if the exercise started correctly.

pauseExercise

Pause the current running exercise session

func pauseExercise()

resumeExercise

Resumes a paused exercise session

func resumeExercise()

stopExercise

Stop the exercise (if one has been started)

func stopExercise(completion:  @escaping(Bool, TerraWatchOSError?) -> Void)

setWorkoutStateListener

Set an update handler to receive updates on the state of the workout. Useful when workout is paused/managed from the iOS app side

func setWorkoutStateListener(_ workoutStateListener: @escaping(WorkoutStates) -> Void)

---

Messaging

setMessageHandler (WatchOS)

Set a message handler to handle the custom message sent from sendMessage function

func setMessageHandler(_ messageHandler: @escaping([String: Any]) -> Void)

sendMessage (WatchOS)

Send a message to the iOS Companion App

func sendMessage(_ data: [String: Any])

• data: A dictionary of data to send to iOS Companion app.