iOS (Swift)

SDK Installation

RealTime streaming on iOS is only available to those registered on the Apple Developer Program

Summary:

1. Add https://github.com/tryterra/TerraRTiOS as a package dependency

2. In your info.plist, add:

   1. Privacy - Bluetooth Always Usage Description: Justification for BLE usage (shown to the user when requesting permission)

   2. Privacy - Motion Usage Description: Justification for phone motion sensor usage (shown to the user when requesting permission - only add if using phone sensors for streaming)

When the app is launched for the first time, these permissions will be requested from the user.

---

Connection setup/management

The SDK revolves around the TerraRT class, which manages Bluetooth connections and real-time data streaming.

SDK Initialization

Always initialize the TerraRT class to begin using the SDK.

Do so every time the app is opened or brought into the foreground.

import TerraRTiOS

let developerId = "yourDeveloperId"
let referenceId: String? = "yourReferenceId"

let terraRT = TerraRT(devId: developerId, referenceId: referenceId) { success in
    if success {
        print("TerraRT initialization successful!")
    } else {
        print("TerraRT initialization failed.")
    }
}

Initializing a Connection

Register the phone by calling initConnection.

This connects the phone to Terra, allows you to use other SDK functions, and allows it to be a producer once a wearable is connected later on.

let token = "yourAuthToken"  // Generated from your backend

terraRT.initConnection(token: token) { success in
    if success {
        print("Connection initialized successfully!")
    } else {
        print("Failed to initialize connection.")
    }
}

To generate the token, make the below call from your backend

Generate a mobile SDK auth token

post

Creates a token to be used with initConnection() functions in the Terra mobile SDKs in order to create a user record for Apple Health or Samsung Health (or equivalent)

Authorizations

x-api-keystringRequired

Your API key for authentication

dev-idstringRequired

Your developer ID for authentication and tracking

Responses

200

200

application/json

statusstringOptionalExample: success

tokenstringOptionalExample: 250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d

expires_inintegerOptionalDefault: 0Example: 180

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/auth/generateAuthToken

POST /api/v2/auth/generateAuthToken HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: YOUR_API_KEY
Accept: */*

{
  "status": "success",
  "token": "250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d",
  "expires_in": 180
}

Connecting a device

iOS devices support connection via BLE or Apple Watch's WatchConnectivity protocol. For Apple Watch, refer to the WatchOS integration guide below.

The startBluetoothScan function returns a SwiftUI TerraBLEWidget view for device selection:

import SwiftUI
import TerraRTiOS

struct BluetoothScanView: View {
    @State private var scanWidget: TerraBLEWidget?
    @State private var connected = false

    var body: some View {
        VStack {
            if let widget = scanWidget {
                widget
            }

            if connected {
                Text("Device connected!")
                    .foregroundColor(.green)
            }

            Button("Start Bluetooth Scan") {
                scanWidget = terraRT.startBluetoothScan(type: .BLE) { success in
                    connected = success
                }
            }
        }
        .padding()
    }
}

---

Streaming Real-Time Data

Once the phone is registered and you've connected a wearable, you can stream data from the wearable to your mobile app.

Start Streaming

Call startRealtime to stream data to your app locally (without sending to Terra's server):

import TerraRTiOS

let connectionType: Connections = .BLE
let dataTypes: Set<DataTypes> = [.HEART_RATE, .STEPS]

terraRT.startRealtime(type: connectionType, dataType: dataTypes) { update in
    if let value = update.val {
        print("\(update.type ?? ""): \(value)")
    }
    if let dataArray = update.d {
        print("\(update.type ?? ""): \(dataArray)")
    }
}

To also send data to Terra's server, see the Your App → Terra guide.

Stop streaming and disconnect

terraRT.stopRealtime(type: .BLE)
terraRT.disconnect(type: .BLE)

---

WatchOS Integration

To receive a data stream from an Apple Watch, the watch must be instructed to initiate a data stream to the iOS phone it is paired with.

For that, you'll need to have a WatchOS companion app running on the watch, which runs startStream or startExercise

Setup

1. Create a WatchOS target within your iOS project:

   File -> New -> Target -> Watch App for iOS App.

2. Enable HealthKit and Background Modes for the WatchOS app, and add the following privacy keys to your Info.plist:

   1. Privacy - Health Share Usage Description

   2. Privacy - Health Update Usage Description

   3. Privacy - Health Records Usage Description

Start Streaming from WatchOS

Outside of a workout session, data recording frequency may be reduced. In order to capture data at the highest possible frequency, you'll want to start a workout session

On the iOS app, listen for updates from the WatchOS app using startRealtime with .WATCH_OS:

WatchOS app

import WatchKit
import TerraRTiOS

class InterfaceController: WKInterfaceController {
    var terra: Terra?

    override func awake(withContext context: Any?) {
        super.awake(withContext: context)

        do {
            terra = try Terra()
            terra?.connect()
            print("Terra SDK initialized on watchOS")
            startStreamingData()
        } catch {
            print("Failed to initialize Terra SDK: \(error)")
        }
    }

    func startStreamingData() {
        let dataTypes: Set<ReadTypes> = [.HEART_RATE, .STEPS]
        terra?.startStream(forDataTypes: dataTypes) { success, error in
            if success {
                print("Streaming started")
            } else {
                print("Failed: \(error?.localizedDescription ?? "Unknown error")")
            }
        }
    }

    func stopStreamingData() {
        terra?.stopStream()
    }
}

iOS app

import TerraRTiOS
import UIKit

class ViewController: UIViewController {
    var terraRT: TerraRT?

    override func viewDidLoad() {
        super.viewDidLoad()

        terraRT = TerraRT(devId: "your-dev-id", referenceId: "your-reference-id") { success in
            if success {
                print("Terra SDK initialized")
                self.setupWatchOSConnection()
            }
        }
    }

    func setupWatchOSConnection() {
        try? terraRT?.connectWithWatchOS()
        listenForDataFromWatch()
    }

    func listenForDataFromWatch() {
        let dataTypes: Set<DataTypes> = [.HEART_RATE, .STEPS]
        terraRT?.startRealtime(type: .WATCH_OS, dataType: dataTypes) { update in
            print("Watch update: \(update.type ?? ""): \(update.val ?? 0)")
        }
    }

    func stopRealtimeData() {
        terraRT?.stopRealtime(type: .WATCH_OS)
    }

    func disconnectWatchOS() {
        terraRT?.disconnect(type: .WATCH_OS)
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        stopRealtimeData()
        disconnectWatchOS()
    }
}

---

Streaming Workouts from WatchOS

The Apple Watch app can also manage a workout session, during which recording frequency is enhanced.

From the Watch: startExercise, stopExercise, pauseExercise, resumeExercise

From the iOS app: pauseWatchOSWorkout, resumeWatchOSWorkout, stopWatchOSWorkout

import WatchKit
import TerraRTiOS

class InterfaceController: WKInterfaceController {
    var terra: Terra?

    override func awake(withContext context: Any?) {
        super.awake(withContext: context)

        do {
            terra = try Terra()
            terra?.connect()
        } catch {
            print("Failed to initialize: \(error)")
        }
    }

    @IBAction func startExerciseTapped() {
        terra?.startExercise(forType: .RUNNING) { success, error in
            if success {
                print("Running exercise started")
            } else {
                print("Failed: \(error?.localizedDescription ?? "Unknown")")
            }
        }
    }

    @IBAction func pauseExerciseTapped() {
        terra?.pauseExercise()
    }

    @IBAction func resumeExerciseTapped() {
        terra?.resumeExercise()
    }

    @IBAction func stopExerciseTapped() {
        terra?.stopExercise { success, error in
            if success {
                print("Exercise stopped")
            } else {
                print("Failed: \(error?.localizedDescription ?? "Unknown")")
            }
        }
    }
}