Use balões para permitir que os usuários participem de conversas

Os balões facilitam a visualização e a participação dos usuários nas conversas.

Figura 1. Um balão de chat.

Os balões são integrados ao sistema de notificações. Eles flutuam sobre o conteúdo de outros apps e seguem o usuário em qualquer tela que ele abra. Os usuários podem expandir os balões para revelar e interagir com o conteúdo do app e podem recolhê-los quando não estiverem usando.

Quando o dispositivo está bloqueado ou a tela está no modo sempre ativada, os balões aparecem como notificações normalmente.

Os balões são um recurso que pode ser desativado. Quando um app apresenta o primeiro balão, uma caixa de diálogo de permissão oferece duas opções:

• Bloquear todos os balões do app. As notificações não são bloqueadas, mas nunca aparecem como balões.
• Permitir todos os balões do app. Todas as notificações enviadas com BubbleMetaData aparecem como balões.

API Bubble

Os balões são criados usando a API de notificação. Envie a notificação normalmente. Se você quiser que a notificação seja exibida como um balão, anexe dados extras a ela.

A exibição expandida de uma bolha é criada a partir de uma atividade escolhida por você. Configure a atividade para ser exibida corretamente como uma bolha. A atividade precisa ser redimensionável e incorporada. Se algum desses requisitos não for atendido, ela será exibida como uma notificação.

O código a seguir demonstra como implementar uma bolha:

<activity
  android:name=".bubbles.BubbleActivity"
  android:theme="@style/AppTheme.NoActionBar"
  android:label="@string/title_activity_bubble"
  android:allowEmbedded="true"
  android:resizeableActivity="true"
/>

Se o app mostrar vários balões do mesmo tipo, como várias conversas de chat com diferentes contatos, a atividade precisa ser capaz de iniciar várias instâncias. Em dispositivos com Android 10 e versões anteriores, as notificações não são mostradas como balões, a menos que você defina documentLaunchMode explicitamente como "always". A partir do Android 11, não é necessário definir explicitamente esse valor, já que o sistema define de forma automática todas as conversas de documentLaunchMode para "always".

Para enviar uma bolha, siga estas etapas:

1. Crie uma notificação como você faz normalmente.
2. Chame BubbleMetadata.Builder(PendingIntent, Icon) ou BubbleMetadata.Builder(String) para criar um objeto BubbleMetadata.
3. Use setBubbleMetadata() para adicionar os metadados à notificação.
4. Se o app for direcionado ao Android 11 ou mais recente, verifique se os metadados ou a notificação do balão fazem referência a um atalho de compartilhamento.
5. Modifique o app para não cancelar notificações que aparecem como balões. Para verificar se a atividade de notificação é iniciada como uma bolha, chame Activity#isLaunchedFromBubble(). O cancelamento de uma notificação remove o balão da tela. Abrir uma bolha esconde automaticamente a notificação associada a ela.

Essas etapas são mostradas no exemplo a seguir:

Kotlin

// Create a bubble intent.
val target = Intent(context, BubbleActivity::class.java)
val bubbleIntent = PendingIntent.getActivity(context, 0, target, 0 /* flags */)
val category = "com.example.category.IMG_SHARE_TARGET"

val chatPartner = Person.Builder()
    .setName("Chat partner")
    .setImportant(true)
    .build()

// Create a sharing shortcut.
val shortcutId = generateShortcutId()
val shortcut =
   ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(setOf(category))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.name)
       .build()

// Create a bubble metadata.
val bubbleData = Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
    .setDesiredHeight(600)
    .build()

// Create a notification, referencing the sharing shortcut.
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setBubbleMetadata(bubbleData)
    .setShortcutId(shortcutId)
    .addPerson(chatPartner)

Java

// Create a bubble intent.
Intent target = new Intent(mContext, BubbleActivity.class);
PendingIntent bubbleIntent =
    PendingIntent.getActivity(mContext, 0, target, 0 /* flags */);

private val CATEGORY_TEXT_SHARE_TARGET =
    "com.example.category.IMG_SHARE_TARGET"

Person chatPartner = new Person.Builder()
        .setName("Chat partner")
        .setImportant(true)
        .build();

// Create a sharing shortcut.
private String shortcutId = generateShortcutId();
ShortcutInfo shortcut =
   new ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(Collections.singleton(CATEGORY_TEXT_SHARE_TARGET))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.getName())
       .build();

// Create a bubble metadata.
Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
        .setDesiredHeight(600)
        .build();

// Create a notification, referencing the sharing shortcut.
Notification.Builder builder =
    new Notification.Builder(mContext, CHANNEL_ID)
        .setContentIntent(contentIntent)
        .setSmallIcon(smallIcon)
        .setBubbleMetadata(bubbleData)
        .setShortcutId(shortcutId)
        .addPerson(chatPartner);

Observação: na primeira vez que você enviar a notificação para mostrar um balão, verifique se ela está em um canal de notificação com IMPORTANCE_MIN ou maior.

Se o app estiver em primeiro plano quando uma bolha for enviada, a importância será ignorada e a bolha será sempre exibida, a menos que o usuário bloqueie bolhas ou notificações do app.

Criar um balão aberto

Você pode configurar sua bolha para que ela seja automaticamente exibida no estado expandido. Recomendamos que esse recurso só seja utilizado se o usuário executar uma ação que resulte na exibição de uma bolha, como tocar em um botão para iniciar um novo bate-papo. Nesse caso, também faz sentido suprimir a notificação inicial enviada quando um balão é criado.

Há métodos que podem ser usados para definir sinalizações que ativem esses comportamentos: setAutoExpandBubble() e setSuppressNotification().

O exemplo a seguir mostra como configurar uma bolha para que ela seja apresentada automaticamente em um estado expandido:

Kotlin

val bubbleMetadata = Notification.BubbleMetadata.Builder()
    .setDesiredHeight(600)
    .setIntent(bubbleIntent)
    .setAutoExpandBubble(true)
    .setSuppressNotification(true)
    .build()

Java

Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder()
        .setDesiredHeight(600)
        .setIntent(bubbleIntent)
        .setAutoExpandBubble(true)
        .setSuppressNotification(true)
        .build();

Ciclo de vida do conteúdo do balão

Quando uma bolha é expandida, a atividade de conteúdo passa pelo ciclo de vida de processo normal, resultando na transformação do aplicativo em um processo em primeiro plano, se esse ainda não for o caso.

Quando o balão é recolhido ou dispensado, a atividade é destruída. Isso pode fazer com que o processo seja armazenado em cache e encerrado mais tarde, dependendo se o app tem outros componentes em primeiro plano em execução.

Quando as bolhas aparecem

Para reduzir as interrupções do usuário, os balões só aparecem em determinadas circunstâncias.

Se um app for direcionado ao Android 11 ou versões mais recentes, uma notificação não aparecerá como um balão a menos que atenda aos requisitos da conversa. Se um app for direcionado ao Android 10 ou versões anteriores, a notificação vai aparecer como um balão somente se uma ou mais das seguintes condições forem atendidas:

• A notificação usa MessagingStyle e tem uma Person adicionada.
• A notificação é de uma chamada para Service.startForeground, tem um category de CATEGORY_CALL e tem um Person adicionado.
• O app está em primeiro plano quando a notificação é enviada.

Se nenhuma dessas condições for atendida, a notificação será exibida em vez de um balão.

Observação: o Android 10 não oferece suporte nativo a bolhas. Para que eles apareçam, ative as Opções do desenvolvedor, procure "bolhas" no menu "Configurações" e ative as configurações de bolhas.

Como iniciar atividades em balões

Quando uma bolha inicia uma nova atividade, ela é iniciada na mesma tarefa e na mesma janela com bolhas ou em uma nova tarefa em tela cheia, reduzindo a bolha que a iniciou.

Para iniciar uma nova atividade na mesma tarefa que a bolha: 1. Use o contexto da atividade ao iniciar intents, activity.startActivity(intent) e 1. Não defina a flag FLAG_ACTIVITY_NEW_TASK na intent.

Caso contrário, a nova atividade será iniciada em uma nova tarefa e a bolha será reduzida.

Lembre-se de que um balão representa uma conversa específica. Portanto, as atividades iniciadas no balão precisam estar relacionadas a essa conversa. Além disso, iniciar uma atividade dentro da bolha aumenta a pilha de tarefas dela e pode complicar a experiência do usuário, principalmente em relação à navegação.

Práticas recomendadas

• Envie uma notificação como balão somente se ela for importante, por exemplo, quando for parte de uma comunicação em andamento ou se o usuário solicitar explicitamente um balão para o conteúdo. Os balões ocupam espaço na tela e cobrem o conteúdo de outros apps.
• Verifique se a notificação em bolha também funciona como uma notificação normal. Quando o usuário desativa o balão, uma notificação de balão é mostrada como uma notificação normal.
• Chame super.onBackPressed ao substituir onBackPressed na atividade do balão. Caso contrário, seu balão pode não se comportar corretamente.

Quando um balão recolhido recebe uma mensagem atualizada, ele exibe um ícone de selo para indicar uma mensagem não lida. Quando o usuário abrir a mensagem no app associado, siga estas etapas:

• Atualize o BubbleMetadata para suprimir a notificação. Chame BubbleMetadata.Builder.setSuppressNotification(). Isso remove o ícone do selo para indicar que o usuário interagiu com a mensagem.
• Defina Notification.Builder.setOnlyAlertOnce() como true para suprimir o som ou a vibração que acompanha a atualização de BubbleMetadata.

App de exemplo

O app de amostra People é um app de conversa que usa balões. Para fins de demonstração, este app usa chatbots. Em aplicativos reais, use balões para mensagens enviadas por humanos.