Terra Grip

A React Native reference app for the Streaming API: pair a wearable, stream live biometrics to Terra, and render them on screen. No backend, no accounts, no API keys on the device.

Terra Grip is a React Native app that shows how to stream real-time wearable data with Terra, built on the terra-rt SDK. Scan a QR code from your Terra dashboard and the phone pairs to a heart-rate strap, watch, or its own sensors and streams live data to Terra for the next several hours.

It's the producer half of a Streaming API integration (the wearable → app → Terra path), and the code you copy to build it into your own app. There's no backend to run: the dashboard QR carries a reusable token, so no API keys are ever typed into or stored by the app.

Terra Grip is the streaming-mobile-app example in the terra-examples repository. Scaffold your own copy with one command:

npm create tryterra-app -- --template streaming-mobile-app
cd my-app/app && npm install && npx expo run:ios

Just want to try the app? Install Terra Grip from the App Store or Google Play, then scan a pairing QR from your dashboard. To build and modify it yourself, follow Run it yourself below.

What it demonstrates

• Opening a producer connection to Terra's WebSocket broker with the terra-rt SDK

• Pairing a wearable to the app over BLE, plus the phone's own sensors and Apple Watch

• QR-code pairing with a reusable rt. token (the no-backend flow), held in the device keychain

• Background streaming with the screen locked (bluetooth-central on iOS, a foreground service on Android)

• Rendering readings live, straight from the local SDK feed, with honest empty and reconnecting states

• A demo mode that runs the whole producer flow on synthetic data, with no hardware, account, or network

The Live tab renders readings straight from the local SDK feed as they stream

How streaming works here

Real-time streaming has four parts: the wearable, your app (the producer), Terra's WebSocket broker, and your backend (the consumer). Terra Grip is the producer: it streams the wearable's data to Terra's backend. A consumer (your backend, or the dashboard's streaming tester) reads the same data back out. For the consumer side, see Terra → Your backend.

Most integrations mint a short-lived token from their backend for each connection (the flow in the RN reference). Terra Grip takes the simpler demo path: the QR from the dashboard streaming page carries a reusable rt. token that already has the user's identity bound into it. The same token registers the SDK and opens every stream for its lifetime, with no minting and no network on reconnect.

Tech stack

Layer	Technology
Framework	React Native 0.81 on Expo SDK 54 (dev build; Expo Go unsupported)
Streaming SDK	terra-rt 0.2.9 (native module)
UI	React 19, react-native-svg charts, lucide-react-native, Poppins
Pairing	expo-camera (QR scan), expo-secure-store (keychain)
State	A hand-rolled ProducerController state machine, bound to React with a useProducer hook

Run it yourself

Prerequisites: Node.js 18+, Xcode (with CocoaPods) or Android Studio, and access to the streaming page of the Terra dashboard. The terra-rt SDK is a native module, so the app needs a development build (the first compile takes a few minutes). Expo Go won't work.

1

Build and launch

npm create tryterra-app -- --template streaming-mobile-app
cd my-app/app
npm install
npx expo run:ios      # or: npx expo run:android

This compiles a development build and launches it on a simulator or connected device. To pair a wearable or scan the dashboard QR you need a physical phone; on a simulator or emulator, use the "Try the demo" path below.

2

Add a test user

On the streaming page of the Terra dashboard, click + Test User. Optionally set a Reference ID to label the user, then choose Use my own wearable device.

Click + Test User, optionally set a Reference ID, and choose "Use my own wearable device"

3

Scan the pairing QR

The dashboard shows a pairing QR code. Leave it on screen for the next step.

The dashboard shows a QR code to pair your device

4

Scan the QR to pair

Scan the dashboard QR either way:

• In the app: open the Pair tab and scan it there.

• With your phone's camera or any QR scanner: if Terra Grip is installed, it opens and pairs directly; if not, you're sent to the App Store or Google Play to install it first, then scan again.

Either way, the app stores the reusable rt. token in the device keychain and shows who you're streaming as, and you're ready to stream from Connect.

Scan the dashboard QR on the app's Pair tab to pair

Scanning the QR needs a physical phone with a camera. The iOS Simulator and Android emulator can't scan it. To try the app without a device (or without dashboard access), tap "Try the demo" on first launch and the full producer flow runs on synthetic local data.

5

Connect a data source

On the Connect tab, pick BLE device (a Polar H10, Wahoo TICKR, Garmin HRM, and similar chest straps), Phone sensors, or Apple Watch on iOS. Tap a discovered device and Continue, and the app connects and starts streaming to Terra automatically.

Pick a BLE sensor, the phone's own sensors, or an Apple Watch on the Connect tab

6

Watch it stream

The Connect tab shows "Streaming to Terra" once the link is live. Open Live to see the readings the SDK is emitting (heart rate, R-R interval, and whatever else the device supports), then open the dashboard streaming tester to see the same data arrive on Terra's side.

Once a device connects, the app streams to Terra until you stop it or the session expires

How the Terra integration works

Two files hold the integration, both kept free of UI so they read as reference code.

app/src/producer/terraSdk.ts is a thin adapter over terra-rt; the demo adapter swaps in behind the same interface. The SDK is initialised with your dev ID and the user's reference_id, then the device is registered with a token:

import * as rt from 'terra-rt';

async initialize(devId, referenceId) {
  throwIfFailed(await rt.initTerra(devId, referenceId), 'initTerra');
},

async registerDevice(token) {
  throwIfFailed(await rt.initConnection(token), 'initConnection');
},

app/src/producer/ProducerController.ts drives the sequence (initialise, fetch the token, register, read back the Terra user_id), then opens the stream. Because the token is reusable, fetchSdkToken and fetchStreamingToken return the same string the QR carried:

// setup(): initTerra → rt. token → initConnection → map reference_id
await sdk.initialize(devId, referenceId);
const token = await api.fetchSdkToken();
await sdk.registerDevice(token);
const userId = await sdk.getUserId();
this.set({ phase: 'ready', userId });

// startStreaming(): pass the token to open the producer connection
const streamingToken = await api.fetchStreamingToken(this.snapshot.userId);
await sdk.startStreaming(this.snapshot.connectionType, STREAM_DATA_TYPES, streamingToken);

startStreaming maps onto rt.startRealtime(connection, dataTypes, token). The token is the only difference from local-only streaming: with it, the SDK opens the WebSocket to Terra and relays every reading in real time.

Explore the code

The full source is on GitHub, including a Jest suite over the producer state machine and demo adapter.

Path	What it holds
app/src/producer/terraSdk.ts	The terra-rt integration surface; start here
app/src/producer/ProducerController.ts	The producer state machine: setup, scanning, streaming lifecycle
app/src/auth/	The pairing session, keychain storage, and reusable-token provider
app/src/datatypes/	One entry per streaming data type; unknown types get a generic renderer
wearos/	The standalone Wear OS companion app

Watch companions

Terra Grip can also stream from a watch. On Apple Watch, a small watchOS companion (generated into the build at prebuild) streams heart rate and steps to the phone over WatchConnectivity. Apple Watch doesn't broadcast standard BLE heart rate, so this can't be reached over BLE. On Wear OS, a standalone companion app in wearos/ streams over Terra's terra-wearos SDK. Both are documented in the template's docs/ folder.