> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/streaming-api/ios-swift.md).

# iOS SDK

Connect a BLE wearable or Apple Watch to your iOS app with TerraRTiOS, then stream its data to Terra.

## Install the SDK

{% hint style="danger" %}
**RealTime streaming on iOS is only available to those registered on the** [**Apple Developer Program**](https://developer.apple.com/programs/enroll/)
{% endhint %}

{% embed url="<https://app.arcade.software/share/FYXtrn9eKX2WqnmrTmNU>" %}

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.

***

## Set up the connection

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

### Initialize the SDK

{% hint style="info" %}
Always initialize the `TerraRT` class to begin using the SDK.

Do so every time the app is opened or brought into the foreground.
{% endhint %}

```swift
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.")
    }
}
```

### Register the phone

Register the [phone](https://docs.tryterra.co/introduction/core-concepts#streaming-api) by calling [`initConnection`](https://docs.tryterra.co/reference/streaming-api/ios-swift#initconnection).

This connects the [phone](https://docs.tryterra.co/introduction/core-concepts#streaming-api) to Terra, allows you to use other SDK functions, and allows it to be a [producer](https://docs.tryterra.co/introduction/core-concepts#streaming-api) once a [wearable](https://docs.tryterra.co/introduction/core-concepts#streaming-api) is connected later on.

```swift
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**

{% openapi src="<https://raw.githubusercontent.com/tryterra/openapi/refs/heads/master/dist/core/v2-bundled.yaml>" path="/auth/generateAuthToken" method="post" %}
<https://raw.githubusercontent.com/tryterra/openapi/refs/heads/master/dist/core/v2-bundled.yaml>
{% endopenapi %}

### Connect a device

iOS devices support connection via BLE or Apple Watch's WatchConnectivity protocol. For Apple Watch, see [Stream from an Apple Watch](#stream-from-an-apple-watch).

The [`startBluetoothScan`](https://docs.tryterra.co/reference/streaming-api/ios-swift#startbluetoothscan-with-built-in-ui) function returns a SwiftUI `TerraBLEWidget` view for device selection:

```swift
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()
    }
}
```

***

## Stream data to your app

Once the [phone is registered](#register-the-phone) and you've [connected a wearable](#connect-a-device), you can stream data from the wearable to your mobile app.

### Start streaming

Call [`startRealtime`](https://docs.tryterra.co/reference/streaming-api/ios-swift#startrealtime-local-only) to stream data to your app locally (without sending to Terra's server):

```swift
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 [Stream to Terra](#stream-to-terra).

### Stop streaming and disconnect

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

***

## Stream from an Apple Watch

{% hint style="info" %}
To receive a data stream from an Apple Watch, the watch must be instructed to initiate a data stream to the iOS [phone](https://docs.tryterra.co/introduction/core-concepts#streaming-api) it is paired with.

For that, you'll need to have a WatchOS companion app running on the watch, which runs [`startStream`](https://docs.tryterra.co/reference/streaming-api/ios-swift#startstream) or [`startExercise`](https://docs.tryterra.co/reference/streaming-api/ios-swift#startexercise)
{% endhint %}

### Add a watchOS target

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 the watch

{% hint style="info" %}
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](#stream-workouts-from-the-watch)
{% endhint %}

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

{% tabs %}
{% tab title="WatchOS app" %}

```swift
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()
    }
}
```

{% endtab %}

{% tab title="iOS app" %}

```swift
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()
    }
}
```

{% endtab %}
{% endtabs %}

### Stream workouts from the watch

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

From the Watch: [`startExercise`](https://docs.tryterra.co/reference/streaming-api/ios-swift#startexercise), [`stopExercise`](https://docs.tryterra.co/reference/streaming-api/ios-swift#stopexercise), [`pauseExercise`](https://docs.tryterra.co/reference/streaming-api/ios-swift#pauseexercise), [`resumeExercise`](https://docs.tryterra.co/reference/streaming-api/ios-swift#resumeexercise)

From the iOS app: [`pauseWatchOSWorkout`](https://docs.tryterra.co/reference/streaming-api/ios-swift#pausewatchosworkout--resumewatchosworkout--stopwatchosworkout), [`resumeWatchOSWorkout`](https://docs.tryterra.co/reference/streaming-api/ios-swift#pausewatchosworkout--resumewatchosworkout--stopwatchosworkout), [`stopWatchOSWorkout`](https://docs.tryterra.co/reference/streaming-api/ios-swift#pausewatchosworkout--resumewatchosworkout--stopwatchosworkout)

```swift
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")")
            }
        }
    }
}
```

***

## Stream to Terra

Once data from the wearable reaches your app, you can also send it to Terra's websocket server (the [broker](https://docs.tryterra.co/introduction/core-concepts#streaming-api)). Your backend then receives it through a [backend consumer](https://docs.tryterra.co/streaming-api/terra-greater-than-your-backend.md).

To do this, use the `startRealtime` overload that accepts a `token` in place of the [local-only call](#start-streaming):

```swift
import TerraRTiOS

// Assumes terraRT is already initialized and a device is connected
// (see the sections above)

let token = "yourStreamingToken"  // Generated from your backend (see below)
let dataTypes: Set<TerraRTiOS.DataTypes> = [.HEART_RATE, .STEPS]

// Stream to BOTH your app AND Terra's websocket server
terraRT.startRealtime(
    type: .BLE,
    dataType: dataTypes,
    token: token,
    callback: { update in
        print("\(update.type ?? ""): \(update.val ?? 0) at \(update.ts ?? "")")
    },
    connectionCallback: { connected in
        print("Websocket connected: \(connected)")
    }
)
```

Pass in a token from the following endpoint, and the SDK streams the same data you were reading in your app to the broker.

{% openapi src="<https://raw.githubusercontent.com/tryterra/openapi/refs/heads/master/dist/core/rt-bundled.yaml>" path="/auth/user" method="post" %}
<https://raw.githubusercontent.com/tryterra/openapi/refs/heads/master/dist/core/rt-bundled.yaml>
{% endopenapi %}
