获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Envie mensagens para grupos de dispositivos em plataformas Apple

As mensagens de grupo de dispositivos permitem adicionar vários dispositivos a um único grupo. Isso é semelhante à mensagem de 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 grupo de dispositivos diferem das mensagens de tópico porque envolvem o gerenciamento de grupos de dispositivos de seus servidores em vez de diretamente em seu aplicativo.

Você pode usar as mensagens do grupo de dispositivos por meio dos protocolos XMPP ou HTTP herdados em seu servidor de aplicativos. As versões mais antigas do SDK Admin do Firebase para Node.js são baseadas nos protocolos legados e também oferecem recursos de mensagens de grupo 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:

  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 do servidor de aplicativos. Consulte a referência do protocolo HTTP legado 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 esta 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 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.

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... para 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 esta:

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

Enviando 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 para a chave de notificação exclusiva para o grupo de dispositivos. Consulte Tipos de mensagem para obter detalhes sobre o suporte a carga útil. Os exemplos nesta página mostram como enviar mensagens de dados para grupos de dispositivos nos protocolos HTTP e XMPP legados.

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" — a notification_key tem 3 tokens de registro associados a ela. 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 não receberam 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 um notification_key , o servidor de aplicativos deve tentar novamente com espera entre as tentativas.

Se o servidor tentar enviar uma mensagem para um grupo de dispositivos que não tenha 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"
}

Aqui está um exemplo de "sucesso parcial" — a notification_key tem 3 tokens de registro associados a ela. A mensagem foi enviada com sucesso apenas para 1 dos tokens de registro. A mensagem de resposta lista os tokens de registro que não receberam a mensagem:

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

Quando o servidor de conexão FCM não entrega 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 .

Enviando mensagens upstream para grupos de dispositivos

Para enviar mensagens upstream para grupos de dispositivos em aplicativos Apple, o aplicativo cliente Apple precisa implementar FIRMessaging.sendMessage :

(void)sendMessage:(nonnull NSDictionary *)message
     to:(nonnull NSString *)receiver
withMessageID:(nonnull NSString *)messageID
timeToLive:(int64_t)ttl;