खास जानकारी

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 राज्य ऐक्टिव एपीआई स्ट्रीम ज़रूरी कार्रवाई
नए उपयोगकर्ता को शामिल करना google सिर्फ़ Google Health API सिस्टम ब्राउज़र में Google OAuth लॉन्च करें और आईडी को users.getIdentity के साथ मैप करें.
Fitbit के मौजूदा उपयोगकर्ता (जिन्होंने अब तक माइग्रेट नहीं किया है) 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 टोकन को रद्द करके, पुराने तरीके से सिंक करने की सुविधा को तुरंत बंद करें. इससे डुप्लीकेट डेटा डालने और दो बार लिंक करने से बचा जा सकता है.

डेटा कंटिन्युइटी (उपयोगकर्ता से मिला डेटा इकट्ठा करके उसे Google Ads में एक्सपोर्ट करना) को पक्का करना

अपने इंटिग्रेशन को Fitbit Web API के लेगसी वर्शन से Google Health API पर माइग्रेट करते समय, डेवलपर ऐप्लिकेशन को उपयोगकर्ता की पहचान करने के स्ट्रक्चर में हुए बदलाव को ध्यान में रखना होगा.

लेगसी Fitbit Web API, खातों की पहचान करने के लिए छह वर्णों वाली अल्फ़ान्यूमेरिक स्ट्रिंग (जैसे, A1B2C3) का इस्तेमाल करता है. वहीं, Google Health API, healthUserId का इस्तेमाल करता है. इसे 63 अंकों और वर्णों वाली स्ट्रिंग के तौर पर फ़ॉर्मैट किया जाता है.

उपयोगकर्ता के कॉन्टेक्स्ट को खोए बिना इस अंतर को कम करने के लिए, डेवलपर getIdentity एंडपॉइंट से क्वेरी करके, Fitbit और Health के यूज़र आईडी पा सकते हैं. यह एंडपॉइंट, legacyUserId और नए healthUserId, दोनों को शामिल करने वाला पेलोड दिखाता है. इससे ऐप्लिकेशन, मौजूदा रिकॉर्ड और नए खाता सिस्टम के बीच डाइनैमिक तौर पर मैपिंग बना सकते हैं.

अनलिंक किए गए Google खातों को मैनेज करना

उपयोगकर्ता को Google Health के मोबाइल ऐप्लिकेशन में साइन इन करना होगा, ताकि वह Google Health को अपने Google खाते से लिंक कर सके. इसके बाद ही, आपका ऐप्लिकेशन Google Health API के ज़रिए डेटा सिंक कर पाएगा. OAuth की सहमति से पहले, Google Health को लिंक करना लेख पढ़ें. Google OAuth 2.0, सहमति देने के दौरान किसी भी मान्य Google खाते की पुष्टि करता है. इसलिए, यह उन खातों को ब्लॉक नहीं कर सकता जिनमें Google Health की कोई चालू प्रोफ़ाइल नहीं है.

अगर कोई उपयोगकर्ता Google Health प्रोफ़ाइल बनाने या अपने लेगसी Fitbit खाते को Google खाते पर माइग्रेट करने से पहले, Google OAuth की सहमति पूरी करता है, तो users.getIdentity या डेटा एंडपॉइंट को कॉल करने पर, एचटीटीपी 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 या बैकग्राउंड में डेटा सिंक करने वाले कॉल से, ACCOUNT_NOT_LINKED की वजह से एचटीटीपी 400 मिलता है, तो खाते को 'कनेक्ट किया गया' के तौर पर मार्क न करें. अगर उपयोगकर्ता, Fitbit Web API के लेगसी वर्शन से माइग्रेट कर रहा है, तो उसके मौजूदा Fitbit कनेक्शन को चालू रखें. साथ ही, उसके लेगसी Fitbit टोकन रद्द न करें.
  3. एक ऐसा प्रॉम्प्ट दिखाएं जिसमें कार्रवाई करने का विकल्प हो. यह प्रॉम्प्ट, उन नए उपयोगकर्ताओं को दिखेगा जिन्होंने कभी Google Health या Fitbit खाता नहीं बनाया है. साथ ही, यह उन मौजूदा Fitbit उपयोगकर्ताओं को दिखेगा जिन्होंने अब तक Google खाते पर माइग्रेट नहीं किया है:

    "आपका Google खाता अब तक Google Health से लिंक नहीं किया गया है. Google Health का मोबाइल ऐप्लिकेशन खोलें और प्रोफ़ाइल बनाने के लिए अपने Google खाते से साइन इन करें. इसके अलावा, अपने मौजूदा Fitbit खाते को Google खाते पर माइग्रेट करें. इसके बाद, कनेक्ट करने के लिए यहां वापस आएं."

  4. कॉल-टू-ऐक्शन बटन दें, जो गड़बड़ी के मेटाडेटा (https://fitbit.google.com/auth/signup) से redirect_uri को खोले या Fitbit के लेगसी उपयोगकर्ताओं को Fitbit खाते को माइग्रेट करने के बारे में सहायता लेख पर रीडायरेक्ट करे.

पुराने डेटा को बैकफ़िल करना

अगर कोई उपयोगकर्ता, लेगसी एंडपॉइंट बंद होने से पहले, Google Health API के नए एंडपॉइंट के लिए अपनी पहचान की पुष्टि नहीं करता है, तो उसका डेटा तब तक उपलब्ध रहेगा, जब तक वह अपने डिवाइस को Google Health ऐप्लिकेशन के साथ सिंक करता रहेगा. हालांकि, हो सकता है कि आपको इस उपयोगकर्ता का पूरा डेटा न मिले.

उपयोगकर्ता के पुराने डेटा को बैकफ़िल करने के लिए, जब उपयोगकर्ता नए एंडपॉइंट पर फिर से पुष्टि कर ले, तब Google Health API का इस्तेमाल किया जा सकता है. ज़्यादा जानकारी के लिए, पुराने डेटा के लिए क्वेरी करना लेख पढ़ें.

माइग्रेशन और लिंकिंग लागू करने का सैंपल

यहां दिए गए रेफ़रंस से पता चलता है कि OAuth कॉलबैक को कैसे मैनेज किया जाए, कुछ हद तक या बिलकुल भी सहमति न मिलने की पुष्टि कैसे की जाए, और users.getIdentity की मदद से उपयोगकर्ता की पहचान कैसे की जाए. इसमें एचटीटीपी 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 पर माइग्रेट करने में मदद करने के लिए, ये सबसे सही तरीके अपनाएं.

वैल्यू-फ़र्स्ट कम्यूनिकेशन

"हमने अपना एपीआई अपडेट किया है" से शुरुआत न करें. इसके बजाय, अपने ऐप्लिकेशन में Google Health डेटा को इंटिग्रेट करने के फ़ायदों से शुरुआत करें. हालांकि, यह पक्का करें कि उन्हें पता हो कि अगर उन्हें अपना डेटा सिंक करना है, तो उन्हें फिर से पुष्टि करनी होगी:

  • साफ़ तौर पर बताएं कि आपके ऐप्लिकेशन में कौनसी सुविधाएं उपलब्ध हैं, जो इंटिग्रेशन की मदद से काम करती हैं. साथ ही, अपने मैसेज को इस तरह से तैयार करें कि उपयोगकर्ता को उन सुविधाओं से फ़ायदा मिले.
  • तकनीकी तौर पर लागू करने की जानकारी देने के बजाय, अपनी सुविधाओं पर ध्यान दें और इस्तेमाल के उदाहरण दें.
  • यह न कहें: "आपके पास Fitbit API से कनेक्ट करने का विकल्प नहीं होगा."
  • यह कहें: "धड़कन की दर के डेटा के साथ कसरत की पूरी जानकारी देखना जारी रखने के लिए, Google Health API को फिर से सहमति दें."

उपयोगकर्ताओं को कब सूचना देनी चाहिए

उपयोगकर्ताओं के साथ होने वाली सभी बातचीत में, Google Health के ब्रैंड से जुड़े दिशा-निर्देशों का पालन करें. साथ ही, खारिज किए जा सकने वाले बैनर, कार्ड या सूचनाओं का इस्तेमाल करें.

  • जब कोई उपयोगकर्ता कसरत कर रहा हो या मैन्युअल तरीके से कोई डेटा लॉग कर रहा हो, तब फिर से सहमति देने वाली स्क्रीन को ट्रिगर न करें.
  • फिर से सहमति लेने की प्रक्रिया को कई हफ़्तों तक चेतावनी देने के बाद ही ज़रूरी बनाएं. यह समयसीमा, Fitbit Web API के बंद होने की आधिकारिक समयसीमा के साथ मेल खानी चाहिए.
  • अगर किसी उपयोगकर्ता ने हार्ड कटऑफ़ के बाद फिर से सहमति नहीं दी है, तो उसे रिकवरी का आसान तरीका उपलब्ध कराएं. बैनर, कार्ड या टूलटिप में मदद करने वाला मैसेज दिखाएं. इससे उन्हें यह समझने में मदद मिलेगी कि उनका डेटा क्यों मौजूद नहीं है और इसे कैसे ठीक करें.

OAuth टोकन के अनुरोध संख्या सीमित करने के लिए प्लान

जब Fitbit के मौजूदा उपयोगकर्ता, Google Health API के लिए फिर से सहमति देते हैं, तो हर उपयोगकर्ता की अनुमति को आपके Google Cloud प्रोजेक्ट के OAuth टोकन की अनुमति देने की दर की सीमा में गिना जाता है. इस सीमा से यह कंट्रोल किया जाता है कि हर मिनट और हर 24 घंटे की स्लाइडिंग विंडो में, कितने उपयोगकर्ता आपके ऐप्लिकेशन को अनुमति दे सकते हैं.

अगर आपको लगता है कि माइग्रेशन के दौरान, 24 घंटे की समयावधि में 10,000 से ज़्यादा उपयोगकर्ता साइन-अप करेंगे या फिर से पुष्टि करेंगे, तो OAuth की अनुरोध संख्या सीमित करने की सुविधा से बचने के लिए, यह तरीका अपनाएं:

  1. अपने Google Cloud प्रोजेक्ट में, टोकन के इस्तेमाल पर नज़र रखें.
  2. इन-ऐप्लिकेशन माइग्रेशन की सूचनाएं भेजने की स्पीड को इस तरह से सेट करें कि वे हर दिन के लिए तय की गई सीमा के अंदर रहें.
  3. उपयोगकर्ताओं के बड़े ग्रुप को फिर से पुष्टि करने के लिए कहने से पहले, OAuth टोकन के लिए ज़्यादा कोटा पाने का अनुरोध करें. अपने इस्तेमाल की जांच करने और सीमा बढ़ाने का अनुरोध करने के निर्देशों के लिए, OAuth ऐप्लिकेशन के लिए अनुरोध संख्या सीमित करना देखें.