Social API temp

by 2 contributors:

Browser Social API Reference

https://github.com/mixedpuppy/socialapi-demo contains a test provider implementation that demonstrates the use of many of these APIs. Reading through it will help illustrate the documentation provided here.

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 are 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 message require a response - this is part of the message specification. Messages which don't require a response are analogous to an unsolicitied '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)

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.

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.

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 users 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.

dispayName

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

profileURL

String, required. URL to the logged in users 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:

name

String. An identifier for the icon. The first time a given name is seen, it effectively creates a new icon. If the same name is used in subsequent calls, the existing icon is updated.

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:

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.

Page Marks

STATUS: TARGETING Fx23 (replacing Link Recommendation below)

Page Marks are a simple mechanism to share a url with a social provider.  Page Marks differs from Share in that the url is only sent to the provider.  This functionality can handle use cases such as Facebook Like, Google +1, Pocket, or other save-for-later features.  When enabled, and additional Mark button will appear at the end of the Social toolbarbutton in Firefox.  There is no UI associated with the button other than a change of the button image to reflect the current marked or unmarked state.

social.page-mark-config

Sent by the worker to notify Firefox of support for Page Marks.  This message can be sent at any time, we recommend sending it when handling the social.initialize message.

Arguments:

images

Object. Must have 2 string keys, 'marked' and 'unmarked', which will be used as the Page Mark button icon.   The user agent will track if the current page has been marked - if so, it will show the 'marked' image, otherwise will show the 'unmarked' image. It can contain a web-addressible image or a data URL containing dynamically-generated image data.  Implementors are strongly encouraged to use a data URL to minimize latency. Each image is expected to be 16px wide and 16px high.

messages

Object. Must have the following string keys:

  • 'markedTooltip', 'unmarkedTooltip': The strings used as the tooltip on the click target when the 'marked' and 'unmarked' images, respectively, are shown.
  • 'markedLabel', 'unmarkedLabel': Strings that will be used to update a label widget after the 'marked' or 'unmarked' action is taken to reflect the transition from marked-to-unmarked or vice-versa.

social.page-mark

Sent by Firefox to the worker when the user marks or unmarks a page.  No response is expected.  Firefox will track the marked state of the page seperately from the provider.  If the user clears history, all tracked page marks will be removed.

Arguments:

url

String. The url of the page being marked.

marked

Boolean.


NOTE: The following user-recommend messages are DEPRECATED and removed as of Fx23.  The have been replaced by Page Marks.

social.user-recommend-prompt

STATUS: DEPRECATED, REMOVED Fx23, REPLACED WITH social.page-mark-config

Sent by the browser to request the visual prompt for the "user recommendation" interface element. The Worker should respond with a user-recommend-prompt-response

Note that typically this message will only be sent when a provider is activated and the response will be used for all URLs. In other words, the provider should not expect this message to be sent each time the user agent navigates or displays a new URL.

Arguments:

None

social.user-recommend-prompt-response

STATUS: DEPRECATED, REMOVED Fx23

The Worker constructs and posts a user-recommend-prompt-response in response to a social.user-recommend-prompt message received from the browser. See social.user-recommend-prompt for more details.

Arguments:

images

Object. Must have 2 string keys, 'share' and 'unshare', which each value being the URL to an image which will be set as the "src" property of an image contained in the user-facing click target for the "recommend" action. The user agent will track if the current page has been shared - if so, it will show the 'unshare' image, otherwise will show the 'share' image. It can contain a web-addressible image or a data URL containing dynamically-generated image data. Implementors are strongly encouraged to use a data URL to minimize latency. Each image is expected to be 16px wide and 16px high.

messages

Object. Must have the following string keys:

  • 'shareTooltip', 'unshareTooltip': The strings used as the tooltip on the click target when the 'share' and 'unshare' images, respectively, are shown.
  • 'sharedLabel', 'unsharedLabel': Strings that will be used to update a label widget after the 'share' or 'unshare' action is taken to reflect the transition from shared-to-unshared or vice-versa. Note that in Fx17, the labels are not visible but are used as an accessibility aid so a screen-reader or similar can note the transition.
  • 'unshareLabel': A string to be displayed on the 'unshare popup' to reflect the item has been shared. Eg: "You previously shared this item".
  • 'portraitLabel': A string used as the aria-label for the user's profile image shown in the 'unshare popup'. Eg: "Your profile image"
  • 'unshareConfirmLabel': A string used as the label on the button on the 'unshare popup' used to perform the 'unshare'. Eg: "Unshare it"
  • 'unshareConfirmAccessKey': A string used as the access key for the unshare button. Typically this should be a letter included in the 'unshareConfirmLabel' string.
  • 'unshareCancelLabel': A string used as the label on the button on the 'unshare popup' when the user desires to continue sharing the item. Eg: "Close".
  • 'unshareCancelAccessKey': A string used as the access key for the unshare cancel button.

social.user-recommend

STATUS: DEPRECATED, REMOVED Fx23, REPLACED WITH social.page-mark

Indicates that the user has clicked the "user recommendation" interface element. The message includes:

Arguments:

url

String, required. The URL that the user is viewing, including query string, but minus any hash text, of the root of the current browser viewing context.

No response is necessary; however, the service may respond on the same port with a user-recommend-prompt-response if the click target should change its appearance.

social.user-unrecommend

STATUS: DEPRECATED, REMOVED Fx23

Indicates that the user would like to retract their previous recommendation. The message includes:

Arguments:

url

String, required. The URL that the user is viewing, including query string, but minus any hash text, of the root of the current browser viewing context.


Widgets

SidebarWidget

If a service defines a SidebarWidget, the browser will instantiate a content region with the SidebarWidget URL as the location on some browser windows. These regions will not be instantiated until the Worker has been fully loaded. The content in these regions has the additional API defined in the Service Content API reference, above.

Sidebars can be in a visible or hidden state.

  • When visible, they will receive a vertical rectangle of screen space in which to render; this rectangle is stable across changes in tab focus and has an independent scrollbar from the scrollbar of tabbed browsing content.
  • When hidden, a sidebar is completely removed from the visual hierarchy. The user agent will continue to deliver messages to it, and the sidebar may pre-render its DOM for later display.

Sidebar windows will only be instantiated on browser windows that have a full tabbed-browsing interface; windows created with window.open that do not have these interface elements will not have a sidebar.

When a tab that is rendered directly by the browser without a location bar is selected, the sidebar will automatically be placed into the hidden state. When the user navigates away from that tab, the sidebar will be made visible again. These tabs include the Add-ons management page, about:permissions, etc.

The minimized/maximized/hidden state of the sidebar widget is will be consistent across all browser windows. The most-recently-set state is remembered and used for new windows, and is persisted across browser restarts.

Messages Sent to Widgets

STATUS: DONE Fx17

socialFrameHide

DOM Event sent by the browser when the user hides the sidebar content.

socialFrameShow

DOM Event sent by the browser when the user shows the sidebar content.

Browser "Panel" Integration

STATUS: DONE Fx17

To allow content to place an ephemeral window in front of normal browser content and chrome, the following API is used:

`navigator.mozSocial.openChatWindow( url, callback)`

The callback will receive the window object from the chat frame.

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 } }

Discovery and Service Manifest

Discovery

STATUS: NOT TARGETED

As a user browses web sites Firefox can discover new social providers and offer installation of those providers. A social providers website would include a LINK tag in the header pointing to a manifest file to enable this form of discovery. If the user either has stored authentication credentials in the Firefox password manager, or if the user frequents the website, Firefox will show a notification bar allowing the user to install the service.

Activation

STATUS: DONE Fx17

A provider can become activated by dispatching a custom event of "ActivateSocialFeature" on the document. The document's location is then checked against a built-in whitelist and if the location is found then the feature is activated for that provider.

We recommend that providers require their users to click a link or button to activate the feature so the user is aware of the new functionality.

function activate() {
  var event = new CustomEvent("ActivateSocialFeature");
  document.dispatchEvent(event);
}
 

Document Tags and Contributors

Contributors to this page: Mixedpuppy, Sheppy
Last updated by: Mixedpuppy,