Esta página foi traduzida pela API Cloud Translation.

Envie mensagens para grupos de dispositivos no Android

As mensagens do grupo de dispositivos permitem adicionar vários dispositivos a um único grupo. Isso é semelhante ao envio de mensagens por tópico, mas inclui autenticação para garantir que a associação ao grupo seja gerenciada apenas por seus servidores. Por exemplo, se você deseja enviar mensagens diferentes para modelos de telefone diferentes, seus servidores podem adicionar/remover registros para os grupos apropriados e enviar a mensagem apropriada para cada grupo. As mensagens de grupos de dispositivos diferem das mensagens de tópicos porque envolvem o gerenciamento de grupos de dispositivos de seus servidores em vez de diretamente em seu aplicativo.

Você pode usar mensagens de grupos de dispositivos por meio dos protocolos herdados XMPP ou HTTP em seu servidor de aplicativos. Versões mais antigas do Firebase Admin SDK para Node.js são baseadas nos protocolos legados e também fornecem recursos de mensagens para grupos de dispositivos. O número máximo de membros permitido para uma chave de notificação é 20.

Gerenciando grupos de dispositivos

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

Obtenha tokens de registro para cada dispositivo que deseja adicionar ao grupo.
Crie a notification_key , que identifica o grupo de dispositivos mapeando um grupo específico (geralmente 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 do servidor de aplicativos. Consulte a referência do protocolo HTTP herdado 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
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 é um nome ou identificador (por exemplo, pode ser um nome de usuário) exclusivo de um determinado grupo. O 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 vão apenas para o aplicativo de destino pretendido.

Formato de resposta

Uma solicitação bem-sucedida retorna um notification_key como o seguinte:

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

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

Recuperando uma chave de notificação

Se você precisar recuperar uma chave de notificação existente, use o 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
Authorization:key=API_KEY
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 de operation definido para add ou remove e forneça os tokens de registro para 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 , envie 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 um notification_key como o seguinte:

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

Envio de mensagens downstream para grupos de dispositivos

O envio de mensagens para um grupo de dispositivos é muito semelhante ao envio de mensagens para um dispositivo individual. Defina o parâmetro to como a chave de notificação exclusiva para o grupo de dispositivos. Consulte Tipos de mensagem para obter detalhes sobre o suporte de carga útil. Os exemplos nesta página mostram como enviar mensagens de dados para grupos de dispositivos nos protocolos herdados HTTP e XMPP.

Solicitação HTTP POST do 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

Aqui está um exemplo de "sucesso" — a notification_key tem 2 tokens de registro associados a ela e a mensagem foi enviada com sucesso para ambos:

{
  "success": 2,
  "failure": 0
}

Aqui está um exemplo de "sucesso parcial" — o notification_key tem 3 tokens de registro associados a ele. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro ( registration_ids ) que falharam ao receber a mensagem:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Quando uma mensagem falha ao ser entregue a um ou mais dos tokens de registro associados a um notification_key , o servidor de aplicativos deve tentar novamente com espera entre novas tentativas.

Se o servidor tentar enviar uma mensagem para um grupo de dispositivos sem membros, a resposta será semelhante à seguinte, com 0 sucesso e 0 falha:

{
  "success": 0,
  "failure": 0
}

Mensagem XMPP do 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 para qualquer um dos dispositivos do grupo com sucesso, o servidor de conexão XMPP responde com um ACK. Se todas as mensagens enviadas para todos os dispositivos do grupo falharem, o servidor de conexão XMPP responderá com um NACK.

Aqui está um exemplo de "sucesso" — o notification_key tem 3 tokens de registro associados a ele e a mensagem foi enviada com sucesso para todos eles:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Quando o servidor de conexão FCM falha ao entregar a todos os dispositivos do grupo. O servidor de aplicativos receberá uma resposta nack.

Para obter a lista completa de opções de mensagens, consulte as informações de referência do protocolo de servidor de conexão escolhido, HTTP ou XMPP .