Premiers pas avec Santé Connect

Ce guide est compatible avec la version 1.1.0-alpha12 de 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. Vous pouvez ouvrir Santé Connect depuis les Paramètres, mais le chemin d'accès varie en fonction de la version d'Android :

  • Sur Android 14 et versions ultérieures : accédez à Paramètres > Sécurité et confidentialité > Paramètres de confidentialité > Santé Connect ou recherchez Santé Connect dans les paramètres.
  • Sur Android 13 ou version antérieure : accédez à Paramètres > Applications > Santé Connect, ou ajoutez Santé Connect au menu Réglages rapides.

É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.2.0-alpha02"
  ...
}

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.

Vérifier la disponibilité des fonctionnalités

Lorsque de nouvelles fonctionnalités sont ajoutées à Santé Connect, les utilisateurs ne mettent pas toujours à jour leur version de Santé Connect. L'API Feature Availability permet de vérifier si une fonctionnalité de Santé Connect est disponible sur l'appareil de votre utilisateur et de décider quelle action entreprendre.

La fonction principale permettant de vérifier la disponibilité d'une fonctionnalité est getFeatureStatus(). Cela renvoie les constantes entières FEATURE_STATUS_AVAILABLE ou FEATURE_STATUS_UNAVAILABLE :

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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 les autorisations de lecture et d'écriture dans le fichier AndroidManifest.xml en fonction des types de données requis, qui doivent correspondre à ceux pour lesquels vous avez déclaré un 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)
  }
}

Étant donné que les utilisateurs peuvent accorder ou révoquer des autorisations à tout moment, votre application doit vérifier régulièrement les autorisations accordées et être capable de gérer les cas de perte d'autorisations.

Intégrer des utilisateurs

De nombreuses applications disposent d'un processus d'acceptation personnalisé proposant une formation aux fonctionnalités ou demandant le consentement de l'utilisateur, par exemple. Pour permettre à Santé Connect de lancer votre flux d'intégration, ajoutez les éléments suivants à votre fichier manifeste :

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Les utilisateurs peuvent lancer la connexion à votre application directement depuis l'application Santé Connect, plutôt que depuis votre application. Si votre application nécessite une interaction supplémentaire en plus de l'autorisation de lire ou d'écrire des données, fournissez une activité d'intégration.

Notez que l'activité d'acceptation peut être lancée plusieurs fois, par exemple si l'utilisateur révoque ultérieurement des autorisations pour votre application, puis la reconnecte.

É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) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        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 readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each 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 :