Tổng quan

Google Health API là một giải pháp toàn diện được xây dựng từ đầu, cung cấp cho nhà phát triển quyền truy cập mạnh mẽ vào nhiều loại dữ liệu sức khoẻ và dữ liệu đa dạng của người dùng đã đồng ý. API Google Health sử dụng một bảng điều khiển mới để đăng ký ứng dụng, Google OAuth 2.0, các loại dữ liệu mới, giản đồ điểm cuối mới và định dạng phản hồi mới.

Hướng dẫn này nhằm giúp nhà phát triển di chuyển các ứng dụng hiện có dùng Fitbit Web API sang Google Health API mới. Tài liệu này đưa ra các đề xuất để đảm bảo quá trình di chuyển diễn ra suôn sẻ mà vẫn giữ chân được người dùng.

Tại sao bạn nên di chuyển?

Đây không chỉ là một bản cập nhật mà còn là một bước đi chiến lược để đảm bảo ứng dụng của bạn an toàn và sẵn sàng cho những tiến bộ trong tương lai của công nghệ y tế. Sau đây là một số lợi ích khi sử dụng Google Health API:

  • Truy cập vào dữ liệu toàn diện: Có quyền truy cập mạnh mẽ vào nhiều loại dữ liệu sức khoẻ của người dùng đã đồng ý và nhiều loại dữ liệu khác.
  • Bảo mật nâng cao: Tuân thủ các phương pháp bảo mật hay nhất của Google, phù hợp với các tiêu chuẩn của Google về bảo mật, quyền riêng tư và danh tính.
  • Tính nhất quán: Loại bỏ sự không nhất quán trước đây về định dạng dữ liệu, múi giờ, đơn vị đo lường và cách xử lý lỗi để mang lại trải nghiệm trực quan hơn cho nhà phát triển.
  • Khả năng mở rộng và thích ứng trong tương lai: Được thiết kế để mở rộng nhằm đáp ứng nhu cầu trong tương lai và hỗ trợ các giao thức hiện đại như gRPC.

Quá trình chuyển đổi từ Fitbit Web API sang Google Health API không chỉ bao gồm các thay đổi về mặt kỹ thuật. Do chuyển sang thư viện OAuth mới, bạn không thể chuyển mã truy cập và mã làm mới hiện có, nên người dùng phải đồng ý lại với bản tích hợp mới của bạn.

Hỗ trợ cả hai phương thức đăng nhập

Vì Fitbit Web API và Google Health API sử dụng các hệ thống khác nhau để xử lý thông tin đăng nhập của người dùng, nên khi Fitbit Web API vẫn hoạt động, ứng dụng của bạn sẽ tạm thời cần hỗ trợ cả hai phương pháp xác thực cho cơ sở người dùng.

Thay vì để ứng dụng yêu cầu dữ liệu trực tiếp, hãy triển khai một lớp quyết định xem có nên giao tiếp với Fitbit Web API hay Google Health API cho một người dùng cụ thể hay không, để phần còn lại của ứng dụng không cần phải lo lắng về các chi tiết.

Cập nhật cơ sở dữ liệu người dùng để thêm một cờ (ví dụ: oauth_type) nhằm xác định hệ thống đăng nhập mà họ đang sử dụng.

  • Đối với người dùng mới: Tự động thiết lập cho họ bằng Google Health API mới (oauth_type: google).
  • Đối với người dùng hiện tại: Tiếp tục cho họ dùng Fitbit Web API cho đến khi họ cập nhật sự đồng ý (oauth_type: fitbit).
Tình huống của người dùng oauth_type Tiểu bang Luồng API đang hoạt động Việc cần làm
Giới thiệu cho người dùng mới google Chỉ Google Health API Chạy Google OAuth trong trình duyệt hệ thống và liên kết mã nhận dạng với users.getIdentity.
Người dùng Fitbit hiện tại (chưa di chuyển) fitbit Chỉ Fitbit Web API Tiếp tục đồng bộ hoá với Fitbit Web API; hiển thị lời nhắc có thể đóng trong ứng dụng để nâng cấp.
Người dùng Fitbit hiện tại hoàn tất quá trình di chuyển fitbit → google Chuyển sang Google Health API Xác minh các phạm vi được cấp, gọi users.getIdentity (legacyUserId → healthUserId), chuyển oauth_type sang google và thu hồi ngay mã thông báo Fitbit cũ.

Để tránh làm gián đoạn trải nghiệm người dùng, bạn không nên buộc mọi người phải đăng xuất rồi đăng nhập lại. Thay vào đó:

  1. Khi người dùng vẫn kết nối với Fitbit Web API tương tác với ứng dụng của bạn, hãy cho họ thấy một thông báo thân thiện khuyến khích họ cập nhật kết nối.
  2. Khi người dùng chấp nhận hành động cập nhật, hãy kích hoạt quy trình đăng nhập Google Health ngay lúc đó.
  3. Sau khi đăng nhập thành công bằng Google, hãy lưu thông tin đăng nhập mới của Google vào hồ sơ của người dùng, chuyển cờ oauth_type của họ từ fitbit sang google và ngay lập tức tắt tính năng đồng bộ hoá cũ bằng cách thu hồi mã thông báo Fitbit cũ của họ theo phương thức lập trình để ngăn chặn việc nhập dữ liệu trùng lặp và liên kết kép.

Đảm bảo tính liên tục của dữ liệu

Khi chuyển đổi một hoạt động tích hợp từ API Fitbit Web cũ sang API Google Health, các ứng dụng của nhà phát triển phải tính đến sự thay đổi trong cấu trúc nhận dạng người dùng.

API Fitbit Web cũ xác định tài khoản bằng một chuỗi chữ và số gồm 6 ký tự (chẳng hạn như A1B2C3), trong khi API Google Health sử dụng healthUserId được định dạng dưới dạng chuỗi gồm tối đa 63 chữ số và ký tự.

Để thu hẹp khoảng cách này mà không làm mất bối cảnh của người dùng, nhà phát triển có thể truy vấn điểm cuối getIdentity để lấy mã nhận dạng người dùng Fitbit và Health. Điểm cuối này trả về một tải trọng chứa cả legacyUserId và healthUserId mới, cho phép các ứng dụng tạo mối liên kết một cách linh động giữa các bản ghi hiện có và hệ thống tài khoản mới.

Xử lý các Tài khoản Google chưa liên kết

Người dùng phải đăng nhập vào ứng dụng di động Google Health để liên kết Google Health với Tài khoản Google của họ thì ứng dụng của bạn mới có thể đồng bộ hoá dữ liệu thông qua API Google Health. Xem phần Liên kết Google Health trước khi có sự đồng ý của OAuth. Vì Google OAuth 2.0 xác thực mọi Tài khoản Google hợp lệ trong quá trình đồng ý, nên Google OAuth 2.0 không thể chặn những tài khoản chưa có hồ sơ Google Health đang hoạt động.

Nếu người dùng hoàn tất quy trình đồng ý OAuth của Google trước khi tạo hồ sơ Google Health hoặc trước khi di chuyển tài khoản Fitbit cũ sang Tài khoản Google, thì việc gọi users.getIdentity hoặc điểm cuối dữ liệu sẽ trả về lỗi HTTP 400 Bad Request có trạng thái FAILED_PRECONDITION và lý do 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"
        }
      }
    ]
  }
}

Cách xác minh quyền truy cập vào tài khoản và xử lý lỗi này:

  1. Đổi mã uỷ quyền OAuth lấy mã thông báo và gọi ngay users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) trước khi đánh dấu tài khoản là đã liên kết trong giao diện người dùng của ứng dụng.
  2. Nếu users.getIdentity hoặc lệnh gọi đồng bộ hoá dữ liệu trong nền trả về HTTP 400 kèm theo lý do ACCOUNT_NOT_LINKED, đừng đánh dấu tài khoản là đã kết nối. Nếu người dùng đang di chuyển từ Fitbit Web API cũ, hãy duy trì kết nối Fitbit hiện có của họ và không thu hồi mã thông báo Fitbit cũ.
  3. Hiển thị lời nhắc có thể thực hiện được, giải quyết cả người dùng mới chưa từng tạo tài khoản Google Health hoặc Fitbit và người dùng Fitbit hiện tại chưa di chuyển sang Tài khoản Google:

    "Tài khoản Google của bạn chưa được liên kết với Google Health. Mở ứng dụng di động Google Health rồi đăng nhập bằng Tài khoản Google của bạn để tạo hồ sơ hoặc chuyển tài khoản Fitbit hiện có sang Tài khoản Google, sau đó quay lại đây để kết nối."

  4. Cung cấp nút kêu gọi hành động để mở redirect_uri từ siêu dữ liệu lỗi (https://fitbit.google.com/auth/signup) hoặc chuyển hướng người dùng Fitbit cũ đến bài viết trợ giúp về việc di chuyển tài khoản Fitbit.

Bổ sung dữ liệu trước đây

Nếu người dùng không xác thực với các điểm cuối mới của API Google Health trước khi các điểm cuối cũ ngừng hoạt động, thì dữ liệu của họ vẫn sẽ được cung cấp miễn là họ tiếp tục đồng bộ hoá thiết bị với ứng dụng Google Health. Tuy nhiên, bạn có thể bị thiếu dữ liệu của người dùng này.

Để bổ sung dữ liệu, sau khi người dùng xác thực lại với các điểm cuối mới, bạn có thể sử dụng Google Health API để bổ sung dữ liệu trước đây của họ. Hãy xem bài viết Truy vấn dữ liệu trong quá khứ để biết hướng dẫn.

Ví dụ về cách triển khai việc di chuyển và liên kết

Cách triển khai tham chiếu sau đây minh hoạ cách xử lý lệnh gọi lại OAuth, xác thực sự đồng ý một phần hoặc không đồng ý, phân giải danh tính người dùng bằng users.getIdentity (bao gồm cả việc xử lý HTTP 400 ACCOUNT_NOT_LINKED), ngăn chặn liên kết kép bằng cách thu hồi mã thông báo Fitbit cũ và định tuyến các yêu cầu dữ liệu bằng 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"],
  }

Giao tiếp và thời gian

Để giúp người dùng chuyển từ OAuth hiện tại của Fitbit sang OAuth mới của Google, hãy làm theo các phương pháp hay nhất sau đây.

Giao tiếp tập trung vào giá trị

Đừng bắt đầu bằng câu "Chúng tôi đã cập nhật API", hãy bắt đầu bằng những lợi ích của việc tích hợp dữ liệu trên Google Health vào ứng dụng của bạn, nhưng hãy đảm bảo rằng họ biết họ cần xác thực lại nếu muốn đồng bộ hoá dữ liệu:

  • Giải thích rõ ràng những tính năng có trong ứng dụng của bạn được hỗ trợ bởi tích hợp và điều chỉnh thông điệp của bạn cho phù hợp với cách người dùng hưởng lợi từ những tính năng đó các tính năng.
  • Tập trung vào các tính năng và cung cấp các trường hợp sử dụng thay vì thông tin chi tiết về cách triển khai kỹ thuật.
  • Đừng nói: "Bạn sẽ không thể kết nối với API Fitbit".
  • Nên nói: "Để tiếp tục xem thông tin chi tiết về bài tập cùng với dữ liệu về tần số tim, hãy đồng ý lại với API Google Health".

Thời điểm thông báo cho người dùng

Trong tất cả thông tin liên lạc với người dùng, hãy tuân thủ nguyên tắc trình bày thương hiệu của Google Health, và sử dụng biểu ngữ, thẻ hoặc cảnh báo có thể đóng.

  • Đừng kích hoạt màn hình xin phép lại khi người dùng đang tập luyện hoặc ghi nhật ký theo cách thủ công.
  • Chỉ bắt buộc người dùng đồng ý lại sau vài tuần cảnh báo, trùng với thời hạn ngừng sử dụng chính thức của Fitbit Web API.
  • Nếu người dùng chưa đồng ý lại sau thời hạn cuối cùng, hãy cung cấp một lộ trình khôi phục dễ dàng. Cung cấp thông báo trợ giúp trong một biểu ngữ, thẻ hoặc chú thích để giúp họ hiểu lý do dữ liệu bị thiếu và cách khắc phục.

Lập kế hoạch cho hạn mức cấp mã thông báo OAuth

Khi người dùng Fitbit hiện tại đồng ý lại với API Google Health, mỗi lần uỷ quyền của người dùng sẽ được tính vào giới hạn tốc độ cấp mã thông báo OAuth của dự án trên đám mây của Google. Hạn mức này kiểm soát số lượng người dùng có thể uỷ quyền cho ứng dụng của bạn mỗi phút và mỗi khoảng thời gian 24 giờ.

Nếu bạn dự kiến sẽ vượt quá 10.000 lượt đăng ký hoặc xác thực lại của người dùng trong khoảng thời gian 24 giờ trong quá trình di chuyển, hãy làm theo các bước sau để tránh đạt đến giới hạn số lượng yêu cầu OAuth:

  1. Theo dõi mức sử dụng mã thông báo được cấp trong dự án trên đám mây của bạn trên Google Cloud.
  2. Điều chỉnh tần suất gửi thông báo di chuyển trong ứng dụng để không vượt quá hạn mức hằng ngày.
  3. Yêu cầu tăng hạn mức cấp mã thông báo OAuth trước khi nhắc các nhóm người dùng lớn xác thực lại. Để biết hướng dẫn về cách kiểm tra mức sử dụng và yêu cầu tăng hạn mức, hãy xem bài viết Giới hạn về tốc độ của ứng dụng OAuth.