Set and manage Android message priority  |  Firebase Cloud Messaging (original) (raw)

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:

Deciding between high and normal priority messages

While normal priority messages are suitable for general updates, choose high priority when you need to ensure immediate delivery for urgent matters or actions. Since the delivery time for normal priority messages can be impacted by Doze mode, setting most of your user visible notifications to high priority will ensure they are delivered promptly. For example, notifications such as, chat messages, problems with an account, or food delivery updates, should be set to high priority.

Message processing for high and normal priority messages

For both high priority and normal priority messages received on an Android device, several seconds are given to process the message payload in theonMessageReceived handler, with slightly more time allocated for high priority messages than normal priority ones. This time is only expected to be long enough to immediately render a notification. If you have to do any additional work such as loading an image from device storage or calling your servers to collect additional content you will need to take additional steps.

The onMessageReceived method is called on a separate worker thread. As best practice, you should process the message payload and display a notification immediately within the onMessageReceived method. You shouldn't be making additional asynchronous network calls or doing payload processing on a separate thread within the onMessageReceived method, doing so can cause your application to be outside of avalid process lifecyclebefore the payload is fully processed. If this happens, you may see that certain FCM messages that are sent result in delayed or missing notifications.

If you do need additional time to process for your message, for example to fetch an imageUrl contained in your message payload, you will need to use a construct such as WorkManager or foreground service to extend the application lifecycle. You should use the following guidance when youoverride the onMessageReceived methodto verify your notifications are fully processed.

Setting priority for messages

You can send notifications to your users using the Admin SDK, theFCM REST API, and the Firebase console. To change your priority setting from theAdmin SDK and FCM REST API, you have to update the message JSON payload. You can use the following code sample to see how to set the priority to high. For notifications sent from the console, setting Android-specific notification fields isn't supported.

 {
  "message": {
      "notification": {
          "body": "Purchase exceeding $500 detected",
          "title": "Credit card purchase"
      },
      "data": {
          "purchaser": "Your child",
          "items": "Gravity Defier Sneakers"
      },
      "android": {
          "priority": "high"
      },
      "apns": {
          "headers": {
              "apns-priority": "5"
          }
      }
  }
}

Test your high priority notifications in Doze mode

To make sure your high priority notifications are being received and processed correctly when received by a user, follow these instructions to test your notifications:

  1. Set your device to Doze mode using the instructions inTest your app with Doze.
  2. Access your FCM registration token from your app on the test device. For more information on how to access the token, seeSend a test message to a background app.
  3. Once you have the FCM token, send your high priority notification to the test device using your FCM notification sending code or acURL commandthat has configuration parameters matching your high priority notification.

Deprioritization of high priority FCM on Android

High priority messages on Android are meant for time sensitive, user visible content, and should result in user-facing notifications. If FCMdetects a pattern in which messages don't result in user-facing notifications, your messages may be deprioritized to normal priority or delegatedfor 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 won't be affected.

Notification delegation with Google Play services

High priority notification 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:

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:

Measuring message deprioritization on Android

Troubleshooting Notification Delays