Enviar mensagens para grupos de dispositivos no C++

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 usando os servidores em vez de diretamente no aplicativo.

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:

1. receber tokens de registro para cada dispositivo que você quer adicionar ao grupo;

2. 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) é realizado por meio da API HTTP v1, usando tokens de curta duração para autorizar solicitações de envio. Consulte Chaves de gerenciamento de grupos de dispositivos 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 um novo 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
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...",
                        ... ]

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.

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

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
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
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.

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

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"
}

Observação: notification_key_name não é obrigatório para adicionar/remover tokens de registro, mas incluí-lo protege você contra o uso acidental da notification_key incorreta.

Chaves de gerenciamento de grupo de dispositivos

A tabela a seguir lista as chaves para criação de grupos de dispositivo e adição e remoção de participantes.

Tabela 10. Chaves de gerenciamento de grupo de dispositivos.

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

Envio de mensagens downstream a grupos de dispositivos

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

O envio de mensagens para um grupo de dispositivos é muito semelhante ao envio 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:

REST

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 do 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.