Social service worker API reference

Service Worker Reference

A Service Worker inherits all the limitations and behaviors available to HTML5 Shared Workers. It can create XMLHttpRequests, use WebSockets, receive messages from windows and the browser, use IndexedDB, and post messages to other windows.

The Worker can use the ononline, onoffline, and navigator.online methods and properties that are available to all Workers to obtain notification of the browser's online/offline status.

In addition to the standard methods, Service Workers have access to additional functionality, all of which is implemented using messages sent and received by worker "message ports". As message ports are inherently asynchronous, any message that requires a response will involve two messages - one for the request and one for the response. Not all messages require a response - this is part of the message specification. Messages that don't require a response are analogous to an unsolicited 'event'. If a message does require a response, then the response must always be sent on the same port as the request and in general, the 'topic' of the response will be the topic of the request with "-response" appended.

Service workers are expected to provide a function at global scope, named onconnect. The browser will invoke onconnect at startup time, passing in an event. The worker should access the ports property of this event to extract a stable communication port back to the browser, and persist it for the life of the worker, like this:

var apiPort;
var ports = [];
onconnect = function(e) {
    var port = e.ports[0];
    ports.push(port);
    port.onmessage = function (msgEvent)
    {
        var msg = msgEvent.data;
        if (msg.topic == "social.port-closing") {
            if (port == apiPort) {
                apiPort.close();
                apiPort = null;
            }
            return;
        }
        if (msg.topic == "social.initialize") {
            apiPort = port;
            initializeAmbientNotifications();
        }
    }
}

// send a message to all provider content
function broadcast(topic, data) {
  for (var i = 0; i < ports.length; i++) {
    ports[i].postMessage({topic: topic, data: data});
  }
}

Every message has a data element with 2 fields; 'topic' and 'data'. The topic identifies which method or event is being used, and the data specifies additional data unique to the topic. All standardized methods and events have topics that begin with "social." - this means services are free to use topics without this prefix as a private implementation detail (for example, to communicate between some content from the service and the service's worker).

Message Serialization

For a message with topic topic and arguments (arg1:val1, arg2:val2), construct an object like:

{ topic: topic, data: { arg1: val1, arg2: val2 } }

Control Messages sent to Service Workers

social.initialize

Sent by the browser during startup. When a worker's JavaScript has been successfully loaded and evaluated, the browser will send a message with this topic.  When the worker receives the social.initalize event, it should send both the social.user-profile and, if Page Marks are supported [as of Fx23], the social.page-mark-config message.

social.port-closing

Sent by the browser during worker shutdown, when a MessagePort to the worker is about to be closed. This will be the last message the worker receives on the port.

Control Messages sent from Service Workers to the browser

social.reload-worker

Sent by the worker to request the browser to reload the worker.

social.cookies-get

Sent by the worker to request the browser to respond with a list of same-origin cookies for the provider. The browser will respond with a social.cookies-get-response message.

social.request-chat

Sent by the worker to request the browser to open a new floating chat panel with the specified url. Chat windows opened by the worker will be opened in a minimized mode.

Arguments:

url

String, required.  The url to the chat page to open in the window.

Ambient Notification Control

social.user-profile

Sent by the worker to set the properties for the provider icon and user profile data used for the toolbar button. If the user's portrait and userName are absent, the button UI will indicate a logged out state. When indicating logged out state, status icons set via social.ambient-notification will be removed. A service that does not handle user login should send this message with values appropriate to the website, such as the site icon, home url, and brand name.

Arguments:

iconURL

String, required. If supplied, specifies the URL to a 16x16 pixel image used for the status icon. The iconURL can be a data url with encoded image to avoid additional http requests (e.g., "data:image/png;base64,...data...").

portrait

String, optional. If supplied, specifies the URL to a 48x48 pixel image of the user. The portrait can be a data url with encoded image to avoid additional http requests.

userName

String, optional. Account name displayed with the portrait in the provider menu.

displayName

String, required. Real name of the user used for display purposes in various UI elements.

profileURL

String, required. URL to the logged in user's profile page. This will be opened in a normal browser tab when the username is clicked on.

social.ambient-notification

Sent by the worker to update or create an ambient notification icon. One is sent for each icon. A user must be logged in to show status icons, and you must call social.user-profile prior to calling social.ambient-notification to set status icons.

Arguments:

label

String, optional.  An label for the icon tooltip, which otherwise defaults to the name given in the manifest.

iconURL

String, optional. If supplied, specifies the URL to a 16x16 pixel image used for the status icon. The iconURL can be a data url with encoded image to avoid additional http requests (e.g., "data:image/png;base64,...data...").

counter

Number, optional. Specifies a number that will be overlaid over the icon, typically used to convey an unread concept.

contentPanel

String, optional. Specifies the URL of content that will be displayed in the popup panel for the icon.

Active Notification Control

social.notification-create

Sent by the worker to create and display a notification object. This requests that the browser notify the user of an immediately-relevant change in state. See https://developer.mozilla.org/en/DOM/navigator.mozNotification for more detail. When the user clicks on the notification, the social.notification-action message is sent to the worker. The title of the notification will always be the name of the provider.

NOTE: We want to augment the mozNotification object defined in the docs with an additional "type" field. Details TBD. NOTE: No way of allowing duration and no way exposed to "cancel" a notification (assumption is they are very short-lived). Is this OK?

Arguments:

id

String: An ID for the notification. This ID will not be displayed but will be passed back via a social.notification-action event if the user clicks on the notification.

type

String: The Type string should be consistent for each type of notification. This may be used by some notification systems to provide user-level filtering of notifications. A provider may choose any string for the type, but should keep the type strings consistent and descriptive for each type of action. For example, chat notifications should always have the same type string. Suggested/example notifications include:

• social.providername.chat-request
• social.providername.friend-request
• social.providername.activity (e.g., someone posted to your activity stream)

icon

String/null. The URL of an image to be placed in the notification. While this can be any valid URL, implementers are strongly encouraged to use a data URL to minimize latency.

body

String: The body of the notification message. This body will be rendered as a hyperlink and may be clicked. HTML markup is not supported.

action

String: An action to perform when the user clicks on the notification. If no action is provided, the notification is not clickable. Currently the only actions supported are link, callback, and openServiceWindow. If the action is defined, actionArgs should also be defined.

actionArgs

Object: An object with arguments for actions (above). Supported actions and their actionArgs are:

• link
  • toURL: String: url to open in a new browser tab

social.notification-action

Sent to the worker as a response to a "callback" notification, after the user has clicked on the notification.

Arguments: None

id

String: the ID of the notification that was clicked.

action

String: The action sent in social.notification-create.

actionArgs

Object: The actionArgs sent in social.notification-create.

Upgrading the Manifest

Available starting Firefox 24

You may fetch and set your manifest data. This allows you to check if the manifest for your provider in Firefox is up to date, and allows you to update the manifest if necessary. When you update your manifest, any content loaded from your provider will be reloaded automatically. It is recommended you use the version attribute on the manifest to track versioning of your provider.

social.manifest-get

Sent by the worker to request the installed manifest data from Firefox. This message can be sent at any time. Firefox will respond with a social.manifest message containing the manifest data.

Arguments: None

social.manifest-set

Sent by the worker to update the installed manifest data in Firefox. This message can be sent at any time. Firefox will reload the provider after saving the new manifest.

Arguments:

data

JSON Object. The manifest data.