Notification Actor

The notification actor sends Firebase notifications. The actor typically runs on a server inside a data center.

Registering to receive notifications

To receive notifications, an actor must register its Firebase token with the notification actor using the following message:

The revision timestamp should contain the current time, and will be used to most-recent merge the registration.

The firebase token is the token the app gets from the firebase system. Notifications will be sent to that token.

The secrets section contains a list of secrets allowed to send notifications. A peer wanting to send a notification must know at least one of these secrets.

The notification actor replies with the following message:

The request message hash weakly points to the request message. A simple ok field without any value denotes that the operation was successful. If an error occurred, the response contains an error field with a short text describing the error.

A registration expires after one year.

Sending notification

To send a notification, a peer sends a message with the following structure to the notification actor:

The recipient hash is actor hash of the recipient. If the recipient is not registered, the message is discarded.

The secret must correspond to one of the secrets registered by the recipient.

The message content is in the data and notification sections. They correspond to the respective firebase message sections. Fields and values must contain UTF-8 text.

The sender field of the data section will be set to the actor hash of the sender, in hexadecimal notation.

Messages are sent with low priority by default, except if the priority field is set to high.

Once the message has been sent, the notification actor sends a reply with either an ok or an error:

Notification is considered successful if the message was passed on to Firebase. Note that delivery to the end user device may be delayed by Firebase.

Secrets

Secrets are used to prevent unsolicited notifications.

In the simplest scenario, the app generates a 16 random byte secret when first started, and shares this secret with its peers, and the notification actor.

In more sophisticated scenarios, an app may use different secrets for different parts, or rotate the secret when necessary.

Notification actors typically allow 32 secrets of 16 bytes each per registration.