Protocolo XMPP do Firebase Cloud Messaging

Este documento fornece uma referência para a sintaxe XMPP usada para transmitir mensagens entre o servidor de aplicativos, os aplicativos cliente e o Firebase Cloud Messaging (FCM). Seu servidor de aplicativos deve se conectar a estes endpoints:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

Os parâmetros e opções disponíveis se enquadram nestas categorias:

Sintaxe de mensagem downstream

Esta seção fornece a sintaxe para enviar mensagens downstream.

Mensagens XMPP downstream (JSON)

A tabela a seguir lista os destinos, opções e carga útil para mensagens JSON XMPP.

Tabela 1 Destinos, opções e carga útil para mensagens XMPP downstream (JSON).

Parâmetro Uso Descrição
Alvo
to Opcional, sequência

Este parâmetro especifica o destinatário de uma mensagem.

O valor pode ser um token de registro de dispositivo, uma chave de notificação de grupo de dispositivos ou um único tópico (prefixado com /topics/ ). Para enviar para vários tópicos, use o parâmetro condition .

condition Opcional, sequência

Este parâmetro especifica uma expressão lógica de condições que determina o destino da mensagem.

Condição suportada: Tópico, formatado como "'yourTopic' em tópicos". Este valor não diferencia maiúsculas de minúsculas.

Operadores suportados: && , || . Máximo de dois operadores por mensagem de tópico suportados.

Opções
message_id Obrigatório, sequência

Este parâmetro identifica exclusivamente uma mensagem em uma conexão XMPP.

collapse_key Opcional, sequência

Este parâmetro identifica um grupo de mensagens (por exemplo, com collapse_key: "Updates Available" ) que pode ser recolhido para que apenas a última mensagem seja enviada quando a entrega for retomada. O objetivo é evitar o envio de muitas mensagens iguais quando o dispositivo voltar a ficar on-line ou sair do sono.

Não há garantia da ordem em que as mensagens são enviadas.

Nota: São permitidas no máximo 4 chaves de recolhimento diferentes a qualquer momento. Isso significa que o FCM pode armazenar simultaneamente 4 mensagens diferentes por aplicativo cliente. Se você exceder esse número, não há garantia de quais 4 chaves de recolhimento o FCM manterá.

priority Opcional, sequência

Define a prioridade da mensagem. Os valores válidos são “normal” e “alto”. Nas plataformas Apple, correspondem às prioridades 5 e 10 dos APNs.

Por padrão, as mensagens de notificação são enviadas com prioridade alta e as mensagens de dados são enviadas com prioridade normal. A prioridade normal otimiza o consumo de bateria do aplicativo cliente e deve ser usada a menos que seja necessária entrega imediata. Para mensagens com prioridade normal, o aplicativo pode receber a mensagem com atraso indeterminado.

Quando uma mensagem é enviada com alta prioridade, ela é enviada imediatamente e o aplicativo pode exibir uma notificação.

content_available Opcional, booleano

Nas plataformas Apple, use este campo para representar content-available na carga útil dos APNs. Quando uma notificação ou mensagem é enviada e definida como true , um aplicativo cliente inativo é ativado e a mensagem é enviada por meio de APNs como uma notificação silenciosa e não por meio de FCM. Observe que as notificações silenciosas em APNs não têm garantia de entrega e podem depender de fatores como o usuário ativar o modo de baixo consumo, forçar o encerramento do aplicativo, etc. No Android, as mensagens de dados ativam o aplicativo por padrão. No Chrome, atualmente não é compatível.

mutable_content Opcional, JSON booleano

Nas plataformas Apple, use este campo para representar mutable-content na carga útil dos APNs. Quando uma notificação é enviada e está definida como true , o conteúdo da notificação pode ser modificado antes de ser exibido, usando uma extensão de aplicativo do Notification Service . Este parâmetro será ignorado para Android e web.

time_to_live Opcional, número

Este parâmetro especifica por quanto tempo (em segundos) a mensagem deve ser mantida no armazenamento FCM se o dispositivo estiver offline. O tempo máximo de vida suportado é de 4 semanas e o valor padrão é de 4 semanas. Para obter mais informações, consulte Configurando a vida útil de uma mensagem .

dry_run Opcional, booleano

Este parâmetro, quando definido como true , permite que os desenvolvedores testem uma solicitação sem realmente enviar uma mensagem.

O valor padrão é false .

Carga útil
data Opcional, objeto

Este parâmetro especifica os pares de valores-chave da carga útil da mensagem.

Por exemplo, com data:{"score":"3x1"}:

Nas plataformas Apple, se a mensagem for entregue por APNs, ela representa os campos de dados personalizados. Se for entregue pelo FCM, será representado como um dicionário de valor-chave em AppDelegate application:didReceiveRemoteNotification: .

No Android, isso resulta em uma score extra nomeada de intenção com o valor da string 3x1 .

A chave não deve ser uma palavra reservada ("from", "message_type" ou qualquer palavra que comece com "google" ou "gcm"). Não use nenhuma das palavras definidas nesta tabela (como collapse_key ).

Valores em tipos de string são recomendados. Você deve converter valores em objetos ou outros tipos de dados que não sejam string (por exemplo, inteiros ou booleanos) em string.

notification Opcional, objeto Este parâmetro especifica os pares de valores-chave predefinidos e visíveis ao usuário da carga de notificação. Consulte Suporte à carga útil de notificação para obter detalhes. Para obter mais informações sobre opções de mensagens de notificação e mensagens de dados, consulte Tipos de mensagens . Se uma carga útil de notificação for fornecida ou a opção content_available for definida como true para uma mensagem para um dispositivo Apple, a mensagem será enviada por meio de APNs , caso contrário, será enviada por meio de FCM.

Suporte a carga útil de notificação

As tabelas a seguir listam as chaves predefinidas disponíveis para criar mensagens de notificação para plataformas Apple e Android.

Tabela 2a. Apple — chaves para mensagens de notificação

Parâmetro Uso Descrição
title Opcional, sequência

O título da notificação.

Este campo não está visível em telefones e tablets.

body Opcional, sequência

O texto do corpo da notificação.

sound Opcional, sequência

O som a ser reproduzido quando o dispositivo recebe a notificação.

String especificando arquivos de som no pacote principal do aplicativo cliente ou na pasta Library/Sounds do contêiner de dados do aplicativo. Consulte a Biblioteca de desenvolvedores iOS para obter mais informações.

badge Opcional, sequência

O valor do selo no ícone do aplicativo na tela inicial.

Se não for especificado, o emblema não será alterado.

Se definido como 0 , o emblema será removido.

click_action Opcional, sequência

A ação associada a um clique do usuário na notificação.

Corresponde à category na carga útil dos APNs.

subtitle Opcional, sequência

O subtítulo da notificação.

body_loc_key Opcional, sequência

A chave para a string do corpo nos recursos de string do aplicativo a serem usados ​​para localizar o texto do corpo para a localização atual do usuário.

Corresponde à loc-key na carga útil dos APNs.

Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.

body_loc_args Opcional, matriz JSON como string

Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em body_loc_key a serem usados ​​para localizar o texto do corpo para a localização atual do usuário.

Corresponde a loc-args na carga útil dos APNs.

Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.

title_loc_key Opcional, sequência

A chave para a string de título nos recursos de string do aplicativo a serem usados ​​para localizar o texto do título para a localização atual do usuário.

Corresponde à title-loc-key na carga útil dos APNs.

Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.

title_loc_args Opcional, matriz JSON como string

Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em title_loc_key a serem usados ​​para localizar o texto do título para a localização atual do usuário.

Corresponde a title-loc-args na carga útil dos APNs.

Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.

Tabela 2b. Android — chaves para mensagens de notificação

Parâmetro Uso Descrição
title Opcional, sequência

O título da notificação.

body Opcional, sequência

O texto do corpo da notificação.

android_channel_id Opcional, sequência

O ID do canal da notificação (novo no Android O).

O aplicativo deve criar um canal com esse ID de canal antes que qualquer notificação com esse ID de canal seja recebida.

Se você não enviar esse ID de canal na solicitação ou se o ID de canal fornecido ainda não tiver sido criado pelo aplicativo, o FCM usará o ID de canal especificado no manifesto do aplicativo.

icon Opcional, sequência

O ícone da notificação.

Define o ícone de notificação como myicon para o recurso drawable myicon . Se você não enviar essa chave na solicitação, o FCM exibirá o ícone do iniciador especificado no manifesto do seu aplicativo.

sound Opcional, sequência

O som a ser reproduzido quando o dispositivo recebe a notificação.

Suporta "default" ou o nome do arquivo de um recurso de som incluído no aplicativo. Os arquivos de som devem residir em /res/raw/ .

tag Opcional, sequência

Identificador usado para substituir notificações existentes na gaveta de notificações.

Se não for especificado, cada solicitação criará uma nova notificação.

Se especificado e uma notificação com a mesma tag já estiver sendo mostrada, a nova notificação substituirá a existente na gaveta de notificações.

color Opcional, sequência

A cor do ícone da notificação, expressa no formato #rrggbb .

click_action Opcional, sequência

A ação associada a um clique do usuário na notificação.

Se especificado, uma atividade com um filtro de intenção correspondente será iniciada quando um usuário clicar na notificação.

body_loc_key Opcional, sequência

A chave para a string do corpo nos recursos de string do aplicativo a serem usados ​​para localizar o texto do corpo para a localização atual do usuário.

Consulte Recursos de String para obter mais informações.

body_loc_args Opcional, matriz JSON como string

Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em body_loc_key a serem usados ​​para localizar o texto do corpo para a localização atual do usuário.

Consulte Formatação e estilo para obter mais informações.

title_loc_key Opcional, sequência

A chave para a string de título nos recursos de string do aplicativo a serem usados ​​para localizar o texto do título para a localização atual do usuário.

Consulte Recursos de String para obter mais informações.

title_loc_args Opcional, matriz JSON como string

Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em title_loc_key a serem usados ​​para localizar o texto do título para a localização atual do usuário.

Consulte Formatação e estilo para obter mais informações.

Tabela 2c. Web (JavaScript) — chaves para mensagens de notificação

Parâmetro Uso Descrição
title Opcional, sequência

O título da notificação.

body Opcional, sequência

O texto do corpo da notificação.

icon Opcional, sequência

A URL a ser usada para o ícone da notificação.

click_action Opcional, sequência

A ação associada a um clique do usuário na notificação.

Para todos os valores de URL, HTTPS é obrigatório.

Interpretar uma resposta de mensagem XMPP downstream

A tabela a seguir lista os campos que aparecem em uma resposta de mensagem XMPP downstream.

Tabela 3 Corpo de resposta XMPP da mensagem downstream.

Parâmetro Uso Descrição
from Obrigatório, sequência

Este parâmetro especifica quem enviou esta resposta.

O valor é o token de registro do aplicativo cliente.

message_id Obrigatório, sequência Este parâmetro identifica exclusivamente uma mensagem em uma conexão XMPP. O valor é uma sequência que identifica exclusivamente a mensagem associada.
message_type Obrigatório, sequência

Este parâmetro especifica uma mensagem ack ou nack do FCM para o servidor de aplicativos.

Se o valor for definido como nack , o servidor de aplicativos deverá examinar error e error_description para obter informações de falha.

error Opcional, sequência Este parâmetro especifica um erro relacionado à mensagem downstream. É definido quando o message_type é nack . Consulte a tabela 4 para obter detalhes.
error_description Opcional, sequência Este parâmetro fornece informações descritivas para o erro. É definido quando o message_type é nack .

Códigos de resposta de erro de mensagem downstream

A tabela a seguir lista os códigos de resposta de erro para mensagens downstream.

Tabela 4 Códigos de resposta de erro de mensagem downstream.

Erro Código XMPP Ação recomendada
Token de registro ausente INVALID_JSON Verifique se a solicitação contém um token de registro (no registration_id em uma mensagem de texto simples ou no campo to ou registration_ids em JSON).
Registro de APNs inválido INVALID_JSON Para registros iOS, verifique se a solicitação de registro do cliente contém um token de APNs e um ID de aplicativo válidos.
Token de registro inválido BAD_REGISTRATION Verifique o formato do token de registro que você passa ao servidor. Certifique-se de que ele corresponda ao token de registro que o aplicativo cliente recebe ao se registrar no FCM. Não trunque ou adicione caracteres adicionais.
Dispositivo não registrado DEVICE_UNREGISTERED Um token de registro existente pode deixar de ser válido em vários cenários, incluindo:
  • Se o aplicativo cliente cancelar o registro no FCM.
  • Se o registro do aplicativo cliente for automaticamente cancelado, o que pode acontecer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se os APNs reportaram o token de APNs como inválido.
  • Se o token de registro expirar (por exemplo, o Google pode decidir atualizar os tokens de registro ou o token de APNs expirou para dispositivos).
  • Se o aplicativo cliente estiver atualizado, mas a nova versão não estiver configurada para receber mensagens.
Para todos esses casos, remova esse token de registro do servidor do aplicativo e pare de usá-lo para enviar mensagens.
Remetente incompatível SENDER_ID_MISMATCH Um token de registro está vinculado a um determinado grupo de remetentes. Quando um aplicativo cliente se registra no FCM, ele precisa especificar quais remetentes têm permissão para enviar mensagens. Você deve usar um desses IDs de remetente ao enviar mensagens para o aplicativo cliente. Se você mudar para um remetente diferente, os tokens de registro existentes não funcionarão.
JSON inválido INVALID_JSON Verifique se a mensagem JSON está formatada corretamente e contém campos válidos (por exemplo, certificando-se de que o tipo de dados correto foi transmitido).
Mensagem muito grande INVALID_JSON Verifique se o tamanho total dos dados de carga incluídos em uma mensagem não excede os limites do FCM: 4.096 bytes para a maioria das mensagens ou 2.048 bytes no caso de mensagens para tópicos. Isso inclui as chaves e os valores.
Chave de dados inválida INVALID_JSON Verifique se os dados da carga útil não contêm uma chave (como from , gcm ou qualquer valor prefixado por google ) usada internamente pelo FCM. Observe que algumas palavras (como collapse_key ) também são usadas pelo FCM, mas são permitidas na carga útil; nesse caso, o valor da carga útil é substituído pelo valor do FCM.
Tempo de vida inválido INVALID_JSON Verifique se o valor usado em time_to_live é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas).
Mensagem ACK incorreta BAD_ACK Verifique se a mensagem ack está formatada corretamente antes de tentar novamente. Consulte a tabela 6 para obter detalhes.
Tempo esgotado SERVICE_UNAVAILABLE

O servidor não conseguiu processar a solicitação a tempo. Tente novamente a mesma solicitação, mas você deve:

  • Implemente a espera exponencial em seu mecanismo de nova tentativa. (por exemplo, se você esperou um segundo antes da primeira tentativa, espere pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante). Se você estiver enviando várias mensagens, atrase cada uma delas de forma independente por um valor aleatório adicional para evitar a emissão de uma nova solicitação para todas as mensagens ao mesmo tempo.
  • O atraso de nova tentativa inicial deve ser definido para um segundo.

Nota: Remetentes que causam problemas correm o risco de serem colocados na lista negra.

Erro do Servidor Interno INTERNAL_SERVER_
ERROR		 O servidor encontrou um erro ao tentar processar a solicitação. Você pode tentar novamente a mesma solicitação seguindo os requisitos listados em "Tempo limite" (veja a linha acima).
Taxa de mensagens do dispositivo excedida DEVICE_MESSAGE_RATE
_EXCEEDED		 A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas para este dispositivo e não tente enviar novamente para este dispositivo imediatamente.
Taxa de mensagens de tópicos excedida TOPICS_MESSAGE_RATE
_EXCEEDED		 A taxa de mensagens para assinantes de um determinado tópico é muito alta. Reduza o número de mensagens enviadas para este tópico e não tente enviar novamente imediatamente.
Drenagem de conexão CONNECTION_DRAINING A mensagem não pôde ser processada porque a conexão está esgotada. Isso acontece porque, periodicamente, o FCM precisa encerrar uma conexão para realizar o balanceamento de carga. Tente novamente a mensagem em outra conexão XMPP.
Credenciais de APNs inválidas INVALID_APNS_CREDENTIAL Uma mensagem direcionada a um dispositivo iOS não pôde ser enviada porque a chave de autenticação de APNs necessária não foi carregada ou expirou. Verifique a validade de suas credenciais de desenvolvimento e produção.
Falha na autenticação AUTHENTICATION_FAILED Falha ao autenticar com serviços push externos. Verifique se você está usando os certificados web push corretos.

Sintaxe da mensagem upstream

Uma mensagem upstream é uma mensagem que o aplicativo cliente envia ao servidor de aplicativos. Atualmente, apenas o XMPP oferece suporte a mensagens upstream. Consulte a documentação da sua plataforma para obter mais informações sobre o envio de mensagens de aplicativos cliente.

Interpretando uma mensagem XMPP upstream

A tabela a seguir descreve os campos na sub-rotina XMPP gerada pelo FCM em resposta a solicitações de mensagens upstream de aplicativos cliente.

Tabela 5 Mensagens XMPP upstream.

Parâmetro Uso Descrição
from Obrigatório, sequência

Este parâmetro especifica quem enviou a mensagem.

O valor é o token de registro do aplicativo cliente.

category Obrigatório, sequência Este parâmetro especifica o nome do pacote de aplicativos do aplicativo cliente que enviou a mensagem.
message_id Obrigatório, sequência Este parâmetro especifica o ID exclusivo da mensagem.
data Opcional, sequência Este parâmetro especifica os pares de valores-chave da carga útil da mensagem.

Enviando uma mensagem ACK

A tabela a seguir descreve a resposta ACK que o servidor de aplicativos deve enviar ao FCM em resposta a uma mensagem upstream recebida pelo servidor de aplicativos.

Tabela 6 Resposta da mensagem XMPP upstream.

Parâmetro Uso Descrição
to Obrigatório, sequência

Este parâmetro especifica o destinatário de uma mensagem de resposta.

O valor deve ser um token de registro do aplicativo cliente que enviou a mensagem upstream.

message_id Obrigatório, sequência Este parâmetro especifica a qual mensagem a resposta se destina. O valor deve ser o valor message_id da mensagem upstream correspondente.
message_type Obrigatório, sequência Este parâmetro especifica uma mensagem ack de um servidor de aplicativos para o CCS. Para mensagens upstream, deve sempre ser definido como ack .

Mensagens do servidor FCM (XMPP)

Esta é uma mensagem enviada do FCM para um servidor de aplicativos. Aqui estão os principais tipos de mensagens que o FCM envia ao servidor de aplicativos:

  • Controle: essas mensagens geradas pelo CCS indicam que é necessária uma ação do servidor de aplicativos.

A tabela a seguir descreve os campos incluídos nas mensagens que o CCS envia para um servidor de aplicativos.

Tabela 7 Mensagens de controle FCM (XMPP).

Parâmetro Uso Descrição
Campo comum
message_type Obrigatório, sequência

Este parâmetro especifica o tipo da mensagem: controle.

Quando definido como control , a mensagem inclui control_type para indicar o tipo de mensagem de controle.

control_type Opcional, sequência

Este parâmetro especifica o tipo de mensagem de controle enviada do FCM.

Atualmente, apenas CONNECTION_DRAINING é compatível. O FCM envia esta mensagem de controle antes de fechar uma conexão para realizar o balanceamento de carga. À medida que a conexão se esgota, não é permitido enviar mais mensagens para a conexão, mas as mensagens existentes no pipeline continuam a ser processadas.