Обзор

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 все ещё активен, вашему приложению временно потребуется поддерживать оба способа аутентификации для всей пользовательской базы.

Вместо того чтобы запрашивать данные напрямую, реализуйте уровень, который решает, к какому API обращаться для конкретного пользователя – Fitbit Web API или Google Health API. Тогда остальной части приложения не придется беспокоиться о деталях.

Добавьте в базу данных пользователей флаг (например, oauth_type), чтобы идентифицировать систему входа, которую они используют.

  • Для новых пользователей. Автоматически настройте для них новый Google Health API (oauth_type: google).
  • Для существующих пользователей. Продолжайте использовать Fitbit Web API, пока они не обновят свое согласие (oauth_type: fitbit).
Сценарий пользователя oauth_type штат Активный поток API Необходимые действия
Регистрация новых пользователей 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 Здоровье.
  3. После успешного входа в Google сохраните новые учетные данные Google в профиле пользователя, измените значение флага oauth_type с fitbit на google и немедленно отключите устаревшую синхронизацию, программно отозвав устаревшие токены Fitbit, чтобы предотвратить дублирование данных и двойное связывание.

Обеспечьте непрерывность данных

При переходе с устаревшего Fitbit Web API на Google Health API приложениям разработчиков необходимо учитывать изменение структуры идентификации пользователей.

Устаревший Fitbit Web API идентифицирует аккаунты с помощью шестизначной буквенно-цифровой строки (например, A1B2C3), а Google Health API использует healthUserId в виде строки, содержащей до 63 цифр и символов.

Чтобы устранить этот пробел, не теряя пользовательский контекст, разработчики могут запросить конечную точку getIdentity, чтобы получить идентификаторы пользователей Fitbit и Health. Эта конечная точка возвращает полезную нагрузку, содержащую как legacyUserId, так и новый healthUserId, что позволяет приложениям динамически создавать сопоставление между существующими записями и новой системой аккаунтов.

Как работать с аккаунтами Google, связь с которыми отменена

Чтобы связать Google Health с аккаунтом Google, пользователю нужно войти в мобильное приложение Google Health. После этого ваше приложение сможет синхронизировать данные через Google Health API. Подробнее о том, как связать Google Health до запроса доступа OAuth… Поскольку Google OAuth 2.0 выполняет аутентификацию любого действительного аккаунта Google во время получения согласия, он не может блокировать аккаунты, у которых ещё нет активного профиля Google Health.

Если пользователь предоставит согласие OAuth, прежде чем создаст профиль Google Health или перенесет устаревший аккаунт Fitbit в аккаунт Google, вызов users.getIdentity или конечной точки данных вернет ошибку 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 или вызов фоновой синхронизации данных возвращает 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. Добавьте кнопку с призывом к действию, которая открывает redirect_uri из метаданных ошибки (https://fitbit.google.com/auth/signup), или направляйте пользователей устаревших аккаунтов 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, каждая авторизация пользователя учитывается в ограничении на количество токенов OAuth для вашего облачного проекта Google Cloud. Это ограничение определяет, сколько пользователей могут авторизовать ваше приложение за минуту и за скользящее 24-часовое окно.

Если вы ожидаете, что в течение 24-часового скользящего окна во время переноса будет выполнено более 10 000 регистраций или повторных аутентификаций пользователей, выполните следующие действия, чтобы избежать превышения ограничений на частоту запросов OAuth:

  1. Отслеживайте использование токенов в проекте Google Cloud.
  2. Чтобы не превысить дневной лимит, отправляйте уведомления о переносе в приложении постепенно.
  3. Прежде чем запрашивать повторную аутентификацию у больших групп пользователей, запросите более высокую квоту на предоставление токенов OAuth. Инструкции о том, как проверить использование и запросить увеличение лимита, приведены в статье Ограничения частоты запросов для приложений OAuth.