Aperçu

L'API Google Health est une solution complète conçue de A à Z, qui offre aux développeurs un accès fiable à un large éventail de données de santé des utilisateurs et à divers types de données, avec leur consentement. L'API Google Health utilise une nouvelle console pour enregistrer vos applications, Google OAuth 2.0, de nouveaux types de données, un nouveau schéma de point de terminaison et un nouveau format de réponse.

Ce guide est conçu pour aider les développeurs à migrer leurs applications API Web Fitbit existantes vers la nouvelle API Google Health. Il propose des recommandations pour assurer une migration fluide tout en fidélisant les utilisateurs.

Pourquoi migrer ?

Il ne s'agit pas d'une simple mise à jour, mais d'une décision stratégique visant à garantir que vos applications sont sécurisées et prêtes pour les futures avancées de la technologie de santé. Voici quelques-uns des avantages de l'API Google Health :

  • Accès à des données complètes : bénéficiez d'un accès fiable à un large éventail de données de santé des utilisateurs et à divers types de données.
  • Sécurité renforcée : conformité avec les bonnes pratiques de sécurité de Google, conformément aux normes de sécurité, de confidentialité et d'identité de Google.
  • Cohérence : élimine les incohérences héritées des formats de données, des fuseaux horaires, des unités de mesure et de la gestion des exceptions pour une expérience de développement plus intuitive.
  • Évolutivité et pérennité : conçu pour évoluer afin de répondre aux besoins futurs et compatible avec les protocoles modernes tels que gRPC.

La transition de l'API Web Fitbit vers l'API Google Health implique plus que des modifications techniques. En raison du passage à une nouvelle bibliothèque OAuth, les jetons d'accès et d'actualisation existants ne peuvent pas être transférés. Les utilisateurs doivent donc donner à nouveau leur consentement pour votre intégration mise à jour.

Prendre en charge les deux méthodes de connexion

Étant donné que l'API Web Fitbit et l'API Google Health utilisent des systèmes différents pour gérer les connexions des utilisateurs, tant que les API Web Fitbit sont actives, votre application devra temporairement prendre en charge les deux méthodes d'authentification pour l'ensemble de votre base d'utilisateurs.

Au lieu que votre application demande directement des données, implémentez une couche qui décide de communiquer avec l'API Web Fitbit ou l'API Google Health pour un utilisateur spécifique, afin que le reste de votre application n'ait pas à se soucier des détails.

Mettez à jour votre base de données utilisateur pour inclure un indicateur (par exemple, oauth_type) permettant d'identifier le système de connexion utilisé.

  • Pour les nouveaux utilisateurs : configurez-les automatiquement avec la nouvelle API Google Health (oauth_type: google).
  • Pour les utilisateurs existants : conservez-les sur l'API Web Fitbit jusqu'à ce qu'ils mettent à jour leur consentement (oauth_type: fitbit).
Scénario utilisateur oauth_type État Flux d'API actif Action requise
Intégration de nouveaux utilisateurs google API Google Health uniquement Lancez Google OAuth dans un navigateur système et mappez les ID avec users.getIdentity.
Utilisateur Fitbit existant (pas encore migré) fitbit API Web Fitbit uniquement Continuer la synchronisation avec l'API Web Fitbit ; afficher une invite dans l'application pour passer à la version supérieure (pouvant être ignorée).
Utilisateur Fitbit existant effectuant la migration fitbit → google Migrer vers l'API Google Health Vérifiez les champs d'application accordés, appelez users.getIdentity (legacyUserId → healthUserId), remplacez oauth_type par google et révoquez immédiatement les anciens jetons Fitbit.

Pour éviter de perturber l'expérience utilisateur, nous vous recommandons de ne pas forcer tous les utilisateurs à se déconnecter et à se reconnecter. Au lieu de cela :

  1. Lorsqu'un utilisateur qui reste connecté aux API Web Fitbit interagit avec votre application, affichez une notification conviviale l'invitant à mettre à jour sa connexion.
  2. Lorsque l'utilisateur accepte l'action de mise à jour, déclenchez immédiatement le flux de connexion Google Santé.
  3. Une fois la connexion Google établie, enregistrez les nouveaux identifiants Google dans le profil de l'utilisateur, remplacez l'indicateur oauth_type par google, et désactivez immédiatement l'ancienne synchronisation en révoquant de manière programmatique les anciens jetons Fitbit pour éviter l'ingestion de données en double et la double association.fitbit

Assurer la continuité des données

Lors de la transition d'une intégration de l'ancienne API Web Fitbit vers l'API Google Health, les applications des développeurs doivent tenir compte d'un changement dans les structures d'identification des utilisateurs.

L'ancienne API Web Fitbit identifie les comptes à l'aide d'une chaîne alphanumérique de six caractères (par exemple, A1B2C3), tandis que l'API Google Health utilise un healthUserId formaté sous la forme d'une chaîne de 63 chiffres et caractères maximum.

Pour combler cet écart sans perdre le contexte utilisateur, les développeurs peuvent interroger le point de terminaison getIdentity pour obtenir les ID utilisateur Fitbit et Santé. Ce point de terminaison renvoie une charge utile contenant à la fois l'legacyUserId et le nouvel healthUserId, ce qui permet aux applications de créer dynamiquement un mappage entre les enregistrements existants et le nouveau système de compte.

Gérer les comptes Google non associés

Un utilisateur doit se connecter à l'application mobile Google Health pour associer Google Health à son compte Google avant que votre application puisse synchroniser les données via l'API Google Health. Consultez Associer Google Santé avant l'autorisation OAuth. Étant donné que Google OAuth 2.0 authentifie tout compte Google valide lors du consentement, il ne peut pas bloquer les comptes qui n'ont pas encore de profil Google Health actif.

Si un utilisateur donne son consentement OAuth Google avant de créer un profil Google Health ou avant de migrer son ancien compte Fitbit vers son compte Google, l'appel de users.getIdentity ou d'un point de terminaison de données renvoie une erreur HTTP 400 Bad Request avec l'état FAILED_PRECONDITION et le motif 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"
        }
      }
    ]
  }
}

Pour vérifier l'accès au compte et gérer cette erreur :

  1. Échangez le code d'autorisation OAuth contre des jetons et appelez immédiatement users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) avant de marquer le compte comme associé dans l'UI de votre application.
  2. Si users.getIdentity ou un appel de synchronisation des données en arrière-plan renvoie l'erreur HTTP 400 avec le motif ACCOUNT_NOT_LINKED, ne marquez pas le compte comme connecté. Si l'utilisateur migre depuis l'ancienne API Web Fitbit, laissez sa connexion Fitbit existante active et ne révoquez pas ses anciens jetons Fitbit.
  3. Affichez une invite exploitable qui s'adresse à la fois aux nouveaux utilisateurs qui n'ont jamais créé de compte Google Health ou Fitbit et aux utilisateurs Fitbit existants qui n'ont pas encore migré vers un compte Google :

    "Votre compte Google n'est pas encore associé à Google Health. Ouvrez l'application mobile Google Health et connectez-vous avec votre compte Google pour créer un profil, ou migrez votre compte Fitbit existant vers votre compte Google, puis revenez ici pour vous connecter."

  4. Fournissez un bouton d'incitation à l'action qui ouvre le redirect_uri à partir des métadonnées d'erreur (https://fitbit.google.com/auth/signup) ou redirigez les utilisateurs d'anciens comptes Fitbit vers l'article d'aide sur la migration des comptes Fitbit.

Remplir les données historiques

Si un utilisateur ne s'authentifie pas auprès des nouveaux points de terminaison de l'API Google Health avant l'arrêt des anciens points de terminaison, ses données resteront disponibles tant qu'il continuera à synchroniser son appareil avec l'application Google Health. Toutefois, il est possible que vous constatiez un manque de données pour cet utilisateur.

Pour remplir les données de l'utilisateur, une fois qu'il s'est authentifié à nouveau auprès des nouveaux points de terminaison, vous pouvez utiliser notre API Google Health pour remplir ses données historiques. Pour en savoir plus, consultez Interroger les données historiques.

Exemple d'implémentation de la migration et de l'association

L'implémentation de référence suivante montre comment gérer le rappel OAuth, valider un consentement partiel ou nul, résoudre l'identité de l'utilisateur avec users.getIdentity (y compris la gestion de HTTP 400 ACCOUNT_NOT_LINKED), empêcher l'association double en révoquant les anciens jetons Fitbit et acheminer les requêtes de données à l'aide de 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"],
  }

Communication et timing

Pour aider vos utilisateurs à passer de leur OAuth Fitbit existant au nouvel OAuth Google, suivez ces bonnes pratiques.

Communication axée sur la valeur

Ne commencez pas par "Nous avons mis à jour notre API", mais par les avantages de l'intégration des données Google Health dans votre application. Assurez-vous toutefois que les utilisateurs savent qu'ils doivent se réauthentifier s'ils veulent que leurs données soient synchronisées :

  • Expliquez clairement quelles fonctionnalités de votre application sont optimisées par l'intégration et adaptez votre message à la façon dont un utilisateur peut en bénéficier.
  • Concentrez-vous sur vos fonctionnalités et fournissez des cas d'utilisation plutôt que des détails d'implémentation technique.
  • À ne pas dire : "Vous ne pourrez pas vous connecter à l'API Fitbit."
  • À dire : "Pour continuer à voir des entraînements détaillés avec des données de fréquence cardiaque, acceptez de nouveau les API Google Health."

Quand informer les utilisateurs

Dans toutes les communications avec les utilisateurs, respectez les consignes relatives à la marque Google Health et utilisez des bannières, des fiches ou des alertes pouvant être ignorées.

  • Ne déclenchez pas l'écran de renouvellement du consentement pendant qu'un utilisateur s'entraîne ou enregistre manuellement une activité.
  • Ne rendez le renouvellement du consentement obligatoire qu'après plusieurs semaines d'avertissements, en même temps que les dates limites officielles d'abandon de l'API Web Fitbit.
  • Si un utilisateur n'a pas donné son consentement après la date limite, proposez-lui un parcours de récupération fluide. Fournissez un message d'aide dans une bannière, une fiche ou une info-bulle pour aider les utilisateurs à comprendre pourquoi leurs données sont manquantes et comment résoudre le problème.

Planifier les limites de débit d'octroi de jetons OAuth

Lorsque les utilisateurs Fitbit existants donnent à nouveau leur consentement pour l'API Google Health, chaque autorisation d'utilisateur est comptabilisée dans la limite de débit d'attribution de jetons OAuth de votre projet Google Cloud. Cette limite contrôle le nombre d'utilisateurs pouvant autoriser votre application par minute et par période glissante de 24 heures.

Si vous prévoyez de dépasser 10 000 inscriptions ou réauthentifications d'utilisateurs sur une période glissante de 24 heures pendant votre migration, suivez ces étapes pour éviter d'atteindre les limites de débit OAuth :

  1. Surveillez l'utilisation des attributions de jetons dans votre projet Google Cloud.
  2. Échelonnez vos notifications de migration dans l'application pour ne pas dépasser votre limite d'octroi quotidienne.
  3. Demandez un quota d'attribution de jetons OAuth plus élevé avant d'inviter de grands groupes d'utilisateurs à se réauthentifier. Pour savoir comment vérifier votre utilisation et demander une augmentation, consultez Limites de débit des applications OAuth.