Firebase Cloud Messaging

References

• Firebase Cloud Messaging

Notes

Firebase Cloud Messaging (FCM) is a cross-platform messaging solution that lets you reliably send messages at no cost. Using FCM, you can notify a client app that new email or other data is available to sync. You can send notification messages to drive user re-engagement and retention. For use cases such as instant messaging, a message can transfer a payload of up to 4096 bytes to a client app.

A FCM implementation includes two main components for sending and receiving:

1. A trusted environment such as Cloud Functions for Firebase or an app server on which to build, target, and send messages,
2. An Apple, Android, or web (JavaScript) client app that receives messages via the corresponding platform-specific transport service.

You can send messages via the Firebase Admin SDK or the FCM server protocol. You can use the Notifications composer for testing and to send marketing or engagement messages using powerful built-in targeting and analytics or custom imported segments..

Implementation:

1. Set up the FCM SDK
2. 1. Set up Firebase and FCM on your app according to the setup instructions for your platform.
2. Develop your client app
3. 1. Add message handling, topic subscription logic, or other optional features to your client app. During the development, you can easily send test messages from the Notifications composer.
3. Develop your app server
4. 1. Decide whether you want to use the Firebase Admin SDK or the server protocol to create your sending logic - logic to authenticate, build send requests, handle responses, and so on. Then build out the logic in your trusted environment.

FCM Architectural Overview

FCM relies on the following set of components that build, transport, and receive messages:

1. Tooling to compose pf build message requests. The Notifications composer provides a GUI-based option for creating notification requests. For full automation and support for all message types, you must build message requests in a trusted server environment that supports the firebase Admin SDK or the FCM server protocol.

2. The FCM backend, which (among other functions) accepts message requests, performs fanout of messages via topic, and generates message metadata such as the message ID.
3. A platform-level transport layer, which routes the message to the targeted device, handles message delivery, and applies a platform-specific configuration where appropriate. This transport layer includes:
4. 1. Android Transport Layer (ATL) for Android devices with Google Play services
   2. Apple Push Notification service (APNs) for Apple devices
   3. Web push protocol for web apps
4. The FCM SDK on the user's device, where the notification is displayed on the message is handled according to the app's foreground/background state and relevant application logic.

Lifecycle Flow

• Register devices to receive messages from FCM: An instance of a client app registers to receive messages, obtaining a registration token that uniquely identifies the app instance.
• Send and receive downstream messages
• • Send a message. The app server sends messages to the client app:
  • • The message is composed, either in the Notifications composer or a trusted environment, and a message request is sent to the FCM backend
    • The FCM backend receives the message request, generates a message ID and other metadata, and sends it to the platform specific transport layer
    • When the device is online, the message is sent via the platform-specific transport layer to the device
    • On the device, the client app receives the message or notification.

About FCM Messages

With FCM, you can send two types of messages to clients:

• Notification messages, sometimes thought of as display messages. These are handled by the FCM SDK automatically.
• Data messages, which are handled by the client app.

Notification messages contain a predefined set of user-visible keys. Data messages, by contrast, contain only your user-defined custom key-value pairs. Notification messages can contain an optional data payload. Maximum payload for both is 4096 bytes.

Use notification messages when you want the FCM SDK to handle displaying a notification automatically when your app is running in the background. Use data messages when you want to process the messages with your own client app code. FCM can send a notification message including an optional data payload. In such cases, FCM handles displaying the notification payload, and the client app handles the data payload.

For testing or for marketing and user re-engagement, you can send notification messages using the Firebase console.

Notification messages are delivered to the notification tray when the app is in the background. For apps in the foreground, messages are handled by a callback function.

App behavior when receiving messages that include both notification and data payloads depends on whether the app is in the background or the foreground - essentially, whether or not it is active at the time of receipt.

• When in the background, apps receive the notification payload in the notification tray, and only handle the data payload when the user taps on the notification.
• When in the foreground, your app receives a message object with both payloads available.

The Firebase Admin SDK and the FCM v1 HTTP protocol both allow your message requests to set all fields available in the message object. This includes:

• a common set of fields to be interpreted by all app instances that receive the message
• platform-specific sets of fields, such as AndroidConfig and WebpushConfig, interpreted only by app instances running on the specified platform.

Platform specific blocks give you the flexibility to customize messages for different platforms to ensure that they are handled correctly when received. The FCM backend will take all specified parameters into account and customize the message to each platform.

Use common fields when you are targeting app instances on all platforms and sending messages to topics. Use platform-specific fields when you want to send fields only to particular platforms and send platform-specific fields in addition to the common fields.

FCM provides a specific set of delivery options for messages sent to android devices, and allows for similar options on Apple platforms and web. For example, collapsible message behavior is supported on Android via FCM's collapse_key, on Apple via apns-collapse-id, and on JavaScript/Web via Topic.

A non-collapsible message denotes that each individual message is delivered to the device. A non-collapsible message delivers some useful content, as opposed to a collapsible message like a content-free ping to the mobile app to contact the server to fetch data. Some typical use cases of non-collapsible messages are chat messages or critical messages. For example, in an IM app, you would want to deliver each message, because every message has different content.

A collapsible message is a message that may be replaced by a new message if it has yet to b delivered to the device. Topic messages with no payload are collapsible by default. Notification messages are always collapsible and will ignore the collapse_key parameter.

Collapsible messages are a better choice from a performance standpoint, provided your app doesn't need to use non-collapsible messages. See the Topic parameter in the message request for web push collapsible messages.

You have two options for assigning delivery priority to downstream messages: normal and high priority.

• Normal priority: messages delivered immediately when the app is in the foreground
• High priority: FCM attempts to deliver high priority messages immediately even if the device is in Doze mode.

You can set the maximum lifespan of a message (max 28 days). When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the service. Rather it means that it was accepted for delivery.

FCM Ports and your Firewall

If your organization has a firewall to restrict traffic to or from the Internet, you need to configure it to allow mobile devices to connect with FCM in order for devices on your network to receive messages. FCM typically uses port 5228, but it sometimes uses 443, 5229, and 5230.

For devices connecting on your network, FCM doesn't provide specific IPs because our range changes too frequently and your firewall rules could get out of date, impacting your users' experience. Ideally, allowlist ports 5228-5230 & 443 with no IP restrictions. However, if you have an IP restriction, you should allowlist all of the IP addresses listed in goog.json. This large list is updated regularly, and you are recommended to update your rules on a monthly basis.

We do offer a set of domain names that can be allow listed instead of IP addresses. Those hostnames are listed below. The list can sometimes be updated

If your network implements Network Address Translation (NAT) or Stateful Packet Inspection (SPI), implement a 30 minute or larger timeout for our connections over ports 5228-5230. This enables us to provide reliable connectivity while reducing the battery consumption of the users' mobile devices.

VPN Interactions and Bypassability

FCM takes various steps to ensure that the push messaging connection from the phone to the server is reliable and available as often as possible. The use of a VPN complicates this effort. The use of a VPN complicates this effort. VPNs mask the underlying information that FCM needs to tune its connection to maximize reliability and battery life. In some cases, VPNs actively break long lived connections resulting in a bas user experience due to missed or delayed messages or a high battery cost. When the VPN is configured to allow us to do so, we bypass the VPN using an encrypted connection (over the base network wifi or LTE) so as to ensure a reliable, battery-friendly experience. FMC's usage of bypassable VPNs is specific to the FCM Push Notification channel. Different VPNs have different methods for controlling whether or not it can be bypassed. If the VPN is not configured to be bypassable then Firebase Cloud Messaging will use the VPN network in order to connect to the server.

• Blog Post on Why you may not see messages

Manage FCM Registration Tokens

If you use FCM APIs to build send requests programmatically, you may find that, over time, you are wasting resources by sending messages to inactive devices with stale registration tokens.

Best practices that you should follow in any app that uses FCM APIs to build send requests programmatically:

• Retrieve registration tokens from FCM and store them on your server: An important role for the server is to keep track of each client's token and keep an updated list of active tokens. We strongly recommend implementing a token timestamp in your code and your servers, and updating this timestamp at regular intervals.
• Maintain token freshness and remove stale tokens: In addition to removing tokens that FCM no longer considered valid, you may want to monitor other signs that tokens have become stale and remove them proactively.

They strongly recommend that you app retrieve the registration token at initial startup and save it to your app server alongside a timestamp. It's important to save the token to the server and update the timestamp whenever it changes.

There is more on token management, but I am moving on.