Envie mensagens para grupos de dispositivos em Web/JavaScript

As mensagens de grupo de dispositivos permitem adicionar vários dispositivos a um único grupo. Isso é semelhante às mensagens de tópico, mas inclui 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 modelos de telefone diferentes, seus servidores poderão adicionar/remover registros nos grupos apropriados e enviar a mensagem apropriada para cada grupo. As mensagens de grupo de dispositivos diferem das mensagens de tópico porque envolvem o gerenciamento de grupos de dispositivos a partir de seus servidores, em vez de diretamente em seu aplicativo.

O número máximo de membros permitidos para uma chave de notificação é 20.

Gerenciando grupos de dispositivos

Antes de enviar mensagens para um grupo de dispositivos, você deve:

1. Obtenha tokens de registro para cada dispositivo que deseja adicionar ao grupo.

2. Crie o notification_key , que identifica o grupo de dispositivos mapeando um grupo específico (normalmente um usuário) para todos os tokens de registro associados ao grupo. Você pode criar chaves de notificação no servidor de aplicativos.

O gerenciamento básico de grupos de dispositivos — criação e remoção de grupos e adição ou remoção de dispositivos — é realizado por meio da API HTTP v1, usando tokens de curta duração para autorizar solicitações de envio . Consulte Chaves de gerenciamento de grupo de dispositivos para obter uma lista de chaves compatíveis.

Gerenciando grupos de dispositivos no servidor de aplicativos

Criando um grupo de dispositivos

Para criar um grupo de dispositivos, envie uma solicitação POST que forneça um nome para o 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 como a seguinte para https://fcm.googleapis.com/fcm/notification :

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

notification_key_name é um nome ou identificador (por exemplo, pode ser um nome de usuário) exclusivo para um determinado grupo. notification_key_name e notification_key são exclusivos para um grupo de tokens de registro. É importante que notification_key_name seja exclusivo por aplicativo cliente se você tiver vários aplicativos cliente para o mesmo ID de remetente . Isso garante que as mensagens cheguem apenas ao aplicativo de destino pretendido.

Formato de resposta

Uma solicitação bem-sucedida retorna uma notification_key como a seguir:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Salve a notification_key e o notification_key_name correspondente para usar em operações subsequentes.

Os tokens de registro inválidos são descartados quando um grupo de dispositivos é criado com êxito.

Recuperando uma chave de notificação

Se você precisar recuperar uma chave de notificação existente, use notification_key_name em uma solicitação GET conforme mostrado:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

Para cada solicitação GET para um determinado nome de chave de notificação, o servidor retorna uma string codificada exclusiva. Embora cada string possa parecer uma chave diferente, na verdade é um valor `notification_key` válido.

Adicionar e remover dispositivos de um grupo de dispositivos

Para adicionar ou remover dispositivos de um grupo existente, envie uma solicitação POST com o parâmetro operation definido como add ou remove e forneça os tokens de registro para adição ou remoção.

Se você remover todos os tokens de registro existentes de um grupo de dispositivos, o FCM excluirá o grupo de dispositivos.

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 de resposta

Uma solicitação bem-sucedida para adicionar ou remover um dispositivo retorna uma notification_key como a seguinte:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Nota: notification_key_name não é necessário para adicionar/remover tokens de registro, mas incluí-lo protege você contra o uso acidental do notification_key incorreto.

Chaves de gerenciamento de grupo de dispositivos

A tabela a seguir lista as chaves para criar grupos de dispositivos e adicionar e remover membros.

Tabela 10. Chaves de gerenciamento de grupo de dispositivos.

Parâmetro	Uso	Descrição
operation	Obrigatório, sequência	A operação a ser executada. Os valores válidos são create , add e remove .
notification_key_name	Obrigatório, sequência	O nome definido pelo usuário do grupo de dispositivos a ser criado ou modificado.
notification_key	Obrigatório (exceto para operação create , string	Identificador exclusivo do grupo de dispositivos. Esse valor é retornado na resposta para uma operação create bem-sucedida e é necessário para todas as operações subsequentes no grupo de dispositivos.
registration_ids	Obrigatório, matriz de strings	Os tokens de dispositivo a serem adicionados ou removidos. Se você remover todos os tokens de registro existentes de um grupo de dispositivos, o FCM excluirá o grupo de dispositivos.

Envio de mensagens downstream para grupos de dispositivos

Para enviar mensagens para grupos de dispositivos, use a API HTTP v1. Se você estiver enviando para grupos de dispositivos usando as APIs de envio legadas obsoletas para HTTP ou XMPP, ou qualquer uma das versões mais antigas do SDK Admin do Firebase para Node.js com base nos protocolos legados, recomendamos fortemente que você migre para o HTTP v1 API na primeira oportunidade. As APIs de envio herdadas serão desativadas e removidas em junho de 2024.

Enviar mensagens para um grupo de dispositivos é muito semelhante a enviar mensagens para um dispositivo individual, usando o mesmo método para autorizar solicitações de envio . Defina o campo token como a chave de notificação do grupo:

DESCANSAR

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

comando cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Observação: diferentemente dos métodos de envio de grupo de dispositivos em APIs legadas obsoletas, a resposta HTTP v1 não contém contagens de sucesso e falha. Um envio bem-sucedido retorna uma resposta vazia.