React Native

Prerequisites

1. Install the terra-rt package:

npm install terra-rt

1. iOS: In your Info.plist, add:

   • Privacy - Bluetooth Always Usage Description: Justification for BLE usage

   • Privacy - Motion Usage Description: Justification for motion sensor usage (required if streaming accelerometer, gyroscope, or step data from the phone's built-in sensors via Connections.APPLE)

2. iOS: Run pod install in your /ios directory.

3. Android: Permissions are requested automatically by the SDK on initialization.

SDK Initialization

Initialize the SDK every time the app is opened or brought into the foreground.

Set up event emitters for receiving data, then initialize:

import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
import {
  initTerra, initConnection, startDeviceScan, startRealtime,
  stopRealtime, disconnect, getUserId,
  Connections, DataTypes,
} from 'terra-rt';
import type { Update, Device, SuccessMessage } from 'terra-rt';

// Set up event listeners (do this once, e.g. in useEffect)
const updateEmitter = new NativeEventEmitter(NativeModules.UpdateHandler);
updateEmitter.addListener('Update', (update: Update) => {
  console.log(`${update.type}: ${update.val}`);
});

const deviceEmitter = new NativeEventEmitter(NativeModules.DeviceHandler);
deviceEmitter.addListener('Device', (device: Device) => {
  console.log(`Found device: ${device.name}`);
});

const connectionEmitter = new NativeEventEmitter(NativeModules.ConnectionHandler);
connectionEmitter.addListener('ConnectionUpdate', (connected: boolean) => {
  console.log(`Websocket connected: ${connected}`);
});

// Initialize the SDK
const result = await initTerra('YOUR_DEV_ID', 'YOUR_REFERENCE_ID');
if (!result.success) {
  console.error('Failed to initialize:', result.error);
}

Initializing a Connection

Register the device with Terra using an authentication token generated from your backend:

const token = 'yourAuthToken'; // Generated from your backend

const connResult = await initConnection(token);
if (connResult.success) {
  console.log('Connection initialized!');
}

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 Scanning

BLE device scanning works differently on iOS and Android:

Android

On Android, use startDeviceScan which shows a built-in device picker:

const scanResult = await startDeviceScan(Connections.BLE);
if (scanResult.success) {
  console.log('Device connected!');
}

iOS

On iOS, startDeviceScan is not supported. Instead, use the BLWidget native view component:

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);
  }}
/>

Render this component when you want to show the BLE scanner. It displays a list of discovered devices and handles connection automatically.

Platform-conditional pattern:

const startScanning = () => {
  if (Platform.OS === 'android') {
    startDeviceScan(Connections.BLE).then((result) => {
      console.log('Connected:', result.success);
    });
  } else {
    // Show BLWidget in your UI (see iOS tab above)
  }
};

Real-Time Data Streaming

Once a device is connected, start streaming data. Updates arrive via the Update event emitter you set up earlier.

const dataTypes = [DataTypes.HEART_RATE, DataTypes.STEPS];

// Start streaming locally (no server)
await startRealtime(Connections.BLE, dataTypes);

To also stream to Terra's server, see Your App → Terra.

Stop & Disconnect

await stopRealtime(Connections.BLE);
await disconnect(Connections.BLE);

WatchOS Integration

To stream data from an Apple Watch, call connectWithWatchOS() on the iOS companion app side, then start streaming with Connections.WATCH_OS:

import { connectWithWatchOS } from 'terra-rt';

// Connect to paired Apple Watch (iOS only — rejects on Android)
await connectWithWatchOS();

// Start receiving watch data
await startRealtime(Connections.WATCH_OS, [DataTypes.HEART_RATE]);

The watchOS app itself must be written in native Swift using the Terra class from the TerraRTiOS framework. See the iOS WatchOS guide for the watch-side setup.