এক নজরে

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)।
  • আগে থেকে থাকা ব্যবহারকারীদের জন্য: তারা সম্মতি আপডেট (oauth_type: fitbit) না করা পর্যন্ত তাদের Fitbit Web API-তে রাখুন।
ব্যবহারকারীর পরিস্থিতি oauth_type রাজ্য অ্যাক্টিভ API স্ট্রিম প্রয়োজনীয় অ্যাকশন
নতুন ব্যবহারকারীর অনবোর্ডিং google শুধুমাত্র Google Health API সিস্টেম ব্রাউজারে Google OAuth চালু করুন এবং users.getIdentity-এর সাথে আইডি ম্যাপ করুন।
fitbit শুধুমাত্র Fitbit Web API Fitbit Web API-এর সাথে সিঙ্ক করা চালিয়ে যান; আপগ্রেড করার জন্য অ্যাপ-মধ্যস্থ প্রম্পট দেখান যা বাতিল করা যায়।
আগে থেকেই Fitbit ব্যবহার করছেন এমন ব্যবহারকারী মাইগ্রেশন সম্পূর্ণ করছেন fitbit → google Google Health API-এ কাট ওভার করুন অনুমতি দেওয়া স্কোপ যাচাই করুন, users.getIdentity (legacyUserId → healthUserId) কল করুন, oauth_type থেকে google-এ পাল্টান এবং পুরনো Fitbit টোকেন অবিলম্বে তুলে নিন।

ব্যবহারকারীর অভিজ্ঞতা যাতে বিঘ্নিত না হয়, তার জন্য আমরা সবাইকে লগ-আউট করে আবার লগ-ইন করার জন্য বাধ্য না করার সাজেশন দিই। তার পরিবর্তে:

  1. Fitbit ওয়েব API-এর সাথে কানেক্টেড থাকা কোনও ব্যবহারকারী আপনার অ্যাপের সাথে এনগেজ হলে, তাকে একটি বন্ধুত্বপূর্ণ বিজ্ঞপ্তি দেখান যাতে তিনি কানেকশন আপডেট করার জন্য উৎসাহিত হন।
  2. ব্যবহারকারী আপডেট অ্যাকশন গ্রহণ করলে, ঠিক তখনই Google Health লগ-ইন ফ্লো ট্রিগার করুন।
  3. Google-এ লগ-ইন করা হয়ে গেলে, ব্যবহারকারীর প্রোফাইলে নতুন Google ক্রেডেনশিয়াল সেভ করুন, তার oauth_type ফ্ল্যাগ fitbit থেকে google-এ পরিবর্তন করুন এবং প্রোগ্রাম্যাটিক্যালি তার পুরনো Fitbit টোকেন তুলে নেওয়ার মাধ্যমে অবিলম্বে পুরনো সিঙ্ক করার সুবিধা বন্ধ করুন যাতে ডুপ্লিকেট ডেটা ইনজেশন ও ডুয়াল-লিঙ্কিং প্রতিরোধ করা যায়।

ডেটার ধারাবাহিকতা নিশ্চিত করুন

পুরনো Fitbit Web API থেকে Google Health API-তে ইন্টিগ্রেশন ট্রানজিশন করার সময়, ডেভেলপার অ্যাপ্লিকেশনকে ব্যবহারকারীর শনাক্তকরণ স্ট্রাকচারে পরিবর্তন করতে হবে।

পুরনো Fitbit Web API ৬-অক্ষরের আলফানিউমেরিক স্ট্রিং (যেমন A1B2C3) ব্যবহার করে অ্যাকাউন্ট শনাক্ত করে, যেখানে Google Health API ৬৩টি পর্যন্ত সংখ্যা ও অক্ষর সহ স্ট্রিং হিসেবে ফর্ম্যাট করা healthUserId ব্যবহার করে।

ব্যবহারকারীর প্রসঙ্গ না হারিয়ে এই ব্যবধান পূরণ করতে, ডেভেলপাররা getIdentity এন্ডপয়েন্টে কোয়েরি করে Fitbit ও Health ব্যবহারকারীর আইডি পেতে পারেন। এই এন্ডপয়েন্ট legacyUserId এবং নতুন healthUserId, দুটিই সহ একটি পেলোড ফিরিয়ে দেয়, যা অ্যাপ্লিকেশনকে আগে থেকে থাকা রেকর্ড এবং নতুন অ্যাকাউন্ট সিস্টেমের মধ্যে ডায়নামিকভাবে একটি ম্যাপিং তৈরি করতে দেয়।

আনলিঙ্ক করা Google অ্যাকাউন্ট ম্যানেজ করা

আপনার অ্যাপ Google Health API-এর মাধ্যমে ডেটা সিঙ্ক করার আগে, ব্যবহারকারীকে Google Health-এর সাথে তার Google অ্যাকাউন্ট লিঙ্ক করতে Google Health মোবাইল অ্যাপে সাইন-ইন করতে হবে। OAuth-এর সম্মতি দেওয়ার আগে Google Health লিঙ্ক করুন লিঙ্কটি দেখুন। সম্মতি দেওয়ার সময় Google OAuth 2.0 যেকোনও বৈধ Google অ্যাকাউন্ট যাচাই করে, তাই এটি এমন অ্যাকাউন্ট ব্লক করতে পারে না যেগুলির এখনও কোনও অ্যাক্টিভ Google Health প্রোফাইল নেই।

কোনও ব্যবহারকারী Google Health প্রোফাইল তৈরি করার আগে অথবা তার পুরনো Fitbit অ্যাকাউন্ট Google অ্যাকাউন্টে মাইগ্রেট করার আগে Google OAuth সম্মতি সম্পূর্ণ করলে, users.getIdentity বা ডেটা এন্ডপয়েন্ট কল করলে, স্ট্যাটাস FAILED_PRECONDITION এবং কারণ ACCOUNT_NOT_LINKED সহ HTTP 400 Bad Request সমস্যা রিটার্ন করে:

{
  "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 অনুমোদনের কোড এক্সচেঞ্জ করুন এবং আপনার অ্যাপ UI-তে অ্যাকাউন্টটি লিঙ্ক করা হিসেবে চিহ্নিত করার আগে অবিলম্বে users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) কল করুন।
  2. users.getIdentity বা ব্যাকগ্রাউন্ড ডেটা সিঙ্ক কল HTTP 400-এর সাথে ACCOUNT_NOT_LINKED কারণ দেখালে, অ্যাকাউন্টটি কানেক্ট করা আছে বলে চিহ্নিত করবেন না। ব্যবহারকারী পুরনো 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 (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 ডেটা ইন্টিগ্রেট করার সুবিধা দিয়ে শুরু করুন, তবে ডেটা সিঙ্ক করতে চাইলে তাদের আবার যাচাই করতে হবে, এই বিষয়টি তাদের জানাতে ভুলবেন না:

  • ইন্টিগ্রেশনের মাধ্যমে আপনার অ্যাপে কী কী ফিচার উপলভ্য আছে তা স্পষ্টভাবে ব্যাখ্যা করুন এবং ব্যবহারকারী কীভাবে সেই ফিচারগুলি থেকে উপকৃত হবেন সেই অনুযায়ী আপনার মেসেজ তৈরি করুন।
  • আপনার ফিচারের উপর ফোকাস করুন এবং টেকনিক্যাল ইমপ্লিমেন্টেশনের বিবরণের পরিবর্তে ব্যবহারের উদাহরণ দিন।
  • বলবেন না: "আপনি Fitbit API-এর সাথে কানেক্ট করতে পারবেন না।"
  • বলুন: "হার্ট রেট ডেটা সহ বিস্তারিত ওয়ার্কআউট দেখা চালিয়ে যেতে, Google Health API-তে আবার সম্মতি দিন।"

ব্যবহারকারীদের কখন জানাতে হবে

ব্যবহারকারীর সাথে সব ধরনের যোগাযোগের ক্ষেত্রে, Google Health ব্র্যান্ড নির্দেশিকা মেনে চলুন, এবং বাতিল করা যায় এমন ব্যানার, কার্ড বা সতর্কতা ব্যবহার করুন।

  • ব্যবহারকারী ওয়ার্কআউট করার সময় বা ম্যানুয়ালি কিছু লগ করার সময় আবার সম্মতি জানানোর স্ক্রিন ট্রিগার করবেন না।
  • কয়েক সপ্তাহ ধরে সতর্ক করার পরেই শুধু আবার সম্মতি নেওয়া বাধ্যতামূলক করুন, যা অফিসিয়াল Fitbit Web API বন্ধ করার ডেডলাইনের সাথে মিলে যায়।
  • হার্ড কাট-অফের পরে কোনও ব্যবহারকারী আবার সম্মতি না দিলে, তাকে রিকভার করার সহজ উপায় প্রদান করুন। ব্যানার, কার্ড বা টুলটিপ-এ একটি সহায়তা মেসেজ প্রদান করুন যা তাদের বুঝতে সাহায্য করে যে কেন তাদের ডেটা নেই এবং কীভাবে এটি ঠিক করা যায়।

OAuth টোকেন গ্র্যান্ট রেট লিমিটের জন্য প্ল্যান করুন

আগে থেকে থাকা Fitbit ব্যবহারকারীরা Google Health API-তে আবার সম্মতি দিলে, প্রতিটি ব্যবহারকারীর অনুমোদন আপনার Google Cloud প্রোজেক্টের OAuth টোকেন গ্রান্ট রেট সীমার মধ্যে গণনা করা হয়। এই সীমা নিয়ন্ত্রণ করে যে প্রতি মিনিটে এবং প্রতি ২৪ ঘণ্টার স্লাইডিং উইন্ডোতে কতজন ব্যবহারকারী আপনার অ্যাপকে অনুমতি দিতে পারবেন।

মাইগ্রেশনের সময় ২৪ ঘণ্টার স্লাইডিং উইন্ডোতে ১০,০০০ ব্যবহারকারীর সাইন-আপ বা আবার যাচাইকরণের সীমা অতিক্রম করার সম্ভাবনা থাকলে, OAuth রেট লিমিট এড়াতে এইসব ধাপ অনুসরণ করুন:

  1. আপনার Google Cloud প্রোজেক্টে টোকেন গ্রান্টের ব্যবহার মনিটর করুন।
  2. আপনার দৈনিক অনুদানের সীমার মধ্যে থাকতে, ইন-অ্যাপ মাইগ্রেশন বিজ্ঞপ্তির গতি নির্ধারণ করুন।
  3. ব্যবহারকারীদের বড় গ্রুপকে আবার যাচাই করার জন্য প্রম্পট করার আগে আরও বেশি OAuth টোকেন গ্র্যান্ট কোটার অনুরোধ করুন। আপনার ব্যবহার চেক করা এবং সীমা বাড়ানোর অনুরোধ করার ব্যাপারে নির্দেশাবলীর জন্য, OAuth অ্যাপ্লিকেশনের রেট লিমিট দেখুন।