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.

Was this helpful?