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 apps cliente e o Firebase Cloud Messaging (FCM). O servidor do app precisa se conectar a estes endpoint

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

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

Os parâmetros e as opções disponíveis enquadram-se nas seguintes categorias:

sintaxe de mensagens downstream

Nesta seção, você encontra a sintaxe para envio de mensagens dowstream.

Mensagens XMPP downstream (JSON)

Na tabela a seguir, estão listados os destinos, as opções e o payload para mensagens JSON XMPP.

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

Parâmetro Uso Descrição
Destino
to Opcional, string

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

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

condition Opcional, string

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

Condição aceita: tópico, formatado como "'seuTópico' em tópicos". Esse valor não diferencia minúsculas de maiúsculas.

Operadores compatíveis: &&, ||. No máximo dois operadores são permitidos por mensagem de tópico.
Opções
message_id Obrigatório, string

Com esse parâmetro, uma mensagem é identificada de modo exclusivo em uma conexão XMPP.
collapse_key Opcional, string

Um parâmetro identifica um grupo de mensagens (p.ex., com collapse_key: "Updates Available") que podem ser recolhidas, para que apenas a última seja enviada quando a entrega é retomada. Isso evita o envio de muitas mensagens repetidas quando o dispositivo retorna on-line ou sai do estado de soneca.

Não há garantia quanto à ordem de envio das mensagens.

No máximo quatro chaves de recolhimento diferentes são permitidas a qualquer momento. Isso significa que o FCM pode armazenar simultaneamente quatro mensagens diferentes por app cliente. Se você exceder esse limite, não há garantia de qual das quatro chaves recolhidas será mantida pelo FCM.

priority Opcional, string

Define a prioridade da mensagem. Os valores válidos são "normal" e "high" (alta). Nas plataformas Apple, eles correspondem às prioridades 5 e 10 de APNs.

Por padrão, as mensagens de notificação são enviadas com prioridade alta e as mensagens de dados com prioridade normal. A prioridade normal otimiza o consumo de bateria do app cliente e deve ser sempre usada, exceto quando a entrega imediata é necessária. Mensagens com prioridade normal podem ser recebidas pelo app com atraso não especificado.

Uma mensagem com prioridade alta é enviada imediatamente, e o app pode exibir uma notificação.

content_available Opcional, booleano

Nas plataformas Apple, use este campo para representar content-available no payload de APNs. Quando uma notificação ou mensagem é enviada e este campo está definido como true, um app cliente inativo é ativado e a mensagem é enviada por APNs como uma notificação silenciosa e não pelo servidor de conexão do FCM. Observe que não é garantido que essas notificações silenciosas em APNs sejam entregues, e isso pode depender de fatores como o usuário ativar o Modo de baixo consumo, saída forçada do app etc. No Android, as mensagens de dados ativam o app por padrão. Ainda não há compatibilidade com o Chrome.
mutable_content Opcional, JSON booleano

Nas plataformas Apple, use este campo para representar mutable-content no payload de APNs. Quando uma notificação é enviada e este campo está definido como true, o conteúdo dela pode ser modificado antes da exibição por uma extensão de app do serviço de notificação. No Android e na Web, esse parâmetro é ignorado.

time_to_live Opcional, número

Este parâmetro especifica o tempo, em segundos, de manutenção da mensagem no armazenamento do FCM se o dispositivo ficar off-line. A vida útil máxima permitida é 4 semanas, que também é o valor padrão. Para mais informações, consulte Definir a vida útil de uma mensagem.

dry_run Opcional, booleano

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

O valor padrão é false.
Payload
data Opcional, objeto

Este parâmetro especifica os pares de chave-valor do payload da mensagem.

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

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

No Android, isso resulta em um intent adicional chamado score com o valor de string 3x1.

A chave não pode ser uma palavra reservada, por exemplo, "from", "message_type" ou qualquer palavra que comece com "google" ou "gcm". Não use palavras definidas nesta tabela como, por exemplo, collapse_key.

É recomendável usar valores do tipo string. É preciso converter os valores nos objetos ou outros tipos de dados sem string (por exemplo, números inteiros ou booleanos) para string.
notification Opcional, objeto Este parâmetro especifica os pares de chave-valor predefinidos do payload da notificação, visíveis ao usuário. Consulte o suporte do payload para mais detalhes. Para ver mais informações sobre a mensagem de notificação e opções de mensagens de dados, consulte Tipos de mensagens. Se houver um payload de notificação ou a opção content_available estiver definida como true em uma mensagem para um dispositivo da Apple, a mensagem será enviada por APNs. Caso contrário, ela será enviada pelo FCM.

Suporte ao payload de notificação

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

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

Parâmetro Uso Descrição
title Opcional, string

O título da notificação.

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

body Opcional, string

O texto do corpo da notificação.
sound Opcional, string

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

String que especifica arquivos de som no pacote principal do app cliente ou na pasta Library/Sounds do contêiner de dados do app. Consulte mais informações na Biblioteca dos desenvolvedores do iOS.

badge Opcional, string

O valor do indicador no ícone do app da tela inicial.

Se não é especificado, o indicador não é alterado.

Se é definido como 0, o indicador é removido.

click_action Opcional, string

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

Corresponde a category no payload de APNs.
subtitle Opcional, string

A legenda da notificação.
body_loc_key Opcional, string

A chave da string de corpo nos recursos de string do app, a ser usada para identificar o texto do corpo na localização atual do usuário.

Corresponde a loc-key no payload de APNs.

Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.

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 para identificar o texto do corpo na localização atual do usuário.

Corresponde a loc-args no payload de APNs.

Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.

title_loc_key Opcional, string

A chave da string de título nos recursos de string do app a ser usada para identificar o texto do título na localização atual do usuário.

Corresponde a title-loc-key no payload de APNs.

Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.

title_loc_args Opcional, matriz JSON como string

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

Corresponde a title-loc-args no payload de APNs.

Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.

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

Parâmetro Uso Descrição
title Opcional, string

O título da notificação.
body Opcional, string

O texto do corpo da notificação.
android_channel_id Opcional, string

O código do canal da notificação (novo no Android O).

O app precisa criar um canal com este ID do canal antes que qualquer notificação com esse ID seja recebida.

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

icon Opcional, string

O ícone da notificação.

Define o ícone da notificação como myicon para o recurso drawable myicon. Se você não enviar essa chave na solicitação, o FCM exibe o ícone do inicializador especificado no manifesto do app.

sound Opcional, string

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

Aceita "default" ou o nome do arquivo de um recurso de som no pacote do app. Arquivos de som precisam residir em /res/raw/.
tag Opcional, string

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

Se não está especificado, cada solicitação cria uma nova notificação.

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

color Opcional, string

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

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

Se especificado, uma atividade com um filtro de intent correspondente é iniciada quando um usuário clica na notificação.

body_loc_key Opcional, string

A chave da string de corpo nos recursos de string do app, a ser usada para identificar o texto do corpo na localização atual do usuário.

Consulte Recursos de string para 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 para identificar o texto do corpo na localização atual do usuário.

Consulte Como formatar e definir estilo para mais informações.

title_loc_key Opcional, string

A chave da string de título nos recursos de string do app a ser usada para identificar o texto do título na localização atual do usuário.

Consulte Recursos de string para mais informações.

title_loc_args Opcional, matriz JSON como string

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

Consulte Como formatar e definir estilo para mais informações.

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

Parâmetro Uso Descrição
title Opcional, string

O título da notificação.
body Opcional, string

O texto do corpo da notificação.
icon Opcional, string

O URL a ser usado para o ícone da notificação.
click_action Opcional, string

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

Um HTTPS é obrigatório para todos os valores de URL.

Interpretar a resposta de uma mensagem XMPP downstream

Na tabela a seguir estão listados os campos mostrados na resposta de uma mensagem XMPP downstream.

Tabela 3 Corpo de resposta da mensagem XMPP downstream.

Parâmetro Uso Descrição
from Obrigatório, string

O remetente da mensagem é especificado nesse parâmetro.

O valor é o token de registro do app cliente.
message_id Obrigatório, string Com esse parâmetro, uma mensagem é identificada de modo exclusivo em uma conexão XMPP. Esse valor é uma string.
message_type Obrigatório, string

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

Quando o valor é definido como nack, o servidor do app verifica error e error_description para receber as informações da falha.

error Opcional, string Um erro relacionado à mensagem downstream é especificado por esse parâmetro. É definido quando message_type é nack. Consulte detalhes na tabela 4.
error_description Opcional, string Informações descritivas do erro são fornecidas por esse parâmetro. É definido quando message_type é nack.

Códigos de resposta de erro de mensagens downstream

Na tabela a seguir, estão listados 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 não encontrado INVALID_JSON Verifique se a solicitação contém um token de registro (no registration_id em uma mensagem de texto sem formatação ou no campo to ou registration_ids no JSON).
Registro inválido de APNs INVALID_JSON Para registros do 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. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncagem nem adicione caracteres adicionais.
Dispositivo não registrado DEVICE_UNREGISTERED Um token de registro existente pode deixar de ser válido em diversas situações, incluindo:
  • Se o app cliente cancelar o registro com o FCM.
  • Se o app cliente tiver o registro cancelado automaticamente, algo que pode ocorrer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, isso ocorre se o token dos APNs é considerado inválido nos APNs.
  • Quando o token de registro expira. Por exemplo, isso ocorre se o Google atualizar os tokens de registro ou se o token de APNs tiver expirado para dispositivos.
  • Quando o app cliente está atualizado, mas a nova versão não está configurada para receber mensagens.
Para todos esses casos, remova o token de registro do servidor do app e pare de utilizá-lo para enviar mensagens.
Remetente incompatível SENDER_ID_MISMATCH Um token de registro está vinculado a um determinado grupo de remetentes. Quando um app cliente se registra no FCM, ele precisa especificar os remetentes autorizados para enviar mensagens. Use um desses IDs de remetente ao enviar mensagens ao app cliente. Quando você muda para outro remetente, os tokens de registro existentes não funcionam.
JSON inválido INVALID_JSON Verifique se a mensagem JSON está formatada corretamente e contém campos válidos. Por exemplo, verifique se o tipo de dados correto é transmitido.
Mensagem grande demais INVALID_JSON Verifique se o tamanho total dos dados de payload 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 do payload não têm uma chave usada internamente pelo FCM, como from, gcm ou qualquer valor com prefixo google. Observe que algumas palavras como collapse_key também são usadas pelo FCM, mas são permitidas no payload. Nesse caso, o valor do payload é modificado pelo valor do FCM.
Time to live (TTL) inválida INVALID_JSON Verifique se o valor usado no 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á devidamente formatada antes de tentar novamente. Consulte detalhes na tabela 6.
Tempo limite SERVICE_UNAVAILABLE

A solicitação não foi processada a tempo no servidor. Tente enviar a mesma solicitação novamente. Para isso, é necessário:

  • Implementar uma espera exponencial no mecanismo de nova tentativa. Por exemplo, se você esperou um segundo antes da primeira nova tentativa, aguarde pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante. Se estiver enviando várias mensagens, atrase cada uma de maneira independente por um período aleatório adicional para evitar emitir uma nova solicitação para todas as mensagens ao mesmo tempo.
  • Definir o atraso inicial para a nova tentativa como 1 segundo.

Observação: os remetentes que causam problemas podem ser incluídos na lista negra.
Erro interno do servidor INTERNAL_SERVER_
ERROR		 Ocorreu um erro no servidor ao tentar processar a solicitação. Tente realizar a mesma solicitação novamente seguindo os requisitos listados em "Tempo limite" (consulte 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 a esse dispositivo e não tente reenviar mensagens a esse dispositivo imediatamente.
Taxa de mensagens de tópico excedida TOPICS_MESSAGE_RATE
_EXCEEDED		 A taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas para esse tópico e não tente reenviar mensagens imediatamente.
Diminuição de conexão CONNECTION_DRAINING Não foi possível processar a mensagem porque a conexão está reduzida. Isso acontece porque o FCM precisa encerrar uma conexão para fazer o balanceamento de carga. Tente reenviar a mensagem por outra conexão XMPP.
Credenciais inválidas de APNs INVALID_APNS_CREDENTIAL Uma mensagem direcionada a um dispositivo iOS não foi enviada porque a chave de autenticação de APNs necessária não foi carregada ou expirou. Verifique a validade das 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 de push da Web corretos.

Sintaxe da mensagem upstream

Uma mensagem upstream é aquela que o app cliente envia ao servidor do app. Atualmente, só o XMPP é compatível com esse tipo de mensagem. Consulte a documentação da sua plataforma para mais informações sobre o envio de mensagens com os apps cliente.

Interpretar uma mensagem XMPP upstream

Na tabela a seguir, são descritos os campos na estrofe XMPP gerados pelo FCM em resposta a solicitações de mensagens upstream dos apps cliente.

Tabela 5 Mensagens XMPP upstream.

Parâmetro Uso Descrição
from Obrigatório, string

O remetente da mensagem é especificado nesse parâmetro.

O valor é o token de registro do app cliente.
category Obrigatório, string O nome do pacote do app cliente que enviou a mensagem é especificado nesse parâmetro.
message_id Obrigatório, string O código exclusivo da mensagem é especificado nesse parâmetro.
data Opcional, string Os pares de chave/valor de payload da mensagem são especificados nesse parâmetro.

Como enviar mensagens ACK

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

Tabela 6 Resposta da mensagem XMPP upstream.

Parâmetro Uso Descrição
to Obrigatório, string

O destinatário de uma mensagem de resposta é especificado nesse parâmetro.

O valor é, obrigatoriamente, um token de registro do app cliente que enviou a mensagem upstream.
message_id Obrigatório, string A resposta à mensagem específica é determinada nesse parâmetro. O valor precisa ser o message_id da mensagem upstream correspondente.
message_type Obrigatório, string Uma mensagem ack de um servidor do app para o CCS é especificada nesse parâmetro. Para mensagens upstream, defina-o sempre como ack.

Mensagens do servidor do FCM (XMPP)

Essa é uma mensagem enviada do FCM para um servidor do app. Os principais tipos de mensagens que o FCM envia ao servidor do app são:

  • Controle: essas mensagens geradas pelo CCS indicam que uma ação do servidor do app é obrigatória.

Na tabela a seguir, são descritos os campos incluídos nas mensagens que o CCS envia para um servidor do app.

Tabela 7 mensagens de controle do FCM (XMPP).

Parâmetro Uso Descrição
Campo comum
message_type Obrigatório, string

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

Ele é definido como control para indicar que a mensagem original control_type foi recebida pelo dispositivo.
control_type Opcional, string

O tipo de mensagem de controle enviada a partir do FCM é especificado nesse parâmetro.

Atualmente, somente CONNECTION_DRAINING é aceito. O FCM envia essa mensagem de controle antes de encerrar uma conexão para fazer o balanceamento de carga. À medida que a conexão é diminuída, as novas mensagens não podem ser enviadas a ela, mas as que já estão no pipeline continuam sendo processadas.