概览

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 表示 Fitbit OAuth，使用 google 表示 Google OAuth。
    • 新用户：默认使用 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 Services (GIS) / Google Auth
用户账号 Fitbit 旧版凭据 Google 账号
令牌类型 Fitbit 专用访问权限 / 刷新 Google 颁发的访问令牌/刷新令牌
范围管理 广泛的权限 精细 / 升级权限

处理账号迁移的细微差别

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

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