遷移指南

Google Health API 是從頭建構的新 API，可供開發人員查詢 Fitbit 使用者資料。這項異動不只是更新，更是策略性措施，可確保您的應用程式安全無虞、穩定可靠，並為未來健康技術的進展做好準備。API 支援新的應用程式註冊控制台、Google OAuth 2.0 支援、新資料類型、新端點結構定義和新回應格式。

本指南旨在協助開發人員將現有的 Fitbit Web API 應用程式遷移至新的 Google Health API。

為什麼要遷移？

使用 Google Health API 的優點如下：

  • 安全再升級：遵守 Google 的安全性最佳做法，符合 Google 的安全性、隱私權和身分識別標準。
  • 一致性：消除資料格式、時區、測量單位和錯誤處理方面的舊版不一致問題，提供更直覺的開發人員體驗。
  • 擴充性與前瞻性：可因應未來需求擴充，並支援 gRPC 等現代通訊協定。

應用程式註冊

所有 Google Health API 應用程式都必須使用 Google Cloud 控制台註冊，這個平台是管理所有 Google 應用程式的中心樞紐。

如需註冊應用程式的操作說明，請按照「開始使用」一文中的步驟操作。以下說明註冊應用程式時會發現的差異。

Fitbit Web API Google Health API
公開連結 https://dev.fitbit.com/apps https://console.cloud.google.com
新增應用程式 按下「Register a new app」(註冊新應用程式)
  1. 建立 Google Cloud 專案
  2. 啟用 Google Health API
基本資訊 請填寫下列欄位：
  • 應用程式名稱
  • 說明
  • 應用程式網站網址
  • 機構
  • 機構網站網址
  • 服務條款網址
  • 隱私權政策網址
 請填寫下列欄位：
  • 應用程式名稱
  • 支援服務電子郵件地址
  • 目標對象 (內部或外部)
  • 聯絡電子郵件
  • 標誌圖示
  • 應用程式網站網址
  • 隱私權政策網址
  • 服務條款網址
  • 授權網域
應用程式類型 開發人員必須選取：
  • 伺服器
  • 用戶端
  • 個人
  • 網頁應用程式
  • Android
  • Chrome 擴充功能
  • iOS
  • 電視
  • 電腦版應用程式
  • 通用 Windows 平台
用戶端 ID 儲存應用程式設定時註冊 另行註冊
存取類型 讀取及寫入權限是在應用程式層級控管 讀取和寫入權限是在範圍層級控管
其他網址
  • 重新導向網址：使用者授權範圍後重新導向的網站
  • 已授權的 JavaScript 來源：代管網頁應用程式的 HTTP 來源
  • 重新導向網址：使用者授權範圍後重新導向的網站

OAuth 實作

Google 健康資料 API 應用程式僅支援 Google OAuth2 用戶端程式庫。我們提供熱門架構的用戶端程式庫，可簡化 OAuth 2.0 的實作程序。Google OAuth2 程式庫與開放原始碼 OAuth2 程式庫的差異如下：

Fitbit Web API Google Health API
支援 OAuth2 程式庫 開放原始碼 Google OAuth2 用戶端程式庫
功能 跨平台不一致 跨平台一致
授權網址 https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
權杖網址 https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
存取權杖存留時間 8 小時 1 小時
存取權杖大小 1,024 個位元組 2048 個位元組
更新權杖 使用授權碼授予流程時，系統會產生更新權杖。每位使用者只能產生 1 個更新權杖。權杖不會過期，但只能使用一次。 如要產生更新權杖，授權字串必須包含查詢參數「access_type=offline」。您可以為單一使用者建立多個重新整理權杖。重新整理權杖可以根據時間設定。如果 6 個月未使用、使用者授予限時存取權，或應用程式處於「測試」模式，存取權就會過期。詳情請參閱「更新權杖到期日」。
權杖回應 JSON 回應包含：
  • 存取權杖
  • 存取權杖到期
  • 範圍
  • 權杖類型
  • 更新權杖
  • 使用者 ID
 JSON 回應包含：
  • 存取權杖
  • 存取權杖到期
  • 範圍
  • 權杖類型
  • 更新權杖

如要取得使用者 ID，請使用 users.getIdentity 端點。

由於您的應用程式使用不同的 OAuth 程式庫，Fitbit 使用者必須重新同意新的整合項目。存取權杖和更新權杖無法轉移至 Google Health API 並正常運作。

範圍

您必須更新授權要求，才能使用 Google Health API 範圍。 範圍會定義應用程式是否支援讀取或寫入作業。請勿使用應用程式不需要的範圍。如果應用程式設計有所變更，您隨時可以新增更多範圍。

Google Health API 範圍是 HTTP 網址，開頭為 https://www.googleapis.com/auth/googlehealth.{scope}。例如，https://www.googleapis.com/auth/googlehealth.activity_and_fitness。

範圍對應

以下說明 Fitbit Web API 範圍如何對應至 Google Health API 範圍：

表格：Fitbit Web API 至 Google Health API 範圍對應
Fitbit Web API 範圍 Google Health API 範圍
活動 .activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness .activity_and_fitness
.activity_and_fitness.readonly
心率 .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
位置 .location.readonly
營養學 .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
資料 .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
設定 .settings
.settings.readonly
睡眠 .sleep
.sleep.readonly
溫度 .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
重量 .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

資料類型

以下列出 Google Health API 資料型別，以及這些型別如何對應至 Fitbit Web API。

表格：Fitbit Web API 到 Google Health API 的資料類型對應
Fitbit Web API 資料類型 Google Health API 資料類型
  端點 ID
活動區間分鐘數 活動區間分鐘數
  active-zone-minutes
包含使用者活動等級的變更 活動量
  activity-level
海拔高度 海拔高度
  altitude
體脂肪 體脂肪
  body-fat
在每個心率區間內的時間：caloriesOut 心率區間消耗的熱量
  calories-in-heart-rate-zone
心率變異度摘要 每日心率變異
  daily-heart-rate-variability
血氧濃度摘要 每日血氧濃度
  daily-oxygen-saturation
靜止心率 每日靜止心率
  daily-resting-heart-rate
皮膚溫度 每日睡眠溫度變化
  daily-sleep-temperature-derivations
距離 距離
  distance
已錄製的活動 運動
  exercise
樓層數 樓層數
  floors
心跳速率 心率
  heart-rate
HRV 當日 心率變異
  heart-rate-variability
當日血氧濃度 血氧濃度
  oxygen-saturation
使用者跑步時的最大攝氧量值 跑步最大攝氧量
  run-vo2-max
活動時間序列分鐘數 (久坐) 不活動時間
  sedentary-period
睡眠 睡眠
  sleep
步驟 步驟
  steps
活動 caloriesOut 總熱量
  total-calories
最大攝氧量值 最大攝氧量
  vo2-max
重量 體重
  weight

端點

REST 端點會針對所有資料類型採用一致的語法。

  • 服務端點：基本 HTTP 網址會變更為 https://health.googleapis.com。
  • 端點語法：Google Health API 支援的端點數量有限，但大多數支援的資料類型都能使用。這項功能可為所有資料類型提供一致的語法，方便您使用端點。
  • 使用者 ID：端點語法中應指定使用者 ID 或 me。使用我時，系統會從存取權杖推斷 User-ID。

範例：以下範例說明如何使用 Google Health API 呼叫 GET Profile 端點

GET https://health.googleapis.com/v4/users/me/profile

端點對應

如需可用資料類型及其支援的 API 方法清單，請參閱「資料類型可用性」表格。

Fitbit Web API 端點類型 Google Health API
GET (記錄 | 摘要 | 每日摘要)，您要求的是單日資料 dailyRollup 方法，其中 windowSize = 1 天
GET (Intraday)，用於要求精細資料 list 方法
依日期或間隔取得 (時間序列) rollUp 或 dailyRollUp 方法，包括日期範圍
GET (記錄清單) list 方法
建立及更新記錄 patch 方法
刪除記錄 batchDelete 方法
取得設定檔 users.getProfile 會傳回使用者的特定資訊
users.getSettings 會傳回使用者的單位和時區
更新個人資料 users.updateProfile 可修改使用者的特定資訊
users.updateSettings 可修改使用者的單位和時區
取得使用者 ID users.getIdentity 會傳回使用者的 Fitbit 舊版和 Google 使用者 ID。

遷移使用者

從 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 版本是開發人員的必要條件。

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

程式碼範例

如要從舊版 Fitbit Web API 遷移至 Google Health API，您需要從一般 OAuth2 程式庫改用 Google Auth 程式庫。以下是架構建議，以及以 JavaScript 撰寫的虛擬程式碼實作方式，可處理這個「雙程式庫」狀態。

1. 「中介軟體切換」

由於您無法一次遷移所有使用者，後端必須根據資料庫中儲存的使用者目前 apiVersion，判斷要使用哪個程式庫。

導入

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. 遷移使用者體驗流程

如要盡量提高留存率，請使用「中斷並升級」模式。這樣可確保使用者在與應用程式互動前，不會被迫重新登入。

重新導向邏輯

當 Fitbit Web API 使用者使用特定功能時，觸發遷移作業：

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. 主要技術轉換

撰寫 JavaScript 遷移指令碼時，請注意以下差異：

功能 Fitbit Web API (舊版) Google Health API (Google-Identity)
權杖端點 https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
驗證程式庫 標準開放原始碼 Google 驗證
範圍 活動 https://www.googleapis.com/auth/googlehealth.activity_and_fitness
使用者 ID /oauth2/token 回應中傳回的 Fitbit 編碼 ID 從 users.getIdentity 端點傳回的使用者 ID

4. 保留檢查清單

  • 工作階段持續性：請勿清除使用者的舊 Fitbit Web API 工作階段，直到 Google Health API access_token 成功驗證並儲存至資料庫為止。
  • 自動撤銷：Google Health API 遷移完成後，請使用 POST 要求傳送至舊版 Fitbit 撤銷端點：https://api.fitbit.com/oauth2/revoke。這樣一來，使用者就不會在 Fitbit 設定中看到「重複」的應用程式權限。
  • 錯誤處理：如果 Fitbit 呼叫傳回 401 Unauthorized，請自動重新導向至 Google OAuth 流程，而非顯示錯誤訊息。