Social API guide

This article describes the lifecycle of a social service worker, how the social service lets the browser interact with a social media site, and so forth.

Lifecycle of a social service worker

A social service provider is defined by a structured text file (JSON) containing a number of keyed URLs, a name, and an icon. URLs have the same origin as the JSON file if remotely loaded.

A service worker is instantiated from the service worker URL provided by the service provider; this URL should resolve to a JavaScript file that is evaluated by the service worker. The worker is a shared worker, rendered "headlessly," in a style very similar to the Web Workers specification (though note that the current implementation is not, in fact, a Worker).

The service worker lives until terminated, either by browser shutdown or by an explicit control command from the user.

If the browser determines that termination of the service worker is necessary, all of the service-level content associated with the service worker is unloaded (that is, all ServiceWindows and sidebars are closed) as part of the termination.

If the browser starts (or restarts) the service during a normal user session, the service worker is fully loaded first, and sidebars are then instantiated on existing windows. ServiceWindows (such as chats) are not restarted automatically.

Implementation flow

This section illustrates how the social service is started up, communicates with the social media site, and shuts down.

<<<add an actual diagram>>>

1. The service is registered with a service, sidebar widget, and share widget.
2. At browser startup time, the service worker is instantiated.
3. The service opens a connection to its service, if a user session is available, and starts receiving push events.
4. When a browser window is created, the sidebar widget content is instantiated.
5. The sidebar may connect with the background worker by using mozSocial.getWorker().port.postMessage("hello").
6. The service worker catches the "hello" message and adds the sidebarContentWindow to a list of event sinks.
7. The sidebar content may then perform more elaborate publish-subscribe handshaking, to limit what events it receives.
8. When the service receives events from the server (or from other content), it may communicate those events to any, or all, of the windows by invoking window.postMessage() on each window reference.
9. If the user clicks in the sidebar to, for example, open a chat window, MozSocial.openChatWindow() is called and a new window is created. The chat window registers with the service by using mozSocial.getWorker().postMessage("hello") and receives a message back telling it who to open a chat with. The service might then deliver server-pushed events to the chat window, perhaps through a publish-subscribe system.