Premiers pas avec Santé Connect

Ce guide vous explique comment commencer à utiliser Santé Connect sur votre application.

Étape 1 : Préparer l'appli Santé Connect

L'application Santé Connect est responsable de la gestion de toutes les requêtes que votre application envoie via le SDK Santé Connect. Ces requêtes incluent le stockage des données et la gestion de leurs accès en lecture et en écriture.

L'accès à Santé Connect dépend de la version d'Android installée sur le téléphone. Les sections suivantes expliquent comment gérer plusieurs versions récentes d'Android.

Android 14

À partir d'Android 14 (niveau d'API 34), Santé Connect fait partie du framework Android. Cette version de Santé Connect est un module de framework. Aucune configuration n'est donc nécessaire.

Android 13 ou version antérieure

Sur Android 13 (niveau d'API 33) et versions antérieures, Santé Connect ne fait pas partie du framework Android. Vous devez alors installer l'application Santé Connect à partir du Google Play Store.

Si vous avez intégré votre application à Santé Connect sur Android 13 et version antérieure et que vous souhaitez effectuer la migration sur Android 14, consultez Migrer d'Android 13 à 14.

Ouvrir l'appli Santé Connect

Santé Connect n'apparaît plus par défaut sur l'écran d'accueil. Pour ouvrir Santé Connect, accédez à Settings > Apps > Health Connect (Paramètres > Applications > Santé Connect), ou ajoutez Santé Connect au menu Quick Settings (Réglages rapides).

En outre, Santé Connect demande à l'utilisateur d'activer le verrouillage de l'écran avec un code PIN, un schéma ou un mot de passe afin que les données de santé stockées dans Santé Connect soient protégées contre les tiers malveillants lorsque l'appareil est verrouillé. Pour définir un verrouillage de l'écran, accédez à Settings > Security > Screen lock (Paramètres > Sécurité > Verrouillage de l'écran).

Étape 2 : Ajouter le SDK Santé Connect à votre appli

Le SDK Santé Connect est chargé d'utiliser l'API Santé Connect pour envoyer des requêtes lors de l'exécution d'opérations sur le datastore de l'application Santé Connect.

Ajoutez la dépendance du SDK Santé Connect dans le fichier build.gradle au niveau de votre module :

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

Reportez-vous aux versions de Santé Connect pour obtenir la dernière version.

Étape 3 : Configurer votre application

Les sections suivantes expliquent comment configurer votre application pour l'intégrer à Santé Connect.

Déclarer des autorisations

L'accès aux données de santé et de remise en forme est un sujet sensible. Santé Connect met en œuvre une couche de sécurité pour les opérations de lecture et d'écriture, ce qui préserve la confiance des utilisateurs.

Dans votre application, déclarez des autorisations de lecture et d'écriture dans le fichier AndroidManifest.xml en fonction des types de données requis, qui doivent correspondre à ceux auxquels vous avez déclaré l'accès dans la Play Console.

Santé Connect utilise le format de déclaration d'autorisation Android standard. Attribuez des autorisations à l'aide des balises <uses-permission>. Imbriquez-les dans les balises <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

Pour obtenir la liste complète des autorisations et des types de données correspondants, consultez la section Liste des types de données.

Affichez la boîte de dialogue des règles de confidentialité de votre application

Le fichier manifeste Android doit comporter une activité qui affiche les règles de confidentialité de votre application, qui correspondent à la justification des autorisations demandées par votre application. Elles décrivent comment les données de l'utilisateur sont utilisées et traitées.

Déclarez cette activité pour gérer l'intent ACTION_SHOW_PERMISSIONS_RATIONALE lorsqu'il est envoyé à l'application quand l'utilisateur clique sur le lien des Règles de confidentialité dans l'écran des autorisations de Santé Connect.

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

Obtenir un client Santé Connect

HealthConnectClient est un point d'entrée de l'API Santé Connect. Elle permet à l'application d'utiliser le datastore de l'application Santé Connect. Elle gère automatiquement sa connexion à la couche de stockage sous-jacente et traite l'ensemble de l'IPC et de la sérialisation des requêtes sortantes et des réponses entrantes.

Pour obtenir une instance de client, déclarez d'abord le nom du package Santé Connect dans votre fichier manifeste Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Ensuite, dans votre activité, vérifiez si Santé Connect est installé à l'aide de getSdkStatus. Si c'est le cas, obtenez une instance HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // Optionally redirect to package installer to find a provider, for example:
  val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
  context.startActivity(
    Intent(Intent.ACTION_VIEW).apply {
      setPackage("com.android.vending")
      data = Uri.parse(uriString)
      putExtra("overlay", true)
      putExtra("callerId", context.packageName)
    }
  )
  return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

Étape 4 : Demander les autorisations à l'utilisateur

Après avoir créé une instance de client, votre application doit demander des autorisations à l'utilisateur. Les utilisateurs doivent être autorisés à accorder ou à refuser des autorisations à tout moment.

Pour ce faire, créez un ensemble d'autorisations pour les types de données requis. Assurez-vous d'abord que les autorisations de l'ensemble sont déclarées dans votre fichier manifeste Android.

// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

Utilisez getGrantedPermissions pour voir si votre application dispose déjà des autorisations requises accordées. Si ce n'est pas le cas, utilisez createRequestPermissionResultContract pour demander ces autorisations. L'écran des autorisations de Santé Connect s'affiche.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Ne partez pas du principe que les autorisations sont constantes, car les utilisateurs peuvent les accorder ou les révoquer à tout moment. Votre appli doit vérifier régulièrement les autorisations accordées et être capable de traiter les cas de perte d'autorisations.

Étape 5 : Effectuer des opérations

Maintenant que tout est configuré, effectuez des opérations de lecture et d'écriture dans votre application.

Écrire des données

Structurez vos données dans un enregistrement. Consultez la liste des types de données disponibles dans Santé Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Écrivez ensuite votre enregistrement avec insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Lire des données

Vous pouvez lire vos données individuellement en utilisant readRecords.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

Vous pouvez également lire des données agrégées à l'aide de aggregate.

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Tutoriels vidéo

Regardez ces vidéos qui expliquent plus en détail les fonctionnalités de Santé Connect, ainsi que les bonnes pratiques pour une intégration optimale :

Ressources

Consultez les ressources suivantes qui faciliteront le développement par la suite.

Étapes suivantes

Consultez les workflows courants pour savoir comment effectuer des opérations dans Santé Connect, par exemple :