Migration de Google Fit vers Health Connect dans Capacitor

La migration de Google Fit vers Health Connect consiste à remplacer chaque appel à l’API Fit de votre app Capacitor par Health Connect sur Android, et par HealthKit sur iOS si vous y publiez aussi. Google a arrêté les nouvelles inscriptions Fit le 1er mai 2024 et ne prendra en charge les API Fit que jusqu’à la fin de 2026. Ce guide associe les types de données et les appels Fit à Health Connect, montre le code de remplacement avec @capgo/capacitor-health, et aborde la revue Play Console liée aux permissions santé.

Calendrier de dépréciation de Google Fit

La FAQ de migration de Google indique qu’il n’existe pas d’alternative à l’API REST Fit API avec la même structure : les applications sur l’appareil passent à Health Connect, et les intégrations cloud passent à l’API Google Health API basée sur le compte. Si vous voyez une date d’arrêt précise citée quelque part, vérifiez-la dans la FAQ de Google avant de planifier quoi que ce soit.

Ce qui change lors du passage à Health Connect

Le changement produit le plus important est le modèle centré sur l’appareil. Les données Health Connect d’un téléphone ne sont pas visibles sur un autre. Si votre application affiche l’historique sur plusieurs appareils, synchronisez les mesures vers votre propre backend.

Mapper les types de données Fit vers Health Connect

Types Fit sans équivalent direct

• Points de cœur (com.google.heart_minutes) Minutes de mouvement (com.google.active_minutes) étaient des scores Google Fit. Health Connect stocke les données brutes, pas ces scores. Recalculez votre propre métrique à partir de la fréquence cardiaque et des sessions d'exercice.
• Échantillons d'activité avec des types d'activité par seconde sont remplacés par des sessions d'exercice avec segments.
• Échantillons de localisation pendant les entraînements deviennent ExerciseRoute des données dans Health Connect, qui nécessitent une permission distincte et ne sont pas exposées par le plugin.
• Cadence, vitesse et puissance existent dans Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) mais ne sont pas couverts par les types du plugin. Si vous en dépendez, une petite méthode native personnalisée est la solution la plus rapide.

Auditez avant d’écrire du code : listez chaque DataType et chaque API que vous appelez (History, Recording, Sessions, Sensors, Config, REST), et marquez chacun comme mappé, recalculé ou supprimé.

Étape 1 : Supprimer Google Fit

Supprimez l’intégration Fit de votre projet Android et de votre JavaScript :

• Supprimer com.google.android.gms:play-services-fitness et, s’il n’est utilisé que pour Fit, play-services-auth depuis build.gradle.
• Supprimez le client OAuth Fit de Google Cloud et les scopes fitness de votre écran de consentement.
• Désinstallez l’ancien plugin communautaire Google Fit Capacitor que vous utilisiez, puis exécutez bunx cap sync.

Keep the Fit code in a branch until the new version is live, so you can export historical data if users ask.

Étape 2 : Installer le plugin santé

bun add @capgo/capacitor-health
bunx cap sync

@capgo/capacitor-health prend en charge Capacitor 8, utilise Health Connect sur Android et HealthKit sur iOS, et nécessite Android minSdk 26.

Configuration Android

Le plugin fusionne les permissions de lecture et d’écriture Health Connect pour les types pris en charge dans votre manifest, ainsi que <queries> entrée pour le package Health Connect et l’activité de justification des permissions. Vous devez :

1. Fournir une politique de confidentialité. Health Connect l’ouvre depuis la feuille d’autorisation. Ajoutez soit android/app/src/main/assets/public/privacypolicy.html, soit définissez une URL dans android/app/src/main/res/values/strings.xml:

<string name="health_connect_privacy_policy_url">https://example.com/privacy</string>

2. Réduisez les autorisations. Google Play examine chaque permission Health Connect que vous déclarez. Si vous ne lisez que les étapes et le rythme cardiaque, supprimez le reste avec tools:node="remove":

<uses-permission
    android:name="android.permission.health.WRITE_BLOOD_GLUCOSE"
    tools:node="remove" />

3. Ajoutez l’accès à l’historique si nécessaire. Health Connect limite les lectures à environ les 30 derniers jours, sauf si l'utilisateur autorise READ_HEALTH_DATA_HISTORY:

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

Configuration iOS

Activez la capacité HealthKit dans Xcode et ajoutez les chaînes d'utilisation à Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>Show your steps and workouts in the app.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>Save the workouts you record in the app.</string>

Étape 3 : Vérifier la disponibilité

Google Fit fonctionnait partout où les Play services étaient présents. Health Connect peut être absent sur Android 13 et versions antérieures, ou nécessiter une mise à jour.

import { Health } from '@capgo/capacitor-health';

export async function ensureHealthAvailable() {
  const result = await Health.isAvailable();
  if (result.available) return true;

  // On Android, send the user to install or update Health Connect
  if (result.platform === 'android') {
    await Health.openHealthConnectSettings();
  }
  console.warn('Health store unavailable:', result.reason);
  return false;
}

Affichez un court écran d'explication avant la redirection. Les utilisateurs qui ne connaissent pas Health Connect sont confus lorsque le Play Store s'ouvre sans prompt.

Étape 4 : Remplacer OAuth par les permissions

Le flux Fit était : Google Sign-In, demande des scopes fitness, puis appels d'API. Le nouveau flux tient en une seule feuille de permissions :

const status = await Health.requestAuthorization({
  read: ['steps', 'distance', 'calories', 'heartRate', 'sleep', 'workouts'],
  write: ['weight'],
  requestHistoryAccess: true, // Android only
});

if (status.readDenied.length > 0) {
  // explain what will not work and offer openHealthConnectSettings()
}
if (status.historyAccessAvailable === false) {
  // provider too old: only the last 30 days are readable
}

Permissions are per data type and the user can grant any subset. Use checkAuthorization avec les mêmes options à chaque démarrage de l'app, car les utilisateurs peuvent révoquer l'accès dans les paramètres de Health Connect à tout moment. Sur iOS, HealthKit masque les refus de lecture pour préserver la confidentialité : un résultat vide peut donc signifier « aucune donnée » ou « aucun accès ».

Étape 5 : Remplacer les lectures d'historique API

Un appel Fit readData pour les échantillons bruts devient readSamples:

const end = new Date();
const start = new Date(end.getTime() - 24 * 60 * 60 * 1000);

const { samples } = await Health.readSamples({
  dataType: 'heartRate',
  startDate: start.toISOString(),
  endDate: end.toISOString(),
  limit: 500,
  ascending: true,
});

for (const s of samples) {
  console.log(s.startDate, s.value, s.unit, s.sourceName, s.deviceType);
}

sourceName et, sur Android, deviceType (watch, phone, chestStrap, and so on) replace Fit’s data source objects. Use them to prefer watch data over phone data when both exist.

Étape 6 : Remplacer les lectures par buckets et agrégées

Fit’s bucketByTime , ce qui aggregate devient queryAggregated:

const { samples: daily } = await Health.queryAggregated({
  dataType: 'steps',
  startDate: new Date(Date.now() - 7 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',          // 'hour' | 'day' | 'week' | 'month'
  aggregation: 'sum',
});

const { samples: hr } = await Health.queryAggregated({
  dataType: 'heartRate',
  bucket: 'hour',
  aggregation: ['min', 'average', 'max'],
  startDate: new Date(Date.now() - 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
});
// hr[i].values.min, hr[i].values.average, hr[i].values.max

Agrégez toujours les pas au lieu d'additionner les échantillons bruts. Health Connect déduplique les données qui se chevauchent entre plusieurs applications lors de l'agrégation, et les sommes brutes comptent souvent en double quand une montre et un téléphone enregistrent tous les deux des pas.

Étape 7 : Remplacer l’API Sessions

Les sessions Fit correspondent aux sessions d'exercice :

const { workouts, anchor } = await Health.queryWorkouts({
  workoutType: 'running',
  startDate: new Date(Date.now() - 30 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  limit: 50,
});

for (const w of workouts) {
  console.log(w.workoutType, w.duration, w.totalDistance, w.totalEnergyBurned);
}
// pass `anchor` back to fetch the next page

Requête workouts dans read les permissions d'abord. Le plugin lit les entraînements mais n'écrit pas de sessions d'exercice, donc si votre application enregistre des entraînements, écrivez les échantillons sous-jacents (distance, calories, fréquence cardiaque) et conservez la session elle-même dans votre backend, ou ajoutez une méthode native pour ExerciseSessionRecord.

Étape 8 : Remplacer les inserts

de Fit insertData devient saveSample:

await Health.saveSample({
  dataType: 'weight',
  value: 72.4, // kilograms
  startDate: new Date().toISOString(),
});

await Health.saveSample({
  dataType: 'bloodPressure',
  value: 120,
  systolic: 120,
  diastolic: 80,
  startDate: new Date().toISOString(),
});

Les valeurs doivent utiliser l'unité par défaut de chaque type (kilogrammes, mètres, kilocalories, bpm). L' metadata option est ignorée par Health Connect.

Étape 9 : Passer la revue de Google Play

Health permissions trigger extra review:

1. Dans la Play Console, ouvrez Contenu de l’app et compléter la Health apps déclaration et le formulaire d'autorisations Health Connect. Justifiez chaque autorisation demandée.
2. Assurez-vous que la politique de confidentialité liée dans Play Console et celle affichée dans la feuille Health Connect décrivent l'utilisation des données de santé.
3. Mettez à jour le Data safety formulaire : données de santé et de forme physique, collectées ou non, partagées ou non.
4. Soumettez un build qui ne déclare que les permissions justifiées. Les permissions déclarées en trop sont la cause n°1 de rejet.

Prévoyez un délai de revue plus long que pour une mise à jour classique. Déployez la migration dans une release dédiée, sans mélanger des fonctionnalités non liées.

Étape 10 : Migrer les attentes des utilisateurs

• Indiquez aux utilisateurs que leur historique provient désormais de Health Connect, et que les données antérieures peuvent être limitées à 30 jours jusqu'à ce qu'ils accordent l'accès à l'historique.
• If your app used Fit as its cloud sync, move that responsibility to your backend now.
• Supprimez les boutons « Connecter Google Fit » et renommez-les « Connecter Health Connect » sur Android et « Connecter Apple Health » sur iOS.

Troubleshooting

isAvailable() renvoie false sur Android 13: Health Connect n'est pas installé ou est obsolète. Appelez openHealthConnectSettings().

La fenêtre de permission n'apparaît jamais: la permission n'est pas déclarée dans le manifest fusionné, ou vous l'avez supprimée avec tools:node="remove". Vérifiez android/app/build/intermediates/merged_manifests.

Les lectures ne renvoient que 30 jours: demandez requestHistoryAccess: true et déclarez READ_HEALTH_DATA_HISTORY.

Les totaux d'étapes sont plus élevés que dans Google Fit: vous avez additionné les échantillons bruts. Utilisez queryAggregated.

Résultats vides sur iOS: soit aucune donnée, soit la permission de lecture est refusée. HealthKit ne vous dit pas laquelle.

La Play Console rejette la mise à jour: supprimez les permissions Health Connect non déclarées ou injustifiées et soumettez à nouveau avec une justification claire.

Déployez la migration par étapes

La partie native (plugin, manifest, capacité HealthKit) nécessite une release sur les stores. Ensuite, les requêtes, l'UI et le mapping des données sont en JavaScript, ce qui vous permet d'itérer avec les live updates Capgo while users test the new flow. If you also read live sensor data, see our guide to créer un moniteur de fréquence cardiaque avec Capacitor, et le docs du plugin Health pour chaque type de données.