Com as mensagens para grupos de dispositivos, é possível adicionar vários dispositivos a um único grupo. Esse processo é semelhante ao das mensagens de tópico, mas inclui a autenticação para garantir que a associação ao grupo seja gerenciada apenas pelos seus servidores. Por exemplo, se você quiser enviar mensagens diferentes para diferentes modelos de smartphone, seus servidores poderão adicionar/remover registros dos grupos e enviar a mensagem relevante para cada um deles. A diferença entre as mensagens para grupos de dispositivos e as mensagens de tópico é que, no primeiro caso, o gerenciamento de grupos de dispositivos é feito a partir dos seus servidores em vez de diretamente no aplicativo.
É possível usar mensagens para grupos de dispositivos com os protocolos XMPP ou HTTP legados no servidor de apps. As versões mais antigas do SDK Admin do Firebase para Node.js são baseadas em protocolos legados e também fornecem recursos de mensagens para grupos de dispositivos. O número máximo permitido de membros em uma chave de notificação é 20.
Gerenciamento de grupos de dispositivos
Antes de enviar mensagens a um grupo de dispositivos, você precisa:
-
receber tokens de registro para cada dispositivo que você quer adicionar ao grupo;
-
criar a
notification_key
, que identifica o grupo de dispositivos, mapeando um grupo particular (normalmente, um usuário) para todos os tokens de registro associados do grupo. É possível criar chaves de notificação no servidor do aplicativo.
O gerenciamento básico de grupos de dispositivos (criar e remover grupos e adicionar ou remover dispositivos) é executado no servidor do app. Consulte a referência de protocolo HTTP legada para ver uma lista de chaves compatíveis.
Como gerenciar grupos de dispositivos no servidor do app
Criação de um grupo de dispositivos
Para criar um grupo de dispositivos, envie uma solicitação POST que forneça um nome
ao grupo e uma lista de tokens de registro para os dispositivos.
O FCM retorna uma nova notification_key
que representa o grupo de dispositivos.
Solicitação HTTP POST
Envie uma solicitação, conforme abaixo, para
https://fcm.googleapis.com/fcm/notification
:
https://fcm.googleapis.com/fcm/notification Content-Type:application/json Authorization:key=API_KEY project_id:SENDER_ID { "operation": "create", "notification_key_name": "appUser-Chris", "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...", ... ]
O notification_key_name
é o nome ou o identificador
(por exemplo, pode ser um nome de usuário) exclusivo para determinado grupo. O
notification_key_name
e a
notification_key
são exclusivos a um grupo de tokens
de registro. É importante que o notification_key_name
seja
exclusivo para cada um dos apps clientes se tiver vários deles para o mesmo
ID do remetente.
Isso garante que a mensagem seja enviada apenas ao aplicativo de destino pretendido.
Formato da resposta
Uma solicitação bem-sucedida retorna uma notification_key
como
esta:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
Salve a notification_key
e o notification_key_name
correspondente
para usar em operações posteriores.
Como recuperar uma chave de notificação
Se for necessário recuperar uma chave de notificação, use o
notification_key_name
em uma solicitação GET como mostrado:
https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris Content-Type:application/json Authorization:key=API_KEY project_id:SENDER_ID {}
O servidor retorna uma string codificada exclusiva para cada solicitação GET referente a um determinado nome de chave de notificação. Cada string pode parecer uma chave diferente, mas, na realidade, é um valor válido de "notification_key".
Como adicionar e remover dispositivos de um grupo de dispositivos
Para adicionar ou remover dispositivos de um grupo, envie uma solicitação
POST com o parâmetro operation
definido como
add
ou remove
e forneça os
tokens de registro de adição ou remoção.
Solicitação HTTP POST
Por exemplo, para adicionar um
dispositivo com o token de registro bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...
a appUser-Chris
, você enviaria esta solicitação:
{
"operation": "add",
"notification_key_name": "appUser-Chris",
"notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}
Formato da resposta
Uma solicitação para adicionar ou remover um dispositivo retorna uma
notification_key
como esta:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
Envio de mensagens downstream a grupos de dispositivos
Enviar mensagens para um grupo de dispositivos é similar ao envio
para um dispositivo individual. Defina o parâmetro to
como a chave de notificação exclusiva do grupo. Consulte
Tipos de mensagem para mais detalhes sobre o
suporte ao payload. Os exemplos nesta página mostram como enviar mensagens
de dados para esses grupos de dispositivos nos protocolos HTTP e XMPP legados.
Solicitação HTTP POST para grupo de dispositivos
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to": "aUniqueKey", "data": { "hello": "This is a Firebase Cloud Messaging Device Group Message!", } }
Resposta HTTP do grupo de dispositivos
Este é um exemplo de êxito na operação: a notification_key
tem dois tokens de registro associados a ela e a mensagem foi
enviada a ambos:
{ "success": 2, "failure": 0 }
Este é um exemplo de "êxito parcial" na operação: a
notification_key
tem três tokens de registro associados
a ela. A mensagem foi enviada apenas para um dos
tokens de registro. A mensagem da resposta lista os tokens
(registration_ids
) onde houve falha ao receber a mensagem:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando uma mensagem não é entregue a um ou mais
tokens de registro associados a uma notification_key
,
o servidor do app faz uma nova tentativa com um intervalo de espera entre elas.
Se o servidor tenta enviar uma mensagem para um grupo de dispositivos que não tem membros, a resposta é parecida com esta, com 0 sucesso e 0 falha:
{ "success": 0, "failure": 0 }
Mensagem XMPP para grupo de dispositivos
<message id=""> <gcm xmlns="google:mobile:data"> { "to": "aUniqueKey", "message_id": "m-1366082849205" , "data": { "hello":"This is a Firebase Cloud Messaging Device Group Message!" } } </gcm> </message>
Resposta XMPP do grupo de dispositivos
Quando a mensagem é enviada com sucesso para qualquer um dos dispositivos do grupo, o servidor de conexões XMPP responde com um ACK. Quando ocorre falha no envio de todas as mensagens a todos os dispositivos do grupo, o servidor responde com um NACK.
Este é um exemplo de "êxito" na operação: a notification_key
tem três tokens de registro associados a ela e a mensagem foi
enviada a todos:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
Este é um exemplo de "êxito parcial" na operação: a
notification_key
tem três tokens de registro associados
a ela. A mensagem foi enviada apenas para um dos
tokens de registro. A mensagem de resposta lista os tokens
que não receberam a mensagem:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
Quando um servidor de conexão FCM não entrega para todos os dispositivos no grupo, o servidor do app receberá uma resposta NACK.
Para ver a lista completa de opções de mensagens, consulte as informações de referência do protocolo do servidor de conexão selecionado, HTTP ou XMPP.