概览

Google Health API 是一种全新的 API，可让开发者查询 Fitbit 用户数据。这不仅仅是一次更新，更是一项战略举措，旨在确保您的应用安全可靠，并为健康技术的未来发展做好准备。该 API 支持用于注册应用的新控制台、Google OAuth 2.0 支持、新数据类型、新端点架构和新响应格式。

本指南旨在帮助开发者将其现有的 Fitbit Web API 应用迁移到新的 Google Health API。

为什么应该进行迁移？

使用 Google Health API 的优势如下：

  • 增强的安全性：符合 Google 的安全最佳实践， 与 Google 的安全、隐私和身份标准保持一致。
  • 一致性：消除了数据格式、时区、计量单位和错误处理方面的旧版不一致性，从而提供更直观的开发者体验。
  • 可伸缩性和面向未来 ：旨在根据未来需求进行扩缩，并支持 gRPC 等现代协议。

迁移用户

从 Fitbit Web API 迁移到 Google Health API 不仅仅是技术更新。由于 OAuth 库发生了变化，您的用户必须重新同意您的新集成。访问令牌和刷新令牌无法转移到 Google Health API 并正常运行。为了帮助您在迁移期间提高用户留存率，我们提供了一些技术和战略建议，以确保迁移顺利完成。

双库策略

由于 Fitbit Web API 和 Google Health API 使用不同的 OAuth2 库，因此您必须管理一个“桥接”期，在此期间，这两个库都存在于您的代码库中。

并行授权管理

  • 封装客户端：为 您的“健康服务”创建抽象层或接口。这样，您的应用的其他部分就可以请求数据，而无需知道哪个库（Fitbit OAuth 与 Google OAuth）对该特定用户处于活跃状态。
  • 数据库架构更新：更新用户表以包含 oauth_type 标志。例如，对 Fitbit OAuth 使用 fitbit，对 Google OAuth 使用 google。
    • 新用户：默认使用 Google Health API 和 Google OAuth 库。将 oauth_type 设置为 google。
    • 现有用户：在用户完成 重新同意流程之前，继续使用 Fitbit Web API。将 oauth_type 设置为 fitbit。

“逐步”重新同意流程

不要强制用户退出，而是使用增量授权 方法：

  1. 检测 Fitbit 开源令牌：当 Fitbit Web API 用户 打开应用时，触发“服务更新”通知。
  2. 启动 Google OAuth 流程：当用户点击“更新”时， 启动 Google OAuth2 库流程。
  3. 替换和撤消 ：成功收到 Google OAuth 令牌后，将其保存到用户个人资料，将 oauth_type 从 fitbit 更新为 google，并（如果可能）以编程方式撤消旧的 fitbit 令牌，以保持用户安全个人资料的整洁。

尽可能留住用户

重新同意是用户流失的“危险区域”。为防止用户放弃应用，请遵循以下用户体验最佳实践：

“价值优先”沟通

不要以“我们更新了 API”开头，而是以新的 Google 支持的系统的优势开头：

  • 增强的安全性：提及 Google 行业领先的账号 保护和双重验证。
  • 可靠性：更快的同步时间和更稳定的数据连接。
  • 功能门控：温和地告知用户，新功能和 数据类型需要更新。

智能时机

  • 不要中断高价值任务：切勿在用户正在锻炼或记录食物时触发重新同意 屏幕。
  • “提示”阶段 ：在前 30 天内，使用可关闭的横幅。
  • “硬性截止”阶段 ：仅在发出数周警告后，才强制用户重新同意，与 Fitbit Web API 的正式弃用截止日期一致。

迁移流程比较

清晰区分新旧流程有助于开发者了解逻辑分支的位置。

功能 Fitbit Web API（旧版） Google Health API (Google-Identity)
身份验证库 标准开源 Google Identity 服务 (GIS) / Google 身份验证
用户账号 Fitbit 旧版凭据 Google 账号
令牌类型 Fitbit 专用访问 / 刷新 Google 颁发的访问/刷新令牌
范围管理 广泛权限 精细 / 增量权限

处理账号迁移的细微差别

根据 Fitbit 的文档，将账号迁移到 Google 的用户通常不会立即失去其第三方连接，但更改 API 版本是开发者端的要求。

  • 检查令牌有效性：使用后台工作器检查 Fitbit 令牌是否因“未经授权”错误而失败。这可能表示用户已迁移其账号，但您的应用尚未跟上。
  • 优雅失败：如果 Fitbit OAuth 调用失败，请将用户重定向 到自定义的“重新连接 Fitbit”页面，该页面专门使用新的 Google OAuth 流程。