Android (Kotlin)

Android Functions

Initializer

class TerraRT(
    private var devId: String,
    private var context: Context,
    private var referenceId: String?,
    completion: (Boolean) -> Unit,
)

• devId: your developer ID

• referenceId: the reference_id for the end user

• context: the [android.app.Activity] context which you initialise this class in

• referenceId: the user ID associated to the user in your system

• completion: a completion function depicting if the initialisation was successful or not

Connection Setup

initConnection

Initialise a connection with Terra's backend for the device

fun initConnection(token: String, callback: (Boolean) -> Unit)

• token: An authentication token that should be generated from the backend.

• callback: A function called when the initialization is complete with a boolean indicating success.

getUserId

A synchronous function that returns the current device's Terra user ID.

fun getUserId(): String?

• Returns String?: The user ID. If none exists, returns null.

disconnect

Disconnects from a connection.

fun disconnect(type: Connections)

• type: Enum representing the connection type to disconnect.

---

Device Connection Management

startDeviceScan

Starts a device scan and allows the user to connect to a device.

fun startDeviceScan(
  type: Connections, 
  useCache: Boolean = false, 
  showWidgetIfCacheNotFound: Boolean = true, 
  callback: (Boolean) -> Unit = {_ -> }
)
// second possible signature
fun startDeviceScan(
  type: Connections, 
  deviceCallback: (Boolean) -> Unit = {_ -> }
)

• type: The connection type you're trying to connect to.

• useCache: If true, uses previously connected devices (default is false).

• showWidgetIfCacheNotFound: if true, shows the connection widget if cached device is not found

• callback: Called with a boolean after the connection is established.

• deviceCallback: callback function called with [Device] object whenever a device is found

getConnectedDevices

Returns a set of devices that are currently connected

fun getConnectedDevices(): Set<ConnectedDevice>

• Returns Set<ConnectedDevice>, the set of currently connected devices

---

Data Streaming

startRealtime

Starts streaming data for a given connection type.

fun startRealtime(
    type: Connections, 
    dataTypes: Set<DataTypes>, 
    token: String? = null, 
    updateHandler: ((Update) -> Unit)? = null, 
    connectionCallback: ((Boolean) -> Unit)? = {_ -> }
)
// alternative signature, used for streaming data locally without 
// sending data to Terra Websocket API
fun startRealtime(
    type: Connections, 
    dataTypes: Set<DataTypes> = setOf(), 
    updateHandler: (Update) -> Unit
)

• type: Enum representing the connection type.

• token: The token used for verification to connect to Terra’s API.

• dataTypes: Enum representing the data types to stream.

• connectionCallback: Called when a websocket connection is either successful or not.

• updateHandler: Called when new updates are available from the device.

stopRealtime

Stops streaming for a given connection type.

fun stopRealtime(type: Connections)

• type: Enum representing the connection type to stop streaming for.