1. Introdução
Metas
Neste codelab, você aprenderá a instrumentar seu app multiplataforma para fazer multicast de mensagens push para vários subgrupos das instâncias do app usando tópicos do FCM.
Quando terminar, você poderá usar a infraestrutura do FCM para gerenciar esses subgrupos, além de usar as mensagens push multicast nos subgrupos.
Visão geral dos tópicos
Os tópicos são uma maneira suportada pela infraestrutura do FCM de alcançar subgrupos das instâncias do seu app com mensagens.
O FCM fornece as APIs para enviar mensagens e manter inscrições nesses tópicos. O ato de associar e dissociar uma instância de app do tópico é chamado de assinar e cancelar inscrição, respectivamente
Os tópicos devem ser usados para conteúdo disponível publicamente. Por exemplo, mensagens sobre atualizações meteorológicas. Se você quiser enviar mensagens sensíveis aos usuários, use o SDK Admin do Firebase para multicast de mensagens em vários dispositivos.
O multicasting baseado em tópicos é otimizado para capacidade de processamento.
O que você aprenderá
- Como inscrever usuários (e cancelar a inscrição) em tópicos usando um app para dispositivos móveis.
- Como enviar mensagens push multicast usando tópicos.
- Como enviar mensagens para uma combinação de tópicos usando as condições do tema.
- Como gerenciar inscrições em tópicos no lado do servidor e fazer assinaturas e cancelamentos de inscrições em massa.
O que você vai criar
- Um app Android que se inscreve/cancela a inscrição em tópicos e recebe mensagens quando enviados a eles.
- Uma integração do lado do servidor usando o SDK Admin do Firebase, que será usado para enviar mensagens de tópicos pelas APIs do FCM.
O que é necessário
- Um navegador da sua escolha, como o Chrome
- IDE IntelliJ IDEA para desenvolver aplicativos Java.
- Ative a compatibilidade com o Gradle durante a instalação.
- Ambiente de desenvolvimento integrado do Android Studio para desenvolvimento de apps Android.
- Um dispositivo para executar o aplicativo Android. Uma das seguintes opções:
- O Android Emulator. Isso requer configuração no Android Studio.
- Um dispositivo Android físico conectado ao computador e configurado para o modo de desenvolvedor.
- Uma Conta do Google para criar e gerenciar seu projeto do Firebase.
2. Etapas da configuração
Buscar o código
Clone o repositório do GitHub na linha de comando:
git clone https://github.com/firebase/quickstart-android.git fcm-codelab
O exemplo de código será clonado no diretório fcm-codelab
.
cd fcm-codelab
O app inicial deste codelab está no diretório messaging
da ramificação fcm-topics-codelab
. Siga as etapas abaixo para chegar ao código inicial. Ele contém dois diretórios, StockNewsApp
e StockNewsServer
. O primeiro contém o app Android inicial e o segundo tem o código inicial do lado do servidor.
git checkout fcm-topics-codelab cd messaging/fcm-topics-codelab/starter
A versão concluída deste codelab é colocada no diretório messaging/fcm-topics-codelab/completed
.
criar um projeto do Firebase
- No Console do Firebase, clique em Adicionar projeto, nomeie o projeto do Firebase como StockNews e clique em continuar. Observação: lembre-se do ID do seu projeto do Firebase ou clique no ícone Editar para definir o ID de sua preferência.
- Você pode pular a ativação do Google Analytics. Para os fins deste codelab, você não precisa dele. Clique em Continuar.
- Clique em Criar projeto.
Parabéns! Você acabou de criar seu projeto do Firebase. Agora, clique no nome do projeto para acessar o console.
3. Configuração do app Firebase específica da plataforma
A maioria das alterações de código necessárias para ativar o suporte do Firebase já foi feita no projeto em que você está trabalhando. No entanto, para adicionar suporte a plataformas móveis, você precisa:
- Registrar a plataforma desejada no projeto do Firebase
- Faça o download do arquivo de configuração específico da plataforma e adicione-o ao código.
Neste codelab, vamos adicionar um app Android do Firebase.
Configurar o Android
- No console do Firebase, selecione Configurações do projeto na parte superior da barra de navegação à esquerda, na engrenagem de configurações, e clique no ícone do Android em Seus apps na página Geral.
Você verá a seguinte caixa de diálogo :
- O valor importante que será fornecido é o nome do pacote Android. Defina-o como
com.ticker.stocknews
.- O nome do pacote informado precisa ser o mesmo informado no
AndroidManifest.xml
do código inicial do StockNewsApp. Para localizá-lo ou alterá-lo, siga estas etapas:- No diretório StockNewsApp, abra o arquivo
app/src/main/AndroidManifest.xml
. - No elemento
manifest
, encontre o valor de string do atributopackage
. Esse valor é o nome do pacote Android.
- No diretório StockNewsApp, abra o arquivo
- O nome do pacote informado precisa ser o mesmo informado no
- Na caixa de diálogo do Firebase, cole o nome do pacote copiado no campo Nome do pacote Android.
- O Certificado de assinatura de depuração SHA-1 não é necessário para este codelab porque este app não será lançado. Deixe em branco.
- Clique em Registrar app.
- Ainda no Console do Firebase, siga as instruções para fazer o download do arquivo de configuração
google-services.json
. - Você pode pular as outras etapas de configuração, já que tudo o mais já está definido no código inicial do app. Você encontrará seu app listado na página principal do Console do Firebase.
- Copie o arquivo
google-services.json
que você acabou de transferir por download para o diretóriomessaging/fcm-topics-codelab/starter/StockNewsApp/app
.
4. Criar e executar seu app
Você já pode começar a trabalhar no seu app. Primeiro, crie e execute o app.
Importar o app inicial
Inicie o Android Studio e importe o messaging/fcm-topics-codelab/starter/StockNewsApp
do diretório do código inicial.
Após o carregamento do projeto, talvez você também veja um alerta informando que o Git não está rastreando todas as alterações locais. Clique em "Ignorar" ou em "X" no canto superior direito. Você não enviará alterações de volta ao repositório Git.
No canto superior esquerdo da janela do projeto, você verá algo parecido com a imagem abaixo se estiver na visualização Android. Se você estiver na visualização Project, precisará expandir o projeto para ver a mesma coisa.
O Android Studio pode levar alguns segundos para compilar o projeto em segundo plano pela primeira vez. Durante esse período, você vai notar um ícone de carregamento na barra de status na parte de baixo do Android Studio:
Recomendamos que você aguarde a conclusão desse processo antes de fazer alterações no código. Isso permitirá que o Android Studio extraia todos os componentes necessários.
Além disso, se você receber a mensagem "Reload for language changes to take apply?" (Recarregar para que as mudanças de idioma entrem em vigor?" ou algo semelhante), selecione "Yes" (Sim).
Configuração do emulador
Se você precisar de ajuda para configurar um Android Emulator, consulte o artigo Executar o app.
Entender o código inicial do app Android
- O código inicial é um app Android leve com funcionalidade e interface mínimas.
- Uma dependência do SDK do firebase-messaging já foi adicionada ao arquivo
app/build.gradle
.
- No
AndroidManifest.xml
, um gerenciador de callbackMESSAGING_EVENT
já foi adicionado.- Esse gerenciador,
StockNewsMessagingService.java
, estende a classeFirebaseMessagingService
, que fornece várias funcionalidades relacionadas ao Firebase Cloud Messaging. Consulte a documentação do FirebaseMessagingService para saber mais.
- A função
onNewToken
é chamada quando o token de registro do FCM é criado ou atualizado. Consulte Monitorar a geração de tokens para mais informações. - A função
onMessageReceived
é chamada quando uma mensagem é recebida e o app está em primeiro plano. No momento, ela apenas registra a mensagem recebida.- Consulte Receber mensagens em um app Android para saber mais sobre as diferenças entre entrega e processamento de mensagens em primeiro e segundo plano.
- Esse gerenciador,
- Além disso, em
AndroidManifest.xml
, uma classeApplication
do Android (link em inglês) também é fornecida com o nomeStockNewsApplication
.- Essa classe será a primeira a ser instanciada quando o app for iniciado.
- Na função
onCreate
da classeStockNewsApplication
, é adicionada uma chamada de criação do token de registro do FCM. Isso gera e registra um token de registro do FCM válido.
- O
MainActivity.java
adiciona aRecyclerView
que mostra as opções da categoria de estoque. - O
SubscriptionAdapter.java
implementa oRecyclerView.Adapter
, que desenha a tela de seleção da categoria de estoque.- Cada categoria de ações tem um nome e um botão de alternância de assinatura ao lado.
- Alterar o botão deve fazer uma chamada de assinatura / cancelamento de assinatura de tópicos do FCM.
- Você vai implementar essas chamadas nas próximas seções.
- A classe
model/StockCategories.java
contém uma lista de todas as categorias de estoque e os nomes dos tópicos associados.
Executar o app inicial
- Conecte o dispositivo Android ao computador ou inicie um emulador.
- Na barra de ferramentas de cima, selecione o dispositivo ou emulador Android de destino e pressione o botão "Executar".
- A interface do app vai ficar assim:
- O app criará e registrará um token de registro do FCM. No entanto, nada vai mudar na interface do app.
- Copie e salve o token de registro do FCM, porque ele será usado nas próximas etapas.
5. Enviar uma mensagem de teste
Agora está tudo pronto para enviar uma mensagem de teste à instância do app configurada na última etapa.
Importar o código do servidor inicial
Inicie o IntelliJ IDEA e abra o projeto messaging/fcm-topics-codelab/starter/StockNewsServer
.
A visualização do projeto na barra de navegação esquerda será parecida com esta:
Pode levar alguns minutos para o IntellIj IDEA criar seu projeto, incluindo a extração das dependências necessárias.
Entender o código inicial do servidor
- O código inicial do servidor é um projeto Java baseado no Gradle.
- O arquivo
build.gradle
já tem a dependência do SDK firebase-admin adicionada a ele. Esse SDK fornece acesso a várias funcionalidades de envio de mensagens do FCM.
- Por fim, há duas classes, a viz:
FcmSender.java
: essa classe contém os seguintes métodos importantes:initFirebaseSDK
: inicializa o SDK firebase-admin.sendMessageToFcmRegistrationToken
: envia uma mensagem para um token de registro do FCM.sendMessageToFcmTopic
: envia uma mensagem para um tópico do FCM.sendMessageToFcmTopicCondition
: envia uma mensagem para uma condição de tópico do FCM.
FcmSubscriptionManager.java
: essa classe contém métodos que permitem gerenciar inscrições em tópicos do lado do servidor.initFirebaseSDK
: inicializa o SDK firebase-admin.subscribeFcmRegistrationTokensToTopic
: inscrever tokens de registro do FCM em um tópico do FCM.unsubscribeFcmRegistrationTokensFromTopic
: cancele a inscrição dos tokens de registro do FCM em um tópico do FCM.
Configurar o código do servidor
- Primeiro, precisamos configurar uma conta de serviço do Firebase que permita ao SDK firebase-admin autorizar chamadas às APIs do FCM.
- Acesse o console do Firebase, clique no ícone de engrenagem ao lado de Visão geral do projeto na barra de navegação à esquerda e selecione Configurações do projeto.
- Na página de configurações, selecione Contas de serviço e clique em Criar conta de serviço.
- Clique no botão Gerar nova chave privada para fazer o download automático do arquivo de chave.
- Renomeie o arquivo de chave como
service-account.json
e copie-o na pastamessaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
. - Tanto o
FcmSender.java
quanto oFcmSubscriptionManager.java
carregam o arquivoservice-account.json
do caminho de classe usando o código a seguir.
- Nesse ponto, o código do servidor está pronto. Execute "Build -> Build Project" na barra de menus da parte de cima.
Como enviar uma mensagem de teste
- Em
FcmSender.java
, localize a funçãosendMessageToFcmRegistrationToken
e insira o token de registro do FCM que você copiou da seção Executar o app inicial no camporegistrationToken
. - Na função
main
, remova a marca de comentário apenas da funçãosendMessageToFcmRegistrationToken
e clique em "Executar" para executar o código.- Observe como o token de registro do FCM é definido no campo
Token
do objetomessage
. - Além disso, observe como usamos a API
send
da interfaceFirebaseMessaging
.
- Observe como o token de registro do FCM é definido no campo
- Uma mensagem será enviada para a instância do app que você configurou na etapa anterior.
- Quando a instância do app está em primeiro plano, o conteúdo da mensagem é registrado.
- Quando a instância do app está em segundo plano, a mensagem aparece na bandeja de notificações.
Ótimo! Você usou o SDK Admin do Firebase para enviar mensagens a uma instância do app. Leia mais sobre como usar o SDK Admin do Firebase no seu servidor.
6. Implementar assinatura / cancelamento de assinatura de tópicos
Nesta etapa, você vai implementar ações de assinatura e cancelamento de assinatura de tópicos no botão de alternância "Categoria de estoque" do app Android.
Quando um usuário do app alterna a chave de uma categoria de estoque específica, uma chamada de assinatura ou cancelamento da assinatura do tópico é feita.
Revisar código
- Navegue até a classe
SubscriptionAdapter.java
no código do app Android e encontre a classeRecyclerViewViewHolder
.
- O construtor de classe configura um listener para a alternância de assinatura usando
setOnCheckedChangeListener
. - Dependendo da alternância de alternância, as ações de inscrição e cancelamento são realizadas chamando os métodos
subscribeToStockCategory
eunsubscribeFromStockCategory
, respectivamente. - O método
setData
é chamado peloonBindViewHolder
do adaptador RecyclerView para vincular o ViewHolder à categoria de estoque adequada.
Implementar a assinatura de tópicos
- No método
subscribeToStockCategory
, você vai implementar a chamada para a APIsubscribeToTopic
do objetoFirebaseMessaging
. O código ficaria mais ou menos assim:
void subscribeToStockCategory() { // Making call to FCM for subscribing to the topic for stockCategory FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener( unused -> { // Subscribing action successful Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName()); Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(), Toast.LENGTH_SHORT).show(); }); }
Implementar o cancelamento da assinatura do tópico
- Da mesma forma, na condição else, você implementará a chamada para a API
unsubscribeFromTopic
. Algo como o seguinte:
void unsubscribeFromStockCategory() { // Making call to FCM for unsubscribing from the topic for stockCategory FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName()) .addOnSuccessListener(unused -> { // Unsubscribing action successful Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName()); Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(), Toast.LENGTH_SHORT).show(); }); }
Vamos fazer um teste
- Execute o app e alterne as opções de categoria de estoque para executar as ações de assinatura e cancelamento de assinatura. Ele será parecido com:
Inscreva-se | Cancelar inscrição |
7. Como enviar sua primeira mensagem de tópico
Nesta etapa, você vai implementar um código do lado do servidor para enviar uma mensagem de tópico do FCM.
Implementar a integração do lado do servidor para enviar mensagens de tópico
- No código do servidor, acesse
FcmSender.java
e localize o métodosendMessageToFcmTopic
.
- Na primeira linha, forneça o tópico do FCM para o qual deseja enviar a mensagem.
- É uma string no formato:
/topics/<Topic Name>
. Por exemplo,/topics/Technology
.
- É uma string no formato:
- Nas próximas linhas, crie um novo objeto
message
(semelhante ao definido na funçãosendMessageToFcmRegistrationToken
).- A diferença será que, em vez de definir o campo
Token
do objetomessage
, você definirá o campoTopic
.
- A diferença será que, em vez de definir o campo
Message message = Message.builder() .putData("FOOTECH", "$1000") .setNotification( Notification.builder() .setTitle("Investor confidence in Tech Stocks growing") .setBody("Foo Tech leading the way in stock growth for Tech sector.") .build()) .setTopic(topicName) .build();
- Agora, adicione a chamada à instância
FirebaseMessaging
para enviar a mensagem (idêntica à chamada de envio feita na funçãosendMessageToFcmRegistrationToken
).
FirebaseMessaging.getInstance().send(message);
- Por fim, atualize a função
main
e ative a chamada apenas para a funçãosendMessageToFcmTopic
.
Enviar mensagem e validar confirmação
- Antes de enviar a mensagem de tópico, verifique se a instância do seu aplicativo está inscrita no tópico que você deseja enviar.
- Para isso, basta alternar o botão de alternância correspondente. Exemplo:
- Agora você pode enviar sua mensagem de tópico executando a função
main
deFcmSender.java
. - Como antes, você poderá observar a confirmação da mensagem na instância do aplicativo.
- Instância do app em primeiro plano
- Instância do app em segundo plano
- Bônus: tente cancelar a inscrição no tópico para o qual você enviou e reenviar a mensagem. Você observaria que a mensagem não está sendo entregue à instância do app.
8. Como enviar sua primeira mensagem de condição de tópico
O recurso de condição do tópico permite que você envie mensagens para uma combinação de tópicos, o que permite fornecer uma definição de público-alvo mais expressiva.
Por exemplo, no app StockNews, considere a possibilidade de enviar mensagens para um grupo de instâncias de apps inscritas nos tópicos "Tecnologia" ou "Automotivo". Isso pode ocorrer, por exemplo, se houver um evento importante envolvendo o Waymo.
Com a API Topics, é possível expressar sua combinação na forma de uma expressão booleana usando os operadores abaixo
- && : AND lógico. Por exemplo,
'Technology' in topics && 'Automotive' in topics
: segmenta apenas as instâncias de apps que estão inscritas nos tópicos "Tecnologia" e "Automotivo". - || : OR lógico. Por exemplo,
'Technology' in topics || 'Automotive' in topics
: segmenta instâncias de apps inscritas nos tópicos "Tecnologia" ou "Automotivo". - () : parênteses para agrupamento. Por exemplo,
'Technology' in topics && ('Automotive' in topics || 'Energy' in topics)
: segmenta apenas instâncias de apps inscritas nos tópicos "Tecnologia" e "Automotivo" ou "Energia".
Leia mais sobre como criar solicitações de envio para usar essa funcionalidade.
Implementar a integração do lado do servidor para enviar mensagens de condição de tópico
- De volta ao código do servidor, vá para
FcmSender.java
e localize o métodosendMessageToFcmTopicCondition
.
- Na primeira linha, para a variável
topicCondition
, forneça a condição do tópico para onde você quer enviar a mensagem. Ele pode ser definido como:'Technology' in topics && 'Automotive' in topics
. - Nas próximas linhas, crie um novo objeto
message
(semelhante ao definido na funçãosendMessageToFcmTopic
).- A diferença será que, em vez de definir o campo
Topic
do objeto, você definirá o campoCondition
.
- A diferença será que, em vez de definir o campo
Message message = Message.builder() .putData("FOOCAR", "$500") .setNotification( Notification.builder() .setTitle("Foo Car shows strong Q2 results") .setBody("Foo Car crosses 1B miles. Stocks rally.") .build()) .setCondition(topicCondition) .build();
- Agora, adicione a chamada à instância
FirebaseMessaging
para enviar a mensagem (idêntica à chamada de envio feita na funçãosendMessageToFcmTopic
).
FirebaseMessaging.getInstance().send(message);
- Por fim, atualize a função
main
e ative a chamada apenas para a funçãosendMessageToFcmTopicCondition
.
Enviar a mensagem e validar a confirmação
- Antes de enviar a mensagem de tópico, certifique-se de que a instância do app satisfaça à condição do tópico especificada assinando a instância do app nos tópicos "Tecnologia" e "Automotivo".
- Agora você pode enviar sua mensagem de tópico executando a função
main
deFcmSender.java
. - Como antes, a confirmação da mensagem deve estar visível na instância do aplicativo.
- Instância do app em primeiro plano
- Instância do app em segundo plano
- Bônus: agora você pode cancelar a inscrição no tópico "Tecnologia" e reenviar a mensagem de condição do tópico. A mensagem não é recebida pela instância do app.
9. Recapitulação
Vamos fazer um resumo rápido do que você aprendeu até agora.
- Como iniciar uma assinatura / cancelamento de assinatura de um tópico em uma instância de app.
- Enviar uma mensagem para o tópico e verificar o recebimento em instâncias de apps inscritas.
- Enviar uma mensagem para uma condição de tópico e verificar o recebimento em uma instância de app que atende à condição.
Na próxima seção, você vai aprender a fazer / cancelar a inscrição de instâncias de apps em tópicos sem precisar instanciar chamadas do lado do cliente.
10. Gerenciar assinaturas de tópicos do lado do servidor
Até agora, neste codelab, todas as chamadas de assinatura e cancelamento de assinatura de tópicos eram iniciadas de uma instância de app.
No entanto, em alguns casos de uso, é possível gerenciar as assinaturas de tópicos no lado do servidor. Por exemplo, talvez você queira inscrever um subgrupo da sua base de usuários atual em um novo tópico sem esperar o lançamento de um app.
Nesta seção, você vai aprender a usar o SDK Admin do Firebase para fazer chamadas do servidor e fazer e cancelar a inscrição de um lote de tokens de registro do FCM em um tópico.
Implementar a assinatura de tokens de registro do FCM no tópico do FCM
- No código do servidor, acesse a classe
FcmSubscriptionManager.java
. Localize o métodosubscribeFcmRegistrationTokensToTopic
. Você implementará a chamada para a APIsubscribeToTopic
aqui.
- Vamos fazer a inscrição da instância do app no tópico Energia. Para isso, primeiro forneça dados para estes dois campos:
registrationTokens
: uma lista de strings separadas por vírgulas que representam os tokens de registro do FCM para os quais você quer criar inscrições em tópicos.topicName
: o nome do tópico Energia, ou seja,/topics/Energy
.
- Nas próximas linhas, implemente a chamada:
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic( registrationTokens, topicName);
- Você pode inspecionar
TopicManagementResponse
para ver algumas estatísticas de resultados de alto nível. Por exemplo, ao imprimir o número de assinaturas de tópicos criadas usandogetSuccessCount
.
System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
- Por fim, na função
main
, ative chamadas apenas para a funçãosubscribeFcmRegistrationTokensToTopic
.
Criar uma assinatura e enviar uma mensagem de tópico
- Agora, você está pronto para criar a assinatura do tópico e enviar uma mensagem para ela.
- Execute a função
main
da classeFcmSubscriptionManager.java
. Isso vai criar uma assinatura de tópico. - Agora, configure o código para enviar a mensagem. Assim como antes,
- Em
FcmSender.java
, localize a funçãosendMessageToFcmTopic
. - Defina o
topicName
como o tópico Energia, ou seja,/topics/Energy
. - Crie um objeto
Message
e direcione-o ao tópico usandosetTopic
. - Por fim, atualize o método
main
para ativar apenas a funçãosendMessageToFcmTopic
.
- Em
- Execute a função
main
deFcmSender.java
. Isso enviará a mensagem para sua instância de aplicativo, e você poderá observá-la no aplicativo da seguinte maneira.- Instância do app em primeiro plano
- Instância do app em segundo plano
Implementar o cancelamento da assinatura de tokens de registro do FCM no tópico do FCM
- Para cancelar a inscrição em tópicos do lado do servidor, use esta API
unsubscribeFromTopic
. Você vai adicionar o código relevante à funçãounsubscribeFcmRegistrationTokensFromTopic
da classeFcmSubscriptionManager.java
.
- A implementação do código de cancelamento de assinatura do lado do servidor e a validação do seu efeito enviando uma mensagem de tópico são um exercício para você.
11. Parabéns
Parabéns, você usou os tópicos do FCM para enviar mensagens multicast a subgrupos das suas instâncias do app. Isso vai simplificar sua capacidade de alcançar os usuários no momento certo com conteúdo relevante.
A seguir
Agora que você concluiu o codelab, teste temas para outras plataformas usando os seguintes guias: