Sobre as mensagens do FCM

Firebase Cloud Messaging (FCM) oferece várias opções de mensagens e funções. As informações nesta página têm o objetivo de ajudar você a entender os diferentes tipos de mensagem do FCM e o que você pode fazer com elas.

Mensagens de notificação com payload de dados opcional

Seja programaticamente ou por meio do Console do Firebase, você pode enviar mensagens de notificação que contenham um payload opcional de pares de chave-valor personalizados. No Editor do Notificações (em inglês), use os campos Dados personalizados nas Opções avançadas.

O comportamento do app que recebe mensagens com payloads de notificação e dados depende de o app estar em primeiro ou segundo plano. Ou seja, se está ou não ativo quando recebe as mensagens.

  • Quando estão em segundo plano, os apps recebem o payload de notificação na bandeja de notificações e processam apenas o payload de dados quando o usuário toca na notificação.
  • Quando estão em primeiro plano, os apps recebem um objeto de mensagem com os dois payloads disponíveis.

Esta é uma mensagem com formatação JSON que contém as chaves notification e data:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Opções de entrega

O FCM fornece um conjunto específico de opções de entrega para mensagens enviadas para dispositivos Android e permite opções semelhantes nas plataformas Apple e Web. Por exemplo, o comportamento de mensagem "recolhível" é aceito no Android via collapse_key do FCM, na Apple via apns-collapse-id e em JavaScript/Web via Topic. Para mais detalhes, veja as descrições nesta seção e a documentação de referência relacionada.

Como definir a prioridade de uma mensagem

Você tem duas opções para atribuir a prioridade de entrega para mensagens downstream: prioridade normal e alta. Embora o comportamento seja um pouco diferente entre as plataformas, a entrega de mensagens de prioridade normal e alta funciona assim:

  • Prioridade normal. As mensagens com prioridade normal são entregues imediatamente quando o app está em primeiro plano. Para apps em segundo plano, a entrega pode ser adiada. Para mensagens menos afetadas pelo tempo, como enviar notificações de novos e-mails, manter a sincronização da sua IU ou sincronizar os dados do app em segundo plano, escolha a prioridade normal de entrega.

  • Prioridade alta. O FCM tenta enviar mensagens de prioridade alta imediatamente, mesmo quando o dispositivo está no modo Soneca. As mensagens de prioridade alta são voltadas para conteúdo visível ao usuário e urgente.

Veja um exemplo de uma mensagem de prioridade normal enviada por meio do protocolo HTTP v1 do FCM para notificar um assinante de revista que um novo conteúdo está disponível para download:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

Para mais detalhes específicos da plataforma na definição da prioridade da mensagem:

Casos de uso de missão crítica

As APIs FCM não estão projetadas para alertas de emergência ou outras atividades de alto risco em que o uso ou a falha das APIs possa resultar em morte, ferimentos em pessoas ou ambientes (como operação de instalações nucleares, controle de tráfego aéreo ou de suporte vital). Qualquer uso desse tipo é expressamente proibido sob a Seção 4. a. 7 dos Termos de Serviço. Você é o único responsável por gerenciar a conformidade do app com os Termos e por qualquer dano resultante da não conformidade. O Google fornece as APIs "no estado em que se encontram" e se reserva o direito de desativá-las ou qualquer parte, recurso ou acesso a elas, por qualquer motivo e a qualquer momento, sem responsabilidade ou outra obrigação para com você ou seus usuários.

Definir a vida útil de uma mensagem

O FCM geralmente entrega mensagens imediatamente após elas terem sido enviadas. No entanto, isso nem sempre é possível. Por exemplo, se a plataforma for Android, o dispositivo poderá estar desligado, desconectado ou indisponível de alguma forma. O FCM pode atrasar mensagens intencionalmente para evitar que um app consuma recursos excessivos, o que prejudica a duração da bateria.

Quando isso acontece, o FCM armazena a mensagem e a entrega o quanto antes. Embora isso não seja um problema na maioria dos casos, em alguns apps é possível que as mensagens atrasadas não sejam entregues. Por exemplo, se a mensagem for uma notificação de chat por vídeo ou uma chamada recebida, ela só vai ser relevante por um breve período até o encerramento da chamada. Se a mensagem for um convite para um evento, ela será inútil se for recebida após o término do evento.

No Android e na Web/em JavaScript, é possível especificar a vida útil máxima de uma mensagem. O valor precisa ter a duração de 0 a 2.419.200 segundos (28 dias) e corresponde ao período máximo pelo qual o FCM armazena e tenta entregar a mensagem. Para as solicitações que não tiverem esse campo preenchido, será usado o valor padrão do período máximo de quatro semanas.

Veja aqui alguns usos possíveis para este recurso:

  • Chamadas de bate-papo por vídeo recebidas
  • Eventos de convite expirando
  • Eventos da agenda

Outra vantagem de especificar a vida útil de uma mensagem é que o FCM não aplica o limite de mensagens colapsáveis a mensagens com um valor de vida útil de 0 segundos. O FCM lida com as mensagens que precisam ser entregues "agora ou nunca". Tenha em mente que um valor time_to_live de 0 significa que mensagens que não podem ser entregues imediatamente são descartadas. No entanto, como essas mensagens nunca são armazenadas, isso gera a melhor latência para o envio de mensagens de notificação.

Veja um exemplo de solicitação que inclui TTL:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

Vida útil de uma mensagem

Quando um servidor do app publica uma mensagem para o FCM e recebe um ID de mensagem de volta, isso não significa que a mensagem já foi entregue ao dispositivo. Na verdade, significa que ela foi aceita para a entrega. O que acontece com a mensagem após a aceitação depende de muitos fatores.

Em uma situação ideal, se o dispositivo estiver conectado ao FCM, a tela estiver ativada e não houver restrições de limite, a mensagem será entregue imediatamente.

Se o dispositivo estiver conectado, mas no modo Soneca, uma mensagem de prioridade baixa é armazenada pelo FCM até o dispositivo sair desse modo. É nesse momento que a sinalização collapse_key desempenha um papel: se já houver uma mensagem com a mesma chave de recolhimento (e token de registro) armazenada e aguardando a entrega, a mensagem antiga será descartada e a nova tomará o lugar dela. Ou seja, a mensagem antiga será recolhida pela nova. No entanto, se a chave de recolhimento não estiver definida, as mensagens novas e antigas serão armazenadas para entrega posterior.

Se o dispositivo não estiver conectado ao FCM, a mensagem será armazenada até que uma conexão seja estabelecida (respeitando novamente as regras da chave de recolhimento). Quando uma conexão é estabelecida, o FCM entrega todas as mensagens pendentes ao dispositivo. Se o dispositivo não se reconectar (por exemplo, se for redefinido para os padrões de fábrica), a mensagem acabará expirando e será descartada do armazenamento do FCM. O tempo limite padrão é de quatro semanas, a menos que a sinalização time_to_live esteja definida.

Para mais informações sobre a entrega de uma mensagem:

    Para mais informações sobre a entrega de mensagens no Android ou Apple, consulte o painel de geração de relatórios do FCM, que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android, além de dados para "impressões" (notificações vistas pelos usuários) de apps Android.

Para dispositivos Android com mensagens de canal direto ativadas, se o dispositivo não estiver conectado ao FCM por mais de um mês, o FCM ainda vai aceitar a mensagem, mas vai descartá-la imediatamente. Se o dispositivo se conectar dentro de quatro semanas a partir da última mensagem de dados enviada a ele, o cliente receberá a callback onDeletedMessages(). O app pode então processar a situação da maneira correta, normalmente solicitando uma sincronização completa do servidor do app.

Por fim, se o FCM tentar entregar uma mensagem ao dispositivo e o app tiver sido desinstalado, o FCM vai descartar a mensagem imediatamente e invalidar o token de registro. As próximas tentativas de enviar uma mensagem a esse dispositivo resultarão em um erro NotRegistered.

Credenciais

Dependendo dos recursos do FCM implementados, as seguintes credenciais do projeto do Firebase podem ser necessárias:

ID do projeto Um identificador exclusivo do projeto do Firebase usado em solicitações para o endpoint HTTP v1 do FCM. Esse valor está disponível no painel painel Configurações do Console do Firebase.
Token de registro

Uma string de token exclusiva que identifica cada instância do app cliente. O token de registro é necessário para mensagens para dispositivos únicos e grupos de dispositivos. Observe que os tokens de registro precisam ser mantidos em segredo.
Código do remetente Um valor numérico exclusivo gerado quando você cria o projeto do Firebase. disponível na guia Cloud Messaging do painel Configurações do Console do Firebase. O ID do remetente é usado para identificar cada remetente que pode enviar mensagens ao app cliente.
Token de acesso Um token OAuth 2.0 de curta duração que autoriza solicitações para a API HTTP v1. Esse token está associado a uma conta de serviço que pertence ao seu projeto do Firebase. Para criar e alternar tokens de acesso, siga as etapas descritas em Autorizar solicitações de envio.