> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/mobile-sdks/terra-grip-companion-app.md).

# Terra Grip

Connect your users' Apple Health, Health Connect or Samsung Health through Terra Grip when you don't have a mobile app of your own.

Apple Health, Health Connect and Samsung Health keep their data on the phone, so they normally need the [Terra mobile SDK](https://docs.tryterra.co/mobile-sdks/mobile-only-sources.md) inside your own app. If you don't have an app, **Terra Grip** can be that app for you.

Send your user to Grip in one of two ways: through the [Terra authentication widget](#connect-a-user-with-the-terra-widget), or with a link you create from your backend. The user opens it on their phone, Grip asks for access to their health data, and Grip then sends that data to Terra in the background. You receive it on your webhook or destination like any other source.

Grip is on the [App Store](https://apps.apple.com/app/id6789555253) and [Google Play](https://play.google.com/store/apps/details?id=co.tryterra.streamingdemo).

| `resource`       | Store                                  | Phone   |
| ---------------- | -------------------------------------- | ------- |
| `APPLE`          | Apple Health                           | iPhone  |
| `HEALTH_CONNECT` | Health Connect                         | Android |
| `SAMSUNG`        | Samsung Health, through Health Connect | Android |

## Connect a user with the Terra widget

If you use the [Terra authentication widget](https://docs.tryterra.co/unified-api/implementation-terra-widget.md), add `"sdk_app": "grip"` to the body of `POST https://access.tryterra.co/api/widget/session`:

```json
{
  "reference_id": "user123@email.com",
  "providers": "APPLE,HEALTH_CONNECT,SAMSUNG,GARMIN",
  "sdk_app": "grip",
  "auth_success_redirect_url": "https://myapp.com/success",
  "auth_failure_redirect_url": "https://myapp.com/failure"
}
```

When the user picks Apple Health, Health Connect or Samsung Health on their phone, the widget shows a **Connect** button that opens Grip, or the store listing if Grip isn't installed. The user then connects in Grip as in [The user connects](#the-user-connects). Other providers in the same session keep their normal login.

* An unknown `sdk_app` value returns a `400`.
* `apple_app_url` and `samsung_app_url` take precedence over `sdk_app`.

## Connect a user with a link

{% stepper %}
{% step %}

### Create a link

From your **backend**, call [`/auth/authenticateUser`](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#post-auth-authenticateuser) with `sdk_app` set to `"grip"`. Make one call per user, with your own ID for that user as `reference_id`.

{% code title="Command Line" %}

```bash
curl --request POST --url 'https://api.tryterra.co/v2/auth/authenticateUser?resource=APPLE' \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
      "sdk_app": "grip",
      "reference_id": "user_123",
      "auth_success_redirect_url": "https://example.com/connected",
      "auth_failure_redirect_url": "https://example.com/failed"
  }'
```

{% endcode %}

The `auth_url` in the response is a Grip link:

```
https://grip.tryterra.co/health-auth?token=…&dev_id=…&reference_id=…&auth_success_redirect_url=…&auth_failure_redirect_url=…&resource=APPLE
```

{% endstep %}

{% step %}

### Send the link to the user

Show the link to the user **on their phone**, for example behind a "Connect Apple Health" button on your web page. If they are on a computer, [show it as a QR code](#show-the-link-as-a-qr-code) instead. Each link is for one user.

A link expires 3 minutes after you create it and works once, so create it when the user is ready to connect.
{% endstep %}

{% step %}

### The user connects

On the right phone, the link opens Grip, or the store listing if Grip isn't installed.

1. Grip opens on its **Health** tab and shows which kinds of data you will receive.
2. The user taps **Agree**, and the phone's own permission sheet asks for access.
3. Grip sends the **last 7 days** of data to Terra, then opens your success URL.
   {% endstep %}

{% step %}

### Handle the redirect

Grip opens your `auth_success_redirect_url` only after the user has agreed, granted access, and the first sync has finished. It adds `user_id`, `reference_id` and `resource` to the URL.

Use absolute `https` URLs for both redirects. If something goes wrong, Grip opens your `auth_failure_redirect_url` with a `reason`:

| `reason`            | When                                                         |
| ------------------- | ------------------------------------------------------------ |
| `ios_only`          | An `APPLE` link was opened on Android                        |
| `android_only`      | A `HEALTH_CONNECT` or `SAMSUNG` link was opened on an iPhone |
| `outside_of_mobile` | The link was opened on a computer                            |
| Any other text      | Connecting failed, for example the link had expired          |
| {% endstep %}       |                                                              |
| {% endstepper %}    |                                                              |

## Show the link as a QR code

When your user is on a computer, show the Grip link as a QR code they scan with their phone. A Grip link opened on a computer fails with `outside_of_mobile`, so a QR code is the way across.

The QR code holds the same `auth_url` from [Create a link](#create-a-link). The user can scan it in either of two ways:

* With the phone's **Camera** app. The link opens Grip, or the store listing if Grip isn't installed.
* From Grip's **Pair** tab, if Grip is already installed.

Render the QR code in your page from a link your backend creates. For example, in a browser with the [`qrcode`](https://www.npmjs.com/package/qrcode) package:

{% code title="connect-qr.js" %}

```javascript
import QRCode from "qrcode";

// Your backend calls /auth/authenticateUser with sdk_app "grip" and returns auth_url.
async function showGripQr(canvas) {
  const response = await fetch("/api/grip-link", { method: "POST" });
  const { auth_url } = await response.json();
  await QRCode.toCanvas(canvas, auth_url, { width: 240 });
}

// A link expires after 3 minutes, so replace the QR code before then.
const canvas = document.getElementById("grip-qr");
showGripQr(canvas);
const refresh = setInterval(() => showGripQr(canvas), 150_000);
// Call clearInterval(refresh) once your backend reports the user has connected.
```

{% endcode %}

Keep these in mind:

* Refresh it. Each link expires 3 minutes after you create it and works once. Create a new link and redraw the QR code every 2 to 3 minutes while the page is open, and stop once the user has connected.
* One code per user. The link carries that user's `reference_id`, so never show the same QR code to two people.
* The redirect opens on the phone. Your success and failure URLs open in the phone's browser, not on the computer showing the QR code. To update the computer's page, have your backend tell it when the user connects, for example when that user's first data reaches your destination.

## Receive data

Syncing is **automatic and runs in the background**. There is no sync button, and the user doesn't need to open Grip for new data to reach you.

* **Background delivery**: iOS wakes Grip when Apple Health receives new data, so a workout reaches Terra without the user opening the app.
* **Scheduled uploads**: Terra's own background scheduler also posts what the SDK already holds.
* **When the user opens Grip**: Grip syncs again, at most once every 15 minutes.

### Which data you receive

Grip asks only for the data types enabled for your developer ID in the [Terra Dashboard](https://dashboard.tryterra.co/), out of activity, daily, sleep, body, nutrition and menstruation. Enable a type later and existing users must open a new link to grant it.

### Backfill

Apple Health data lives on the phone, so a backfill you request from the dashboard is carried out by Grip the next time the user opens Grip's **Health** tab.

### Several customers on one phone

One phone can share with several Terra customers. A new link adds a customer rather than replacing one, and each customer receives only the data types its own account enables. Grip lists every connected customer on its Health tab.

## Limits

* **The legacy `/auth/generateWidgetSession` ignores `sdk_app`.** Use the [widget session endpoint](#connect-a-user-with-the-terra-widget) or `/auth/authenticateUser`.
* **The phone can't end a customer's connection.** Grip's **Forget** only hides a customer from its list, and sharing continues. A connection ends when you [deauthenticate the user](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#delete-auth-deauthenticateuser), or when the user turns off Terra Grip's Apple Health access in iOS **Settings**. The second stops every customer on that phone at once.

## Health Connect and Samsung Health on Android

The same flow works on Android with `resource=HEALTH_CONNECT` or `resource=SAMSUNG`. A few differences:

* Grip never reads menstruation data on Android.
* Health Connect shows a second sheet with **Access past data** and **Access data in the background**. Both start off. Without them Grip still connects, but syncs reach back only 30 days and run only while Grip is open.
* `SAMSUNG` reads Samsung Health through Health Connect. Grip sees data only after the user turns on Health Connect sync in Samsung Health (**Settings > Health Connect**).
* One customer connected through both stores is two separate connections.
* The user's off switch is turning off Terra Grip's access in Health Connect settings.

## Next steps

* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): handle the data Grip sends to your destination.
* [Terra authentication widget](https://docs.tryterra.co/unified-api/implementation-terra-widget.md): add Grip to an existing widget session.
