Détecter quand les utilisateurs démarrent ou arrêtent une activité

Dans certaines applications, il est parfois nécessaire d'identifier le moment où un utilisateur démarre ou arrête une activité particulière, telle que la marche, le vélo ou la conduite. Par exemple, une application de suivi du kilométrage pourrait commencer à comptabiliser le nombre de kilomètres parcourus lorsque l'utilisateur se met à conduire, ou une application de messagerie pourrait couper le son de toutes les conversations jusqu'à ce qu'il arrête de conduire.

L'API Activity Recognition Transition permet de détecter les changements d'activité de l'utilisateur. Votre application s'abonne à une transition dans des activités spécifiques, et l'API ne l'informe que lorsque cela est nécessaire. Cette page explique comment utiliser l'API Activity Recognition Transition, également appelée API Transition.

Configurer votre projet

Pour utiliser l'API Transition dans votre application, vous devez déclarer une dépendance à la version 12.0.0 ou ultérieure de 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.

1. Pour déclarer une dépendance à l'API, ajoutez une référence au dépôt Maven Google et ajoutez une entrée d'implémentation à com.google.android.gms:play-services-location:12.0.0 dans la section des dépendances du fichier build.gradle de votre application. Pour en savoir plus, consultez la section Configurer les services Google Play.

2. Pour spécifier l'autorisation com.google.android.gms.permission.ACTIVITY_RECOGNITION, ajoutez un élément <uses-permission> au fichier manifeste de l'application, comme indiqué dans l'exemple suivant :

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
            package="com.example.myapp">
   
      <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />
      …
    </manifest>
   

S'inscrire pour recevoir des informations sur la transition des activités

Pour commencer à recevoir des notifications sur les transitions d'activité, vous devez implémenter les éléments suivants :

• Un objet ActivityTransitionRequest qui spécifie le type d'activité et de transition.
• Un rappel PendingIntent où votre application reçoit les notifications. Pour en savoir plus, consultez Utiliser un intent en attente.

Pour créer l'objet ActivityTransitionRequest, vous devez élaborer une liste d'objets ActivityTransition, qui représentent la transition pour laquelle vous souhaitez recevoir des notifications. Un objet ActivityTransition inclut les données suivantes :

• Un type d'activité, représenté par la classe DetectedActivity. L'API Transition accepte les activités suivantes :
  • IN_VEHICLE
  • ON_BICYCLE
  • RUNNING
  • STILL
  • WALKING
• Type de transition ACTIVITY_TRANSITION_ENTER ou ACTIVITY_TRANSITION_EXIT (pour plus d'informations, reportez-vous à la classe ActivityTransition).

Le code suivant montre comment créer une liste d'objets ActivityTransition :

val transitions = mutableListOf<ActivityTransition>()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

transitions +=
        ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build()

List<ActivityTransition> transitions = new ArrayList<>();

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_ENTER)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.IN_VEHICLE)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

transitions.add(
        new ActivityTransition.Builder()
          .setActivityType(DetectedActivity.WALKING)
          .setActivityTransition(ActivityTransition.ACTIVITY_TRANSITION_EXIT)
          .build());

Vous pouvez créer un objet ActivityTransitionRequest en transmettant la liste d'ActivityTransitions à la classe ActivityTransitionRequest, comme illustré dans l'exemple suivant :

val request = ActivityTransitionRequest(transitions)

ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);

Pour commencer à recevoir les notifications de transition d'activité, transmettez l'instance ActivityTransitionRequest et l'objet PendingIntent à la méthode requestActivityTransitionUpdates(). La méthode requestActivityTransitionUpdates() renvoie un objet Task pour lequel vous pouvez vérifier la réussite ou l'échec, comme indiqué dans l'exemple de code suivant :

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .requestActivityTransitionUpdates(request, myPendingIntent)

task.addOnSuccessListener {
    // Handle success
}

task.addOnFailureListener { e: Exception ->
    // Handle error
}

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
          .requestActivityTransitionUpdates(request, myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            // Handle success
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            // Handle error
        }
    }
);

Une fois que vous êtes inscrit pour être averti en cas de transition d'une activité, votre application reçoit des notifications dans l'élément PendingIntent enregistré.

Traiter les événements de transition des activités

Lorsque la transition demandée d'une activité se produit, votre application reçoit un rappel Intent. Un objet ActivityTransitionResult peut être extrait à partir de l'Intent, qui inclut la liste des objets ActivityTransitionEvent. Les événements sont classés par ordre chronologique. Par exemple, si une application demande le type d'activité IN_VEHICLE au niveau des transitions ACTIVITY_TRANSITION_ENTER et ACTIVITY_TRANSITION_EXIT, elle reçoit un objet ActivityTransitionEvent lorsque l'utilisateur commence à conduire, et un autre lorsqu'il passe à une autre activité.

Pour implémenter votre rappel, créez une sous-classe de BroadcastReceiver et implémentez la méthode onReceive() pour obtenir la liste des événements de transition d'activité. Pour en savoir plus, consultez la section Diffusions. L'exemple suivant montre comment mettre en œuvre la méthode onReceive() :

override fun onReceive(context: Context, intent: Intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        val result = ActivityTransitionResult.extractResult(intent)!!
        for (event in result.transitionEvents) {
            // chronological sequence of events....
        }
    }
}

@Override
public void onReceive(Context context, Intent intent) {
    if (ActivityTransitionResult.hasResult(intent)) {
        ActivityTransitionResult result = ActivityTransitionResult.extractResult(intent);
        for (ActivityTransitionEvent event : result.getTransitionEvents()) {
            // chronological sequence of events....
        }
    }
}

Demander à ne plus recevoir de notifications sur les transitions d'activité

Pour ne plus recevoir les notifications de transition d'activité, appelez la méthode removeActivityTransitionUpdates() de ActivityRecognitionClient et transmettez l'objet PendingIntent en tant que paramètre, comme illustré dans l'exemple suivant :

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
val task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent)

task.addOnSuccessListener {
    myPendingIntent.cancel()
}

task.addOnFailureListener { e: Exception ->
    Log.e("MYCOMPONENT", e.message)
}

// myPendingIntent is the instance of PendingIntent where the app receives callbacks.
Task<Void> task = ActivityRecognition.getClient(context)
        .removeActivityTransitionUpdates(myPendingIntent);

task.addOnSuccessListener(
    new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void result) {
            myPendingIntent.cancel();
        }
    }
);

task.addOnFailureListener(
    new OnFailureListener() {
        @Override
        public void onFailure(Exception e) {
            Log.e("MYCOMPONENT", e.getMessage());
        }
    }
);

Ressources supplémentaires

Pour en savoir plus sur l'utilisation de l'API de reconnaissance de l'activité des utilisateurs, consultez les ressources suivantes :

Exemples

Exemple illustrant les bonnes pratiques concernant la reconnaissance de l'activité des utilisateurs