# React Native

## Connections

| Value                        | Platform | Description                                                  |
| ---------------------------- | -------- | ------------------------------------------------------------ |
| `Connections.APPLE_HEALTH`   | iOS      | Apple Health (HealthKit)                                     |
| `Connections.SAMSUNG`        | Android  | Samsung Health (direct SDK access)                           |
| `Connections.HEALTH_CONNECT` | Android  | Health Connect (reads all data sources)                      |
| `Connections.GOOGLE`         | Android  | Google Fit (via Health Connect, filtered to Google Fit data) |

## CustomPermissions

Use these to request a subset of permissions. When not specified, all permissions from your developer scopes are requested. 45 values available — see the [CustomPermissions enum](https://github.com/tryterra/terra-react/blob/master/src/enums/CustomPermissions.ts) for the full list.

## Types

### SuccessMessage

```typescript
type SuccessMessage = {
  success: boolean;
  error: string | null;
};
```

### DataMessage

```typescript
type DataMessage = {
  success: boolean;
  data: Object;
  error: string | null;
};
```

When `toWebhook` is `true`, the `data` field contains `{ reference: string }` — a reference ID for the webhook payload. When `false`, `data` contains the full normalized health data object.

### GetUserId

```typescript
type GetUserId = {
  success: boolean;
  userId: string | null;
};
```

## **Initialization**

### initTerra

Creates and authenticates a Terra SDK instance. This **makes a network call** to Terra's servers to validate your developer ID and reconnect existing users.

```typescript
function initTerra(
  devID: string,
  referenceId: string | null,
): Promise<SuccessMessage>
```

* `devID: string` ➡ Your developer ID from the [Terra Dashboard](https://dashboard.tryterra.co).
* `referenceId: string | null` ➡ An identifier for your app's user. This value appears as `reference_id` in webhook payloads and API responses, allowing you to map Terra users back to your own user system.

**returns** `Promise<SuccessMessage>`

{% hint style="warning" %}
You must `await` this call and verify `success` is `true` before calling any other SDK function.
{% endhint %}

## **Connection setup/management**

### **initConnection**

Authenticates a new user connection with Terra's servers and triggers the platform permission dialog (HealthKit on iOS, Health Connect on Android). This **makes a network call**.

This function should only be called **once** per user/connection type. On subsequent app launches, `initTerra` will automatically reconnect existing users.

```typescript
function initConnection(
  connection: Connections,
  token: string,
  schedulerOn: boolean,
  customPermissions: CustomPermissions[] = []
): Promise<SuccessMessage>
```

* `connection: Connections` ➡ The connection type (e.g. `Connections.APPLE_HEALTH`, `Connections.SAMSUNG`, `Connections.HEALTH_CONNECT`). Must match the platform — passing an iOS connection on Android (or vice versa) will fail.
* `token: string` ➡ A **single-use** authentication token from the [Generate Authentication Token](https://docs.tryterra.co/reference/generate-authentication-token) endpoint.
* `schedulerOn: boolean` ➡ Enables automatic data delivery. On **iOS**, enables HealthKit background delivery (also requires `setUpBackgroundDelivery` in AppDelegate). On **Android**, enables periodic WorkManager-based data fetches (activity every 20min, other types every 8hrs).
* (Optional) `customPermissions: CustomPermissions[]` ➡ Request specific permissions. Empty array defaults to all scopes.

**returns** `Promise<SuccessMessage>` — check `error` field for specific failure reasons (invalid token, user limit reached, etc.)

### checkAuth

Checks whether a connection is authenticated by **making a network call** to Terra's servers.

```typescript
function checkAuth(
  connection: Connections,
  devID: string
): Promise<Pick<SuccessMessage, 'success'>>
```

* `connection: Connections` ➡ The connection type to check.
* `devID: string` ➡ Your developer ID.

**returns** `Promise<{ success: boolean }>`

### getUserId

Returns the Terra user ID for a connection. This is a local read with no network call.

The returned `userId` is the same identifier used in webhook payloads, API requests, and the Terra dashboard.

```typescript
function getUserId(connection: Connections): Promise<GetUserId>
```

* `connection: Connections` ➡ The connection to get the user ID for.

**returns** `Promise<GetUserId>` — `userId` is `null` if no connection exists for this type.

## Data retrieval

All data retrieval functions **make network calls** — even with `toWebhook = false`, the SDK sends data to Terra's normalization servers and returns the normalized result.

{% hint style="info" %}
**`toWebhook` behavior:**
{% endhint %}

| `toWebhook`      | What happens                                      | `DataMessage.data` contains                   |
| ---------------- | ------------------------------------------------- | --------------------------------------------- |
| `true` (default) | Data is fetched and sent to your webhook          | `{ reference: string }` — a reference ID only |
| `false`          | Data is fetched, normalized, and returned locally | The full normalized health data object        |

{% hint style="info" %}
Both paths require network connectivity.
{% endhint %}

### **getActivity**

Retrieves workout and exercise session data.

```typescript
function getActivity(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getDaily**

Retrieves daily summary data (steps, calories, distance, heart rate, etc.).

```typescript
function getDaily(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getBody**

Retrieves body measurement data (weight, height, BMI, heart rate, blood pressure, etc.).

```typescript
function getBody(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  latestReading: boolean = false,
  toWebhook: boolean = true
): Promise<DataMessage>
```

* `latestReading: boolean` ➡ When `true`, returns only the most recent reading for each body metric, ignoring the date range. Defaults to `false`. **Note: this parameter only takes effect on iOS.** On Android, it is accepted but not forwarded to the native SDK.

### getSleep

Retrieves sleep session data (stages, duration, heart rate during sleep, etc.).

```typescript
function getSleep(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### **getNutrition**

Retrieves nutrition and meal data.

```typescript
function getNutrition(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### getMenstruation

Retrieves menstrual cycle data. **iOS only** — rejects with an error on Android.

```typescript
function getMenstruation(
  connection: Connections,
  startDate: Date,
  endDate: Date,
  toWebhook: boolean = true
): Promise<DataMessage>
```

### getAthlete

Retrieves the user's athlete profile (biographical data, no date range needed). **iOS only** — rejects with an error on Android.

{% hint style="warning" %}
Unlike other data getters, `getAthlete` does not parse the native response. The `data` field may contain a raw JSON string rather than a parsed object.
{% endhint %}

```typescript
function getAthlete(
  connection: Connections,
  toWebhook: boolean = true
): Promise<DataMessage>
```

## Writing data

### postActivity

Writes workout data into Apple Health. **iOS only** (iOS 14+) — rejects on Android.

```typescript
function postActivity(
  connection: Connections,
  payload: TerraActivityPayload
): Promise<SuccessMessage>
```

* `connection: Connections` ➡ Use `Connections.APPLE_HEALTH`.
* `payload: TerraActivityPayload` ➡ Activity data to write. Required fields: `metadata` (start\_time, end\_time, type), `device_data` (at least one field). Optional: `distance_data`, `calories_data`.

**returns** `Promise<SuccessMessage>`

## Android-only methods

These functions are **only available on Android**. They will reject with an error on iOS.

### isHealthConnectAvailable

Checks if Health Connect is available on the device. Local check, no network call.

```typescript
function isHealthConnectAvailable(): Promise<boolean>
```

### openHealthConnect

Opens the Health Connect settings screen.

```typescript
function openHealthConnect(): void
```

### grantedPermissions

Returns the Health Connect permissions currently granted to your app. Returns permission name strings like `"READ_HEART_RATE"`, `"READ_STEPS"`, etc.

```typescript
function grantedPermissions(): Promise<Array<string>>
```

## iOS-only methods

### setIgnoredSources

Filters out health data from specific apps when reading from Apple Health. Use this to prevent double-counting when a user connects a data source both through Terra's API (e.g. WHOOP, Garmin) and has that same app syncing into Apple Health.

```typescript
function setIgnoredSources(ignoredSources: Array<string>): void
```

* `ignoredSources: Array<string>` ➡ App bundle identifiers to exclude (e.g. `["com.whoop.app", "com.garmin.connect.mobile"]`).

{% hint style="info" %}

* Takes effect on the next data fetch (including background delivery).
* **Not persisted across app launches** — call this on every app start if needed.
* **Android: this function is a no-op.** It is accepted but does nothing.
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/reference/health-and-fitness-api/sdk-references/react-native.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.