Informazioni sulla consegna dei messaggi

Per risolvere i problemi di pubblicazione dei messaggi in corso, utilizza lo strumento per la risoluzione dei problemi di FCM e consulta questo blog post per comprendere i diversi motivi per cui potresti non visualizzare il messaggio. Puoi anche visitare la dashboard dello stato di FCM per identificare eventuali interruzioni del servizio in corso che interessano FCM.

FCM fornisce anche tre set di strumenti per aiutarti a ottenere insight su una valutazione generale del successo e della strategia di messaggistica:

• Report Consegna messaggi della console Firebase
• Metriche di pubblicazione dell'SDK Android aggregate dall'API di dati Firebase Cloud Messaging
• Esportazione completa dei dati in Google BigQuery

L'esportazione dei dati in BigQuery e la scheda Report nella console Firebase richiedono entrambe Google Analytics per funzionare. Puoi attivare Google Analytics nella settings Impostazioni > scheda Integrazioni della console Firebase. I dati di pubblicazione aggregati non richiedono Google Analytics per funzionare.

Tieni presente che la generazione di report per molte delle statistiche di questa pagina è soggetta a ritardi fino a 24 ore a causa del raggruppamento dei dati di analisi.

Report Consegna messaggi

Nella console Firebase, vai a DevOps e coinvolgimento > Messaggistica > scheda Report per visualizzare i seguenti dati per i messaggi inviati agli SDK FCM per Android o Apple, inclusi quelli inviati utilizzando il Notifications Composer e le API FCM:

• Invii: il messaggio di dati o di notifica è stato messo in coda per la consegna o è stato trasmesso correttamente a un servizio di terze parti come APN per la consegna. Tieni presente che le statistiche sugli invii potrebbero essere in ritardo di un paio d'ore. Per saperne di più, consulta la sezione Durata di un messaggio.
• Ricevuto (disponibile solo su dispositivi Android): il messaggio di dati o di notifica è stato ricevuto dall'app. Questi dati sono disponibili quando sul dispositivo Android di ricezione è installato FCM l'SDK 18.0.1 o versioni successive.
• Impressioni (disponibili solo per i messaggi di notifica sui dispositivi Android): la notifica è stata visualizzata sul dispositivo mentre l'app è in background.
• Aperture: 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 Aggiunta di etichette di analisi ai messaggi.

Quando visualizzi i report sui messaggi, puoi impostare un intervallo di date per i dati visualizzati, con l'opzione di esportazione in formato CSV. Puoi anche filtrare in base ai seguenti criteri:

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

Aggiungere etichette di analisi ai messaggi

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

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

• -
• ~
• %

La lunghezza massima è di 50 caratteri. Puoi specificare fino a 100 etichette uniche al giorno; i messaggi con etichette aggiunte oltre questo limite non vengono segnalati.

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

Dati di pubblicazione aggregati utilizzando l'API di dati FCM

L'API di dati di Firebase Cloud Messaging ti consente di recuperare informazioni che possono aiutarti a comprendere i risultati delle richieste di messaggi destinate alle app per Android. L'API fornisce dati aggregati su tutti i dispositivi Android abilitati alla raccolta dei dati in un progetto. Sono inclusi i dettagli sulla percentuale di messaggi consegnati senza ritardi, nonché il numero di messaggi ritardati o eliminati all'interno del livello di trasporto Android. La valutazione di questi dati può rivelare tendenze generali nella distribuzione dei messaggi e aiutarti a trovare modi efficaci per migliorare il rendimento delle tue richieste di invio. Consulta 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 pubblicazione sono suddivisi per applicazione, data ed etichetta di analisi. Una chiamata all'API restituirà i dati per ogni combinazione di data, applicazione ed etichetta di analisi. Ad esempio, un singolo oggetto JSON androidDeliveryData avrebbe questo 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 consegna indicano la percentuale di messaggi che rientrano in ciascuna delle seguenti metriche. È possibile che un singolo messaggio soddisfi più metriche. A causa delle limitazioni nel modo in cui raccogliamo i dati e del livello di granularità con cui abbiamo aggregato le metriche, alcuni risultati dei messaggi non sono rappresentati nelle metriche, quindi le percentuali riportate di seguito non danno come somma 100%.

Conteggio messaggi accettati

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

Percentuali di esito del messaggio

I campi inclusi nell'oggetto MessageOutcomePercents forniscono informazioni sugli esiti delle richieste di messaggi. Le categorie si escludono a vicenda. Può rispondere a domande come "I miei messaggi vengono recapitati?" e "Che cosa causa la mancata ricezione dei messaggi?"

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

Percentuali di rendimento della consegna

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

Percentuali degli insight sui messaggi

Questo oggetto fornisce informazioni aggiuntive su tutti gli invii di messaggi. Il campo priorityLowered indica la percentuale di messaggi accettati la cui priorità è stata ridotta da HIGH a NORMAL. Se questo valore è elevato, prova a inviare meno messaggi ad alta priorità o assicurati di mostrare 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 differiscono da quelli esportati in BigQuery?

L'esportazione BigQuery fornisce log dei singoli messaggi sull'accettazione dei messaggi da parte del backend FCM e sul recapito dei messaggi nell'SDK sul dispositivo (passaggi 2 e 4 dell'architettura FCM). Questi dati sono utili per garantire 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 di 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 sulla consegna 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 eliminati durante il 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 vengono arrotondate
• Non mostriamo metriche al di sotto di una soglia di privacy
• Manca una parte dei risultati dei messaggi a causa delle ottimizzazioni nel modo in cui gestiamo l'elevato volume di traffico.

Limitazioni dell'API

Cronologie dei dati aggregati

L'API restituirà 7 giorni di dati storici; tuttavia, i dati restituiti da questa API verranno ritardati fino a 5 giorni. Ad esempio, il 20 gennaio saranno disponibili i dati dal 9 al 15 gennaio, ma non quelli del 16 gennaio o di date successive. Inoltre, i dati vengono forniti secondo il criterio del "best effort". In caso di interruzione dei dati, FCM si adopererà per risolvere il problema e non eseguirà il backfill dei dati dopo la risoluzione del problema. In caso di interruzioni più estese, i dati potrebbero non essere disponibili per una settimana o più.

Copertura dei dati

Le metriche fornite dall'API di dati di Firebase Cloud Messaging hanno lo scopo di fornire insight sulle tendenze generali della distribuzione dei messaggi. Tuttavia, non forniscono una copertura del 100% di tutti gli scenari dei messaggi. I seguenti scenari sono risultati noti non riflessi 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 ai dispositivi inattivi

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

Messaggi ai dispositivi con determinate preferenze utente

I messaggi degli utenti che hanno disattivato la raccolta di informazioni su utilizzo e diagnostica sui loro dispositivi non verranno inclusi nel nostro conteggio, in conformità con le loro preferenze.

Arrotondamento e valori minimi

FCM arrotonda ed esclude deliberatamente i conteggi se i volumi non sono sufficientemente elevati.

Esportazione dei dati di BigQuery

Puoi esportare i dati dei messaggi in BigQuery per ulteriori analisi. BigQuery ti consente di analizzare i dati utilizzando BigQuery SQL, esportarli in un altro cloud provider o utilizzarli per i tuoi 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 utilizzando l'API o Notifications Composer.

Per i messaggi inviati ai dispositivi con le seguenti versioni minime dell'SDK FCM, hai l'opzione aggiuntiva per 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 Firebase per il web 12.14.0 o versioni successive

Per iniziare, collega il tuo progetto a BigQuery utilizzando la console Firebase:

1. Scegli una delle seguenti opzioni:

   • Vai a DevOps e coinvolgimento > Messaggistica > Compositore di Notifiche, quindi fai clic su Accedi a BigQuery in fondo alla pagina.

   • Vai alla scheda settings Settings (Impostazioni) > Integrations (Integrazioni). Quindi, in BigQuery, fai clic su Collega.

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

2. Segui le istruzioni sullo schermo per attivare BigQuery.

Per saperne di più, consulta Collega 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 potrebbe richiedere fino a 48 ore per essere completata.

  • Puoi pianificare manualmente i backfill dei dati fino a 30 giorni prima.

• Dopo la creazione del set di dati, la località non può essere modificata, ma puoi copiare il set di dati in un'altra località oppure spostare (ricreare) manualmente il set di dati in un'altra località. Per saperne di più, consulta Modifica la località del set di dati.

• Firebase configura sincronizzazioni regolari dei dati dal progetto Firebase a BigQuery. Queste operazioni di esportazione giornaliere iniziano alle 04:00 Pacific Time e di solito terminano entro 24 ore.

• Per impostazione predefinita, tutte le app del progetto sono collegate a BigQuery e tutte le app che aggiungi in un secondo momento al progetto vengono collegate automaticamente a BigQuery. Puoi gestire le app che inviano dati.

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

Abilitare l'esportazione dei dati di recapito dei messaggi

// For alert notifications, call the API inside the service extension:
class NotificationService: UNNotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    Messaging.serviceExtension().exportDeliveryMetrics(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

// For background notifications, call the API inside the
// UIApplicationDelegate or NSApplicationDelegate method:
func application(_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
  Messaging.serviceExtension().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

FirebaseMessaging.getInstance().setDeliveryMetricsExportToBigQuery(true);

<application>
  <meta-data android:name="delivery_metrics_exported_to_big_query_enabled"
      android:value="true" />
</application>

// userConsent holds the decision of the user to give big query export consent.
const userConsent = ...;

const messaging = getMessagingInSw(app);

experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, userConsent);

Quali dati vengono esportati in BigQuery?

Tieni presente che il targeting di token inattivi o registrazioni inattive potrebbe gonfiare alcune di queste statistiche.

Lo schema della tabella esportata è:

Che cosa puoi fare con i dati esportati?

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

Conteggio dei 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;

Conteggio delle istanze di app uniche targetizzate 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';

Conteggio dei 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';

Conteggio dei 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';

Conteggiare 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 per un messaggio inviato a un argomento specifico, modifica questa query per sostituire AND message_id != '' con AND message_id = <your message id>;.

Calcolare la durata della distribuzione per un determinato argomento o campagna

L'ora di inizio del fanout è l'ora in cui viene ricevuta la richiesta originale, mentre l'ora di fine è l'ora in cui viene creato l'ultimo singolo messaggio 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;

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;

Monitora 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;