Detectar quando usuários iniciam ou encerram uma atividade

Pode ser necessário projetar seu app para identificar quando um usuário inicia ou interrompe uma atividade específica, como caminhar, pedalar ou dirigir. Por exemplo, um app de rastreamento de quilometragem pode começar a rastrear quilômetros quando um usuário começar a dirigir, ou um app de mensagens pode ignorar todas as conversas até que ele pare de dirigir.

A API Activity Recognition Transition pode ser usada para detectar mudanças na atividade do usuário. Seu app assina uma transição nas atividades de interesse e a API notifica seu app somente quando necessário. Esta página mostra como usar a API Activity Recognition Transition, também chamada de API Transition.

Configurar seu projeto

Para usar a API Transition no seu app, você precisa declarar uma dependência à API Google Location and Activity Recognition versão 12.0.0 ou mais recente e especificar a permissão com.google.android.gms.permission.ACTIVITY_RECOGNITION no manifesto do app.

  1. Para declarar uma dependência à API, adicione uma referência ao repositório maven do Google e uma entrada de implementação para com.google.android.gms:play-services-location:12.0.0 à seção de dependências do arquivo build.gradle do seu app. Para mais informações, consulte Configurar o Google Play Services.
  2. Para especificar a permissão com.google.android.gms.permission.ACTIVITY_RECOGNITION, adicione um elemento <uses-permission> no manifesto do app, como mostrado no exemplo a seguir:

    <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>
    

Inscrever-se para atualizações de transição de atividades

Para começar a receber notificações sobre transições de atividade, implemente o seguinte:

Para criar o objeto ActivityTransitionRequest, é preciso criar uma lista de objetos ActivityTransition, que representam a transição sobre a qual você quer receber notificações. Um objeto ActivityTransition inclui os seguintes dados:

O código a seguir mostra como criar uma lista de objetos ActivityTransition:

Kotlin

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()

Java

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());

É possível criar um objeto ActivityTransitionRequest transmitindo a lista de ActivityTransitions para a classe ActivityTransitionRequest, conforme mostrado no exemplo a seguir:

Kotlin

val request = ActivityTransitionRequest(transitions)

Java

ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);

Para se registrar para receber atualizações de transição de atividade, transmita sua instância de ActivityTransitionRequest e seu objeto PendingIntent para o método requestActivityTransitionUpdates(). O método requestActivityTransitionUpdates() retorna um objeto Task que pode ser verificado para identificar se houve sucesso ou falha, conforme mostrado no exemplo de código abaixo:

Kotlin

// 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
}

Java

// 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
        }
    }
);

Depois de se inscrever para receber atualizações de transição de atividades, o app receberá notificações no PendingIntent registrado.

Eventos de transição da atividade do processo

Quando a transição de atividade solicitada ocorre, seu app recebe um callback Intent. É possível extrair um objeto ActivityTransitionResult do Intent, que inclui uma lista de objetos ActivityTransitionEvent. Os eventos são ordenados cronologicamente. Por exemplo, se um app solicitar o tipo de atividade IN_VEHICLE nas transições ACTIVITY_TRANSITION_ENTER e ACTIVITY_TRANSITION_EXIT, ele vai receber um objeto ActivityTransitionEvent quando o usuário começar a dirigir e outro quando o usuário fizer a transição para qualquer outra atividade.

Para implementar o callback, crie uma subclasse de BroadcastReceiver e implemente o método onReceive para receber a lista de eventos de transição de atividade. Para mais informações, consulte Transmissões. O exemplo a seguir mostra como implementar o método onReceive:

Kotlin

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....
        }
    }
}

Java

@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....
        }
    }
}

Cancelar o registro das atualizações de transição de atividades

Para cancelar o registro de atualizações de transição de atividade, chame o método removeActivityTransitionUpdates() do ActivityRecognitionClient e transmita o objeto PendingIntent como um parâmetro, conforme mostrado no exemplo a seguir:

Kotlin

// 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)
}

Java

// 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());
        }
    }
);

Outros recursos

Para saber mais sobre o uso da API de reconhecimento de atividade do usuário, consulte o material abaixo:

Amostras

Exemplo (em inglês) para demonstrar as práticas recomendadas para o reconhecimento de atividade do usuário.