terra-connections

Terra Connections 是 Terra API 中负责设备与提供商连接的技能，用于将用户连接到 150+ 可穿戴设备与健康数据提供商。

用途

该技能面向需要接入可穿戴设备或健康数据源的开发者，帮助完成用户与设备提供商之间的授权连接、会话管理、连接状态查询与断开等操作。

支持的提供商

可穿戴与健身追踪器：Garmin（所有型号，完整历史数据）、Fitbit（所有设备，支持营养）、Apple Health（需要 iOS SDK）、Oura Ring（睡眠、准备度、活动）、WHOOP（恢复、负荷、睡眠）、Polar（训练、睡眠、活动）、Withings（手表、体重秤、血压）、Samsung Health（需要 Android SDK）、Google Fit / Health Connect（需要 Android SDK）、Suunto、Coros、Biostrap、Zepp。
营养应用：MyFitnessPal（食物记录、宏量营养素）、Cronometer（详细营养）、MacrosFirst、FatSecret（餐食追踪）。
医疗设备：Freestyle Libre（CGM 血糖数据）、Dexcom（CGM 血糖，特殊流程）、Omron（血压计）。

连接方式

方式一：Widget 流程（推荐）

使用预构建 UI，集成最简单。通过 client.authentication.generatewidgetsession 生成 widget 会话，传入 reference_id、成功/失败重定向 URL，可选 providers 过滤提供商。用户访问 widget URL 后选择提供商、完成 OAuth，重定向到成功 URL，并向你的端点发送 type: "auth" 的 Webhook。

方式二：自定义 UI 流程

自行构建提供商选择界面。先通过 client.integrations.fetch() 获取可用集成，用户选择提供商后调用 client.authentication.authenticateuser 生成授权 URL。注意：授权 URL 必须在真实浏览器中打开，不能使用 WebView 或 iFrame（OAuth 安全要求）。

方式三：移动 SDK（Apple/Samsung/Health Connect 必需）

这些数据源没有 Web API，必须使用移动 SDK：

iOS（Swift）— Apple Health：使用 TerraiOS，调用 Terra.initTerra 初始化，再调用 Terra.initConnection 连接，可设置 schedulerOn: true 启用后台同步。
Android（Kotlin）— Samsung Health / Health Connect：使用 co.tryterra.terra.Terra，minSDK 28，调用 Terra.initTerra 与 Terra.initConnection，可设置 schedulerOn = true。
React Native：使用 terra-react，调用 Terra.initTerra 与 Terra.initConnection。

主要操作

connect-user：将用户连接到可穿戴提供商。支持指定提供商（自定义 UI 流程）或不指定（Widget 流程，由用户选择）。
disconnect-user：断开用户并移除其数据，调用 client.authentication.deauthenticateuser。
get-user-info：获取用户连接状态与详情，包括 user_id、provider、reference_id、scopes、last_webhook_update。
list-connected-users：通过 client.user.getsubscriptions() 列出所有已连接用户。
get-users-by-reference：按内部 reference_id 查找 Terra 用户，返回 TerraUser 列表。

多设备设置

一个用户可以连接多个可穿戴设备。每个提供商创建独立的 Terra User ID，但共享同一个 reference_id。

提供商特定说明

Apple Health（iOS）：需要移动 SDK、iOS 13+，无 Web API，必须使用原生应用，可启用后台同步，连接时请求权限。
Samsung Health / Health Connect（Android）：需要移动 SDK、minSDK 28；Health Connect 是 Google 的统一健康 API，Samsung 使用 Samsung Health SDK。
WHOOP：特殊流程，需联系 Terra 激活；数据包括恢复、负荷、睡眠、HRV。
Dexcom（CGM）：特殊流程，需联系 Terra 激活；数据为连续血糖监测。
Freestyle Libre（EU）：需要专用 API 密钥；数据为 CGM 血糖读数。
Strava：需要专用 API 密钥；数据为活动、路线。

连接相关 Webhook 事件

用户连接或断开时会收到 Webhook：

连接成功（type: "auth"）：包含 user_id、provider、reference_id，status 为 authenticated。
断开连接（type: "deauth"）：包含 user_id、provider，status 为 deauthenticated。
连接错误（type: "connection_error"）：包含 user_id、provider 及错误消息。

数据库表建议

资料提供了 terra_connections 表结构建议，包含 id、user_id、terra_user_id、provider、reference_id、connected_at、last_sync、status、scopes 等字段，并建议在 user_id 与 reference_id 上建立索引。

限制

Apple Health、Samsung Health、Health Connect 必须使用移动 SDK，无法通过 Web API 连接；WHOOP、Dexcom 需要联系 Terra 激活特殊流程；Freestyle Libre（EU）与 Strava 需要专用 API 密钥；授权 URL 必须在真实浏览器中打开，不能使用 WebView 或 iFrame。

技能介绍

用途