Adicionar elementos relacionados ao chat a um aplicativo Android com as APIs Messaging e People

1. Antes de começar

Criar um aplicativo de mensagens é uma tarefa desafiadora. Embora a experiência geral do usuário seja subjetiva, o Android oferece as APIs Messaging e People, que melhoram e agilizam a experiência do chat.

Neste codelab, você vai aprender como usar essas APIs para criar um ecossistema atraente para aplicativos de chat no Android. Você vai estender o JetChat, um aplicativo de chat básico e não funcional que usa o Jetpack Compose.

Pré-requisitos

• Conhecimento básico de desenvolvimento para Android.
• Conhecimento básico sobre notificações

O que você vai criar

Um app JetChat estendido que faz o seguinte:

• Exibe notificações que representam conversas na seção de conversa reservada da gaveta de notificações.
• Menciona as metas de compartilhamento nessas notificações, que permitem o compartilhamento nas conversas do seu aplicativo.
• Aplica as práticas recomendadas para a criação desses objetos a fim de aproveitar as experiências padrão fornecidas pelo sistema que aprimora seu app.

O que você vai aprender

• Como exibir notificações relacionadas à conversa na seção de conversa reservada da gaveta de notificação.
• Como entender as diversas experiências viabilizadas pelas APIs Messaging e People.

O que é necessário

• Git
• Android Studio
• Uma conta no GitHub

2. Configuração

O ponto de partida é baseado no app JetChat. O código inicial estende o JetChat para mostrar melhor as APIs Messaging e People.

Acessar o código inicial

Para acessar o código inicial desse codelab, siga as etapas abaixo:

1. Na linha de comando, copie o código deste repositório do GitHub:

git clone –branch starter-code \
https://github.com/android/people-messaging-codelab.git

2. Abra o projeto no Android Studio e clique em Executar aplicativo. O painel do Emulador vai aparecer e mostrar o aplicativo.

Conheça a extensão do aplicativo JetChat

1. Na caixa de texto Message #composers, digite uma mensagem e clique em Enviar.
2. Saia do aplicativo. Depois de alguns segundos, você vai receber uma notificação mostrando que há uma resposta no chat.

Observação: a resposta não é de uma pessoa de verdade. O aplicativo é programado para responder simulando a experiência de uma conversa.

3. Crie notificações de conversa

O Android 11 apresentou APIs que permitem que notificações relacionadas a chats apareçam em uma seção específica da gaveta de notificações, que é estritamente para conversas.

A notificação deve ser da classe Notification.MessagingStyle e deve mencionar um atalho de compartilhamento de longa duração. Nesta seção, você vai aprender como preencher esses requisitos de API para exibir essas notificações que representam conversas na seção de conversa.

Para notificar a classe NotificationCompat.MessagingStyle, siga estas etapas:

1. Na guia Projeto do Android Studio, clique em app > java > com.example.compose.jetchat > conversation e depois clique duas vezes em ConversationFragment.
2. No documento ConversationFragment.kt, encontre a classe ConversationFragment, depois o bloco de código Notification da função createNotification onde a notificação é criada.
3. Substitua o método setContentText por um método setStyle que defina o estilo da notificação para a classe NotificationCompat.MessagingStyle. Essa classe auxiliar adiciona a mensagem que foi definida com o método setContextText com contexto adicional relevante para a mensagem, como a hora em que foi enviada e a pessoa que a enviou.

ConversationFragment.kt

private fun createNotification(
   notificationId: Int,
   message: Message,
   person: Person,
   shortcut: ShortcutInfoCompat,
   time: Long
): Notification? {
    ...
    .setStyle(NotificationCompat.MessagingStyle(person).addMessage(
                      NotificationCompat.MessagingStyle.Message(
                          message.content,
                          time,
                          person
                      )
    )
    )
    ...
    .build()
}

Executar o aplicativo

1. Execute o aplicativo.
2. Na caixa de texto Message #composers, digite uma mensagem e clique em Enviar.
3. Saia do aplicativo. Você vai receber uma notificação novamente, mas com um estilo diferente. Desta vez, incluindo um avatar. No entanto, ainda existem etapas a serem concluídas antes de as suas notificações aparecerem onde devem.

4. Crie metas de compartilhamento para conversas

Você precisa mencionar um atalho de compartilhamento ou uma meta de compartilhamento na notificação. Metas de compartilhamento são definidas no documento shortcuts.xml e são os pontos de partida para lidar com os atalhos que são definidos de forma programada. Os atalhos que você cria representam as conversas no app e permitem que você compartilhe conteúdo nas suas conversas.

Observação: você vai criar metas de compartilhamento especificamente para as mensagens recebidas, que são exibidas como notificações no aparelho do usuário. Também podem ser criadas para as mensagens enviadas, mas esse conteúdo não é abordado no codelab. No entanto, as mesmas etapas e amostras de código se aplicam tanto às metas de compartilhamento para mensagens recebidas quanto às mensagens enviadas.

Definir metas de compartilhamento

1. Na guia Projeto, clique com o botão direito do mouse no diretório res e depois selecione Novo > Diretório.
2. Na caixa de texto, digite xml e pressione Enter (ou return no macOS).
3. Clique com o botão direito do mouse no diretório xml e selecione Arquivo.
4. Na caixa de texto, digite shortcuts.xml e pressione Enter (ou return no macOS).
5. No arquivo shortcuts.xml, declare a meta de compartilhamento responsável pelo compartilhamento de dados do tipo text/plain:

shortcuts.xml

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.compose.jetchat.NavActivity">
   <data android:mimeType="text/plain" />
   <category android:name="com.example.compose.jetchat.share.TEXT_SHARE_TARGET" />
 </share-target>
</shortcuts>

6. Na guia Projeto, clique em manifests e depois clique duas vezes em AndroidManifest.xml.
7. No documento AndroidManifest.xml, defina o documento shortcuts.xml:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.compose.jetchat">

   <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/Theme.Jetchat.NoActionBar">
...
 <meta-data android:name="android.app.shortcuts"
            android:resource="@xml/shortcuts" />

    </application>
</manifest>

8. No componente AndroidManifest.xml do documento activity, defina o filtro de intenção que contenha a lógica compartilhada:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.compose.jetchat">

   ...
       <activity
           ...
           <intent-filter>
               <action android:name="android.intent.action.SEND" />
               <category android:name="android.intent.category.DEFAULT" />
               <data android:mimeType="text/plain" />
           </intent-filter>
...

Defina os atalhos

Para cada notificação, você vai precisar associar o atalho relevante. Defina apenas um atalho exclusivo por conversa, porque ele representa o único contato que você quer compartilhar.

Para gerar um atalho, siga estas etapas:

1. Na guia Projeto , clique em app > java > com.example.compose.jetchat > conversation > util e depois clique duas vezes em ConversationUtil.
2. No documento ConversationUtil.kt, adicione uma função generateShortcut:

ConversationUtil.kt

import android.content.Intent
import androidx.core.content.pm.ShortcutInfoCompat
import com.example.compose.jetchat.NavActivity

class ConversationUtil {

   companion object {
...
fun generateShortcut(context: Context, shortcutId: String): ShortcutInfoCompat {
   return ShortcutInfoCompat.Builder(context, shortcutId)
   .setCategories(setOf(CATEGORY_SHARE))
   .setLongLived(true)
   .setShortLabel(shortcutId)
   .setLongLabel(shortcutId)
   .setIntent(
       Intent(context, NavActivity::class.java)
           .setAction(Intent.ACTION_VIEW)
   )
   .build()
}

Esta função contém os métodos setPerson e setLongLived, que são necessários para a conversa. A pessoa é o contato associado ao atalho. Além disso, definir como um valor true de longa duração garante que esse atalho seja armazenado em cache pelo sistema e exibido em várias superfícies na interface do usuário.

Mencionar o atalho na notificação

Observação: metas de compartilhamento publicadas para mensagens enviadas não estão vinculadas a uma notificação porque normalmente não acionam uma notificação para o usuário que envia a mensagem.

Você precisa mencionar o atalho de compartilhamento na notificação. Mas não deixe de criar o atalho antes da notificação.

Para isso, siga estas etapas:

1. No arquivo ConversationFragment.kt, encontre a classe ConversationFragment.
2. Antes da chamada para a variável notification, crie uma variável shortcut que mencione o atalho gerado a partir do ConversationUtil.generateShortcut.
3. No método createNotification da variável notification, substitua null pela variável shortcut como parâmetro.

ConversationFragment.kt

private fun simulateResponseAsANotification() {
   ...
   if (message.author != "me") {
       ...
       val shortcut = ConversationUtil.generateShortcut(context!!, message.author)
       val notification = createNotification(notificationId, message, person, shortcut, time)
       ...
   }
}

4. No método createNotification, adicione o método NotificationCompat.Builder#setShortcutInfo e transmita a variável shortcut como parâmetro.

ConversationFragment.kt

private fun createNotification(
  notificatoinIf: Int,
  messagin: Message,
  person: Person,
  shortcut: ShortcutInfoCompat?,
  time: Long
): Notification {
...
return NotificationCompat.Builder(context!!,  ConversationUtil.CHANNEL_MESSAGES)
   ...
   .setShortcutInfo(shortcut)
   .build()
}

Observação: o método NotificationCompat.Builder#setShortcutInfo também define a classe LocusId no atalho, o que é altamente recomendado. Se você anotar a atividade associada à classe LocusId, enviará sinais à inteligência do dispositivo de que o atalho está associado a essa conversa. Esses sinais são usados para classificar a conversa de maneira adequada, o que garante a exibição correta dela com base na atividade do usuário. Para mais informações, consulte Práticas recomendadas.

Observação: metas de compartilhamento não são exclusividade das conversas, podendo existir fora delas. Para saber mais sobre metas de compartilhamento, consulte API Sharing Shortcuts.

Publicar o atalho

• Para publicar o atalho, na função simulateResponseAsANotification antes do método notificationManager.notify, chame o método pushDynamicShortcut:

ConversationFragment.kt

import androidx.core.content.pm.ShortcutManagerCompat

...private fun simulateResponseAsANotification() {
   ...
   if (message.author != "me") {
       ...
       ShortcutManagerCompat.pushDynamicShortcut(context!!, shortcut)
       ...
   }
}

Observação: há várias formas de publicar uma etapa, mas o método pushDynamicShortcut usa a API de reportShorcutUsed, que é um sinal para a inteligência da máquina de que esse é um contato para compartilhar. O método pushDynamicShortcut também garante que os atalhos sejam atualizados sem a necessidade de lidar com o limite de contagem de atalhos.

Observação: manter pressionada uma notificação MessagingStyle sem um atalho mencionado destaca que ela não oferece suporte a recursos de conversação. Com um atalho mencionado, você pode definir a prioridade e as configurações para essa notificação. Para mais informações, consulte Como testar notificações e atalhos de conversa.

Executar o aplicativo

1. Execute o aplicativo.
2. Na caixa de texto Message #composers, digite uma mensagem e clique em Enviar.
3. Saia do aplicativo. Você vai receber uma notificação novamente, porém mais parecida com a notificação relacionada à conversa. O ícone do avatar é mais nítido e se integra ao ícone do aplicativo. O remetente, a hora e o texto também são mais simplificados.

5. Opcional: permitir balões

Os balões foram introduzidos no Android 9 e aprimorados e reaproveitados para uso no contexto de conversas do Android 11. Eles são sobreposições circulares que servem de avatar para suas conversas, além de aparecerem no iniciador de aplicativos e permitirem que você responda facilmente às conversas em um balão expandido. Mesmo quando implementados, os balões são opcionais dependendo das preferências de usuário.

Para habilitar os balões, siga estas etapas:

1. No arquivo AndroidManifest.xml, adicione o allowEmbedded e os atributos resizeableActivity e depois defina cada um deles para um valor true:

AndroidManifest.xml

<activity
  ...
  android:allowEmbedded="true"
  android:resizeableActivity="true"
  ...
</activity>

2. Na classe ConversationUtil.kt do arquivo ConversationUtil, adicione os metadados do balão:

ConversationUtil.kt

import androidx.core.app.NotificationCompat
import androidx.core.graphics.drawable.IconCompat

fun createBubbleMetadata(context: Context, icon: IconCompat): NotificationCompat.BubbleMetadata {
        // Create bubble intent
        val target = Intent(context, NavActivity::class.java)
        val bubbleIntent = PendingIntent.getActivity(context, REQUEST_BUBBLE, target, flagUpdateCurrent(mutable = true))

        // Create bubble metadata
        return NotificationCompat.BubbleMetadata.Builder(bubbleIntent, icon)
            .setDesiredHeight(400)
            .setSuppressNotification(true)
            .build()
    }

3. No arquivo ConversationFragment.kt, crie e mencione os metadados do balão na notificação:

ConversationFragment.kt

private fun createNotification(
  notificatoinIf: Int,
  messagin: Message,
  person: Person,
  shortcut: ShortcutInfoCompat?,
  time: Long
): Notification {
...
// Reference the bubble metadata in the notification.
  return NotificationCompat.Builder(context!!,     ConversationUtil.CHANNEL_MESSAGES)
    ...
     .setBubbleMetadata(ConversationUtil.createBubbleMetadata(context!!, person.icon!!))
...
    .build()
}

Executar o aplicativo

1. Execute o aplicativo.
2. Na caixa de texto Message #composers, digite uma mensagem e clique em Enviar.
3. Saia do aplicativo. Após alguns segundos, você vai receber uma notificação do chat na forma de um balão.
4. Toque no balão. A conversa vai abrir no balão.

6. Opcional: compartilhar um link

Você declarou metas de compartilhamento e as mencionou em suas notificações, o que também permitiu que seu contato aparecesse na planilha de compartilhamento, um componente ascendente que aparece quando uma intenção ACTION é enviada. As metas de compartilhamento aparecem na parte superior da planilha e permitem que você compartilhe conteúdo avançado em suas conversas.

Para exibir o Sharesheet, siga estas etapas:

1. Em seu dispositivo, abra o Google Chrome e navegue até uma página da Web de sua escolha, como developer.android.com.
2. Se necessário, clique nos três pontos verticais.
3. Clique em Compartilhar. O Sharesheet vai aparecer na parte inferior da tela.

4. Se possível, clique em JetChat. A URL será compartilhada na conversa.
5. Se o JetChat não aparecer, clique em Mais para exibir o sistema Sharesheet, e depois arraste para cima no ShareSheet e clique em JetChat. A URL será compartilhada na conversa.

Este é um exemplo simples. Existem tipos de conteúdo mais avançados para compartilhar. Para mais informações, consulte Como recuperar dados simples de outros apps.

7. Parabéns

Parabéns! Agora você sabe como adicionar recursos relacionados ao chat a um app Android com as APIs Messaging e People. Divirta-se enviando mensagens!

Saiba mais

• Compatibilidade com emoji
• Receber conteúdo avançado
• Classe PeopleManager
• Pessoas e conversas