WebAPI/PushAPI old

Contents

ATTENTION: OLD DOCS

This document is an old version of the PushAPI. This is updated by WebAPI/PushAPI.

OLD DOC

Push notifications are a way for websites to send small messages to users when
the user is not on the site. iOS and Android devices already support their own
push notification services, but we want to make notifications available to the
whole web.

Status

The server API needs to be verified by someone that knows server-infrastructure better than me.

We should also verify this API against the experiences from Google here: [1]

The url property contains the URL which the site can send messages to this user. It's up to the site to send the URL to the backend for storage.

The supportedVersions property contains a list of server-protocol versions that the server supports. The website should always use the first version in this array that it supports. Later versions in the array are more likely to be deprecated first.

The userMessages/appMessages/appBadges properties indicate which types of push messages the website is allowed to push using the server API.

If the site has been granted permission already and is calling requestURL() again, we can return the same URL without bothering the user.

getCurrentURL() lets the site ask Firefox if the site has a push URL without bothering the user. The function behaves the same way as requestURL() except for the case when requestURL() would prompt the user. I.e. if the user has already granted permission, or if the user has permanently denied permission, then getCurrentURL behaves the same as requestURL. However if the user hasn't yet made a decision, then getCurrentURL results in a success event, but with request.result set to null.

revokeURL() lets the website indicate that it no longer wants to be able to push messages using the indicated URL.

Server API

On the server side we're looking at an HTTP interface that accepts POSTs
with these attributes:

type: "userMessage", "appMessage" or "appBadge"

body: Secondary text of the notification. Only relevant for "userMessage" and "appMessage"

iconUrl: URL of the icon to be shown with this notification. Only relevant for "userMessage"

title: Primary text of the notification. Only relevant for "userMessage"

actionUrl: URL to be opened if the user clicks on the notification. Only relevant for "userMessage"

replaceId: A string which identifies a group of like messages. If the user is offline, only the last message with the same replaceId will be sent when the user comes back online. Only relevant for "userMessage"

count: The new badge count for the app. Only relevant for "addBadge"

The format of the payload is still TBD; it's a toss-up between
JSON blobs and form-urlencoded parameters.

The server can also issue a DELETE request to the URL to indicate that it no longer wants to send push messages. This is useful for example if the developer accidentally leaked the URL.