This article is part of the weekly learning pathways we’re releasing leading up to Firebase Summit. See the full pathway and register for the summit here.
When you send a push notification to your users, things can go wrong in many places: the network might be down, the device might have performance issues or the send request might be invalid. And each platform has its own complexity so the challenges can keep adding up. All of this makes it difficult to know whether your notifications actually got delivered to users.
To get a better understanding of whether your notifications were delivered and where things might have gone wrong, you need one central place to collect all information and then run an analysis. This is where BigQuery can help. BigQuery, Google's solution for building data warehouses, gives you the ability to run queries and build custom dashboards that provide deep insights and actionable information.
With the Firebase Cloud Messaging Android SDK, you can log notification delivery data and export it to BigQuery. We recently expanded the same support for iOS and the web. In this article, we will walk you through the process of setting this up so you can better understand your delivery rate and identify ways to troubleshoot or improve it.
First, you need to enable BigQuery for your Firebase project. You can do this by navigating to the Firebase console > Project Settings > Integrations, and then click Link on the BigQuery card. It's worth noting that, by default, this integration uses the BigQuery sandbox. This lets you explore BigQuery capabilities at no cost, so you can evaluate if it fits your use case. After you link your Firebase project to BigQuery, Firebase will export your data to BigQuery. The initial propagation of data might take up to 48 hours to complete.
Once the data is successfully exported, you should be able to see a data table created under your project’s firebase_messaging tab in the BigQuery console.
data
firebase_messaging
To collect Notification Delivery data, you need to enable logging on the client side. In the next step, we're going to set up the iOS client and start logging some data to BigQuery.
With the Firebase Messaging iOS SDK 8.6.0 or higher, you can now enable notification delivery logging in your app that exports to BigQuery by calling a new API we recently added. You will need to log alert and background notifications separately (this is only required for Apple's platforms).
Alert notifications and Notification Service Extension
To log alert notifications delivery, you first need to add a Notification Service Extension to your project in Xcode. The Notification Service Extension lets you customize the content of notifications before they become visible to users. Apple’s developer documentation has more details about how to add a service extension to your project.
After adding the Notification Service Extension to your project, find the NotificationService didReceiveNotificationRequest:withContentHandler: method inside the service extension target. This is where you will add code to enable logging.
NotificationService didReceiveNotificationRequest:withContentHandler:
In Firebase 8.6.0, We have introduced a new method to the Firebase Messaging API: the delivery data export API FIRMessagingExtensionHelper exportDeliveryMetricsToBigQueryWithMessageInfo:. Logging is disabled by default, so you will need to explicitly enable it by calling this API inside the Notification Service Extension.
FIRMessagingExtensionHelper exportDeliveryMetricsToBigQueryWithMessageInfo:
override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { self.contentHandler = contentHandler bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent) if let bestAttemptContent = bestAttemptContent { // Modify the notification content here... bestAttemptContent.title = "\(bestAttemptContent.title) 👩🏻💻" // Log Delivery signals and export to BigQuery. Messaging.serviceExtension() .exportDeliveryMetricsToBigQuery(withMessageInfo: request.content.userInfo) // Add image, call this last to finish with the content handler. Messaging.serviceExtension() .populateNotificationContent(bestAttemptContent, withContentHandler: contentHandler) } }
Note that, if you use the Firebase Cloud Messaging SDK to add an image to your notification, you need to make sure to call the deliver data export API before calling Messaging.serviceExtension().populateNotificationContent(_:withContentHandler), as shown in the code snippet above.
Messaging.serviceExtension().populateNotificationContent(_:withContentHandler)
The Apple system only passes the notification to the service extension if the notification payload contains the key "mutable-content" :1, so make sure you specify this key if you use the HTTP v1 API. If you use the Firebase console to send notifications, "mutable-content" :1 will be set automatically.
"mutable-content" :1
Background notifications
Background notifications are hidden messages that allow your app to wake up and update data in the background. To enable delivery data export for these kinds of notifications, you will need to implement the application:didReceiveRemoteNotification:fetchCompletionHandler: method and call exportDeliveryMetricsToBigQueryWithMessageInfo: method as shown below:
application:didReceiveRemoteNotification:fetchCompletionHandler:
exportDeliveryMetricsToBigQueryWithMessageInfo:
// For background notifications, call the API inside the UIApplicationDelegate method: func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) { Messaging.extensionHelper().exportDeliveryMetricsToBigQuery(withMessageInfo:userInfo) }
Make sure to include "content-available":1 to specify it’s a background notification when you use the HTTP v1 API to send the notification.
"content-available":1
Notification Delivery Logging is newly available on the web for Firebase JS SDK versions 9.0.0 and newer. To enable delivery data export, all you need to do is to enable the flag on a service worker as shown below. This is handled similarly to Android.
// userConsent holds the decision of the user to give big query export consent. const userConsent = ...; const messaging = getMessagingInSw(app); experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, userConsent)
Notification Delivery Logging has been supported on Android since Firebase SDKs version 20.1.0 or higher. On Android, you can call the delivery data logging API to enable data export for both display and data messages like this:
FirebaseMessaging.getInstance().setDeliveryMetricsExportToBigQuery(true)
By default, Notification Delivery Logging is disabled on all three platforms, and will only be activated once you call the API to enable it for the particular platform your app is running on. You can also deactivate the BigQuery export any time by unlinking your project in the Firebase console.
Results on BigQuery
Once you have successfully logged some data you will see this data in the BigQuery console. Keep in mind that the data is regularly pushed from Firebase to BigQuery and the daily propagation might take some time (up to a couple of hours, depending on the amount of data) to complete.
BigQuery data also includes customized analytics labels that help you to create custom queries. Here’s a preview what type of data you can get from the iOS platform:
With the delivery data on BigQuery, you can now run custom queries or build a customized dashboard based on your needs. It provides detailed information about your campaign, including message identifier, message type, SDK platform and timestamp so you can get a lot of useful information helping you identify if the message was sent as expected. You can also segment the data based on your custom analytics labels. And if you are interested in getting additional aggregate information about message delivery on Android, check out this Medium post to find out how to use FCM Aggregation API for advanced data analysis.
View the full learning pathway on FCM message delivery for additional codelabs, videos and articles. And don’t forget to register for Firebase Summit and join us on November 10th to learn how Firebase can help you accelerate your app development, release with confidence and scale with ease!
Over the course of this series, I've introduced the concept of Pirate Metrics, followed by individual posts discussing how to track (and improve) acquisition, activation and retention with Firebase and its' suite of products.
Every product owner dreams of seeing the work they create go viral. When your users love what you built so much that they want everyone around them to use it as well, it validates all the effort and hard work that went into it.
But here's the thing: while your users are typically more than happy to refer your application to their friends, family and colleagues, they are unlikely to be interested in putting in a lot of effort. The simple, easy way is to ensure you make it easy to simply share the URL for your application. However, you want to easily track how your referrals are doing, and you also want to smoothen the onboarding process for the new, incoming user.
The first product I'd like to talk about in this post is Dynamic Links. These links, which can be generated either on the Firebase console or programmatically, offer the benefit of redirecting users appropriately based on where they're opening them. That is, users on Android can be automatically sent to the Play Store while users on iOS can be sent to the App Store. If the user already has the app, they can be deeplinked to specific content inside it.
You can take Dynamic Links a few steps further as well by taking advantage of the fact that the data associated with each links survives the app installation process. This means that if the link was meant to deeplink to specific content (such as a product in an E-commerce service), you can take the user straight to the appropriate page once the new user completes the installation.
You can also consider using Dynamic Links to personalize the onboarding process for new users. For example, if you provide a referral bonus to users which relies on sharing of codes, you could ensure the link has this code already added as a parameter and add it automatically for the user right after install. This offers the opportunity to earn a lot of goodwill.
Links are only one part of the solution we have to offer - if you also use Firebase Invites, you can provide users with a simple options of choosing which contacts they would like to share your app with instead of relying upon third party apps. This list of contacts is also sorted to highlight those people the user frequently communicates with.
Firebase Invites referrals are sent over SMS and E-mails, and give you the benefits of Dynamic Links mentioned before. You can customize the invitation content, including the ability to specify templates with rich HTML content for E-mail. And you don't need the user to be signed in to your service or know their E-mail address either.
Your users are your best advocates, and we highly recommend minimizing the friction that might prevent them from sharing your application with the other people in their lives. Regardless of what your product is, you are likely to benefit from gently nudging - especially your more active ones.
