L'API Android Sleep

1. Introduction

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez créer une application Android pour détecter le temps de sommeil des utilisateurs. Cette application va :

Demander des autorisations
S'inscrire pour utiliser l'API Android Sleep
Récupérer les événements d'API et les afficher dans l'interface utilisateur
Se désinscrire lorsque l'API n'est plus nécessaire

Ce dont vous aurez besoin

Une version récente d'Android Studio avec les outils Android Build version 21 ou ultérieure.
Un appareil exécutant Android 10 (niveau d'API 29) ou une version ultérieure.

2. Configuration

Cloner les éléments du projet de démarrage

Pour vous aider à démarrer le plus rapidement possible, nous avons préparé un projet de démarrage. Vérifiez si vous disposez déjà de Git en saisissant git --version dans le terminal/la ligne de commande. Si ce n'est pas le cas, suivez ces instructions pour installer Git. Ensuite, vous pouvez simplement exécuter la commande suivante pour cloner le projet.

 git clone https://github.com/android/codelab-android-sleep/

Importer le projet

Lancez Android Studio, sélectionnez "Open an existing Android Studio project" (Ouvrir un projet Android Studio existant) sur l'écran d'accueil, puis ouvrez le répertoire du projet.

Une fois le projet chargé, une alerte peut s'afficher, indiquant que Git ne suit pas toutes les modifications locales. Vous pouvez cliquer sur Ignore (Ignorer) ou sur le X en haut à droite. (Vous ne transmettrez pas vos modifications au dépôt Git.)

En haut à gauche de la fenêtre du projet, vous devriez obtenir une image semblable à celle affichée dans la vue Android. (Si vous êtes dans la vue Project (Projet), vous devez développer le projet pour voir la même chose.)

Deux icônes de dossier s'affichent (start et complete). Chacun est considéré comme un "module" distinct.

Notez que, la première fois, Android Studio peut mettre plusieurs secondes pour compiler le projet en arrière-plan. Pendant ce temps, une icône de chargement s'affiche dans la barre d'état en bas d'Android Studio :

Nous vous recommandons d'attendre la fin de cette opération avant de modifier le code. Android Studio pourra ainsi récupérer tous les composants nécessaires.

Si une invite "Reload for language changes to take effect?" (Charger à nouveau pour appliquer les modifications de langue) ou similaire apparaît sélectionnez "Yes" (Oui).

Comprendre le projet de démarrage

La configuration initiale est terminée, nous pouvons passer à la reconnaissance de l'activité. Nous utiliserons le module start, qui constitue le point de départ de cet atelier de programmation. En d'autres termes, vous allez ajouter le code de chaque étape à start.

Vous pouvez utiliser le module complete pour vérifier votre travail ou comme référence si vous rencontrez des problèmes.

Les principaux composants :

MainActivity.kt permet d'afficher l'écran principal lorsque l'utilisateur lance l'application.
SleepReceiver.kt extrait les événements de sommeil de l'API et les stocke dans la base de données.
BootReceiver.kt se réinscrit à l'API Android Sleep après le démarrage de l'appareil, afin de continuer à écouter les événements.

Exécuter le projet de démarrage

Exécutons notre application.

Connectez votre appareil Android à votre ordinateur.
Dans la barre d'outils, choisissez la configuration start dans le menu déroulant, sélectionnez votre appareil, puis cliquez sur le bouton d'exécution (en forme de triangle vert) situé à côté :

L'application devrait s'afficher sur votre appareil :

Nous n'avons pas encore ajouté de code pour suivre le sommeil. Nous le ferons dans les sections suivantes.

Dans la prochaine section, nous allons passer en revue la bibliothèque et les autorisations requises.

3. Examiner la bibliothèque et ajouter des autorisations

Vérifier build.gradle et AndroidManifest.xml

Pour utiliser l'API Android Sleep dans votre application, vous devez déclarer une dépendance à l'API Google Location and Activity Recognition et spécifier l'autorisation com.google.android.gms.permission.ACTIVITY_RECOGNITION dans le fichier manifeste de l'application.

Dans le fichier build.gradle du module start, recherchez TODO: Review Play services library required for activity recognition (Examiner les bibliothèques de services Play requises pour la reconnaissance d'activité). Vous n'avez pas besoin d'intervenir. Examinez simplement la dépendance déclarée dont nous avons besoin. Cela devrait se présenter comme ceci :

    // TODO: Review play services library required for activity recognition.
    implementation 'com.google.android.gms:play-services-location:18.0.0'

Dans le fichier AndroidManifest.xml du module start, recherchez TODO: Add activity recognition and boot complete permissions (Ajouter la reconnaissance de l'activité et les autorisations après démarrage) et ajoutez le code suivant à l'élément <manifest>.

<!-- TODO: Add activity recognition and receive boot complete permissions. -->
<!-- Required for 29+. -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

Votre code doit maintenant ressembler à ceci :

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.android.example.sleepcodelab">
...
<!-- TODO: Add activity recognition and receive boot complete permissions. -->
<!-- Required for 29+. -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
  ...
</manifest>

Comme vous pouvez le voir dans les commentaires, vous devez ajouter l'autorisation d'exécution pour la version 29 de l'API.

Et voilà ! Votre application peut désormais prendre en charge la reconnaissance de l'activité liée au sommeil. Il nous suffit d'ajouter le code pour l'obtenir.

Vérifier les autorisations liées à la reconnaissance de l'activité

Nous devons vérifier et demander les éventuelles autorisations d'exécution nécessaires :

Dans MainActivity.kt, nous vérifierons les autorisations liées à la reconnaissance de l'activité.
Si ces autorisations ne sont pas accordées, nous appellerons displayPermissionSettingsSnackBar(). Ce snackbar explique pourquoi l'autorisation est nécessaire et permet aux utilisateurs de l'accorder dans les paramètres système.

Dans le fichier MainActivity.kt du module start, recherchez TODO: Review Activity Recognition permission check (Vérifier les autorisations liées à la reconnaissance de l'activité). Vous devriez obtenir cet extrait de code.

Remarque : Cette section ne demande aucune intervention de votre part.

// TODO: Review Activity Recognition permission checking.
private fun activityRecognitionPermissionApproved(): Boolean {
   return PackageManager.PERMISSION_GRANTED == ActivityCompat.checkSelfPermission(
           this,
           Manifest.permission.ACTIVITY_RECOGNITION
   );
}

Activer ou désactiver le suivi du sommeil

Dans le fichier MainActivity.kt du module start, recherchez TODO: Enable/Disable Sleep tracking and ask for permissions if needed (Activer/Désactiver le suivi du sommeil et demander les autorisations si nécessaire). Remplacez la méthode onClickRequestSleepData() par le code suivant.

// TODO: Enable/Disable sleep tracking and ask for permissions if needed.
fun onClickRequestSleepData(view: View) {
   if (activityRecognitionPermissionApproved()) {
       if (subscribedToSleepData) {
           unsubscribeToSleepSegmentUpdates(applicationContext, sleepPendingIntent)
       } else {
           subscribeToSleepSegmentUpdates(applicationContext, sleepPendingIntent)
       }
   } else {
       requestPermissionLauncher.launch(permission.ACTIVITY_RECOGNITION)
   }
}

Si l'autorisation Reconnaissance de l'activité est accordée, et si l'utilisateur s'est abonné aux données sur le sommeil, nous devons nous abonner aux mises à jour de ces données. Sinon, nous devons nous désabonner.

Si l'autorisation n'est pas accordée, nous devons rediriger l'utilisateur vers l'écran de démarrage, qui explique pourquoi nous avons besoin de l'autorisation, et l'inviter à nous l'accorder.

4. S'abonner aux mises à jour de l'API Android Sleep

Créer un PendingIntent

Dans le fichier MainActivity.kt du module start, recherchez TODO: Create a PendingIntent for Sleep API events (Créer un PendingIntent pour les événements de l'API Android Sleep). Collez l'extrait de code suivant.

// TODO: Create a PendingIntent for Sleep API events
sleepPendingIntent =
   SleepReceiver.createSleepReceiverPendingIntent(context = applicationContext)

Nous pouvons maintenant obtenir des mises à jour lorsque les données de l'API Android Sleep sont disponibles.

Demander les mises à jour de l'API Android Sleep

Dans le fichier MainActivity.kt du module start, recherchez TODO: Request Sleep API updates (Demander les mises à jour de l'API Android Sleep). Collez l'extrait de code suivant.

// TODO: Request Sleep API updates
val task = ActivityRecognition.getClient(context).requestSleepSegmentUpdates(
   pendingIntent,
   // Registers for both SleepSegmentEvent and SleepClassifyEvent data.
   SleepSegmentRequest.getDefaultSleepSegmentRequest()
)

task.addOnSuccessListener {
   mainViewModel.updateSubscribedToSleepData(true)
   Log.d(TAG, "Successfully subscribed to sleep data.")
}
task.addOnFailureListener { exception ->
   Log.d(TAG, "Exception when subscribing to sleep data: $exception")
}

Lorsque vous êtes abonné aux mises à jour de l'API Android Sleep, votre application reçoit des notifications de détection liées au sommeil dans le PendingIntent enregistré.

Dans le fichier receiver/BootReceiver.kt du module start, recherchez TODO: Request Sleep API when boot complete (Demander l'API Android Sleep une fois le démarrage terminé). Collez l'extrait de code suivant.

// TODO: Request Sleep API upon boot complete
val subscribedToSleepData = repository.subscribedToSleepDataFlow.first()
if (subscribedToSleepData) {
   subscribeToSleepSegmentUpdates(
       context = context,
       pendingIntent = SleepReceiver.createSleepReceiverPendingIntent(context)
   )
}

Le code permet à l'application de continuer à recevoir les mises à jour de l'API Android Sleep après un redémarrage de l'appareil.

5. Traiter les événements

Lorsqu'un événement de classification ou de détection du temps de sommeil se produit, votre application reçoit un rappel d'intent. Une liste d'objets SleepSegmentEvent ou SleepClassifyEvent peut être extraite de l'intent.

Ajoutons le code permettant de gérer ces événements.

Dans le fichier receiver/SleepReceiver.kt du module start, recherchez TODO: Extract sleep information from PendingIntent (Extraire les informations concernant le sommeil du PendingIntent). Ajoutez le code suivant après le commentaire.

// TODO: Extract sleep information from PendingIntent.
if (SleepSegmentEvent.hasEvents(intent)) {
   val sleepSegmentEvents: List<SleepSegmentEvent> =
       SleepSegmentEvent.extractEvents(intent)
   addSleepSegmentEventsToDatabase(repository, sleepSegmentEvents)
} else if (SleepClassifyEvent.hasEvents(intent)) {
   val sleepClassifyEvents: List<SleepClassifyEvent> =
       SleepClassifyEvent.extractEvents(intent)
   addSleepClassifyEventsToDatabase(repository, sleepClassifyEvents)
}

Ce code permet d'enregistrer les données SleepSegmentEvent ou SleepClassifyEvent dans une base de données Room. MainActivity accède aux informations de la base de données via un ViewModel à l'aide de LiveData. Pour en savoir plus sur la combinaison de ces classes, consultez l'atelier de programmation sur Room.

Et voilà ! Vous avez terminé. Essayez d'exécuter l'application.

6. Installer l'application et examiner le code

Connectez votre appareil à la station de travail à l'aide d'un câble. Dans Android Studio, cliquez sur "Run" (Exécuter) pour installer et exécuter l'application sur votre appareil. Après avoir accordé l'autorisation Reconnaissance de l'activité et appuyé sur le bouton "SUBSCRIBE TO SLEEP DATA (S'abonner aux données de sommeil)", le premier événement SleepClassifyEvent met environ 10 minutes à apparaître, tandis que l'événement SleepSegmentEvent devrait survenir sous 24 heures.

N'hésitez pas à lire l'intégralité du code pour examiner ce que vous avez fait et mieux comprendre comment ces éléments fonctionnent ensemble.

Revues de code (facultatif)

Les revues de code suivantes sont facultatives. Elles fournissent des détails sur le mappage de données entre l'API Android Sleep et les entités de base de données :

data/db/SleepClassifyEventEntity.kt
data/db/SleepSegmentEventEntity.kt