Comprendre la distribution des messages

Pour résoudre les problèmes de diffusion de messages en cours, utilisez l'outil de dépannage FCM et consultez cet article de blog pour comprendre les différentes raisons pour lesquelles vous ne voyez peut-être pas votre message. Vous pouvez également consulter le tableau de bord d'état FCM pour savoir si des interruptions de service affectent actuellement FCM.

FCM fournit également trois ensembles d'outils pour vous aider à obtenir des insights sur l'évaluation globale de la réussite et de la stratégie de messagerie :

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

L'exportation de données BigQuery et l'onglet Rapports de la console Firebase nécessitent 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. Les données de livraison agrégées ne nécessitent pas Google Analytics pour fonctionner.

N'oubliez pas que le reporting de nombreuses statistiques sur cette page peut être retardé jusqu'à 24 heures en raison du traitement par lot des données analytiques.

Rapports sur la distribution 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 des plates-formes Android ou Apple, y compris ceux envoyés via le compositeur de notifications et les API FCM :

• Envoi : le message de données ou de notification a été mis en file d'attente pour la distribution ou a été transmis avec succès à un service tiers tel qu'APNs pour la distribution. Notez que les statistiques sur les envois peuvent être différées de quelques heures. Pour en savoir plus, consultez la section Durée de vie d'un message.
• Reçu (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 récepteur est équipé du SDK 18.0.1 ou version ultérieure.FCM
• Impressions (disponibles uniquement pour les messages de notification sur les appareils Android) : la notification s'est affichée sur l'appareil lorsque l'application était en arrière-plan.
• Ouvertures : 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 libellés. Pour en savoir plus sur les libellés, consultez 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 et les exporter au format CSV. Vous pouvez également filtrer les résultats selon les critères suivants :

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

Ajouter des libellés Analytics aux messages

L'ajout de libellés aux messages est très utile pour les analyses personnalisées. 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 auxquels vous ajoutez des libellés 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 remise agrégées à l'aide de l'API de données FCM

L'API Firebase Cloud Messaging Data vous permet de récupérer des informations qui peuvent vous aider à comprendre les résultats des demandes de messages ciblant les applications Android. L'API fournit des données agrégées pour tous les appareils Android sur lesquels la collecte de données est activée dans un projet. Cela inclut des informations sur le pourcentage de messages remis sans délai, ainsi que sur le nombre de messages retardés ou abandonnés dans la couche de transport Android. L'évaluation de ces données peut révéler des tendances générales dans la distribution des messages et vous aider à trouver des moyens efficaces d'améliorer les performances de vos demandes d'envoi. Pour en savoir plus sur la disponibilité des plages de dates dans les rapports, consultez Chronologies 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 ventilées ?

Les données de diffusion sont ventilées par application, par date et par libellé Analytics. Un appel à l'API renverra des données pour chaque combinaison de date, d'application et de libellé Analytics. Par exemple, un seul objet JSON androidDeliveryData se présenterait 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 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 liées à la façon dont nous collectons les données et au niveau de précision auquel nous avons agrégé les métriques, certains résultats de messages ne sont pas du tout représentés dans les métriques. Les pourcentages ci-dessous ne totalisent donc pas 100 %.

Nombre de messages acceptés

Le seul nombre inclus dans l'ensemble de données est celui des messages acceptés par FCM pour être distribués aux appareils Android. Tous les pourcentages utilisent cette valeur comme dénominateur. N'oubliez pas que ce nombre n'inclut pas les messages ciblés sur 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 demandes de messages. Les catégories s'excluent mutuellement. Il peut répondre à des questions telles que "Mes messages sont-ils distribués ?" et "Qu'est-ce qui fait que des messages sont 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 indiquer qu'il est temps de mettre à jour les jetons d'enregistrement sur votre serveur, en supprimant les jetons obsolètes et en les désabonnant des thèmes. Pour connaître les bonnes pratiques dans ce domaine, consultez Gérer les jetons d'enregistrement FCM.

Pourcentages de performances de livraison

Les champs de l'objet DeliveryPerformancePercents fournissent des informations sur les messages qui ont été remis. 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 indiquerait clairement que vous dépassez les limites maximales par appareil et que vous devez ajuster la fréquence d'envoi des messages.

Pourcentages des insights sur les messages

Cet objet fournit des informations supplémentaires sur tous les envois de messages. Le champ priorityLowered indique le pourcentage de messages acceptés dont la priorité a été abaissée de HIGH à NORMAL. Si cette valeur est élevée, essayez d'envoyer moins de messages à priorité élevée ou assurez-vous d'afficher systématiquement 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 de celles exportées vers BigQuery ?

L'exportation BigQuery fournit des journaux de messages individuels sur l'acceptation des messages par le backend FCM et sur la distribution des messages dans le SDK sur l'appareil (étapes 2 et 4 de l'architecture FCM). Ces données sont utiles pour s'assurer que les messages individuels ont été acceptés et remis. 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 de transport Android (ou à l'étape 3 de l'architecture FCM). Ces données fournissent des informations sur la distribution des messages des backends FCM au SDK Android. Il est particulièrement utile pour afficher les tendances expliquant pourquoi les messages ont été retardés ou supprimé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 prennent en compte qu'une partie de tous les messages.
• Les métriques agrégées sont arrondies.
• Nous ne présentons pas les métriques en dessous d'un seuil de confidentialité.
• Il manque une partie des résultats des messages en raison des optimisations apportées à la gestion du volume de trafic élevé.

Limites de l'API

Chronologies des données agrégées

L'API renverra sept jours de données historiques. Toutefois, les données renvoyées par cette API seront différées de cinq jours maximum. Par exemple, le 20 janvier, les données du 9 au 15 janvier seraient disponibles, mais pas celles du 16 janvier ni des jours suivants. De plus, les données sont fournies dans la mesure du possible. En cas d'indisponibilité des données, FCM s'efforcera de résoudre le problème pour l'avenir, mais ne remplira pas les données manquantes 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 Firebase Cloud Messaging Data sont destinées à fournir des informations sur les grandes tendances de diffusion des messages. Toutefois, ils ne couvrent pas 100 % des 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 du journal indiquée, le message ne sera pas comptabilisé comme droppedTtlExpired à cette date.

Messages envoyés aux appareils inactifs

Les messages envoyés à des appareils inactifs peuvent s'afficher ou non dans l'ensemble de données, selon le chemin de données qu'ils empruntent. Cela peut entraîner des erreurs de comptage dans les champs droppedDeviceInactive et pending.

Messages envoyés aux appareils avec certaines préférences utilisateur

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

Arrondis 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 messages 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 qu'ils aient été envoyés via l'API ou le compositeur de notifications.

Pour les messages envoyés aux appareils avec les versions minimales du SDK FCM suivantes, vous avez la possibilité supplémentaire d'activer l'exportation des données de distribution 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

Vous trouverez ci-dessous des informations sur l'activation de l'exportation de données pour Android et iOS.

Pour commencer, associez votre projet à BigQuery :

1. Choisissez l'une des options suivantes :

   • Ouvrez le composeur 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 sur la fiche BigQuery.

     Cette page affiche les options d'exportation FCM pour toutes les applications compatibles avec FCM dans le 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 à exporter 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éé, l'emplacement ne peut plus être modifié, mais vous pouvez copier l'ensemble de données dans un autre emplacement ou le déplacer (recréer) manuellement dans un autre emplacement. Pour en savoir plus, consultez 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 du matin (heure du Pacifique) et se terminent généralement sous 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 distribution des messages de leur application. FCM est compatible avec l'exportation de données pour les notifications d'alerte et en arrière-plan. Avant d'activer ces options, vous devez d'abord créer le lien FCM-BigQuery pour votre projet, comme décrit dans 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 affichés. 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 remise 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.

Nombre de 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;

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

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

Comptabiliser 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 pour un thème ou une campagne donnés

L'heure de début du fan-out correspond au moment où la demande 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;

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

Calculer la latence 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;