React Native

Connections

export enum Connections {
  ANT = 'ANT',
  BLE = 'BLE',
  WEAR_OS = 'WEAR_OS',
  WATCH_OS = 'WATCH_OS',
  ANDROID = 'ANDROID',
  ALL_DEVICES = 'ALL_DEVICES',
  APPLE = 'APPLE',
}

Platform availability:

Value	iOS	Android
BLE	Yes	Yes
APPLE	Yes	No
WATCH_OS	Yes	No
ANT	No	Yes
WEAR_OS	No	Yes
ANDROID	No	Yes
ALL_DEVICES	No	Yes

Passing an unsupported connection type for the current platform will silently fail.

DataTypes

export enum DataTypes {
  HEART_RATE = 'HEART_RATE',
  ECG = 'ECG',
  STEPS = 'STEPS',
  HRV = 'HRV',
  CALORIES = 'CALORIES',
  LOCATION = 'LOCATION',
  DISTANCE = 'DISTANCE',
  ACTIVITY = 'ACTIVITY',
  ACCELERATION = 'ACCELERATION',
  GYROSCOPE = 'GYROSCOPE',
  FLOORS_CLIMBED = 'FLOORS_CLIMBED',
  STEPS_CADENCE = 'STEPS_CADENCE',
  SPEED = 'SPEED',
  POWER = 'POWER',
  BIKE_CADENCE = 'BIKE_CADENCE',
  MET = 'MET',
  RR_INTERVAL = 'RR_INTERVAL',
}

On iOS, only 12 of these 17 values are recognized: HEART_RATE, ECG, STEPS, HRV, CALORIES, LOCATION, SPEED, DISTANCE, STEPS_CADENCE, FLOORS_CLIMBED, GYROSCOPE, ACCELERATION. The others (ACTIVITY, POWER, BIKE_CADENCE, MET, RR_INTERVAL) are silently ignored on iOS.

Types

SuccessMessage

export type SuccessMessage = {
  success: Boolean;
  error: String | null;
};

GetUserId

export type GetUserId = {
  success: Boolean;
  userId: String | null;
};

Update

Data points delivered via the "Update" event emitter.

export type Update = {
  ts: String | null;     // ISO 8601 timestamp
  val: number | null;    // Scalar value (e.g. heart rate BPM)
  type: String | null;   // Data type identifier (e.g. "HEART_RATE")
  d: Array<number> | null;  // Array for multi-axis data (e.g. [x, y, z])
};

Device

export type Device = {
  id: String | null;
  name: String | null;
  type: String;
};

---

Initialization

initTerra

Creates and authenticates the RT SDK instance. Makes a network call.

function initTerra(devId: String, referenceId?: String): Promise<SuccessMessage>

• devId ➡ Your developer ID.

• referenceId ➡ Optional user identifier in your system.

initConnection

Authenticates the SDK user. Makes a network call. Token should be generated server-side.

function initConnection(token: String): Promise<SuccessMessage>

getUserId

Returns the Terra user ID for the device.

function getUserId(): Promise<GetUserId>

disconnect

Disconnects from the specified connection type.

function disconnect(connections: Connections): Promise<SuccessMessage>

Device Scanning

startDeviceScan

Starts device scanning with the built-in UI widget. Android only — on iOS, this returns {success: false} with an error directing you to use the BLWidget native view instead.

function startDeviceScan(
  connections: Connections,
  useCache: Boolean = false,
  showWidgetIfCacheNotFound: Boolean = false
): Promise<SuccessMessage>

startDeviceScanWithCallback

Starts device scanning and emits discovered devices via the "Device" event. Use connectDevice() to connect to a chosen device.

function startDeviceScanWithCallback(
  connections: Connections
): Promise<SuccessMessage>

Listen for devices using NativeEventEmitter:

import { NativeEventEmitter, NativeModules } from 'react-native';
const deviceEmitter = new NativeEventEmitter(NativeModules.DeviceHandler);
deviceEmitter.addListener('Device', (device: Device) => {
  // Handle discovered device
});

connectDevice

Connects to a specific device discovered via startDeviceScanWithCallback.

function connectDevice(device: Device): Promise<SuccessMessage>

Data Streaming

startRealtime

Starts real-time data streaming. When token is provided, data is sent to Terra's websocket server. When null, data is streamed locally only.

function startRealtime(
  connections: Connections,
  dataTypes: Array<DataTypes>,
  token: String | null = null
): Promise<SuccessMessage>

Data updates and connection state changes are delivered via NativeEventEmitter:

import { NativeEventEmitter, NativeModules } from 'react-native';

const updateEmitter = new NativeEventEmitter(NativeModules.UpdateHandler);
updateEmitter.addListener('Update', (update: Update) => {
  // Handle data point
});

const connectionEmitter = new NativeEventEmitter(NativeModules.ConnectionHandler);
connectionEmitter.addListener('ConnectionUpdate', (connected: boolean) => {
  // Handle websocket connection state
});

stopRealtime

Stops streaming for the specified connection type.

function stopRealtime(connections: Connections): Promise<SuccessMessage>

WatchOS Integration

connectWithWatchOS

Establishes a WatchConnectivity session with the paired Apple Watch. iOS only — rejects on Android.

function connectWithWatchOS(): Promise<SuccessMessage>

iOS Native View: BLWidget

On iOS, the BLE device scanner is provided as a native view component (since iOS does not support the startDeviceScan widget flow). Use requireNativeComponent:

import { requireNativeComponent } from 'react-native';
const BLWidget = requireNativeComponent('BLWidget');

// In your JSX:
<BLWidget
  style={{ flex: 1 }}
  withCache={false}
  onSuccessfulConnection={(event) => {
    console.log('Connected:', event.nativeEvent.success);
  }}
/>