企业官网建设流程全解析

移动端健康数据同步全解：Open Wearables iOS、Android、Flutter与React Native四大SDK使用指南

【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables

Open Wearables是一个自托管的可穿戴健康数据统一平台，它的移动端 SDK 能帮你把Apple HealthKit、Samsung Health、Health Connect里的健康数据自动同步到统一 API，而且 iOS、Android、Flutter、React Native 四大框架全部支持。这篇指南会用最少的心智负担，讲清楚移动端健康数据同步的完整流程：认证怎么配、五个生命周期调用怎么排、四个 SDK 怎么选、数据同步后流向哪里，以及上线前的关键检查清单。

一、为什么移动端健康数据要"主动推送"？

先理解一个关键区别：

上图是云端服务商的集成流程。而 HealthKit、Samsung Health 和 Health Connect没有云 API——健康数据只保存在用户设备上，所以 Open Wearables 为移动端设计了一套推送模型：SDK 读取本地健康数据 → 推送到POST /api/v1/sdk/users/{userId}/sync→ 平台归一化存入统一数据模型。

四大 SDK 的核心能力完全一致：

• ⚡后台同步：iOS 用 Background App Refresh + BGTaskScheduler，Android 用 WorkManager，App 在后台也能同步
• 🎯增量更新：基于锚点查询，只同步上次同步之后的新数据，省电池省流量
• 🔐安全存储：凭证存在 iOS Keychain / Android EncryptedSharedPreferences，API 密钥永不出你的后端
• 📊40+ 数据类型：步数、心率、HRV、血氧、睡眠、运动、体脂、血糖等

二、认证架构：后台签发短令牌，App 永远不碰 app_secret

无论用哪个 SDK，认证流程都是同一条路（详见 docs/sdk/integration.mdx）：

1. 在开发者门户Settings → Credentials → SDK Applications创建应用，拿到app_id和app_secret，存放在你自己的后端
2. 后端调用POST /api/v1/users/{user_id}/token，换取该用户的access_token（60 分钟有效）+refresh_token
3. 后端通过你自己的 API 把令牌转给 App，App 调用 SDK 的signIn()
4. SDK 用 access token 上传数据；令牌过期时自动走POST /api/v1/token/refresh刷新

⚠️安全红线：永远不要把app_id/app_secret打包进 App。SDK 令牌只能写/sdk/*端点且仅限本用户，即使泄露也无法读取数据或冒充他人。

没有自己后端的场景（比如个人自托管使用）可以改用一次性邀请码：通过POST /api/v1/users/{user_id}/invitation-code生成，App 在POST /api/v1/invitation-code/redeem兑换令牌。官方文档明确建议：生产级多用户集成请走后台令牌流程。

三、SDK 生命周期：记住这张图的 5 个调用

四大 SDK 的调用顺序完全相同，这也是新手最容易踩坑的地方：

每次 App 启动：

1. configure(host)—— 先配置你的 Open Wearables 地址，并自动恢复已有用户的后台同步
2. isSessionValid()—— 若为 true，什么都不用做，后台同步自己会跑

每个用户只执行一次的首次连接：

3. 从你的后端拿到令牌 →signIn(userId, accessToken, refreshToken)
4. setProvider("google")（仅 Android，选 Health Connect 或 Samsung Health）
5. requestAuthorization(types)—— 只申请需要的类型，权限列表过长会降低用户授权率
6. startBackgroundSync(syncDaysBack)——syncDaysBack: 0表示不限量（上传全部历史），建议先设 30/90 天

三个高频坑：

• 🚫别在每次启动都调signIn()：它会重置同步状态，导致历史窗口重复上传
• 🔁 收到onAuthError（刷新令牌失效）时，从后端拿新令牌调updateTokens()，不要重新signIn()
• 🔌 用户退出时，先用 SDK access token 调DELETE /api/v1/users/{user_id}/connections/{provider}上报断开，再stopBackgroundSync()+signOut()；否则后端永远不会知道用户已离开（iOS SDK 0.15.0 起signOut()会自动上报）

四、四大 SDK 选型与安装速查

4.1 一张表看懂差异

选型口诀：原生 App 用原生 SDK；Flutter / React Native 项目直接用对应封装版——核心同步逻辑（后台执行、流式上传、重试、安全存储）全部由底层原生实现承担，跨平台层只提供统一 API。

4.2 各平台必须做的配置

iOS（HealthKit 配置一次，一劳永逸）：

• Info.plist加NSHealthShareUsageDescription、UIBackgroundModes（fetch + processing）、两个com.openwearables.healthsdk.task.*后台任务标识
• Xcode 里开启 HealthKit capability 并勾选Background Delivery
• 在AppDelegate挂上setBackgroundCompletionHandler（后台上传必需）
• 只能在真机测试——模拟器不支持 HealthKit

Android（双数据源，注意上架合规）：

• minSdk = 29，compileSdk = 36
• SDK 会自动合并所需权限；用不到的READ_*权限请用tools:node="remove"移除，Google Play 会逐条审查健康权限
• 在 Play Console 完成 Health apps 声明并公开隐私政策；Android 13+ 运行时请求POST_NOTIFICATIONS，否则同步通知会被隐藏
• setProvider("google")选 Health Connect（类型覆盖最全），或"samsung"选 Samsung Health（需三星审批后才能用于发布版）

React Native 特别提醒📦：包尚未发布到 npm，目前需从 GitHub 固定 commit 安装，且 Android 原生依赖要先publishToMavenLocal，详见 docs/sdk/react-native/index.mdx。Expo 项目记得加open-wearablesconfig plugin 并设minSdkVersion: 29。

各平台的完整代码示例见官方集成指南：iOS、Android、Flutter、React Native。

五、同步后的数据去向：统一数据模型

SDK 把原始数据推上来后，Open Wearables 会做归一化：不同类型的时序数据（步数、心率、体重、能量……）各建一条独立数据系列；运动、睡眠等事件型数据进入EventRecord，挂上WorkoutDetails/SleepDetails明细。

之后你可以通过 REST API 读取摘要、时序数据、运动记录和健康评分，也可以通过 Webhook 在新数据到达时收到通知——移动端同步只是数据入口，后续消费全部走平台统一的 API。

六、上线前检查清单与常见问题

• ✅app_id/app_secret只存在后端，App 端只有短令牌
• ✅ iOS：HealthKit Background Delivery 已开启、两个后台任务 ID 已注册、真机验证过同步
• ✅ Android：Play Console 健康应用声明完成、冗余健康权限已移除、通知权限已请求
• ✅ 首次历史上传期间用getSyncStatus()的initialExportDone判断进度，期间提示用户保持 App 在前台
• ✅ 用户注销流程：先调 DELETE 断开连接，再stopBackgroundSync()+signOut()

遇到同步不动、权限拒绝、后台不触发等问题，各平台都配有排障文档：iOS · Android · Flutter · React Native。

七、从 0 到跑起来：上手步骤

1. 克隆仓库并启动平台（Docker 一条命令）：

   docker compose up -d

2. 打开 http://localhost:3000 开发者门户，创建 SDK Application 拿到app_id/app_secret（详见 README 与 docs/sdk/index.mdx）

3. 为你的用户调用POST /api/v1/users创建 Open Wearables 用户

4. 按本文第三、四节在你的 App 里接上 SDK，先设一个 90 天的syncDaysBack试跑

更多深入内容建议直接阅读仓库内的 SDK 文档目录：docs/sdk/ 下有总览、跨平台集成指南，以及 iOS、Android、Flutter、React Native 四个子目录的完整指南与排障手册。

【免费下载链接】open-wearablesSelf-hosted platform to unify wearable health data through one AI-ready API.项目地址: https://gitcode.com/gh_mirrors/op/open-wearables