This document provides a reference to the push notification server.
Clients are identified on the push server as an opaque string of characters. If our Firefox has this token:
token = abc123
...and facebook.com asks us to allow push notifications, Firefox will request a new push URL for facebook.com.
POST https://push.mozilla.org/queue/
domain=facebook.com&token=abc123
The API server will create a new queue and return a URL like:
https://push.mozilla.org/queue/xyz
Facebook stores this URL on their backend, associated with our user account.
When that URL is created, the push server maps the queue token to our user token:
queues_to_users = {"xyz": "abc123"}
When Facebook sends us a notification
POST https://push.mozilla.org/queue/xyz/
Content-Type: application/json
{"title": "Thanks for using Facebook."}
...the push server looks up the user token for that queue and delivers the notification to us.
Send a new notification. This is how third-party sites send notifications to users. The URLs are created through the navigator.notification.requestRemotePermission() API.
POST params: |
|
---|
title is the only required parameter.
The data can be posted as application/json or application/x-www-form-urlencoded.
Example request:
POST https://push.mozilla.org/queue/5116f9fd4/
Content-Type: application/x-www-form-urlencoded
title=message+one&body=hi
or
POST https://push.mozilla.org/queue/5116f9fd4/
Content-Type: application/json
{"title": "message one", "body": "hi"}
The client (e.g. Firefox) is responsible for managing push URLs, reading/streaming messages, and syncing device state.
Create a new authentication token. This token is used to identify the client in all other requests.
Example response:
{"token": "TOKEN",
"queue": "https://push.mozilla.org/queue/TOKEN/"}
The token is a randomly generated string that should be stored and kept secret by the client. The queue is a URL where the client can check for new messages over HTTP.
Create a new queue for the given token and domain.
POST params: |
|
---|
Example response:
{"queue": "https://push.mozilla.org/queue/QUEUE"}
The queue URL is given to the third-party site to send notifications to the user.
Get all of the user’s queues. This can be used for syncing state between clients.
Query params: | token – The client token created by POST /token/. |
---|
Example response:
{"example.org": "https://push.mozilla.org/queue/QUEUE1",
"micropipes.com": "https://push.mozilla.org/queue/QUEUE2"}
The object keys are domains and the values are push URLs.
Delete a queue. The user will no longer receive messages from the site once this push URL is destroyed.
Query params: | token – The client token created by POST /token/. |
---|
Mark a message as read.
POST params: | key – message key extracted from notification metadata. |
---|
This will only work on queues created in POST /token/, i.e. the queue directly tied to the user token.
Get all the stored messages for the queue.
Opt. params: | since – Only return messages newer than this timestamp or message key. Should be formatted as seconds since epoch in GMT, or the hexadecimal message key. |
---|
Example response:
{"messages": [
{
"key": "4ae183428d8e11e1a007109add558619",
"timestamp": "1335217807.899117",
"queue": "https://push.mozilla.org/queue/5116f9fd48d3c792d0d93df93d889fa3bfada77f",
"body": {
"title": "message one",
"body": "hi"
}
},
{
"key": "4ae417618d8e11e193d7109add558619",
"timestamp": "1335217807.916016",
"queue": "https://push.mozilla.org/queue/5116f9fd48d3c792d0d93df93d889fa3bfada77f",
"body": {
"title": "message two",
"body": "hi"
}
},
]}
Get a list of WebSocket server IP:port addresses.
Example response:
{"nodes": ["63.245.217.105:8000",
"63.245.217.105:9000",
"63.245.217.106:8000"]
To make a WebSocket connection the client should attempt to connect to each address in the order provided.
After connecting to one of the addresses given in GET /nodes/, the client must authenticate:
>>> token: TOKEN
Following authentication the client listens for messages published from the server.
New messages will come down the WebSocket in either the new message or read message format.
Messages are stored on the server and can be retrieved over HTTP or through a WebSocket connection. The format of a single message is the same over either protocol.
New messages coming from the server have the following format:
{
"key": "4ae183428d8e11e1a007109add558619",
"timestamp": "1335217807.899117"
"queue": "https://push.mozilla.org/queue/5116f9fd48d3c792d0d93df93d889fa3bfada77f",
"body": {
"title": "message one",
"body": "hi",
"actionUrl": "http://example.com/action",
"replaceId": "one"
}
}
The outer layer describes metadata created by the server, with the actual notification inside the body element.
When a client marks a notification as read a new message is pushed onto the user’s queue in this format:
{
"key": "4b89c48a8d8e11e18db6109add558619",
"queue": "https://push.mozilla.org/queue/5116f9fd48d3c792d0d93df93d889fa3bfada77f",
"timestamp": "1335217809.001793",
"body": {
"read": "4ae183428d8e11e1a007109add558619"
}
}
The outer layer is the same as the new message format.
The body differs in that it contains a single key read, with a value that points to the key of a previous message.