Android

Prerequisites

Ensure you have the following before you begin:

1. Android Studio: The latest stable version.

2. Terra Account: Access to your Terra Developer account and API key.

3. Gradle Dependency: Ensure you include the TerraRT SDK in your project by adding the necessary dependencies.

   implementation 'co.tryterra:terra-rtandroid:X.X.X'

   based on the latest version on maven central

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.

To do this, run the TerraRT manager initialization function as below:

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import co.tryterra.terrartandroid.TerraRT

class MainActivity : AppCompatActivity() {
    private lateinit var terraRT: TerraRT

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

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

        terraRT = TerraRT(
            devId = developerId,
            context = this,
            referenceId = referenceId
        ) { success ->
            if (success) {
                println("TerraRT initialized successfully")
            } else {
                println("Failed to initialize TerraRT")
            }
        }
    }
}

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 device is connected later on.

Use the terraRT instance created above and call initConnection as below using an authentication token.

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

terraRT.initConnection(token) { success ->
    if (success) {
        println("Connection initialized successfully!")
    } else {
        println("Failed to initialize connection.")
    }
}

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

Deprecated

Generate a mobile SDK auth token (deprecated)

post

Deprecated spelling of POST /auth/tokens, which it is identical to. Kept indefinitely because shipped mobile SDK versions call this path; new integrations should use POST /auth/tokens.

Authorizations

x-api-keystringRequired

Your API key for authentication

dev-idstringRequired

Your developer ID for authentication and tracking

Query parameters

reference_idstringOptional

Your identifier for the end user this token is being issued for. When supplied, the token is bound to it and redemption ignores the reference_id the SDK sends, so a token cannot be used to attach a device to a different user. Omit to keep the SDK-supplied value.

Example: user-42

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
}

Device Connection Management

Once initialized, you can scan for devices and connect to them using the TerraRT SDK.

You can scan for devices using

• BLE

• ANT+ (if supported by the Android phone used)

Start Device Scan

You can start scanning for devices and allow the user to connect to a wearable device using startDeviceScan.

You can choose whether to use cached devices (ones you've connected to before) or show a connection widget if no cached device is found.

import co.tryterra.terrartandroid.enums.Connections

// Option 1: Widget-based scan with auto-connection
terraRT.startDeviceScan(
    type = Connections.BLE,
    useCache = false,
    showWidgetIfCacheNotFound = true
) { success ->
    if (success) {
        println("Device connected successfully!")
    } else {
        println("Failed to connect to the device.")
    }
}

// Option 2: Programmatic scan with device callback
terraRT.startDeviceScan(type = Connections.BLE) { device ->
    println("Found device: ${device.deviceName}")
    // Connect to the chosen device
    terraRT.connectDevice(device) { connected ->
        println("Device connected: $connected")
    }
}

Real-Time Data Streaming

Once the device is connected, you can start streaming real-time data such as heart rate, steps, and more.

Receiving a real time data stream depends on the device being configured to broadcast the data it is collecting through BLE or ANT+

Start Real-Time Streaming

import co.tryterra.terrartandroid.enums.DataTypes

val dataTypes: Set<DataTypes> = setOf(DataTypes.HEART_RATE, DataTypes.STEPS)

// Stream data locally (no server)
terraRT.startRealtime(type = Connections.BLE, dataTypes = dataTypes) { update ->
    println("${update.type}: ${update.`val`}")
}

Stop Real-Time Streaming

terraRT.stopRealtime(type = Connections.BLE)

Disconnect Device

terraRT.disconnect(type = Connections.BLE)

Example Usage

Full Example: Managing a BLE Connection and Streaming Data

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import co.tryterra.terrartandroid.TerraRT
import co.tryterra.terrartandroid.enums.Connections
import co.tryterra.terrartandroid.enums.DataTypes
import co.tryterra.terrartandroid.models.Update

class MainActivity : AppCompatActivity() {
    private lateinit var terraRT: TerraRT

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        terraRT = TerraRT(
            devId = "yourDeveloperId",
            context = this,
            referenceId = "yourReferenceId"
        ) { success ->
            if (success) {
                println("TerraRT initialized")
                connectAndStream()
            }
        }
    }

    private fun connectAndStream() {
        val token = "yourAuthToken"

        terraRT.initConnection(token) { success ->
            if (success) {
                // Scan and connect to a BLE device
                terraRT.startDeviceScan(
                    type = Connections.BLE,
                    useCache = false
                ) { scanSuccess ->
                    if (scanSuccess) {
                        // Start streaming heart rate data
                        val dataTypes = setOf(DataTypes.HEART_RATE, DataTypes.STEPS)
                        terraRT.startRealtime(
                            type = Connections.BLE,
                            dataTypes = dataTypes
                        ) { update ->
                            handleUpdate(update)
                        }
                    }
                }
            }
        }
    }

    private fun handleUpdate(update: Update) {
        println("${update.type}: ${update.`val`} at ${update.ts}")
    }

    override fun onDestroy() {
        super.onDestroy()
        terraRT.stopRealtime(type = Connections.BLE)
        terraRT.disconnect(type = Connections.BLE)
    }
}