Informazioni sulla consegna dei messaggi

FCM fornisce tre insiemi di strumenti per aiutarti a ottenere informazioni sulla consegna dei messaggi:

• Firebase report sulla consegna dei messaggi della console
• Metriche aggregate relative alla pubblicazione dell'SDK Android dall'Firebase Cloud Messaging API di dati
• Esportazione completa dei dati in Google BigQuery

Per funzionare, tutti gli strumenti di generazione di report descritti in questa pagina richiedono Google Analytics. Se Google Analytics non è abilitato per il tuo progetto, puoi configurarlo nella scheda Integrazioni delle impostazioni del progetto Firebase.

Tieni presente che la generazione di report per molte delle statistiche riportate in questa pagina è soggetta a ritardi fino a 24 ore a causa dell'aggregazione dei dati di analisi.

Report sulla consegna dei messaggi

Nella scheda Report della console Firebase, puoi visualizzare i seguenti dati per i messaggi inviati agli SDK FCM per le piattaforme Android o Apple, inclusi quelli inviati tramite il Compose di Notifiche e le API FCM:

• Invii: il messaggio di dati o di notifica è stato inserito in coda per la consegna o è stato trasmesso correttamente a un servizio di terze parti come gli APN per la consegna. Per saperne di più, consulta la sezione Vita utile di un messaggio.
• Ricevuto (disponibile solo sui dispositivi Android): il messaggio di dati o il messaggio di notifica è stato ricevuto dall'app. Questi dati sono disponibili quando sul dispositivo Android di destinazione è installato l'SDK FCM 18.0.1 o versioni successive.
• Impressioni (disponibile solo per i messaggi di notifica sui dispositivi Android): la notifica è stata visualizzata sul dispositivo mentre l'app era in background.
• Apre: l'utente ha aperto il messaggio di notifica. Registrate solo per le notifiche ricevute quando l'app è in background.

Questi dati sono disponibili per tutti i messaggi con un payload di notifica e per tutti i messaggi di dati etichettati. Per scoprire di più sulle etichette, consulta Aggiungere etichette di analisi ai messaggi.

Quando visualizzi i report sui messaggi, puoi impostare un intervallo di date per i dati visualizzati, con la possibilità di esportarli in formato CSV. Puoi anche filtrare in base ai seguenti criteri:

• Piattaforma (iOS o Android)
• App
• Etichette di analisi personalizzate

Aggiunta di etichette di analisi ai messaggi

L'etichettatura dei messaggi è molto utile per le analisi personalizzate, in quanto consente di filtrare le statistiche di recapito in base a etichette o insiemi di etichette. Puoi aggiungere un'etichetta a qualsiasi messaggio inviato tramite l'API HTTP v1 impostando il campo fcmOptions.analyticsLabel nell'oggetto message o nei campi AndroidFcmOptions o ApnsFcmOptions specifici della piattaforma.

Le etichette di analisi sono stringhe di testo nel formato ^[a-zA-Z0-9-_.~%]{1,50}$. Le etichette possono includere lettere maiuscole e minuscole, numeri e i seguenti simboli:

• -
• ~
• %

La lunghezza massima è di 50 caratteri. Puoi specificare fino a 100 etichette univoche al giorno. I messaggi con etichette aggiunte oltre questo limite non vengono registrati.

Nella scheda Report della messaggistica della Firebaseconsole, puoi cercare un elenco di tutte le etichette esistenti e applicarle singolarmente o in combinazione per filtrare le statistiche visualizzate.

Dati di importazione aggregati tramite l'API FCM Data

L'API Firebase Cloud Messaging Data ti consente di recuperare informazioni che possono aiutarti a comprendere i risultati delle richieste di messaggi indirizzate alle applicazioni Android. L'API fornisce dati aggregati su tutti i dispositivi Android abilitati alla raccolta dei dati in un progetto. Sono inclusi dettagli sulla percentuale di messaggi recapitati senza ritardi, nonché il numero di messaggi che hanno subito ritardi o sono stati persi nel livello di trasporto di Android. La valutazione di questi dati può rivelare tendenze generali nell'invio dei messaggi e aiutarti a trovare modi efficaci per migliorare il rendimento delle richieste di invio. Consulta la sezione Cronologie dei dati aggregati per informazioni sulla disponibilità dell'intervallo di date nei report.

L'API fornisce tutti i dati disponibili per una determinata applicazione. Consulta la documentazione di riferimento dell'API.

Come vengono suddivisi i dati?

I dati di importazione sono suddivisi per applicazione, data ed etichetta di analisi. Una chiamata all'API restituirà dati per ogni combinazione di data, applicazione ed etichetta di analisi. Ad esempio, un singolo oggetto JSON androidDeliveryData ha il seguente aspetto:

 {
  "appId": "1:23456789:android:a93a5mb1234efe56",
  "date": {
    "year": 2021,
    "month": 1,
    "day": 1
  },
  "analyticsLabel": "foo",
  "data": {
    "countMessagesAccepted": "314159",
    "messageOutcomePercents": {
      "delivered": 71,
      "pending": 15
    },
   "deliveryPerformancePercents": {
      "deliveredNoDelay": 45,
      "delayedDeviceOffline": 11
    }
  }

Come interpretare le metriche

I dati di recapito illustrano la percentuale di messaggi che rientrano in ciascuna delle seguenti metriche. È possibile che un singolo messaggio corrisponda a più metriche. A causa delle limitazioni del modo in cui raccogliamo i dati e del livello di granularità a cui abbiamo aggregato le metriche, alcuni risultati dei messaggi non sono affatto rappresentati nelle metriche, pertanto la somma delle percentuali riportate di seguito non corrisponde al 100%.

Contare i messaggi accettati

L'unico conteggio incluso nel set di dati è il numero di messaggi accettati da FCM per la consegna ai dispositivi Android. Tutte le percentuali utilizzano questo valore come denominatore. Tieni presente che questo conteggio non include i messaggi indirizzati agli utenti che hanno disattivato la raccolta delle informazioni di Utilizzo e diagnostica sui loro dispositivi.

Percentuali di risultati dei messaggi

I campi inclusi nell'oggetto MessageOutcomePercents forniscono informazioni sui risultati delle richieste di messaggi. Le categorie sono tutte mutuamente esclusive. Può rispondere a domande come "I miei messaggi vengono recapitati?" e "Qual è la causa dell'interruzione della consegna dei messaggi?"

Ad esempio, un valore elevato per il campo droppedTooManyPendingMessages potrebbe indicare che le istanze dell'app stanno ricevendo volumi di messaggi non comprimibili superiori al limite di 100 messaggi in attesa di FCM. Per ridurre il problema, assicurati che la tua app gestisca le chiamate a onDeletedMessages e valuta la possibilità di inviare messaggi comprimibili. Analogamente, percentuali elevate per droppedDeviceInactive potrebbero indicare la necessità di aggiornare i token di registrazione sul tuo server, rimuovendo i token non validi e annullando la sottoscrizione agli argomenti. Consulta Gestire i token di registrazione FCM per conoscere le best practice in questo ambito.

Percentuali di rendimento della pubblicazione

I campi dell'oggetto DeliveryPerformancePercents forniscono informazioni sui messaggi che sono stati recapitati correttamente. Può rispondere a domande come "I miei messaggi sono in ritardo?" e "Perché i messaggi sono in ritardo?" Ad esempio, un valore elevato per delayedMessageThrottled indica chiaramente che stai superando i limiti massimi per dispositivo, e dovresti regolare la frequenza di invio dei messaggi.

Percentuali di approfondimenti sui messaggi

Questo oggetto fornisce informazioni aggiuntive su tutti gli invii di messaggi. Il campo priorityLowered esprime la percentuale di messaggi accettati la cui prioritaria è stata ridotta da HIGH a NORMAL. Se questo valore è elevato, prova a inviare meno messaggi ad alta priorità o assicurati di visualizzare sempre una notifica quando viene inviato un messaggio ad alta priorità. Per saperne di più, consulta la nostra documentazione sulla priorità dei messaggi

In che modo questi dati sono diversi da quelli esportati in BigQuery?

L'esportazione BigQuery fornisce log dei singoli messaggi relativi all'accettazione dei messaggi da parte del backend FCM e al recapito dei messaggi nell'SDK sul dispositivo (passaggi 2 e 4 dell'architettura FCM). Questi dati sono utili per verificare che i singoli messaggi siano stati accettati e recapitati. Scopri di più sull'esportazione dei dati di BigQuery nella sezione successiva.

Al contrario, l'API di dati Firebase Cloud Messaging fornisce dettagli aggregati su ciò che accade nello specifico nel livello di trasporto Android (o nel passaggio 3 dell'architettura FCM). Questi dati forniscono informazioni specifiche sul recapito dei messaggi dai backend FCM all'SDK Android. È particolarmente utile per mostrare le tendenze relative al motivo per cui i messaggi sono stati ritardati o persi durante questo trasporto.

In alcuni casi, è possibile che i due set di dati non corrispondano esattamente per i seguenti motivi:

• Le metriche aggregate campionano solo una parte di tutti i messaggi
• Le metriche aggregate sono arrotondate
• Non presentiamo le metriche al di sotto di una soglia di privacy
• Una parte dei risultati dei messaggi non è presente a causa di ottimizzazioni nel modo in cui gestiamo l'elevato volume di traffico.

Limitazioni dell'API

Tempistiche dei dati aggregati

L'API restituirà 7 giorni di dati storici; tuttavia, i dati restituiti da questa API saranno in ritardo fino a 5 giorni. Ad esempio, il 20 gennaio saranno disponibili i dati dal 9 al 15 gennaio, ma non dal 16 gennaio in poi. Inoltre, i dati vengono forniti secondo il criterio del "best effort". In caso di interruzione del servizio di invio dei dati, FCM cercherà di correggere il problema in modo da non dover eseguire il backfill dei dati dopo la risoluzione del problema. In caso di interruzioni più lunghe, i dati potrebbero non essere disponibili per una settimana o più.

Copertura dei dati

Le metriche fornite dall'API Firebase Cloud Messaging Data hanno lo scopo di fornire informazioni sulle tendenze generali di recapito dei messaggi. Tuttavia, non coprono al 100% tutti gli scenari di messaggi. I seguenti scenari sono risultati noti non riportati nelle metriche.

Messaggi scaduti

Se la durata (TTL) scade dopo la fine della data del log specificata, il messaggio non verrà conteggiato come droppedTtlExpired in questa data.

Messaggi a dispositivi inattivi

I messaggi inviati a dispositivi inattivi possono o meno essere visualizzati nel set di dati, a seconda del percorso di dati che seguono. Ciò può portare a un conteggio errato nei campi droppedDeviceInactive e pending.

Messaggi a dispositivi con determinate preferenze utente

In base alle loro preferenze, i messaggi degli utenti che hanno disattivato la raccolta di informazioni sull'utilizzo e sulla diagnostica sui propri dispositivi non verranno inclusi nel nostro conteggio.

Arrotondamento e valori minimi

FCM arrotondamento deliberato ed esclude i conteggi in cui i volumi non sono sufficientemente elevati.

Esportazione dei dati di BigQuery

Puoi esportare i dati dei messaggi in BigQuery per ulteriori analisi. BigQuery consente di analizzare i dati utilizzando BigQuery SQL, esportarli in un altro fornitore cloud o utilizzarli per i modelli ML personalizzati. Un'esportazione in BigQuery include tutti i dati disponibili per i messaggi, indipendentemente dal tipo di messaggio o dal fatto che il messaggio venga inviato tramite l'API o il riquadro di composizione delle notifiche.

Per i messaggi inviati ai dispositivi con le seguenti versioni minime dell'SDK FCM, hai la possibilità aggiuntiva di attivare l'esportazione dei dati di recapito dei messaggi per la tua app:

• Android 20.1.0 o versioni successive.
• iOS 8.6.0 o versioni successive
• SDK web di Firebase 9.0.0 o versioni successive

Di seguito sono riportati i dettagli per attivare l'esportazione dei dati per Android e iOS.

Per iniziare, collega il progetto a BigQuery:

1. Scegli una delle seguenti opzioni:

   • Apri lo strumento per la creazione di notifiche, quindi fai clic su Accedi a BigQuery in fondo alla pagina.

   • Nella pagina Integrazioni della console Firebase, fai clic su Collega nella scheda BigQuery.

     Questa pagina mostra le opzioni di esportazione di FCM per tutte le app FCM abilitate nel progetto.

2. Segui le istruzioni sullo schermo per attivare BigQuery.

Per ulteriori informazioni, consulta Collegare Firebase a BigQuery.

Quando attivi l'esportazione di BigQuery per Cloud Messaging:

• Firebase esporta i tuoi dati in BigQuery. Tieni presente che la propagazione iniziale dei dati per l'esportazione può richiedere fino a 48 ore.

  • Puoi pianificare manualmente i backfill dei dati fino agli ultimi 30 giorni.

• Dopo la creazione del set di dati, la località non può essere modificata, ma puoi copiarlo in un'altra posizione o spostarlo (ricrearlo) manualmente in un'altra posizione. Per saperne di più, consulta Modificare la posizione del set di dati.

• Firebase configura sincronizzazioni regolari dei dati dal progetto Firebase a BigQuery. Queste operazioni di esportazione giornaliere iniziano alle 04:00 (ora del Pacifico USA) e di solito terminano entro 24 ore.

• Per impostazione predefinita, tutte le app del progetto sono collegate a BigQuery e qualsiasi app che aggiungi in seguito viene collegata automaticamente a BigQuery. Puoi gestire le app che inviano dati.

Per disattivare l'esportazione di BigQuery, scollega il progetto nella console Firebase.

Attivare l'esportazione dei dati di recapito dei messaggi

I dispositivi iOS con l'SDK FCM 8.6.0 o versioni successive possono attivare l'esportazione dei dati di recapito dei messaggi della propria app. FCM supporta l'esportazione dei dati sia per le notifiche di avviso sia per quelle in background. Prima di attivare queste opzioni, devi creare il FCMcollegamento a BigQuery per il tuo progetto come descritto in Esportazione dei dati di BigQuery.

Attivare l'esportazione dei dati di recapito per le notifiche di avviso

Poiché solo le notifiche di avviso possono attivare le estensioni di app per i servizi di notifica, devi aggiungere un'estensione di servizio di notifica alla tua app e chiamare questa API all'interno di un'estensione di servizio per attivare il monitoraggio dei messaggi visualizzati. Consulta la documentazione di Apple su come modificare i contenuti nelle notifiche appena inviate.

La chiamata seguente deve essere effettuata per ogni notifica ricevuta:

// For alert notifications, call the API inside the service extension:
class NotificationService: UNNotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
  Messaging.extensionHelper()
      .exportDeliveryMetricsToBigQuery(withMessageInfo:request.content.userInfo)
  }
}

// For alert notifications, call the API inside the service extension:
@implementation NotificationService
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                   withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:request.content.userInfo];
}
@end

Se stai creando richieste di invio utilizzando l'API HTTP v1, assicurati di specificare mutable-content = 1 nell'oggetto del payload.

Attivare l'esportazione dei dati di recapito per le notifiche in background

Per i messaggi in background ricevuti quando l'app è in primo piano o in background, puoi chiamare l'API di esportazione dei dati all'interno del gestore dei messaggi di dati dell'app principale. Questa chiamata deve essere effettuata per ogni notifica ricevuta:

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
  Messaging.extensionHelper().exportDeliveryMetricsToBigQuery(withMessageInfo:userInfo)
}

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
@implementation AppDelegate
- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:userInfo];
}
@end

Quali dati vengono esportati in BigQuery?

Tieni presente che il targeting di token non validi o registrazioni non attive potrebbe gonfiare alcune di queste statistiche.

Lo schema della tabella esportata è:

Che cosa puoi fare con i dati esportati?

Le sezioni seguenti forniscono esempi di query che puoi eseguire in BigQuery sui dati FCM esportati.

Contare i messaggi inviati per app

SELECT app_name, COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_id != ''
GROUP BY 1;

Conteggiare le istanze di app univoche scelte come target dai messaggi

SELECT COUNT(DISTINCT instance_id)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED';

Contare i messaggi di notifica inviati

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DISPLAY_NOTIFICATION';

Contare i messaggi di dati inviati

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DATA_MESSAGE';

Contare i messaggi inviati a un argomento o a una campagna

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND bulk_id = your bulk id AND message_id != '';

Per monitorare gli eventi relativi a un messaggio inviato a un determinato argomento, modifica questa query sostituendo AND message_id != '' con AND message_id = <your message id>;.

Calcolare la durata del fanout per un determinato argomento o campagna

L'ora di inizio del fanout corrisponde al momento in cui viene ricevuta la richiesta originale e l'ora di fine corrisponde al momento in cui viene creato l'ultimo messaggio singolo che ha come target una singola istanza.

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 ID.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 ID.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;

Contare la percentuale di messaggi recapitati

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 ID.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 ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND (event = 'MESSAGE_DELIVERED'
      AND message_id
      IN (
        SELECT message_id FROM `project ID.firebase_messaging.data`
        WHERE
          _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
          AND event = 'MESSAGE_ACCEPTED'
        GROUP BY 1
      )
  ) delivered;

Monitorare tutti gli eventi per un determinato ID messaggio e ID istanza

SELECT *
FROM `project ID.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;

Calcola la latenza per un determinato ID messaggio e ID istanza

SELECT
  TIMESTAMP_DIFF(
    MAX(delivered_time), MIN(accepted_time), MILLISECOND
  ) AS latency_ms
FROM (
    SELECT event_timestamp AS accepted_time
    FROM `project ID.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 ID.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'
  ) delivered;