Ir para o console

Noções básicas sobre o envio de mensagens

Com o FCM, você tem ferramentas para acessar informações sobre a entrega de mensagens. Além dos relatórios de entrega e da análise de funil de notificação integrados ao Console do Firebase, o FCM oferece uma exportação de dados abrangente para o Google BigQuery.

A geração de relatórios de muitas das estatísticas nesta página está sujeita a atrasos de até 24 horas devido ao agrupamento de dados de análise.

Relatórios de entrega de mensagens

É possível avaliar se as mensagens enviadas atingem seus usuários. Na guia Relatórios Console do Firebase, é possível visualizar os seguintes dados sobre mensagens enviadas para SDKs do FCM para Android ou iOS, incluindo as enviadas pelo Editor do Notificações e pelas APIs do FCM:

  • Envios: a mensagem de dados ou de notificação foi enfileirada ou transmitida para entrega a um serviço de terceiros, como APNs. Para mais informações, consulte Vida útil de uma mensagem.
  • Recebidas (disponível apenas em dispositivos Android): a mensagem de dados ou de notificação foi recebida pelo aplicativo. Esses dados estarão disponíveis se o dispositivo Android receptor tiver a versão 18.0.1 do SDK do FCM ou posterior instalada.
  • Impressões (disponível apenas para mensagens de notificação em dispositivos Android): a notificação de exibição foi exibida no dispositivo enquanto o aplicativo estava em segundo plano.
  • Aberturas: o usuário abriu a mensagem de notificação. Informado apenas para notificações recebidas enquanto o aplicativo estava em segundo plano.

Esses dados estão disponíveis para todas as mensagens com um payload de notificação e todas as mensagens de dados com rótulo. Para saber mais sobre rótulos, consulte Como adicionar rótulos de análise às mensagens.

Ao visualizar relatórios de mensagens, é possível definir um período para os dados exibidos, com a opção de exportar para um arquivo CSV. Também é possível filtrar por estes critérios:

  • Plataforma (iOS ou Android)
  • App
  • Rótulos de análise personalizados

Como adicionar rótulos de análise às mensagens

A rotulação de mensagens é muito útil para a realização de análises personalizadas. Ao fazer isso, é possível filtrar estatísticas de entrega por rótulos ou conjuntos de rótulos. Para adicionar um rótulo a qualquer mensagem enviada por meio da API HTTP v1, basta definir o campo fcmOptions.analyticsLabel no objeto message (em inglês) ou nos campos AndroidFcmOptions ou ApnsFcmOptions específicos da plataforma.

Os rótulos de análise são strings de texto no formato ^[a-zA-Z0-9-_.~%]{1,50}$. Os rótulos podem incluir letras maiúsculas e minúsculas, números e os seguintes símbolos:

  • -
  • ~
  • %

O comprimento máximo é de 50 caracteres. É possível especificar até 100 rótulos exclusivos por dia. As mensagens que receberem rótulos além desse limite não serão informadas.

Na guia Relatórios de mensagem do Console do Firebase, é possível pesquisar uma lista de todos os rótulos existentes e aplicá-los sozinhos ou em conjunto para filtrar as estatísticas exibidas.

Análise do funil de notificação

Com a integração da análise do funil do Notificações, você observa como seus usuários respondem a determinadas notificações enviadas do Console do Firebase. Essa visualização inclui dados para dispositivos iOS e Android segmentados nestas categorias:

  • Notificações enviadas: a mensagem foi enfileirada ou transmitida para entrega a um serviço de terceiros, como APNs. A segmentação de tokens obsoletos ou registros inativos pode aumentar essas estatísticas.
  • Notificações abertas: o número de notificações abertas. Informado apenas para notificações recebidas enquanto o aplicativo estava em segundo plano.
  • O número de usuários únicos que acionaram um evento de conversão, se houver um evento definido.

Para ver a análise do funil do Notificações, faça o seguinte:

  1. No Editor do Notificações, selecione a guia Notificações.
  2. Clique em uma mensagem concluída ou em andamento na lista de mensagens. Uma visualização expandida com uma análise do funil é exibida.

Os relatórios do Analytics são atualizados periodicamente, mas pode haver um atraso entre o momento em que o usuário abre a notificação e a disponibilização dos dados do evento no console. Além desses relatórios na guia Notificações, também é possível criar funis personalizados no Google Analytics para visualizar a taxa de conclusão de uma sequência de etapas no seu app.

Exportação de dados do BigQuery

É possível exportar os dados da sua mensagem ao BigQuery para uma análise mais detalhada. Com isso, você pode fazer análises usando o BigQuery SQL, exportar os dados para outro provedor de nuvem ou usá-los para seus modelos personalizados de ML. Uma exportação para o BigQuery inclui todas as mensagens, independentemente da plataforma, tipo de mensagem ou se a mensagem é enviada por meio da API ou do Editor do Notificações.

Consulte a página Vincular o Firebase ao BigQuery para mais informações.

  1. Para começar, use uma das seguintes opções:

    • Abra o Editor do Notificações (em inglês) e selecione Vincular BigQuery na parte inferior da página.

    • Na página Integrações (em inglês) no Console do Firebase, clique em Vincular no cartão do BigQuery.

      Veja nesta página as opções de exportação do FCM para todos os aplicativos habilitados esse serviço no projeto.

  2. Siga as instruções na tela para ativar o BigQuery.

Quando você vincula seu projeto ao BigQuery:

  • o Firebase exporta seus dados para o BigQuery;

  • o Firebase configura sincronizações regulares dos dados do projeto do Firebase para o BigQuery;

  • todos os apps no projeto são vinculados ao BigQuery por padrão, e todos os apps adicionados posteriormente ao projeto são vinculados automaticamente ao BigQuery. É possível gerenciar quais apps enviam dados.

Para desativar a exportação do BigQuery, desvincule seu projeto no Console do Firebase.

Quais dados são exportados para o BigQuery?

A segmentação de tokens obsoletos ou registros inativos pode aumentar algumas dessas estatísticas.

Veja a seguir o esquema da tabela exportada:

_PARTITIONTIME TIMESTAMP Essa pseudocoluna contém um carimbo de data/hora para o início do dia, no fuso horário UTC. Essa data e hora representam o momento em que os dados foram carregados. Para a partição AAAAMMDD, essa pseudocoluna contém o valor TIMESTAMP('AAAA-MM-DD').
event_timestamp TIMESTAMP É o carimbo de data/hora do evento conforme registrado pelo servidor.
project_number INTEGER Esse número identifica o projeto que enviou a mensagem.
message_id STRING O ID da mensagem identifica uma mensagem. Gerado usando o ID do aplicativo e do carimbo de data/hora. O ID da mensagem pode, em alguns casos, não ser exclusivo globalmente.
instance_id STRING É o código da instância do app para onde a mensagem é enviada (quando disponível).
message_type STRING É o tipo de mensagem. Pode ser uma mensagem de notificação ou de dados. O tópico é usado para identificar a mensagem original em um envio de tópico ou campanha. As mensagens subsequentes são mensagens de notificação ou de dados.
sdk_platform STRING É a plataforma do aplicativo do destinatário.
app_name STRING É o nome do pacote de apps para Android ou o ID do pacote de apps para iOS.
collapse_key STRING A chave de recolhimento identifica um grupo de mensagens que podem ser recolhidas. Quando um dispositivo não está conectado, apenas a última mensagem com uma determinada chave de recolhimento é enfileirada para eventual entrega.
priority INTEGER É 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.
ttl INTEGER Esse parâmetro especifica por quanto tempo (em segundos) a mensagem deverá ser mantida no armazenamento do FCM se o dispositivo ficar off-line.
topic STRING É o nome do tópico para o qual uma mensagem foi enviada (quando aplicável).
bulk_id INTEGER O código em massa identifica um grupo de mensagens relacionadas, como um envio específico para um tópico.
device_recently_active BOOLEAN Esse parâmetro será verdadeiro se o dispositivo tiver se conectado recentemente.
event STRING O tipo do evento. Estes são os valores possíveis:
  • MESSAGE_ACCEPTED: a mensagem foi recebida pelo servidor do FCM, e o pedido é válido.
  • MESSAGE_DELIVERED: a mensagem foi enviada para o dispositivo.
  • MESSAGE_DELIVERED_ON_RECONNECT: a mensagem foi enviada para o dispositivo quando o dispositivo foi reconectado.
  • MISSING_REGISTRATIONS: o pedido foi rejeitado devido a um registro faltando.
  • MESSAGE_EXPIRED: a mensagem expirou antes que o dispositivo fosse conectado e a mensagem pudesse ser entregue.
  • MESSAGE_DELAYED_DOZE: a entrega da mensagem para o dispositivo foi atrasada porque o dispositivo está no modo "Soneca".
  • UNAUTHORIZED_REGISTRATION: a mensagem foi rejeitada porque o remetente não está autorizado a enviar para o registro.
  • MESSAGE_COLLAPSED: a mensagem foi substituída por uma mensagem mais recente com a mesma chave de recolhimento antes que ela pudesse ser entregue.
  • MESSAGE_RECEIVED_INTERNAL_ERROR: ocorreu um erro não especificado ao processar a solicitação de mensagem.
  • MESSAGE_DELAYED_THROTTLED: a entrega da mensagem para o dispositivo foi atrasada devido à limitação de sua chave de recolhimento.
  • MISMATCH_SENDER_ID: a solicitação de envio de uma mensagem foi rejeitada devido a uma incompatibilidade entre o código do remetente que enviou a mensagem e a informação declarada ao ponto de extremidade.
  • QUOTA_EXCEEDED: a solicitação de envio de uma mensagem foi rejeitada devido a uma cota insuficiente.
  • INVALID_REGISTRATION: a solicitação de envio de uma mensagem foi rejeitada devido a um registro inválido.
  • INVALID_PACKAGE_NAME: a solicitação de envio de uma mensagem foi rejeitada devido a um nome de pacote inválido.
  • INVALID_APNS_CREDENTIAL: a solicitação de envio de uma mensagem foi rejeitada devido a um certificado inválido de APNs.
  • INVALID_PARAMETERS: a solicitação de envio de uma mensagem foi rejeitada devido a parâmetros inválidos.
  • PAYLOAD_TOO_LARGE: a solicitação de envio de uma mensagem foi rejeitada devido a um payload maior que o limite.
  • DEVICE_NOT_FOUND: a solicitação de envio de uma mensagem foi rejeitada porque o dispositivo não foi encontrado no nosso banco de dados.
  • AUTHENTICATION_ERROR: a solicitação de envio de uma mensagem foi rejeitada devido a um erro de autenticação. Verifique a chave da API usada para enviar a mensagem.
  • INVALID_TTL: a solicitação de envio de uma mensagem foi rejeitada devido a um TTL inválido.
analytics_label STRING Com a [API HTTP v1](/docs/reference/fcm/rest/v1/projects.messages), o rótulo de análise pode ser definido ao enviar a mensagem a fim de marcá-la para fins de análise.

O que você pode fazer com os dados exportados?

Contar mensagens enviadas por app

SELECT app_name, COUNT(1)
FROM [<project name>:firebase_messaging.data]
WHERE
  _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_id != ''
GROUP BY 1;

Contar instâncias de apps exclusivas segmentadas por mensagens

SELECT COUNT(DISTINCT instance_id)
FROM [<project name>:firebase_messaging.data]
WHERE
  _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
  AND event = 'MESSAGE_ACCEPTED';

Contar mensagens de notificação enviadas

SELECT COUNT(1)
FROM [<project name>:firebase_messaging.data]
WHERE
  _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DISPLAY_NOTIFICATION';

Contar mensagens de dados enviadas

SELECT COUNT(1)
FROM [<project name>:firebase_messaging.data]
WHERE
  _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DATA_MESSAGE';

Contar mensagens enviadas para um tópico ou campanha a partir do console de notificações

SELECT COUNT(1)
FROM [<project name>:firebase_messaging.data]
WHERE
  _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
  AND event = 'MESSAGE_ACCEPTED'
  AND bulk_id = <your bulk id> AND message_id != '';

Calcular a duração do fanout para um determinado tópico ou campanha

O horário de início do fanout representa o momento em que a solicitação original é recebida. A hora de término representa o momento da criação da última mensagem individual que segmenta uma instância única.

SELECT
  TIMESTAMP_DIFF(
    end_timestamp, start_timestamp, MILLISECOND
  ) AS fanout_duration_ms,
  end_timestamp,
  start_timestamp
FROM (
    SELECT MAX(event_timestamp) AS end_timestamp
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = <your bulk id>
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS start_timestamp
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = <your bulk id>
      AND message_type = 'TOPIC'
  ) initial_message;

Contar a porcentagem de mensagens entregues

SELECT
  messages_sent,
  messages_delivered,
  messages_delivered / messages_sent * 100 AS percent_delivered
FROM (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_sent
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_delivered
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
      AND (event = 'MESSAGE_DELIVERED' OR event = 'MESSAGE_DELIVERED_ON_RECONNECT')
      AND message_id
      IN (
        SELECT message_id FROM [<project name>:firebase_messaging.data]
        WHERE
          _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
          AND event = 'MESSAGE_ACCEPTED'
        GROUP BY 1
      )
  ) delivered;

Rastrear todos os eventos para um determinado código de mensagem e instância

SELECT *
FROM [<project name>:firebase_messaging.data]
WHERE
    _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
    AND message_id = '<your message id>'
    AND instance_id = '<your instance id>'
ORDER BY event_timestamp;

Calcular a latência de um determinado ID de mensagem e instância

SELECT
  TIMESTAMP_DIFF(
    MAX(delivered_time), MIN(accepted_time), MILLISECOND
  ) AS latency_ms
FROM (
    SELECT event_timestamp AS accepted_time
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>')
      AND message_id = '<your message id>'
      AND instance_id = '<your instance id>'
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS delivered_time
    FROM [<project name>:firebase_messaging.data]
    WHERE
      _PARTITIONTIME = TIMESTAMP('<date as YYYY-MM-DD>') AND
      message_id = '<your message id>' AND instance_id = '<your instance id>'
      AND (event = 'MESSAGE_DELIVERED' OR event = 'MESSAGE_DELIVERED_ON_RECONNECT')
  ) delivered;