Firebase Summit 2021
What is FCM Aggregated Delivery Data?
FCM Aggregated Delivery Data sheds light on what occurs between FCM accepting your messages for delivery and it arriving at your application. This dataset provides insight into what happens internally when FCM attempts to deliver a message, and why some messages may be delayed or dropped.
After FCM accepts a message, it attempts to route it to the targeted device; however, it is possible that a message could be delayed, or even dropped, during this delivery. For example, messages can be delayed if the target device is not connected to FCM servers at the time when the message was sent. FCM Aggregated Delivery Data helps developers understand these message delivery outcomes for Android devices.
The Aggregated Delivery Data provides daily reports detailing what happened during message delivery for messages intended for Android users. The data is available from the new FCM Data API and can answer questions such as “What percentage of my messages were delivered?” and “What percentage of my messages were delayed or dropped?”.
To protect end user privacy, FCM only uses data from Android users that have opted-in to share anonymous stats. Additionally, FCM will not return data in cases where there is insufficient information.
How does this data fit with the BigQuery Export?
FCM has supported BigQuery export for a while now, and we’ve recently expanded this functionality to iOS and the web as well. Aggregated Data Delivery completes the picture by providing a full view of the life of a message to Android devices. FCM’s BigQuery export provides individual message logs when FCM accepts a message at its backend and when it is delivered to the FCM SDK. The Aggregated Delivery Data provides an aggregated view of everything that happens in between those two steps.
Why use FCM Aggregated Delivery Data?
The Aggregated Delivery Data is great for understanding long term trends in message delivery. The data can be used to create a dashboard to track delivery performance over time. By storing and plotting the data over time, we can detect trends, as explored in the examples below:
Notice in the Message Outcomes graph that the percentage of messages marked as Delivered drops over time. We also see the percentage of messages marked as Dropped Device Inactive increases over this time. This would be a good indicator that this sender is not pruning their tokens as devices go inactive; the sender should look into token management.
Next, we see in the Delivery Performance graph, that around 08/08 there was an increase in messages Delayed Throttled and corresponding drop in messages Delivered with No Delay. This could be due to a change in the sender’s send pattern that caused messages to hit FCM’s throttling limits.
Finally, we notice around 08/22 that the count of messages deprioritized spikes up, which corresponds with an increase in messages being Delayed due to Doze. This could be caused by the sender using more high priority messages and starting to hit the high priority quota.
Important signals in the FCM Aggregated Delivery Data
Here is a quick cheat sheet for interpreting important signals from the aggregate data:
- Increasing percentage of messages that were dropped due to inactive device — token management
- High percentage of messages that had their priority lowered — Understanding message priority
- High percentage of messages that were throttled — FCM throttling
- High percentage of messages that were dropped due to too many pending messages — Understanding collapse keys
How to access the FCM Aggregated Delivery Data?
The data can be accessed via the new FCM Data API. You can explore this new API via the API explorer here, which also contains information about all the fields returned.
For convenience, the autogenerated Google API Client Libraries can be used in a variety of languages to access the API. Below is an example of accessing the API using the Java Client.
Prerequisites For Accessing the API
To access the API, we’ll need either a user or a service account that has the “fcmdata.deliverydata.list” permission. This permission can be granted by assigning one of the following curated roles to the user/service account:
- Firebase Cloud Messaging Admin
- Firebase Cloud Messaging Viewer
- Firebase Grow Admin
- Firebase Grow Viewer
- Firebase Admin
- Firebase Viewer
To create a service account with the necessary permissions:
- Navigate to the Cloud Platform Console “Service Account” tab.
- Select “Create Service Account”
- Fill in the name and description for the account
- Grant the service account one of the roles listed above
To obtain a key-file for the service account:
- Select the service account from the Cloud Platform Console “Service Account” tab.
- Select the “Keys” tab
- Click “Add Key” → “Create New Key” → “JSON”
- The key file will then be downloaded. Use this key file to access the API, as shown below.
Including the Auto Generated Java Client
Add the following to your pom.xml file to include the necessary dependencies:
Accessing the FCM Data API via the Java Client
The API can then be queried programmatically as seen below:
