Guide de migration

L'API Google Health est une nouvelle API entièrement conçue pour permettre aux développeurs d'interroger les données utilisateur Fitbit. Il ne s'agit pas d'une simple mise à jour, mais d'une décision stratégique visant à garantir la sécurité et la fiabilité de vos applications, et à les préparer aux futures avancées de la technologie de santé. L'API est compatible avec une nouvelle console permettant d'enregistrer vos applications, avec Google OAuth 2.0, avec de nouveaux types de données, avec un nouveau schéma de point de terminaison et avec un nouveau format de réponse.

Ce guide est conçu pour aider les développeurs à migrer leurs applications Fitbit Web API existantes vers la nouvelle API Google Health.

Pourquoi migrer ?

Voici les avantages de l'utilisation de l'API Google Health :

  • Sécurité renforcée : respect des bonnes pratiques de Google en matière de sécurité, conformément aux normes de Google en matière de sécurité, de confidentialité et d'identité.
  • Cohérence : élimine les incohérences héritées dans les formats de données, les fuseaux horaires, les unités de mesure et la gestion des erreurs 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.

Enregistrement de l'application

Toutes les applications Google Health API doivent être enregistrées à l'aide de la console Google Cloud, qui sert de plate-forme centrale pour gérer toutes vos applications Google.

Pour savoir comment enregistrer votre application, suivez les étapes décrites dans Premiers pas. Voici les différences que vous remarquerez lors de l'enregistrement de vos applications.

API Web Fitbit API Google Health
Lien(s) public(s) https://dev.fitbit.com/apps https://console.cloud.google.com
Ajouter une application Appuyez sur Enregistrer une nouvelle application.
  1. Créer un projet Google Cloud
  2. Activez l'API Google Health.
Informations générales Champs à remplir :
  • Nom de l'application
  • Description
  • URL du site Web de l'application
  • Organisation
  • URL du site Web de l'organisation
  • URL des conditions d'utilisation
  • URL des règles de confidentialité
 Champs à remplir :
  • Nom de l'application
  • Adresse e-mail d'assistance
  • Audience (interne ou externe)
  • Adresse e-mail de contact
  • Icône de logo
  • URL du site Web de l'application
  • URL des règles de confidentialité
  • URL des conditions d'utilisation
  • Domaine autorisé
Types d'applications Le développeur doit sélectionner :
  • Serveur
  • Client
  • Personal
  • Application Web
  • Android
  • Extension Chrome
  • iOS
  • Téléviseurs
  • Application de bureau
  • Plate-forme Windows universelle
ID client Enregistré lorsque les paramètres de l'application sont enregistrés Enregistré séparément
Type d'accès L'accès en lecture et en écriture est contrôlé au niveau de l'application. L'accès en lecture et en écriture est contrôlé au niveau du champ d'application.
URL supplémentaires
  • URL de redirection : site vers lequel les utilisateurs sont redirigés après avoir autorisé les niveaux d'accès.
  • Origines JavaScript autorisées : origine HTTP qui héberge l'application Web
  • URL de redirection : site vers lequel les utilisateurs sont redirigés après avoir autorisé les niveaux d'accès.

Implémentation d'OAuth

Les applications de l'API Google Health ne sont compatibles qu'avec les bibliothèques clientes Google OAuth2. Des bibliothèques clientes sont disponibles pour les frameworks courants, ce qui simplifie l'implémentation d'OAuth 2.0. Voici les différences entre les bibliothèques Google OAuth2 et les bibliothèques OAuth2 Open Source :

API Web Fitbit API Google Health
Compatibilité avec la bibliothèque OAuth2 Open Source Bibliothèques clientes Google OAuth2
Fonctionnalité Incohérence entre les plates-formes Cohérence entre les plates-formes
URL d'autorisation https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
URL du jeton https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Durée de vie du jeton d'accès 8 heures 1 heure
Taille du jeton d'accès 1 024 octets 2 048 octets
Jeton d'actualisation Les jetons d'actualisation sont générés lorsque vous utilisez le flux d'attribution du code d'autorisation. Un seul jeton d'actualisation peut être généré pour un utilisateur. Les jetons n'expirent jamais et ne peuvent être utilisés qu'une seule fois. Pour générer un jeton d'actualisation, la chaîne d'autorisation doit contenir le paramètre de requête "access_type=offline". Il est possible de créer plusieurs jetons d'actualisation pour un même utilisateur. Les jetons d'actualisation peuvent être basés sur le temps. Ils expirent s'ils n'ont pas été utilisés depuis six mois, si l'utilisateur a accordé un accès limité dans le temps ou si l'application est en mode "Test". Pour en savoir plus, consultez Expiration du jeton d'actualisation.
Réponse du jeton La réponse JSON contient les éléments suivants :
  • jeton d'accès
  • expiration du jeton d'accès
  • scopes
  • type de jeton
  • jeton d'actualisation
  • ID utilisateur
 La réponse JSON contient les éléments suivants :
  • jeton d'accès
  • expiration du jeton d'accès
  • scopes
  • type de jeton
  • jeton d'actualisation

Pour obtenir l'ID utilisateur, utilisez le point de terminaison users.getIdentity.

Les utilisateurs Fitbit doivent redonner leur consentement à votre nouvelle intégration, car votre application utilise une bibliothèque OAuth différente. Il n'est pas possible de transférer des jetons d'accès et d'actualisation vers l'API Google Health et de les faire fonctionner.

Niveaux d'accès

Vous devez mettre à jour votre demande d'autorisation pour utiliser les niveaux d'accès de l'API Google Health. Les niveaux d'accès définissent si votre application accepte les opérations de lecture ou d'écriture. N'utilisez pas de portées dont votre application n'a pas besoin. Vous pourrez toujours en ajouter d'autres ultérieurement si la conception de votre application change.

Les champs d'application de l'API Google Health sont des URL HTTP commençant par https://www.googleapis.com/auth/googlehealth.{scope}. Par exemple, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Mappages de portée

Voici comment les champs d'application de l'API Fitbit Web correspondent à ceux de l'API Google Health :

Tableau : Mappages des portées de l'API Web Fitbit vers l'API Google Santé
Niveaux d'accès de l'API Fitbit Web Champs d'application des API Google Health
activité .activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness .activity_and_fitness
.activity_and_fitness.readonly
fréquence cardiaque .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
position .location.readonly
nutrition .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
profil .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
paramètres .settings
.settings.readonly
sommeil .sleep
.sleep.readonly
température .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
weight .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

Types de données

Vous trouverez ci-dessous la liste des types de données de l'API Google Santé et leur correspondance avec l'API Fitbit Web.

Tableau : Mappages des types de données de l'API Web Fitbit vers l'API Google Santé
Type de données de l'API Web Fitbit Type de données de l'API Google Health
  ID du point de terminaison
Minutes en zone active Minutes en zone active
  active-zone-minutes
Contient les modifications apportées aux niveaux d'activité de l'utilisateur Niveau d'activité
  activity-level
Élévation Altitude
  altitude
Masse grasse Masse grasse
  body-fat
caloriesOut dans chaque zone de fréquence cardiaque Calories brûlées dans la zone de fréquence cardiaque
  calories-in-heart-rate-zone
Récapitulatif de la VFC Variabilité quotidienne de la fréquence cardiaque
  daily-heart-rate-variability
Récapitulatif de la SpO2 Saturation en oxygène quotidienne
  daily-oxygen-saturation
Fréquence cardiaque au repos Fréquence cardiaque au repos quotidienne
  daily-resting-heart-rate
Température cutanée Dérivations quotidiennes de la température du sommeil
  daily-sleep-temperature-derivations
Distance Distance
  distance
Activité enregistrée Exercise
  exercise
Étages Étages
  floors
Fréquence cardiaque Fréquence cardiaque
  heart-rate
VRC intrajournalière Variabilité de la fréquence cardiaque
  heart-rate-variability
SpO2 intrajournalier Saturation en oxygène
  oxygen-saturation
Valeur de la VO2 max lorsque l'utilisateur court VO2 max de la course
  run-vo2-max
Minutes sédentaires de la série temporelle d'activité Période sédentaire
  sedentary-period
Sommeil Sommeil
  sleep
Étapes Étapes
  steps
Activité caloriesOut Total des calories
  total-calories
Valeur de la VO2 max VO2 max
  vo2-max
Poids Poids
  weight

Points de terminaison

Les points de terminaison REST adoptent une syntaxe cohérente pour tous les types de données.

  • Point de terminaison de service : l'URL HTTP de base devient https://health.googleapis.com.
  • Syntaxe des points de terminaison : l'API Google Health est compatible avec un nombre limité de points de terminaison, qui peuvent être utilisés par la plupart des types de données compatibles. Cela permet d'obtenir une syntaxe cohérente pour tous les types de données et de faciliter l'utilisation des points de terminaison.
  • Identifiant utilisateur : l'ID utilisateur ou "me" doivent être spécifiés dans la syntaxe du point de terminaison. Lorsque vous utilisez "me", l'ID utilisateur est déduit du jeton d'accès.

Exemple : Voici un exemple de point de terminaison GET Profile appelé à l'aide de l'API Google Santé.

GET https://health.googleapis.com/v4/users/me/profile

Mappages des points de terminaison

Consultez le tableau Disponibilité des types de données pour obtenir la liste des types de données disponibles et des méthodes d'API qu'ils prennent en charge.

Type de point de terminaison de l'API Web Fitbit API Google Health
GET (Log | Summary | Daily Summary) where you are requesting a single day of data Méthode dailyRollup avec windowSize = 1 jour
GET (intraday) lorsque vous demandez des données précises Méthode list
GET (série temporelle) par date ou intervalle Méthode rollUp ou dailyRollUp incluant une plage de dates
GET (liste des journaux) Méthode list
CRÉER ET MODIFIER des journaux Méthode patch
SUPPRIMER les journaux Méthode batchDelete
GET Profile users.getProfile renvoie les informations spécifiques de l'utilisateur.
users.getSettings renvoie les unités et les fuseaux horaires de l'utilisateur.
MODIFIER le profil users.updateProfile modifie les informations spécifiques de l'utilisateur.
users.updateSettings modifie les unités et les fuseaux horaires de l'utilisateur.
Obtenir l'ID utilisateur users.getIdentity renvoie l'ancien ID utilisateur Fitbit et l'ID utilisateur Google de l'utilisateur.

Migrer vos utilisateurs

La migration de l'API Fitbit Web vers l'API Google Santé est plus qu'une mise à jour technique. Vos utilisateurs doivent à nouveau donner leur consentement à votre nouvelle intégration en raison du changement de bibliothèque OAuth. Il n'est pas possible de transférer des jetons d'accès et d'actualisation vers l'API Google Health et de les faire fonctionner. Pour vous aider à fidéliser vos utilisateurs lors de la migration, voici quelques suggestions techniques et stratégiques pour réussir votre migration.

Stratégie à double bibliothèque

Étant donné que l'API Fitbit Web et l'API Google Santé utilisent des bibliothèques OAuth2 différentes, vous devez gérer une période de transition pendant laquelle les deux bibliothèques existent dans votre code.

Gestion des autorisations en parallèle

  • Encapsuler les clients : créez une couche d'abstraction ou une interface pour votre "Service de santé". Cela permet au reste de votre application de demander des données sans savoir quelle bibliothèque (Fitbit OAuth ou Google OAuth) est active pour cet utilisateur spécifique.
  • Mise à jour du schéma de base de données : mettez à jour votre table utilisateur pour inclure un indicateur oauth_type. Par exemple, utilisez fitbit pour Fitbit OAuth et google pour Google OAuth.
    • Nouveaux utilisateurs : par défaut, l'API Google Health et la bibliothèque Google OAuth. Définissez oauth_type sur google.
    • Utilisateurs existants : continuez à utiliser l'API Fitbit Web jusqu'à ce qu'ils aient terminé le processus de réconsentement. Définissez oauth_type sur fitbit.

Processus de recueil du consentement "Step-Up"

Au lieu de forcer la déconnexion, utilisez une approche d'autorisation incrémentielle :

  1. Détecter le jeton Fitbit Open Source : lorsqu'un utilisateur de l'API Fitbit Web ouvre l'application, déclencher une notification "Mise à jour du service".
  2. Lancer le flux Google OAuth : lorsque l'utilisateur clique sur "Mettre à jour", lancez le flux de la bibliothèque Google OAuth2.
  3. Remplacer et révoquer : une fois le jeton Google OAuth reçu, enregistrez-le dans le profil utilisateur, mettez à jour oauth_type de fitbit à google et (si possible) révoquez par programmation l'ancien jeton fitbit pour que le profil de sécurité de l'utilisateur reste propre.

Maximiser la fidélisation des utilisateurs

La réobtention du consentement est une "zone à risque" pour le churn. Pour éviter que les utilisateurs n'abandonnent l'application, suivez ces bonnes pratiques en matière d'UX :

La communication "Value-First"

Ne commencez pas par "Nous avons mis à jour notre API". Commencez par présenter les avantages du nouveau système soutenu par Google :

  • Sécurité renforcée : mentionnez la protection de compte et l'authentification à deux facteurs (2FA) de Google, qui sont les meilleures du secteur.
  • Fiabilité : synchronisation plus rapide et connexions de données plus stables.
  • Feature Gating : informez les utilisateurs en douceur que les nouvelles fonctionnalités et les nouveaux types de données nécessitent la mise à jour.

Timing intelligent

  • N'interrompez pas les tâches à forte valeur ajoutée : ne déclenchez jamais l'écran de recueil du consentement lorsqu'un utilisateur est en train de faire de l'exercice ou d'enregistrer des aliments.
  • Phase d'incitation : pendant les 30 premiers jours, utilisez une bannière pouvant être fermée.
  • Phase de "coupure nette" : ne rendez le reconsentement obligatoire qu'après plusieurs semaines d'avertissements, en même temps que les dates limites officielles de l'arrêt de l'API Fitbit Web.

Comparaison des flux de migration

Une distinction visuelle claire entre les anciens et les nouveaux flux aide les développeurs à comprendre où la logique se divise.

Fonctionnalité API Web Fitbit (ancienne) API Google Health (Google-Identity)
Bibliothèque Auth Open Source standard Google Identity Services (GIS) / Authentification Google
Comptes utilisateur Identifiants Fitbit hérités Compte Google
Type de jeton Accès / Actualisation spécifiques à Fitbit Jetons d'accès/d'actualisation émis par Google
Gestion du champ d'application Autorisations générales Autorisations précises / incrémentielles

Gérer les nuances de la migration de compte

Selon la documentation de Fitbit, les utilisateurs qui migrent leur compte vers Google ne perdent généralement pas immédiatement leurs connexions tierces, mais la modification de la version de l'API est une exigence côté développeur.

  • Vérifier la validité du jeton : utilisez un worker en arrière-plan pour vérifier si les jetons Fitbit échouent avec des erreurs "Non autorisé". Cela peut indiquer que l'utilisateur a migré son compte, mais que votre application n'a pas suivi.
  • Échecs élégants : si un appel Fitbit OAuth échoue, redirigez l'utilisateur vers une page personnalisée "Reconnecter Fitbit" qui utilise spécifiquement le nouveau flux Google OAuth.

Exemple de code

Pour migrer de l'ancienne API Web Fitbit vers l'API Google Health, vous passerez des bibliothèques OAuth2 générales à la bibliothèque Google Auth. Vous trouverez ci-dessous une suggestion d'architecture et une implémentation en pseudo-code écrit en JavaScript pour gérer cet état de "double bibliothèque".

1. Le "Middleware Switch"

Étant donné que vous ne pouvez pas migrer tous les utilisateurs en même temps, votre backend doit déterminer quelle bibliothèque utiliser en fonction de l'apiVersion actuel de l'utilisateur stocké dans votre base de données.

Mise en œuvre

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Migrer le flux UX

Pour maximiser la fidélisation, utilisez un modèle "Interruption et mise à niveau". Cela garantit que l'utilisateur n'est pas obligé de se reconnecter tant qu'il n'est pas déjà engagé avec l'application.

Logique de redirection

Lorsqu'un utilisateur de l'API Fitbit Web accède à une fonctionnalité spécifique, déclenchez la migration :

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Transitions techniques clés

Lorsque vous rédigez vos scripts de migration JavaScript, gardez à l'esprit les différences suivantes :

Fonctionnalité API Web Fitbit (ancienne) API Google Health (Google-Identity)
Point de terminaison du jeton https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Bibliothèque Auth Open Source standard Authentification Google
Champ d'application activité https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID utilisateur ID Fitbit encodé renvoyé dans la réponse /oauth2/token ID utilisateur renvoyé par le point de terminaison users.getIdentity

4. Checklist de rétention

  • Persistance de la session : ne supprimez pas l'ancienne session de l'API Fitbit Web de l'utilisateur tant que le jeton access_token de l'API Google Health n'a pas été validé et enregistré dans votre base de données.
  • Révocation automatique : une fois la migration de l'API Google Santé terminée, envoyez une requête POST au point de terminaison de révocation Fitbit hérité : https://api.fitbit.com/oauth2/revoke. L'utilisateur ne verra ainsi pas d'autorisations d'application "en double" dans ses paramètres Fitbit.
  • Gestion des erreurs : si un appel Fitbit renvoie une erreur 401 Unauthorized, redirigez automatiquement vers le flux Google OAuth au lieu d'afficher un message d'erreur.