How to send push notifications to Firebase Cloud Messaging

In this guide we'll walk through how to configure a Firebase Cloud Messaging (FCM) provider in Knock to send mobile or web push notifications. This guide assumes that you've already created an FCM channel in the Knock dashboard.

How to configure FCM with Knock

To configure FCM with Knock, you'll need your Firebase Project ID and the complete contents of your Service Account JSON file.

You can get both of these by logging into the Firebase console and navigating to project settings. Once you have them, go back to the environment configuration for your FCM channel, enter in your Project ID and Service Account JSON file, and you're good to go.

Using FCM with Knock

In order to use FCM with Knock you'll need to synchronize your users device tokens retrieved from the FCM SDK in either Android, iOS, or Web to Knock by setting channel data for your recipient.

You can follow the appropriate quickstart guide for either iOS, Android, or Web on FCM to see how to get the device token.

Once you have the device token, you can use the Knock SDK to set the channel data for your recipient. In the case of web push, you can send the token to your app server and use the corresponding Knock SDK to set the channel data:

Managing tokens

By default, Knock makes no assumptions about managing your device tokens. This means you are responsible for removing tokens when a recipient opts out of notifications on a device or when their token expires.

However, Knock does provide an opt-in token deregistration feature that automatically removes invalid tokens from a recipient's channel data when a message bounces. When enabled, Knock will automatically remove invalid or expired tokens upon receiving a bounce event from the provider.

You can configure token deregistration on a per-environment basis in your channel's environment configurations. See our token deregistration guide for more details on enabling and working with this feature.

Data passed to FCM

When sending a notification to FCM, we also pass through the following attributes:

Property	Type	Description
knock_message_id*	string	The message ID of the corresponding Knock message
data*	string	Any key/value data passed through in your trigger call, formatted for FCM (all nested objects are flattened, and all values are converted to strings)

The following example illustrates how Knock will format your trigger data for FCM:

becomes

Silent/data notifications

We support sending FCM notifications as "silent," data-only notifications within Knock. You can enable this per push notification template by clicking "Manage template settings" in the header of the template editor.

When silent push is enabled, we'll no longer pass through the message payload. All properties in the data payload described above will be sent with your notification still.

Using overrides to customize notifications

We have full support for overriding the payload sent to FCM for adding things like badge counts, extra data properties, and sound files. You can set push overrides on the template settings modal, which is accessed by clicking on the "Manage template settings" button when viewing a push notification template within the workflow editor. Push overrides support Liquid for injecting data properties and referencing attributes on your recipients.

By default, payload overrides will be merged into the base data and will not replace other trigger data being passed to FCM. The override also needs to match the format that is expected by FCM, meaning that any custom key-value pairs should be contained inside of a data dictionary:

If you want to fully replace the trigger data with your override rather than merge additional properties, you'll also need to set a replace __strategy__:

See the FCM documentation for details.

Property	Type	Description
apns	dictionary	APNS specific overrides
data	dictionary	Extra data properties to add
android	dictionary	Android specific overrides
fcm_options	dictionary	FCM specific options
notification	dictionary	Notification overrides
webpush	dictionary	Webpush specific overrides

Common FCM errors

The following are common FCM errors you may see in your message delivery logs:

Error	Meaning / action to take
UNREGISTERED	The device token provided is not valid and should be removed from the recipients channel data.
INVALID_ARGUMENT	The device token given may be incorrect.

Channel data requirements

In order to use a configured FCM channel you must store a list of one or more device tokens for the user or the object that you wish to deliver a notification to. If you use multiple device tokens for a single user or object, Knock will generate and try and deliver a notification for each unique token.

Property	Type	Description
tokens*	string[]	One or more device tokens