סקירה כללית

‫Google Health API הוא פתרון מקיף שנבנה מהיסוד, ומספק למפתחים גישה חזקה למגוון רחב של נתוני בריאות וכושר של משתמשים שהתקבלה מהם הסכמה, ולסוגי נתונים שונים. ב-Google Health API יש מסוף חדש לרישום אפליקציות, Google OAuth 2.0, סוגי נתונים חדשים, סכימה חדשה של נקודות קצה ופורמט חדש לתגובות.

המדריך הזה נועד לעזור למפתחים להעביר את האפליקציות הקיימות שלהם מ-Fitbit Web API ל-Google Health API החדש. הוא כולל המלצות שיעזרו לכם להעביר את המשתמשים בצורה חלקה ולשמר אותם.

למה כדאי לעבור?

זה לא סתם עדכון, אלא מהלך אסטרטגי שנועד לוודא שהאפליקציות שלכם מאובטחות ומוכנות לפיתוחים עתידיים בטכנולוגיה בתחום הבריאות. אלה כמה מהיתרונות של השימוש ב-Google Health API:

  • גישה לנתונים מקיפים: גישה נרחבת למגוון רחב של נתוני בריאות וכושר של משתמשים שהביעו הסכמה, ולסוגי נתונים שונים.
  • אבטחה משופרת: עמידה בשיטות המומלצות של Google לאבטחה, בהתאם לתקני האבטחה, הפרטיות והזהות של Google.
  • עקביות: מבטלת חוסר עקביות בפורמטים של נתונים, באזורי זמן, ביחידות מידה ובטיפול בשגיאות, כדי לספק למפתחים חוויה אינטואיטיבית יותר.
  • יכולת התאמה לעומס ומוכנות לעתיד: הממשק מותאם לעומסים כדי לעמוד בדרישות עתידיות, והוא תומך בפרוטוקולים מודרניים כמו gRPC.

המעבר מ-Fitbit Web API ל-Google Health API כולל יותר משינויים טכניים. בגלל המעבר לספריית OAuth חדשה, אי אפשר להעביר טוקנים קיימים של גישה וטוקנים רענון, והמשתמשים צריכים להביע שוב הסכמה לשילוב המעודכן.

תמיכה בשתי שיטות ההתחברות

ממשק Fitbit Web API וממשק Google Health API משתמשים במערכות שונות כדי לטפל בהתחברויות של משתמשים. לכן, כל עוד ממשקי Fitbit Web API עדיין פעילים, האפליקציה שלכם תצטרך לתמוך באופן זמני בשתי שיטות האימות בקרב בסיס המשתמשים שלכם.

במקום שהאפליקציה תבקש נתונים ישירות, צריך להטמיע שכבה שמחליטה אם לתקשר עם Fitbit Web API או עם Google Health API בשביל משתמש ספציפי, כדי ששאר האפליקציה לא תצטרך להתעסק בפרטים.

מעדכנים את מסד הנתונים של המשתמשים כך שיכלול דגל (לדוגמה, oauth_type) כדי לזהות באיזו מערכת התחברות הם משתמשים.

  • למשתמשים חדשים: הגדרה אוטומטית של Google Health API החדש (oauth_type: google).
  • למשתמשים קיימים: משאירים אותם ב-Fitbit Web API עד שהם מעדכנים את ההסכמה שלהם (oauth_type: fitbit).
תרחיש לדוגמה מדינה אחת (oauth_type) Active API Stream פעולה נדרשת
הדרכה למשתמשים חדשים google רק Google Health API מפעילים את Google OAuth בדפדפן של המערכת וממפים את המזהים באמצעות users.getIdentity.
משתמשי Fitbit קיימים (שעדיין לא עברו לחשבון Google) fitbit רק Fitbit Web API להמשיך לסנכרן עם Fitbit Web API; להציג הודעה באפליקציה שאפשר לסגור כדי לשדרג.
משתמשי Fitbit קיימים שמשלימים את ההעברה fitbit ← google מעבר ל-Google Health API מאמתים את היקפי ההרשאות שניתנו, קוראים ל-users.getIdentity (legacyUserId ← healthUserId), מחליפים את oauth_type ב-google ומבטלים מיד את האסימונים הקודמים של Fitbit.

כדי לא לפגוע בחוויית המשתמש, מומלץ לא לאלץ את כולם לצאת ולהיכנס מחדש. במקום זאת:

  1. כשמשתמש שעדיין מחובר ל-Fitbit Web API יוצר אינטראקציה עם האפליקציה, כדאי להציג לו הודעה ידידותית שמעודדת אותו לעדכן את החיבור.
  2. כשהמשתמש מאשר את פעולת העדכון, צריך להפעיל את תהליך ההתחברות ל-Google Health באותו רגע.
  3. אחרי שההתחברות ל-Google תצליח, שמרו את פרטי הכניסה החדשים של Google בפרופיל של המשתמש, שנו את הדגל oauth_type שלו מ-fitbit ל-google, והשביתו מיד את הסנכרון הקודם על ידי ביטול הטוקנים הקודמים של Fitbit באופן פרוגרמטי כדי למנוע הטמעת נתונים כפולים וקישור כפול.

המשכיות הנתונים

כשמעבירים שילוב מ-Fitbit Web API הקודם ל-Google Health API, האפליקציות של המפתחים צריכות להביא בחשבון שינוי במבנים של זיהוי המשתמשים.

ממשק Fitbit Web API הקודם מזהה חשבונות באמצעות מחרוזת אלפאנומרית באורך 6 תווים (למשל A1B2C3), ואילו Google Health API משתמש ב-healthUserId בפורמט של מחרוזת באורך של עד 63 ספרות ותווים.

כדי לגשר על הפער הזה בלי לאבד את ההקשר של המשתמש, המפתחים יכולים לשלוח שאילתה לנקודת הקצה (endpoint) של getIdentity כדי לקבל את מזהי המשתמשים ב-Fitbit וב-Health. נקודת הקצה הזו מחזירה מטען ייעודי (payload) שמכיל גם את legacyUserId וגם את healthUserId החדש, וכך מאפשרת לאפליקציות ליצור באופן דינמי מיפוי בין הרשומות הקיימות לבין מערכת החשבונות החדשה.

טיפול בחשבונות Google לא מקושרים

כדי שהאפליקציה שלכם תוכל לסנכרן נתונים באמצעות Google Health API, המשתמש צריך להיכנס לאפליקציה לנייד של Google Health ולקשר את Google Health לחשבון שלו ב-Google. קישור של Google Health לפני הסכמה ל-OAuth מכיוון ש-Google OAuth 2.0 מאמת כל חשבון Google תקין במהלך ההסכמה, הוא לא יכול לחסום חשבונות שעדיין אין להם פרופיל פעיל ב-Google Health.

אם משתמש משלים את הסכמת Google OAuth לפני שהוא יוצר פרופיל ב-Google Health או לפני שהוא מעביר את החשבון הקודם שלו ב-Fitbit לחשבון Google, קריאה ל-users.getIdentity או לנקודת קצה (endpoint) של נתונים מחזירה שגיאת HTTP 400 Bad Request עם הסטטוס FAILED_PRECONDITION והסיבה ACCOUNT_NOT_LINKED:

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

כדי לבדוק את הגישה לחשבון ולטפל בשגיאה הזו:

  1. מחליפים את קוד ההרשאה של OAuth באסימונים וקוראים מיד ל-users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) לפני שמסמנים את החשבון כמקושר בממשק המשתמש של האפליקציה.
  2. אם users.getIdentity או קריאה לסנכרון נתונים ברקע מחזירה את קוד הסטטוס 400 של HTTP עם הסיבה ACCOUNT_NOT_LINKED, אל תסמנו את החשבון כמחובר. אם המשתמש עובר מ-Fitbit Web API הקודם, צריך להשאיר את החיבור הקיים ל-Fitbit פעיל ולא לבטל את הטוקנים הקודמים של Fitbit.
  3. הצגת הנחיה לפעולה שמתייחסת גם למשתמשים חדשים שמעולם לא יצרו חשבון Google Health או Fitbit, וגם למשתמשי Fitbit קיימים שעדיין לא עברו לחשבון Google:

    "חשבון Google שלך עדיין לא מקושר ל-Google Health. כדי ליצור פרופיל, פותחים את אפליקציית Google Health לנייד ונכנסים באמצעות חשבון Google. אפשר גם להעביר את חשבון Fitbit הקיים לחשבון Google, ואז לחזור לכאן כדי להתחבר".

  4. מוסיפים כפתור קריאה לפעולה שפותח את redirect_uri מהמטא-נתונים של השגיאה (https://fitbit.google.com/auth/signup) או מפנה משתמשים עם חשבון Fitbit מדור קודם למאמר העזרה בנושא העברת חשבון Fitbit.

מילוי חוסרים בנתונים היסטוריים

אם משתמש לא יאמת את נקודות הקצה החדשות של Google Health API לפני שנקודות הקצה הקודמות יושבתו, הנתונים שלו עדיין יהיו זמינים כל עוד הוא ימשיך לסנכרן את המכשיר שלו עם אפליקציית Google Health. עם זאת, יכול להיות שיהיה פער בנתונים של המשתמש הזה.

כדי למלא את הנתונים ההיסטוריים של המשתמשים, אחרי שהם יאמתו מחדש את נקודות הקצה החדשות, תוכלו להשתמש ב-Google Health API. להנחיות, ראו שאילתות לגבי נתונים היסטוריים.

הטמעה לדוגמה של העברה וקישור

ההטמעה הבאה לדוגמה ממחישה איך לטפל בקריאה החוזרת (callback) של OAuth, לאמת הסכמה חלקית או חוסר הסכמה, לזהות את המשתמש באמצעות users.getIdentity (כולל טיפול ב-HTTP 400 ACCOUNT_NOT_LINKED), למנוע קישור כפול על ידי ביטול טוקנים קודמים של Fitbit, ולנתב בקשות נתונים באמצעות oauth_type:

import requests

GOOGLE_HEALTH_IDENTITY_URL = "https://health.googleapis.com/v4/users/me/identity"
FITBIT_REVOKE_URL = "https://api.fitbit.com/oauth2/revoke"
DEFAULT_SIGNUP_URL = "https://fitbit.google.com/auth/signup"


def complete_google_health_linking(user_record: dict, oauth_token_response: dict, fitbit_client_creds: str) -> dict:
  """Completes Google Health account linking and migrates legacy Fitbit users."""
  # 1. Check granted scopes (handle zero consent and partial consent)
  granted_scopes = set(oauth_token_response.get("scope", "").split())
  health_scopes = {s for s in granted_scopes if s.startswith("https://www.googleapis.com/auth/googlehealth")}
  if not health_scopes:
    return {
        "status": "MISSING_PERMISSIONS",
        "ui_action": "ROUTE_TO_MISSING_PERMISSIONS_SCREEN",
        "message": "At least one permission is required to connect to Google Health.",
    }

  access_token = oauth_token_response["access_token"]

  # 2. Call users.getIdentity and handle HTTP 400
  # (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED").
  identity_resp = requests.get(
      GOOGLE_HEALTH_IDENTITY_URL,
      headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
      timeout=10,
  )
  if identity_resp.status_code == 400:
    error_payload = identity_resp.json().get("error", {})
    if error_payload.get("status") == "FAILED_PRECONDITION":
      for detail in error_payload.get("details", []):
        if detail.get("reason") == "ACCOUNT_NOT_LINKED":
          redirect_uri = detail.get("metadata", {}).get("redirect_uri", DEFAULT_SIGNUP_URL)
          return {
              "status": "ACCOUNT_NOT_LINKED",
              "ui_action": "PROMPT_LINK_GOOGLE_HEALTH_ACCOUNT",
              "redirect_uri": redirect_uri,
              "message": (
                  "Your Google Account isn't linked to Google Health yet. "
                  "Open the Google Health mobile app and sign in with your Google Account "
                  "to create a profile, or move your existing Fitbit account to your "
                  "Google Account, then return here to connect."
              ),
          }
  identity_resp.raise_for_status()
  identity = identity_resp.json()

  # 3. Verify legacyUserId and map legacyUserId -> healthUserId.
  previous_oauth_type = user_record.get("oauth_type")
  legacy_fitbit_refresh_token = user_record.get("fitbit_refresh_token")
  existing_legacy_id = user_record.get("legacy_user_id")
  returned_legacy_id = identity.get("legacyUserId")
  legacy_id_verified = bool(returned_legacy_id) and (
      not existing_legacy_id or returned_legacy_id == existing_legacy_id
  )
  if previous_oauth_type == "fitbit" and not legacy_id_verified:
    return {
        "status": "LEGACY_ID_MISMATCH",
        "ui_action": "PROMPT_VERIFY_FITBIT_MIGRATION_ACCOUNT",
        "message": (
            "The Google Account you signed in with does not match your linked "
            "Fitbit account. Sign in with the Google Account linked to your "
            "Fitbit profile."
        ),
    }

  # 4. Cut over oauth_type and revoke legacy Fitbit token once verified.
  user_record.update({
      "health_user_id": identity.get("healthUserId") or user_record.get("health_user_id"),
      "legacy_user_id": returned_legacy_id or existing_legacy_id,
      "google_access_token": access_token,
      "google_refresh_token": oauth_token_response.get("refresh_token"),
      "granted_scopes": list(health_scopes),
      "oauth_type": "google",
      "fitbit_access_token": None,
      "fitbit_refresh_token": None,
  })

  if previous_oauth_type == "fitbit" and legacy_fitbit_refresh_token:
    requests.post(
        FITBIT_REVOKE_URL,
        headers={
            "Authorization": f"Basic {fitbit_client_creds}",
            "Content-Type": "application/x-www-form-urlencoded",
        },
        data={"token": legacy_fitbit_refresh_token},
        timeout=10,
    )

  return {
      "status": "CONNECTED",
      "health_user_id": user_record["health_user_id"],
      "granted_scopes": user_record["granted_scopes"],
  }

תקשורת ותזמון

כדי לעזור למשתמשים לעבור מ-Fitbit OAuth הקיים ל-Google OAuth החדש, כדאי לפעול לפי השיטות המומלצות הבאות.

תקשורת שמתמקדת בערך

אל תתחילו עם "עדכנו את ה-API שלנו", אלא עם היתרונות של שילוב הנתונים ב-Google Health באפליקציה שלכם, אבל ודאו שהם מודעים לכך שהם צריכים לאמת מחדש אם הם רוצים שהנתונים שלהם יסונכרנו:

  • חשוב להסביר בבירור אילו תכונות באפליקציה מופעלות באמצעות השילוב, ולהתאים את המסר ליתרונות שהמשתמשים יכולים להפיק מהתכונות האלה.
  • התמקדו בתכונות שלכם וספקו תרחישי שימוש במקום פרטים טכניים על ההטמעה.
  • מה לא להגיד: "לא תהיה לך אפשרות להתחבר ל-API של Fitbit".
  • מה כן להגיד: "כדי להמשיך לראות אימונים מפורטים עם נתוני דופק, צריך להביע שוב הסכמה לממשקי ה-API של Google Health".

מתי להודיע למשתמשים

בכל התקשורת עם המשתמשים, צריך לפעול לפי הנחיות המיתוג של Google Health ולהשתמש בבאנרים, בכרטיסים או בהתראות שאפשר לסגור.

  • אל תפעילו את מסך ההסכמה מחדש בזמן שהמשתמש באמצע אימון או מתעד משהו באופן ידני.
  • רק אחרי כמה שבועות של אזהרות, כדאי להפוך את קבלת ההסכמה מחדש לחובה, בהתאם למועדים הרשמיים להוצאה משימוש של Fitbit Web API.
  • אם משתמש לא הביע הסכמה מחדש אחרי המועד האחרון, צריך לספק לו דרך נוחה להביע הסכמה. הציגו הודעת עזרה בבאנר, בכרטיס או בהסבר קצר כדי לעזור להם להבין למה הנתונים שלהם חסרים ואיך לפתור את הבעיה.

תכנון המגבלות על קצב הקצאת אסימוני OAuth

כשמשתמשי Fitbit קיימים מסכימים מחדש ל-Google Health API, כל הרשאת משתמש נספרת במגבלת הקצב של הענקת אסימוני OAuth בפרויקט בענן שלכם ב-Google Cloud. המגבלה הזו קובעת כמה משתמשים יכולים לאשר את האפליקציה שלכם בדקה ובחלון זמן של 24 שעות.

אם אתם צופים שתחרגו מ-10,000 הרשמות של משתמשים או אימותים מחדש בחלון זמן של 24 שעות במהלך ההעברה, בצעו את השלבים הבאים כדי להימנע מהגבלת קצב של יצירת בקשות OAuth:

  1. עוקבים אחרי השימוש בהקצאת הטוקנים בפרויקט בענן ב-Google Cloud.
  2. כדאי לתזמן את ההתראות על המעבר באפליקציה כדי לא לחרוג מהמגבלה היומית של המענקים.
  3. לפני שאתם מבקשים מקבוצות גדולות של משתמשים לאמת מחדש את הזהות שלהם, בקשו להגדיל את המכסה של הקצאת אסימוני OAuth. במאמר מגבלות קצב של יצירת בקשות באפליקציות OAuth מוסבר איך בודקים את השימוש ומבקשים להגדיל את המכסה.