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, conforme 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:

• Um objeto ActivityTransitionRequest que especifica o tipo de atividade e a transição.
• Um callback PendingIntent em que seu app recebe notificações. Para mais informações, consulte Uso de um intent pendente.

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

• Um tipo de atividade, representado pela classe DetectedActivity. A API Transition é compatível com as seguintes atividades:
  • IN_VEHICLE
  • ON_BICYCLE
  • RUNNING
  • STILL
  • WALKING
• Um tipo de transição de ACTIVITY_TRANSITION_ENTER ou ACTIVITY_TRANSITION_EXIT. Para mais informações, consulte a classe ActivityTransition.

O código a seguir mostra como criar uma lista de objetos 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());

Você pode criar um objeto ActivityTransitionRequest transmitindo a lista de ActivityTransitions para a classe ActivityTransitionRequest, como mostrado no exemplo a seguir:

val request = ActivityTransitionRequest(transitions)

ActivityTransitionRequest request = new ActivityTransitionRequest(transitions);

Você pode se inscrever para atualizações de transição de atividades transmitindo sua instância de ActivityTransitionRequest e seu objeto PendingIntent para o método requestActivityTransitionUpdates(). O método requestActivityTransitionUpdates() retorna um objeto Task que você pode verificar quanto a sucesso ou falha, como mostrado no exemplo de código a seguir:

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

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

Processar eventos de transição da atividade

Quando a transição da atividade solicitada ocorre, seu app recebe um callback de Intent. Um objeto ActivityTransitionResult pode ser extraído do Intent, que inclui uma lista de objetos ActivityTransitionEvent. Os eventos são organizados em ordem cronológica. Por exemplo, se um app solicita o tipo de atividade IN_VEHICLE nas transições ACTIVITY_TRANSITION_ENTER e ACTIVITY_TRANSITION_EXIT, ele recebe um objeto ActivityTransitionEvent quando o usuário começa a dirigir e outro quando o usuário faz a transição para qualquer outra atividade.

Você pode implementar o callback criando uma subclasse de BroadcastReceiver e implementando o método onReceive() para acessar a lista de eventos de transição de atividade. Para mais informações, consulte Visão geral de transmissões. O exemplo a seguir mostra como implementar o método 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....
        }
    }
}

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

É possível cancelar o registro das atualizações de transição de atividade chamando o método removeActivityTransitionUpdates() do ActivityRecognitionClient e transmitindo o objeto PendingIntent como um parâmetro, como mostrado no exemplo a seguir:

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

Outros recursos

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

Exemplos

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