Set and manage message priority

You have two options for assigning delivery priority to downstream messages on Android: normal and high priority. Delivery of normal and high priority messages works like this:

  • Normal priority. This is the default priority for data messages. Normal priority messages are delivered immediately when the device is not sleeping. When the device is in Doze mode, delivery may be delayed to conserve battery until the device exits doze. For less time-sensitive messages, such as notifications of new email, keeping your UI in sync, or syncing app data in the background, choose normal delivery priority.

    When receiving a normal priority message on Android that requests a background data sync for your app, you can schedule a task with WorkManager to handle it when the network is available.

  • High priority. FCM attempts to deliver high priority messages immediately, allowing FCM to wake a sleeping device when necessary and to run some limited processing (including very limited network access). High priority messages generally should result in user interaction with your app or its notifications.

Message handling and deprioritization on Android

High priority messages on Android are meant for time sensitive, user visible content, and should result in user-facing notifications. If FCM detects a pattern in which messages do not result in user-facing notifications, your messages may be deprioritized to normal priority or delegated for handling by Google Play Services.

FCM uses 7 days of message behavior when determining whether to deprioritize or proxy messages; it makes this determination independently for every instance of your application. If, in response to high priority messages, notifications are displayed in a way that is visible to the user, then your future high-priority messages will not be affected.

Notification delegation with Google Play services

High priority notification messages (not data messages) that meet certain criteria are proxied by Google Play Services instead of being deprioritized. This means that the notifications are displayed by Google Play services on behalf of the app, without any need to start the app. This is done to provide a better overall user experience on Android devices.

Note that proxied notification messages introduce changes in how analytics related to messages being received are reported:

  • In order for analytics for proxied notifications to be reported, your app must use FCM SDK version 24.0.0 or higher.
  • You may notice delays or drops in the number of messages received versus the number prior to the introduction of proxied notifications. This is because analytics for proxied notifications are only reported once your app starts, and might not be reported at all if the notification doesn't result in the app opening.

Proxying notification messages in this way is the default behavior for apps using Android Q+ and Google Play services version 19054000 or later. Messages sent through HTTP v1 API are proxied, but messages sent through the Firebase console or legacy APIs will not be proxied. Note that this feature is currently in Beta, and is subject to change.

Though we strongly recommend leaving delegation enabled for its benefits to device battery and memory, you can opt out of this behavior in any of these ways:

  • On an app-level basis: in your app manifest, add the directive <meta-data android:name= "delivery_metrics_exported_to_big_query_enabled" android:value="false"/>.
  • On an app instance basis: For the app instance, set fun setNotificationDelegationEnabled(disable: Boolean): Task<Void!> in the UI flow for your app, depending on the specific use case.
  • On a per-message basis: Set the proxy key to DENY in the AndroidNotification object for the send request.

Measuring message deprioritization on Android

  • Individual Messages. On delivery, you can determine whether an individual message was deprioritized or not by comparing its delivered priority, from getPriority(), with its original priority, from getOriginalPriority().

  • All Messages. The FCM Aggregate Delivery Data API can report what percentage of all your messages to Android are being deprioritized. Some messages may be omitted from the aggregate data reports, but overall they should give a global view of message deprioritization rates. See our article on aggregated delivery data for more information and sample code for querying the API; it can also be explored from the API explorer.

  • Proxied Notifications. Proxied notifications won't be counted in current FCM or GA delivery metrics, so you may experience a drop of up to 15% in notification delivery metrics. For reporting on proxied messages, use the FCM Aggregate Delivery Data API. ProxyNotificationInsightPercents reports the percentage of successfully proxied notifications as well as details for messages that could not be successfully proxied.

Troubleshooting

  • Ensure that your app instance has notifications enabled. If the user has disabled the notification permission for your app, none of your notifications will be posted, as a result, your messages will be deprioritized. You should verify that notifications are enabled before sending high priority messages to an application instance.

  • Do not call home before posting a notification. Because a small portion of the Android mobile population are on high latency networks, avoid opening a connection to your servers before displaying a notification. Calling back to the server before the end of the allowed processing time may be risky for users on high latency networks. Instead, include the notification content in the FCM message and display it immediately. If you need to sync for additional in-app content on Android, you can schedule a task with WorkManager to handle that in the background.