Usar a API Ongoing Activity para engajar os usuários do Wear OS de novas maneiras

cb2a383284f10acd.gif

Assista à animação acima (demonstração de uma atividade em andamento). Observação: os GIFs são animados apenas uma vez. Se você perdeu a animação, recarregue a página.

No mostrador do relógio, você verá um ícone animado para um timer. Se um usuário tocar no ícone, o app será iniciado, ligando o timer.

Uma atividade em andamento é um novo recurso do Wear OS que permite que uma notificação em andamento seja exibida em outras plataformas na interface do usuário do Wear OS. Isso permite que os usuários fiquem mais engajados com atividades de execução longa.

Notificações em andamento normalmente são usadas para indicar que uma notificação está relacionada a uma tarefa em segundo plano com que o usuário está ativamente engajado (por exemplo, uma música tocando) ou que está pendente de alguma forma e, portanto, ocupando o dispositivo (por exemplo, um download de arquivo, uma operação de sincronização ou uma conexão de rede ativa).

Por exemplo, um usuário do Wear OS pode usar um app de timer para agendar um evento e sair dele para iniciar outra tarefa (ver o clima, iniciar um treino etc.).

Quando o usuário sair do app de timer, o app geralmente passará para uma notificação em andamento vinculada a algum trabalho em segundo plano (serviços, gerenciadores de alarme etc.) para manter o usuário informado sobre quanto tempo resta no timer.

O usuário pode ver a notificação para receber atualizações e interagir com ela.

No entanto, para ver a notificação, o usuário ainda precisa deslizar para a bandeja de notificações abaixo do mostrador do relógio e encontrar a notificação correta, o que não é tão prático quanto em outras plataformas.

Com a API Ongoing Activity, um app pode expor informações para várias plataformas novas e convenientes no Wear OS para manter o usuário engajado.

No caso do app de timer, as informações podem ser exibidas no mostrador do relógio do usuário como um ícone que pode ser tocado (indicador de atividade na parte inferior da captura de tela):

1fc8f1c0d0b5776d.png

O app de timer também pode ser exibido na seção Recentes do Acesso rápido aos apps global, que lista todas as atividades em andamento:

92926c4d6dc3aad5.png

Acesso rápido global

O melhor de tudo é que você só precisa adicionar cerca de 10 linhas de código.

O que você aprenderá

  • Criar e personalizar uma atividade em andamento.
  • Vincular uma atividade em andamento a uma notificação em andamento.
  • Testar uma atividade em andamento em um dispositivo/emulador.
  • Adicionar interação à sua atividade em andamento (toque).

O que você criará

Você estenderá um app de monitoramento de caminhada já existente com uma atividade em andamento personalizada que exibe pontos de caminhada no mostrador do relógio principal para a caminhada ativa e na seção Recentes do Acesso rápido aos apps.

Pré-requisitos

Nesta etapa, você configurará seu ambiente e fará o download de um projeto inicial.

O que é necessário

  • A versão Beta mais recente do Android Studio (Arctic Fox) que inclui a Visualização do desenvolvedor do emulador do Wear OS.
  • Emulador do Wear OS (nível da API 30 ou mais recente).
  • As atividades em andamento estão disponíveis apenas no nível 30 da API ou mais recente.
  • Não conhece os emuladores? Veja como configurá-los neste link.

Fazer o download do código

Se você tiver o git instalado, execute o comando abaixo para clonar o código deste repositório. Para verificar se o git está instalado, digite git --version no terminal ou na linha de comando e verifique se ele é executado corretamente.

git clone https://github.com/googlecodelabs/ongoing-activity.git
cd ongoing-activity

Caso você não tenha o git, clique no botão abaixo para fazer o download de todo o código para este codelab:

Fazer o download do ZIP

Você pode executar qualquer um dos módulos no Android Studio a qualquer momento alterando a configuração de execução na barra de ferramentas.

8a2e49d6d6d2609d.png

Abrir o projeto no Android Studio

  1. Na janela "Welcome to Android Studio", selecione 1f5145c42df4129a.png Open an Existing Project.
  2. Selecione a pasta [Download Location]
  3. Depois que o Android Studio importar o projeto, teste se você pode executar os módulos start e finished em um emulador ou dispositivo físico do Wear OS.
  4. O módulo start será parecido com a captura de tela abaixo. É nele que você fará todo o trabalho.

a3817357e22438af.png

Teste o app iniciando um treino de caminhada. Você começará a ganhar pontos a cada 3 segundos, mais ou menos. O app usa dados simulados para que você não precise realmente caminhar.

Tente sair do app. Se você navegar na bandeja de navegação abaixo do mostrador do relógio, encontrará a notificação em andamento que continua rastreando seus pontos de caminhada.

Ao tocar nela, o resultado será semelhante a este:

990814a9f59a510a.png

ac59318b7243c403.png

Você pode parar a caminhada.

No final deste codelab, as mesmas informações de caminhada serão exibidas no mostrador do relógio e na seção Recentes do Acesso rápido aos apps global.

App exibido no mostrador do relógio (veja o Indicador de atividade na parte inferior):

61112a8afe935eb5.png

App exibido na seção Recentes do Acesso rápido aos apps:

717a9825221a8f86.png

Conhecer o código inicial

No módulo start:

  • build.gradle contém uma configuração básica de app. Inclui as dependências necessárias para criar uma atividade em andamento.
  • manifest > AndroidManifest.xml inclui as partes necessárias para marcar o item como um app do Wear OS.
  • java > ... > data > WalkingWorkoutsRepository.kt vincula-se à classe WalkingWorkoutsDataStore.kt para armazenar pontos de caminhada e status de um treino de caminhada. Não se preocupe com os detalhes. Não será necessário revisar essas classes neste codelab.
  • java > ... > MainApplication.kt cria um Singleton do repositório. Não se preocupe com os detalhes. Não será necessário revisar essas classes neste codelab.
  • java > ... > ForegroundOnlyWalkingWorkoutService.kt contém o código para iniciar e interromper um treino de caminhada. Se um treino estiver ativo e o usuário sair do app, ele será desvinculado da atividade e iniciará uma notificação em andamento para manter o usuário informado sobre os pontos de treino (usando dados simulados). Adicionaremos o código da atividade em andamento aqui (próximo ao código de notificação).
  • java > ... > MainActivity.kt contém uma IU para que o usuário inicie/interrompa um treino de caminhada. A atividade é vinculada ao serviço acima para permitir o gerenciamento de todas as tarefas de treino.
  • java > ... > MainViewModel.kt é um ViewModel simples para lidar com código que não é da IU em MainActivity.kt. Não se preocupe com os detalhes. Não será necessário revisar essas classes neste codelab.

O app já oferece funcionalidades de treino de caminhada.

Como você viu nas etapas anteriores, pode abrir o app e iniciar/parar um treino de caminhada. Conforme o tempo passa durante um treino ativo, você acumula pontos de caminhada.

Os pontos são redefinidos para cada nova caminhada.

Se sair do app durante um treino ativo, poderá deslizar para baixo para ver uma notificação em andamento que atualizará você sobre seu progresso.

Na notificação, você pode interromper o treino ou abrir o app.

Normalmente, você calcularia os pontos de caminhada usando os dados de localização e do sensor com um algoritmo próprio. No nosso caso, estamos apenas simulando os dados para simplificar.

Como funciona?

A MainActivity cria a interface do usuário e vincula-se a um serviço e também a um ViewModel para receber atualizações sobre status do treino / pontos de caminhada.

Quando um treino for iniciado ou interrompido, a MainActivity chamará um método de início ou parada equivalente no serviço para gerenciar o trabalho pesado de monitorar o treino.

Se o usuário sair do app, a MainActivity será desvinculada do serviço.

A maior parte do trabalho é realizada no ForegroundOnlyWalkingWorkoutService. Essa é a classe que inicia/interrompe os treinos e salva as alterações feitas no status ou nos pontos de caminhada no repositório.

O serviço também faz a transição para um serviço em primeiro plano e se vincula a uma notificação em andamento caso o usuário saia da MainActivity durante uma sessão.

A notificação em andamento continua o trabalho de monitorar um treino e é vinculada ao serviço acima como um serviço em primeiro plano.

Não se preocupe se você não compreender todos os detalhes. O importante é entender que esse é um app funcional com a notificação já criada para ele. Só queremos estender essa notificação para torná-la visível em mais plataformas usando uma atividade em andamento.

Esse código de notificação fica no ForegroundOnlyWalkingWorkoutService, e é nele que você fará todo o trabalho para este codelab.

Analisar as dependências

Nesta etapa, não faremos nenhuma programação. Apenas analisaremos as dependências da atividade em andamento.

Abra o arquivo app/build.gradle no módulo start e procure por "TODO: Review dependencies for Ongoing Activity".

Você verá isto:

Etapa 1

    // TODO: Review dependencies for Ongoing Activity.
    implementation "androidx.wear:wear-ongoing:1.0.0-beta01"
    // Includes LocusIdCompat and new Notification categories for Ongoing Activity.
    implementation "androidx.core:core-ktx:1.6.0"

A primeira dependência é necessária para usar a API Ongoing Activity do Wear OS.

A segunda dependência é para extrair os recursos mais recentes das APIs de notificação compatíveis com vários recursos usados em conjunto com uma atividade em andamento. Os dois recursos a seguir podem ser aplicados a notificações em andamento e, portanto, também a atividades em andamento:

  • Categoria: o Android usa algumas categorias predefinidas do sistema para determinar se o usuário receberá uma notificação específica quando ele ativar o modo Não perturbe. A categoria determina a prioridade da atividade em andamento no mostrador do relógio. Novas categorias foram adicionadas recentemente para serem compatíveis com o Wear.
  • LocusId: o Locus é um novo conceito introduzido no Android 10 (nível 29 da API) e permite ao sistema Android correlacionar o estado entre diferentes subsistemas, como captura de conteúdo, atalhos e notificações. Se você tiver vários acessos rápidos, poderá usar o ID do locus para vincular a atividade em andamento a um Shortcut dinâmico específico, para que ele seja exibido corretamente na seção Recentes do Acesso rápido aos apps.

Analisar o código de notificação em andamento

Nesta etapa, não faremos nenhuma programação. Em vez disso, analisaremos o código de notificação.

Abra o arquivo ForegroundOnlyWalkingWorkoutService.kt no módulo start e procure por "TODO: Review Notification builder code".

Você verá isto:

Etapa 2

// TODO: Review Notification builder code.
val notificationBuilder = notificationCompatBuilder
    .setStyle(bigTextStyle)
    .setContentTitle(titleText)
    .setContentText(mainText)
    .setSmallIcon(R.mipmap.ic_launcher)
    .setDefaults(NotificationCompat.DEFAULT_ALL)
    // Makes Notification an Ongoing Notification (a Notification with a background task).
    .setOngoing(true)
    // Android uses some pre-defined system-wide categories to determine whether to
    // disturb the user with a given notification when the user has enabled Do Not Disturb
    // mode. The Category determines the priority of the Ongoing Activity and new
    // categories were added recently to support Wear
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .addAction(
        R.drawable.ic_walk, getString(R.string.launch_activity),
        activityPendingIntent
    )
    .addAction(
        R.drawable.ic_cancel,
        getString(R.string.stop_walking_workout_notification_text),
        servicePendingIntent
    )

// TODO: Create an Ongoing Activity.
// SKIP TODO FOR REVIEW STEP

return notificationBuilder.build()

Analise o código acima e leia os comentários (pule a seção TODO ao final, que será usada em uma etapa posterior).

Há muito mais código de notificação acima desse bloco que configura tudo para esse builder.

No entanto, neste codelab, precisamos nos concentrar na chamada setOngoing() e em setCategory() no builder de notificações.

A categoria ajuda o Wear OS a determinar a prioridade da notificação para o mostrador do relógio.

A chamada setOngoing() transforma nossa notificação em uma notificação em andamento, ou seja, uma notificação com uma tarefa em segundo plano com que o usuário está ativamente envolvido, por exemplo, monitorando um treino de caminhada.

Criamos essa notificação quando o usuário tem um treino de caminhada ativo e sai da MainActivity.

Criar uma atividade em andamento

Uma atividade em andamento precisa estar vinculada a uma notificação em andamento. Agora que temos uma notificação em andamento, vamos criar uma atividade em andamento.

Procure "TODO: Add Ongoing Activity variable" e substitua a linha "// SKIP TODO FOR REVIEW STEP" pelo código abaixo.

Etapa 4

        // TODO: Create an Ongoing Activity.
        val ongoingActivityStatus = Status.Builder()
            // Sets the text used across various surfaces.
            .addTemplate(mainText)
            .build()

        val ongoingActivity =
            OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
                // Sets icon that will appear on the watch face in active mode. If it isn't set,
                // the watch face will use the static icon in active mode.
                // Supported animated icon types: AVD and AnimationDrawable.
                .setAnimatedIcon(R.drawable.animated_walk)
                // Sets the icon that will appear on the watch face in ambient mode.
                // Falls back to Notification's smallIcon if not set. If neither is set,
                // an Exception is thrown.
                .setStaticIcon(R.drawable.ic_walk)
                // Sets the tap/touch event, so users can re-enter your app from the
                // other surfaces.
                // Falls back to Notification's contentIntent if not set. If neither is set,
                // an Exception is thrown.
                .setTouchIntent(activityPendingIntent)
                // In our case, sets the text used for the Ongoing Activity (more options are
                // available for timers and stop watches).
                .setStatus(ongoingActivityStatus)
                .build()

        // Applies any Ongoing Activity updates to the notification builder.
        // This method should always be called right before you build your notification,
        // since an Ongoing Activity doesn't hold references to the context.
        ongoingActivity.apply(applicationContext)

Antes de criar uma atividade em andamento, primeiro crie um Status para ela que inclua o texto que será exibido nas várias plataformas do Wear OS.

Definiremos o texto usando .addTemplate() no Status.Builder com o mesmo texto principal que usaremos para a notificação.

Você pode personalizar a aparência do texto (especificar cores, negrito etc.), mas manteremos o texto simples neste codelab. Para saber mais, leia o Guia de atividades em andamento.

Em seguida, criaremos a OngoingActivity. Transmitiremos o contexto, um código de notificação e o builder de notificações que criamos acima desse código para o construtor de OngoingActivity.Builder().

O ID da notificação e a instância do NotificationCompat.Builder são importantes para vincular a OngoingActivity à notificação em andamento.

Primeiro, definiremos um ícone animado, para o mostrador do relógio no modo ativo, e um ícone estático, para o mostrador do relógio no modo ambiente.

Em seguida, definiremos um evento de toque e, por fim, o texto usando o objeto Status que criamos antes de fechar a instrução com .build().

A interface do usuário da OngoingActivity é fornecida usando o ícone e o texto do Status. O evento de toque permite que o usuário toque novamente no app no mostrador do relógio ou na seção Recentes do Acesso rápido aos apps global.

Por fim, chamamos apply() na atividade em andamento e transmitimos o contexto. Essa é a etapa final que aplica as alterações na atividade em andamento ao builder de notificações.

Pronto, acabamos!

Quando o notificationManager.notify(NOTIFICATION_ID, notification) for chamado com essa notificação, ele aparecerá nas novas plataformas.

Agora, execute o app no novo emulador ou dispositivo Wear OS.

Inicie uma caminhada no app e deslize para sair dele.

No mostrador do relógio, você verá um pequeno ícone de uma pessoa caminhando como este, mas animado:

61112a8afe935eb5.png

Ao tocar no ícone, você voltará ao app.

Saia do app novamente e toque no botão do Acesso rápido aos apps no dispositivo Wear OS.

Você verá algo semelhante a isto:

717a9825221a8f86.png

Se você clicar no app de caminhada na seção Recentes, voltará ao app.

Parabéns! Você aprendeu a criar uma atividade em andamento no Wear OS.

As atividades em andamento são uma ótima maneira de manter o engajamento dos usuários em novas plataformas do Wear.

Qual é a próxima etapa?

Confira os outros codelabs do Wear OS:

Leia mais