Ir para o console

Protocolo XMPP do Firebase Cloud Messaging

Neste documento, você encontra uma referência para a sintaxe XMPP usada para passar mensagens entre o servidor do app, os apps cliente e o Firebase Cloud Messaging (FCM). O servidor do app precisa se conectar a estes pontos de extremidade:

// 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 da 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 aceitos: &&, ||. 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

Com esse parâmetro, você identifica um grupo de mensagens (por exemplo, com collapse_key: "Updates Available") que podem ser recolhidas para que apenas a última mensagem 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.

Observação: 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). No iOS, 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

No iOS, 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 meio de APNs como uma notificação silenciosa e não por meio do servidor de conexão 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 aplicativo 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

Atualmente, apenas para dispositivos iOS 10 ou posteriores. No iOS, 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 meio de 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

Com esse parâmetro, você especifica o tempo, em segundos, de manutenção da mensagem no armazenamento do FCM, caso o dispositivo esteja off-line. A vida útil máxima permitida é quatro semanas e esse também é o valor padrão. Para mais informações, consulte Como configurar a vida útil de uma mensagem.

delivery_receipt_
requested
Opcional, booleano

Com esse parâmetro, você define se o servidor do app solicita a confirmação de entrega da mensagem.

Quando ele é definido como true, um comprovante de entrega é enviado pelo FCM no momento em que o recebimento da mensagem é confirmado no dispositivo.

Observação: esse parâmetro não é compatível com mensagens enviadas para dispositivos iOS. O valor padrão é false.

dry_run Opcional, booleano

Com esse parâmetro definido como true, você permite que os desenvolvedores testem uma solicitação sem realmente enviar uma mensagem.

O valor padrão é false.

Payload
data Opcional, objeto

Os pares de chave/valor de payload da mensagem são especificados nesse parâmetro.

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

No iOS, se a mensagem é enviada por meio de APNs, ela é representada por campos de dados personalizados. Quando ela é enviada pelo FCM, ela é representada como um dicionário de valores de chave 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. Converta os valores dos objetos ou outros tipos de dados não string (por exemplo, números inteiros ou booleanos) em string.

notification Opcional, objeto Este parâmetro especifica os pares chave/valor visíveis ao usuário e predefinidos do payload da notificação. Consulte a compatibilidade com o payload para mais detalhes. Para mais informações sobre as opções de mensagens de dados e de notificação, consulte Tipos de mensagens. Se um payload de notificação for fornecido ou a opção content_available estiver definida como true para uma mensagem em um dispositivo iOS, a mensagem será enviada por meio de APNs. Caso contrário, ela será enviada por meio do servidor de conexão do FCM.

Compatibilidade com o payload de notificação

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

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

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

O título da notificação.

Este campo não é visível em smartphones e tablets iOS.

body Opcional, string

O texto do corpo da notificação.

sound Opcional, string ou dicionário

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 (em inglês).

Para notificações críticas, use um dicionário que contenha informações de som para alertas críticos. Consulte a biblioteca de desenvolvedores do iOS para acessar as chaves necessárias. Para notificações regulares, use a string de som.

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 (ambos em inglês).

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 (ambos em inglês).

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 (ambos em inglês).

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 (ambos em inglês).

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 envia 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. Os arquivos de som precisam estar 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 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 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. Isso pode ser encontrado no registration_id em uma mensagem de texto sem formatação ou no JSON, no campo to ou registration_ids.
Token de registro inválido BAD_REGISTRATION Verifique o formato do token de registro que você passa ao servidor. Ele precisa corresponder ao token de registro que o app cliente recebe quando se registra no FCM. Não trunque nem adicione outros caracteres.
Dispositivo não registrado DEVICE_UNREGISTERED Um token de registro existente pode deixar de ser válido em diversos cenários como:
  • quando o app cliente cancela o registro com o FCM;
  • quando o app cliente tem o registro cancelado automaticamente, o que pode ocorrer se o usuário desinstala o app. Por exemplo, no iOS, isso ocorre se o token dos APNs é considerado inválido nos APNs;
  • quando o token de registro expira, por exemplo, se o Google decide atualizar os tokens de registro, ou o token dos APNs expira para os dispositivos iOS;
  • 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 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 app cliente se registra no FCM, os remetentes autorizados a enviar mensagens precisam ser especificados. 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, se o tipo de dados passado está correto.
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 google como prefixo. 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 é substituído pelo valor do FCM.
Vida útil 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 os 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 o backoff exponencial no mecanismo de nova tentativa. Por exemplo, se você esperou 1 segundo antes de tentar novamente pela primeira vez, aguarde pelo menos 2 segundos antes da próxima, depois 4 segundos e assim por diante. Se você está enviando várias mensagens, atrase cada uma de maneira independente. Para isso, use um tempo aleatório como intervalo para evitar que todas as novas solicitações sejam emitidas 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 quando ele tentou processar a solicitação. Tente novamente seguindo os requisitos listados em "Tempo limite", na linha acima.
Taxa de mensagens do dispositivo excedida DEVICE_MESSAGE_RATE
_EXCEEDED
A taxa de mensagens de um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviá-las imediatamente para ele.
Taxa de mensagens de tópico excedida TOPICS_MESSAGE_RATE
_EXCEEDED
A taxa de mensagens enviadas a inscritos em determinado tópico é muito alta. Reduza o número de mensagens enviadas para esse tópico e não tente reenviá-las 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.

Sintaxe de mensagens 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.

Interpretação de mensagens 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.

Envio de 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 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:

  • Comprovante de entrega: se o servidor do app incluiu delivery_receipt_requested na mensagem downstream, um comprovante de entrega será enviado pelo FCM após a confirmação de que o dispositivo recebeu a mensagem.
  • 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

Esse parâmetro especifica o tipo de mensagem: comprovante de entrega ou controle.

Quando está definido como receipt, a mensagem inclui os campos from, message_id, category e data para fornecer informações adicionais.

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

Específico do comprovante de entrega
from Obrigatório, string Esse parâmetro é definido como gcm.googleapis.com, indicando que a mensagem foi enviada a partir do FCM.
message_id Obrigatório, string O ID da mensagem original à qual o comprovante se refere é especificado nesse parâmetro. Ele tem dr2: como prefixo para indicar que a mensagem é um comprovante de entrega. Uma mensagem ack com esse ID precisa ser enviada pelo servidor do app para confirmar o recebimento do comprovante. Consulte a tabela 6 para o formato de mensagem ack.
category Opcional, string O nome do pacote do app cliente que recebe a mensagem à qual esse comprovante de entrega se refere é especificado nesse parâmetro. Disponível quando message_type é receipt.
data Opcional, string Os pares de chave-valor para a mensagem do comprovante de entrega são especificados nesse parâmetro. Disponível quando o tipo de mensagem é receipt.
  • message_status: o status da mensagem do comprovante é especificado nesse parâmetro. Ele é definido como MESSAGE_SENT_TO_DEVICE para indicar que a mensagem original foi recebida pelo dispositivo.
  • original_message_id: o ID da mensagem original enviada do servidor do app para o app cliente é especificado nesse parâmetro.
  • device_registration_id: o token de registro do app cliente para o qual a mensagem original foi enviada é especificado nesse parâmetro.
Específico de controle
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.