Comprendre la distribution des messages

FCM propose trois ensembles d'outils pour vous aider à mieux comprendre la distribution des messages:

• Firebase rapports sur la distribution des messages dans la console
• Métriques de diffusion agrégées du SDK Android à partir de l'API Data Firebase Cloud Messaging
• Exportation complète des données vers Google BigQuery

Les outils de création de rapports décrits sur cette page nécessitent tous Google Analytics pour fonctionner. Si Google Analytics n'est pas activé pour votre projet, vous pouvez le configurer dans l'onglet Intégrations des paramètres de votre projet Firebase.

N'oubliez pas que la création de rapports pour la plupart des statistiques de cette page peut prendre jusqu'à 24 heures en raison du traitement par lot des données d'analyse.

Accusés de réception des messages

Dans l'onglet Rapports de la console Firebase, vous pouvez afficher les données suivantes pour les messages envoyés aux SDK FCM de la plate-forme Android ou Apple, y compris ceux envoyés via l'outil de création de notifications et les API FCM :

• Envois : le message de données ou le message de notification a été mis en file d'attente pour être distribué ou a bien été transmis à un service tiers tel qu'APNs pour la distribution. Pour en savoir plus, consultez la section Durée de vie d'un message.
• Received (disponible uniquement sur les appareils Android) : le message de données ou de notification a été reçu par l'application. Ces données sont disponibles lorsque l'appareil Android destinataire est équipé du SDK FCM 18.0.1 ou version ultérieure.
• Impressions (disponible uniquement pour les messages de notification sur les appareils Android) : la notification d'affichage a été affichée sur l'appareil lorsque l'application est exécutée en arrière-plan.
• Ouvre : l'utilisateur a ouvert le message de notification. Signalé uniquement pour les notifications reçues lorsque l'application est en arrière-plan.

Ces données sont disponibles pour tous les messages avec une charge utile de notification et tous les messages de données avec libellé. Pour en savoir plus sur les libellés, consultez la section Ajouter des libellés d'analyse aux messages.

Lorsque vous consultez les rapports sur les SMS, vous pouvez définir une plage de dates pour les données affichées, avec l'option de les exporter au format CSV. Vous pouvez également appliquer un filtre en fonction des critères suivants:

• Plate-forme (iOS ou Android)
• Appli
• Étiquettes d'analyse personnalisées

Ajouter des libellés Analytics aux messages

L'étiquetage des messages est très utile pour les analyses personnalisées, car il vous permet de filtrer les statistiques de distribution par libellé ou par ensemble de libellés. Vous pouvez ajouter un libellé à n'importe quel message envoyé via l'API HTTP v1 en définissant le champ fcmOptions.analyticsLabel dans l'objet message ou dans les champs AndroidFcmOptions ou ApnsFcmOptions spécifiques à la plate-forme.

Les libellés Analytics sont des chaînes de texte au format ^[a-zA-Z0-9-_.~%]{1,50}$. Les libellés peuvent inclure des lettres minuscules et majuscules, des chiffres et les symboles suivants :

• -
• ~
• %

La longueur maximale est de 50 caractères. Vous pouvez spécifier jusqu'à 100 libellés uniques par jour. Les messages dont les libellés dépassent cette limite ne sont pas signalés.

Dans l'onglet Rapports de la messagerie de la console Firebase, vous pouvez rechercher une liste de tous les libellés existants et les appliquer individuellement ou en combinaison pour filtrer les statistiques affichées.

Données de livraison agrégées via l'API FCM Data

L'API Data Firebase Cloud Messaging vous permet de récupérer des informations qui peuvent vous aider à comprendre les résultats des requêtes de messages ciblées sur des applications Android. L'API fournit des données globales sur tous les appareils Android avec collecte de données activée dans un projet. Cela inclut des informations sur le pourcentage de messages distribués sans délai, ainsi que le nombre de messages retardés ou abandonnés dans la couche transport Android. L'évaluation de ces données peut révéler des tendances générales concernant la distribution des messages et vous aider à trouver des moyens efficaces d'améliorer les performances de vos requêtes d'envoi. Pour en savoir plus sur la disponibilité des plages de dates dans les rapports, consultez Chronologie des données agrégées.

L'API fournit toutes les données disponibles pour une application donnée. Consultez la documentation de référence de l'API.

Comment les données sont-elles réparties ?

Les données de diffusion sont réparties par application, date et libellé Analytics. Un appel à l'API renvoie des données pour chaque combinaison de date, d'application et de libellé d'analyse. Par exemple, un seul objet JSON androidDeliveryData se présente comme suit :

 {
  "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
    }
  }

Interpréter les indicateurs

Les données de distribution indiquent le pourcentage de messages correspondant à chacune des métriques suivantes. Il est possible qu'un même message corresponde à plusieurs métriques. En raison des limites de la manière dont nous collectons les données et du niveau de précision auquel nous avons agrégé les métriques, certains résultats des messages ne sont pas du tout représentés dans les métriques. Par conséquent, le total des pourcentages ci-dessous ne sera pas égal à 100 %.

Nombre de messages acceptés

Le seul nombre inclus dans l'ensemble de données est le nombre de messages acceptés par FCM pour être distribués sur les appareils Android. Tous les pourcentages utilisent cette valeur comme dénominateur. N'oubliez pas que ce nombre n'inclut pas les messages ciblant les utilisateurs qui ont désactivé la collecte des informations d'utilisation et de diagnostic sur leurs appareils.

Pourcentages de résultats des messages

Les champs inclus dans l'objet MessageOutcomePercents fournissent des informations sur les résultats des requêtes de messages. Ces catégories s'excluent mutuellement. Il peut répondre à des questions telles que "Mes messages sont-ils distribués ?" et "Pourquoi les messages sont-ils abandonnés ?".

Par exemple, une valeur élevée pour le champ droppedTooManyPendingMessages peut indiquer que les instances d'application reçoivent des volumes de messages non réductibles dépassant la limite de FCM, qui était de 100 messages en attente. Pour atténuer ce problème, assurez-vous que votre application gère les appels à onDeletedMessages et envisagez d'envoyer des messages réductibles. De même, des pourcentages élevés pour droppedDeviceInactive peuvent être un signal pour mettre à jour les jetons d'enregistrement sur votre serveur, supprimer les jetons obsolètes et les désabonner des sujets. Consultez la section Gérer les jetons d'enregistrement FCM pour connaître les bonnes pratiques à ce sujet.

Pourcentages de performances de diffusion

Les champs de l'objet DeliveryPerformancePercents fournissent des informations sur les messages qui ont bien été distribués. Il peut répondre aux questions telles que "Mes messages ont-ils été retardés ?" et "Pourquoi les messages sont-ils retardés ?". Par exemple, une valeur élevée pour delayedMessageThrottled indique clairement que vous dépassez les limites maximales par appareil et que vous devez ajuster la fréquence à laquelle vous envoyez des messages.

Pourcentages d'insights sur les messages

Cet objet fournit des informations supplémentaires sur tous les messages envoyés. Le champ priorityLowered indique le pourcentage de messages acceptés dont la priorité a été réduite de HIGH à NORMAL. Si cette valeur est élevée, essayez d'envoyer moins de messages à priorité élevée ou veillez à toujours afficher une notification lorsqu'un message à priorité élevée est envoyé. Pour en savoir plus, consultez notre documentation sur la priorité des messages.

En quoi ces données diffèrent-elles des données exportées vers BigQuery ?

L'exportation BigQuery fournit des journaux de messages individuels sur l'acceptation des messages par le backend FCM et la distribution des messages dans le SDK sur l'appareil (étapes 2 et 4 de l'architecture FCM). Ces données sont utiles pour vérifier que les messages individuels ont été acceptés et distribués. Pour en savoir plus sur l'exportation de données BigQuery, consultez la section suivante.

En revanche, l'API Firebase Cloud Messaging Data fournit des informations agrégées sur ce qui se passe spécifiquement dans la couche transport Android (ou l'étape 3 de l'architecture FCM). Ces données fournissent des informations spécifiques sur la distribution des messages des backends FCM vers le SDK Android. Il est particulièrement utile pour déterminer les raisons pour lesquelles les messages ont été retardés ou supprimés pendant ce transport.

Dans certains cas, il est possible que les deux ensembles de données ne correspondent pas précisément pour les raisons suivantes:

• Les métriques agrégées ne représentent qu'une partie de tous les messages.
• Les métriques agrégées sont arrondies
• Nous ne présentons pas les métriques inférieures à un seuil de confidentialité
• Une partie des résultats des messages ne s'affiche pas en raison d'optimisations de la gestion du volume important de trafic.

Limites de l'API

Calendriers des données agrégées

L'API renvoie sept jours de données historiques. Cependant, les données renvoyées par cette API ont un délai maximal de cinq jours. Par exemple, le 20 janvier, les données de la période du 9 au 15 janvier seront disponibles, mais pas celles du 16 janvier ni d'une date ultérieure. De plus, les données sont fournies au mieux. En cas d'indisponibilité des données, FCM s'efforce de résoudre le problème et ne remplit pas les données une fois le problème résolu. En cas d'indisponibilité plus longue, les données peuvent être indisponibles pendant une semaine ou plus.

Données couvertes

Les métriques fournies par l'API Data Firebase Cloud Messaging sont destinées à fournir des insights sur les tendances générales de diffusion des messages. Cependant, ils n'offrent pas une couverture à 100% de tous les scénarios de messages. Les scénarios suivants sont des résultats connus qui ne sont pas reflétés dans les métriques.

Messages expirés

Si la valeur TTL (Time To Live) expire après la fin de la date de journalisation donnée, le message ne sera pas comptabilisé comme droppedTtlExpired à cette date.

Messages à des appareils inactifs

Les messages envoyés à des appareils inactifs peuvent apparaître ou non dans l'ensemble de données, en fonction du chemin de données emprunté. Cela peut entraîner des erreurs de comptage dans les champs droppedDeviceInactive et pending.

Messages envoyés à des appareils avec certaines préférences utilisateur

Les messages des utilisateurs qui ont désactivé la collecte d'informations d'utilisation et de diagnostic sur leurs appareils ne seront pas inclus dans notre comptabilisation, conformément à leurs préférences.

Arrondissements et valeurs minimales

FCM arrondit et exclut délibérément les nombres lorsque les volumes ne sont pas assez importants.

Exportation de données BigQuery

Vous pouvez exporter les données de vos messages dans BigQuery pour une analyse plus approfondie. BigQuery vous permet d'analyser les données à l'aide de BigQuery SQL, de les exporter vers un autre fournisseur cloud ou de les utiliser pour vos modèles de ML personnalisés. Une exportation vers BigQuery inclut toutes les données disponibles pour les messages, quel que soit leur type ou s'ils sont envoyés via l'API ou l'outil de création de notifications.

Pour les messages envoyés aux appareils équipés des versions minimales du SDK FCM suivantes, vous avez la possibilité d'activer l'exportation des données de diffusion des messages pour votre application :

• Android 20.1.0 ou version ultérieure
• iOS 8.6.0 ou version ultérieure
• SDK Web Firebase 9.0.0 ou version ultérieure

Consultez ci-dessous pour savoir comment activer l'exportation des données pour Android et iOS.

Pour commencer, associez votre projet à BigQuery:

1. Choisissez l'une des options suivantes :

   • Ouvrez l'outil de création de notifications, puis cliquez sur Accéder à BigQuery en bas de la page.

   • Sur la page Intégrations de la console Firebase, cliquez sur Associer dans la fiche BigQuery.

     Cette page affiche les options d'exportation FCM pour toutes les applications du projet compatibles avec FCM.

2. Suivez les instructions à l'écran pour activer BigQuery.

Pour en savoir plus, consultez Associer Firebase à BigQuery.

Lorsque vous activez l'exportation BigQuery pour Cloud Messaging :

• Firebase exporte vos données vers BigQuery. Notez que la propagation initiale des données pour l'exportation peut prendre jusqu'à 48 heures.

  • Vous pouvez planifier manuellement des remplissages de données pour les 30 derniers jours.

• Une fois l'ensemble de données créé, son emplacement ne peut plus être modifié, mais vous pouvez le copier dans un autre emplacement ou le déplacer manuellement (recréer) dans un autre emplacement. Pour en savoir plus, consultez la page Modifier l'emplacement d'un ensemble de données.

• Firebase configure des synchronisations régulières de vos données depuis votre projet Firebase vers BigQuery. Ces opérations d'exportation quotidiennes commencent à 4h (heure du Pacifique) et se terminent généralement dans un délai de 24 heures.

• Par défaut, toutes les applications de votre projet sont associées à BigQuery. Si vous en ajoutez d'autres ensuite, elles seront également automatiquement associées à BigQuery. Vous pouvez gérer les applications qui envoient des données.

Pour désactiver l'exportation BigQuery, dissociez votre projet dans la console Firebase.

Activer l'exportation des données de distribution des messages

Les appareils iOS équipés du SDK FCM 8.6.0 ou version ultérieure peuvent activer l'exportation des données de distribution des messages de leur application. FCM est compatible avec l'exportation de données pour les alertes et les notifications en arrière-plan. Avant d'activer ces options, vous devez d'abord créer l'association FCM-BigQuery pour votre projet, comme décrit dans la section Exportation de données BigQuery.

Activer l'exportation des données de livraison pour les notifications d'alerte

Étant donné que seules les notifications d'alerte peuvent déclencher des extensions d'application de service de notification, vous devez ajouter une extension de service de notification à votre application et appeler cette API dans une extension de service pour activer le suivi des messages d'affichage. Consultez la documentation d'Apple sur la modification du contenu des notifications nouvellement envoyées.

L'appel suivant doit être effectué pour chaque notification reçue:

// 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

Si vous créez des requêtes d'envoi à l'aide de l'API HTTP v1, veillez à spécifier mutable-content = 1 dans l'objet de la charge utile.

Activer l'exportation des données de livraison pour les notifications en arrière-plan

Pour les messages en arrière-plan reçus lorsque l'application est exécutée au premier plan ou en arrière-plan, vous pouvez appeler l'API d'exportation de données dans le gestionnaire de messages de données de l'application principale. Cet appel doit être effectué pour chaque notification reçue:

// 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

Quelles données sont exportées vers BigQuery ?

Notez que le ciblage de jetons obsolètes ou d'enregistrements inactifs peut gonfler certaines de ces statistiques.

Le schéma de la table exportée est le suivant:

Que pouvez-vous faire avec les données exportées ?

Les sections suivantes proposent des exemples de requêtes que vous pouvez exécuter dans BigQuery sur vos données FCM exportées.

Compter les messages envoyés par application

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;

Compter les instances d'application uniques ciblées par les messages

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

Nombre de messages de notification envoyés

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

Compter les messages de données envoyés

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

Compter les messages envoyés à un thème ou à une campagne

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 != '';

Pour suivre les événements d'un message envoyé à un sujet particulier, modifiez cette requête pour remplacer AND message_id != '' par AND message_id = <your message id>;.

Calculer la durée de diffusion d'un sujet ou d'une campagne donnés

L'heure de début du fanage correspond au moment où la requête d'origine est reçue, et l'heure de fin correspond au moment où le dernier message individuel ciblant une seule instance est créé.

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;

Nombre de messages distribués en pourcentage

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;

Suivre tous les événements pour un ID de message et un ID d'instance donnés

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;

Latence de calcul pour un ID de message et un ID d'instance donnés

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;