Comprendre la distribution des messages

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

FCM fournit également trois ensembles d'outils pour vous aider à évaluer de manière générale la réussite et la stratégie de messagerie :

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

L'exportation de données vers BigQuery et l'onglet Rapports de la console Firebase nécessitent tous deux Google Analytics pour fonctionner. Vous pouvez activer Google Analytics dans l'onglet settings Paramètres > Intégrations de la console Firebase. Les Données de diffusion agrégées ne nécessitent pas Google Analytics pour fonctionner.

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

Rapports sur la distribution des messages

Dans la console Firebase, accédez à l'onglet DevOps et engagement > Messagerie > Rapports pour afficher les données suivantes concernant les messages envoyés aux SDK FCM des plates-formes Android ou Apple, y compris ceux envoyés à l'aide de l'outil de création de notifications et des API FCM :

• Envois : le message de données ou de notification a été mis en file d'attente pour distribution ou a été transmis à un service tiers tel qu'APNs pour distribution. Notez que les statistiques d'envoi peuvent être retardées de quelques heures. Pour en savoir plus, consultez 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 le SDK FCM 18.0.1 ou version ultérieure est installé sur l'appareil Android de réception.
• Impressions (disponibles uniquement pour les messages de notification sur les appareils Android) : la notification d'affichage a été affichée sur l'appareil alors que l'application est en arrière-plan.
• Ouvertures : l'utilisateur a ouvert le message de notification. Signalé uniquement pour les notifications reçues lorsque l'application est exécutée 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 Ajouter des libellés d'analyse aux messages.

Lorsque vous consultez les rapports sur les messages, vous pouvez définir une plage de dates pour les données affichées, avec la possibilité de les exporter au format CSV. Vous pouvez également filtrer les résultats selon les critères suivants :

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

Ajouter des étiquettes d'analyse aux messages

L'ajout d'étiquettes aux messages est très utile pour l'analyse personnalisée, car il vous permet de filtrer les statistiques de distribution par étiquettes ou ensembles d'étiquettes. Vous pouvez ajouter un libellé à n'importe quel message envoyé à l'aide de 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 sont ajoutés au-delà de cette limite ne sont pas signalés.

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

Données de distribution 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 requêtes de messages ciblant les applications Android. L'API fournit des données globales sur tous les appareils Android d'un projet pour lesquels la collecte de données est activée. Cela inclut des détails sur le pourcentage de messages distribués sans délai, ainsi que sur le nombre de messages retardés ou supprimé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 requêtes d'envoi. Pour en savoir plus sur la disponibilité des plages de dates dans les rapports, consultez Chronologies 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 réparties ?

Les données de diffusion sont réparties par application, par date et par libellé d'analyse. Un appel à l'API renvoie les données pour chaque combinaison de date, d'application et d'étiquette 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 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 collecte des données et du 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. Par conséquent, la somme des pourcentages ci-dessous n'est pas égale à 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 aux appareils Android. Tous les pourcentages utilisent cette valeur comme dénominateur. Sachez que ce nombre n'inclut pas les messages ciblant les utilisateurs qui ont désactivé la collecte d'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. Les catégories s'excluent toutes mutuellement. Il peut répondre à des questions telles que "Mes messages sont-ils distribués ?" et "Qu'est-ce qui entraîne l'abandon des messages ?".

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 limiter 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 nécessaire de mettre à jour les jetons d'enregistrement sur votre serveur, de supprimer les jetons obsolètes et de les désabonner des thèmes. Consultez Gérer les jetons d'enregistrement FCM pour connaître les bonnes pratiques dans ce domaine.

Pourcentages de performances de livraison

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 que vous devez ajuster la fréquence d'envoi des messages.

Pourcentages d'insights sur les messages

Cet objet fournit des informations supplémentaires sur tous les envois de messages. Le champ priorityLowered exprime 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 de 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 de celles exportées vers BigQuery ?

L'exportation BigQuery fournit des journaux de messages individuels concernant 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 s'assurer 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 de transport Android (ou l'étape 3 de l'architecture FCM). Ces données fournissent spécifiquement des informations sur la distribution des messages des backends FCM au SDK Android. Il est particulièrement utile pour identifier les tendances expliquant pourquoi des 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 exactement pour les raisons suivantes :

• Les métriques agrégées n'échantillonnent qu'une partie de tous les messages
• Les métriques agrégées sont arrondies
• Nous ne présentons pas de métriques en dessous d'un seuil de confidentialité.
• Une partie des résultats des messages est manquante en raison des optimisations apportées à la gestion du volume élevé de trafic.

Limites de l'API

Chronologies des données globales

L'API renvoie sept jours de données historiques. Toutefois, les données renvoyées par cette API seront 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 d'une date ultérieure. De plus, les données sont fournies dans la mesure du possible. En cas d'interruption des données, FCM s'efforcera de corriger le problème et ne remplira pas les données une fois le problème résolu. En cas de pannes plus importantes, 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 insights sur les grandes tendances de distribution 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 de journalisation donnée, le message ne sera pas comptabilisé comme droppedTtlExpired à cette date.

Messages envoyés à des appareils inactifs

Les messages envoyés à des appareils inactifs peuvent apparaître 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 selon 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.

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 les données de vos messages vers BigQuery pour les analyser plus en détail. 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 le type de message ou si le message est envoyé à l'aide de l'API ou de l'outil de création de notifications.

Pour les messages envoyés aux appareils dotés des versions minimales du SDK FCM suivantes, vous avez également la possibilité 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 12.14.0 ou version ultérieure

Pour commencer, associez votre projet à BigQuery à l'aide de la console Firebase :

1. Choisissez l'une des options suivantes :

   • Accédez à DevOps et engagement > Messagerie > Outil de création de notifications, puis cliquez sur Accéder à BigQuery en bas de la page.

   • Accédez à l'onglet settings Paramètres > Intégrations. Ensuite, dans BigQuery, cliquez sur Associer.

     Cette page affiche les options d'exportation FCM pour toutes les applications du projet pour lesquelles FCM est activé.

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 que vous avez créé l'ensemble de données, son emplacement ne peut plus être modifié, mais vous pouvez le copier dans un autre emplacement ou le déplacer (recréer) manuellement dans un autre emplacement. Pour en savoir plus, consultez Modifier l'emplacement de l'ensemble de données.

• Firebase configure des synchronisations régulières de vos données entre votre projet Firebase et BigQuery. Ces opérations d'exportation quotidiennes commencent à 4h00 (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 distribution des messages

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

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

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 distribution pour un sujet ou une campagne donnés

L'heure de début de la distribution correspond à la réception de la requête d'origine, et l'heure de fin correspond à la création du dernier message individuel ciblant une seule instance.

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;

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;