Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
Obsolete since Gecko 48 (Firefox 48 / Thunderbird 48 / SeaMonkey 2.45)
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Service Workers based on SocialAPI are deprecated, and were removed in Firefox 48. You can use Service Workers or Shared Workers to accomplish some of the same capabilities.
This Service worker is part of Mozilla's Social API. If you are looking for information on the new W3C ServiceWorker proposal for caching, http response control , etc., go to the ServiceWorker landing page instead.
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.