總覽

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 Services (GIS) / Google Auth
使用者帳戶 Fitbit 舊版憑證 Google 帳戶
權杖類型 Fitbit 專屬存取權 / 重新整理 Google 發出的存取/更新權杖
範圍管理 權限過於寬鬆 精細 / 增量權限

處理帳戶遷移的細微差異

根據 Fitbit 的文件，使用者將帳戶遷移至 Google 時，通常不會立即失去第三方連結，但變更 API 版本是開發人員端的要求。

  • 檢查權杖是否有效：使用 BackgroundWorker 檢查 Fitbit 權杖是否因「未授權」錯誤而失敗。這可能表示使用者已遷移帳戶，但您的應用程式尚未跟上。
  • 正常失敗：如果 Fitbit OAuth 呼叫失敗，請將使用者重新導向至自訂的「重新連結 Fitbit」頁面，該頁面專門使用新的 Google OAuth 流程。