Using the Terra Connect widget

The connection widget is the client-side component that your users will interact with in order to link their accounts to Terra and allow you to access their data via the Terra API. Put simple, it renders a selection of wearables from which the user selects their device.

The Terra Connect flow begins when your user wants to connect their fitness data provider account to your app.

Terra Connect flow overview

📘

Connecting SDK-based resources

APPLE & SAMSUNG connections will always automatically skip to the auth_success_redirect_url when the button is pressed. Once this is done, you should call the appropriate authentication package from one of the SDKs, shown in Adding Terra to your Apple project

1. Call /auth/generateWidgetSession to create a session_id and pass the url containing it to your app's client.
2. Use the session URL to open Terra Connect for your user.
3. Receive a webhook on your app's server for a successful user authentication
4. Store the user_id field and map it to one of your users with the help of the reference_id, then start receiving & requesting data for your user!

Terra Connect is initialized by opening the URL returned in the request. The exact implementation details for passing the link_token will vary by platform, but an in-app browser session is appropriate for mobile platforms, and opening it in a new tab is appropriate for web apps.

Once authentication has been completed, your users will be redirected to the auth_success_redirect_url you passed in, or to a default Terra Connect success URL. You are encouraged to provide a deep link in order to redirect users back into your app

The connection's user_id, resource, and reference_id` will be appended as query parameters as such:

https://example.com/?user_id=wow_a_new_user&reference_id=fun_identifier&resource=PROVIDERNAME

❗️

OAuth & Webviews

OAuth flows, which are used by a lot of the integrations provided, severely discourage the use of mobile WebViews due to security concerns (the URL bar not being visible as a main flaw, which means the user is vulnerable to spoofing of pages), and some, such as a Google Fit, outright restrict it.

Make sure you use an in-app browser session instead when implementing Terra Connect on a mobile app