Comprendre la distribution des messages

FCM fournit trois ensembles d'outils pour vous aider à obtenir des insights sur la distribution des messages :

• Rapports sur la distribution des messages de la console Firebase
• 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 l'autorisation 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.

Gardez à l'esprit que la création de rapports sur de nombreuses statistiques de cette page peut prendre jusqu'à 24 heures en raison du traitement par lot des données analytiques.

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 :

• Envoi : le message de données ou de notification a été mis en file d'attente pour l'envoi ou a été transmis à un service tiers tel que les APN pour l'envoi. 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 étiquetés. Pour en savoir plus sur les libellés, consultez la section Ajouter des libellés d'analyse aux messages.

Lorsque vous consultez des rapports sur les messages, vous pouvez définir une période pour les données affichées, avec la possibilité de les exporter au format CSV. Vous pouvez également filtrer les données en fonction des critères suivants :

• Plate-forme (iOS ou Android)
• Appli
• Libellés d'analyse personnalisés

Ajouter des libellés Analytics aux messages

L'étiquetage des messages est très utile pour l'analyse personnalisée, car il vous permet de filtrer les statistiques de diffusion par libellés ou ensembles 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 étiquettes uniques par jour. Les messages auxquels des étiquettes ont été ajoutées au-delà de cette limite ne sont pas inclus dans les rapports.

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 diffusion agrégées via l'API Data FCM

L'API Firebase Cloud Messaging Data vous permet de récupérer des informations qui peuvent vous aider à comprendre les résultats des requêtes de message ciblant les applications Android. L'API fournit des données agrégées pour tous les appareils Android compatibles avec la collecte de données d'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 les grandes tendances dans 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 globales.

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 ventilées ?

Les données de diffusion sont ventilées par application, date et libellé d'analyse. 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 métriques

Les données de diffusion 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 message. 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 100 messages en attente de FCM. 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 à des 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 doit 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 Data Firebase Cloud Messaging fournit des informations agrégées sur ce qui se passe spécifiquement dans la couche transport Android (ou é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 montrer les tendances expliquant pourquoi les messages ont été retardés ou abandonnés lors de 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 n'affichons pas les métriques en dessous d'un seuil de confidentialité
• Une partie des résultats des messages est manquante en raison des optimisations de la façon dont nous gérons le grand volume de trafic.

Limites de l'API

Chronologie des données agrégées

L'API renvoie les données historiques sur sept jours. Toutefois, les données renvoyées par cette API sont retardées de cinq jours maximum. Par exemple, le 20 janvier, les données du 9 au 15 janvier sont disponibles, mais pas celles du 16 janvier ou plus tard. De plus, les données sont fournies au mieux. En cas d'indisponibilité des données, FCM s'efforcera de résoudre le problème à l'avenir et ne rajoutera pas les données une fois le problème résolu. En cas de panne plus importante, 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 non 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 n'est 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 un comptage incorrect 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.

Arrondi 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 vos données de message vers 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 de services 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 compatibles avec FCM du projet.

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 des données de votre projet Firebase vers BigQuery. Ces opérations d'exportation quotidiennes commencent à 4h du matin, heure du Pacifique, et se terminent généralement en 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 diffusion 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 diffusion 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 diffusion 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 charge utile.

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

Pour les messages en arrière-plan reçus lorsque l'application est 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';

Nombre de 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 sujet 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 la distribution ramifiée d'un thème 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;

Compter le pourcentage de messages distribués

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;