A social service manifest is a JSON file that describes to the browser how to instantiate a service worker for a service provider.  The manifest is installed through a web activation page located on the providers website, or from a directory service such as AMO.  You can see an example of the manifest and activation on the github demo project.

Service discovery

Services are expected to promote their providers to their users either through their own website or through Mozilla Marketplace.  You are expected to follow criteria we have for SocialAPI providers in Firefox.

Service activation

Activating your service from your website is available starting in Firefox 23.

A Service is described by a small JSON manifest.  This manifest can be sent to the browser by creating and dispatching the ActivateSocialFeature DOM event.  This event must be user initiated for the browser to accept the data.  The target element of the event must have a data-service attribute containing the serialized manifest.  Details of the manifest contents are below. 

Once the user clicks the activate button, they will be presented with an installation panel to enable your provider.  If they choose to enable your provider, they will then see an explanatory panel that highlights the new Social toolbarbutton as well as indicates how they may manage their social providers through the Add-ons Manager.

Here is an example of providing a button on your webpage to allow users to activate your provider:

<html>
<head>
  <title>Demo Social Service</title>
</head>
<script>
var loc = location.href;
var baseurl = loc.substring(0,loc.lastIndexOf('/'));

var data = {
  // currently required
  "name": "Demo Social Service",
  "iconURL": baseurl+"/firefox16.png",
  "icon32URL": baseurl+"/firefox32.png",
  "icon64URL": baseurl+"/firefox64.png",

  // the URL of the contents for the share panel
  "shareURL": baseurl+"/share.html?url=%{url}",

  // icons should be 32x32 pixels
  "markedIcon": baseurl+"/unchecked.jpg",
  "unmarkedIcon": baseurl+"/checked.jpg",

  // should be available for display purposes
  "description": "A short paragraph about this provider",
  "author": "Shane Caraveo, Mozilla",
  "homepageURL": "https://github.com/mixedpuppy/socialapi-demo/",

  // optional
  "version": "1.0"
}

function activate(node) {
  var event = new CustomEvent("ActivateSocialFeature");
  node.setAttribute("data-service", JSON.stringify(data));
  node.dispatchEvent(event);
}
</script>
<body>
  <button onclick="activate(this)" title="activate the demo provider">Activate The Demo Provider</button>
</body>
</html>

Manifest contents

At a minimum, a social service manifest must contain a services object property that contains a social object property. All URLs in the manifest should be HTTPS URLs, though DATA URLs are currently supported for images.  The social object may contain the following values:

name
The name of the service.
iconURL, icon32URL, icon64URL
The URL of an icon to use for the service in the user interface.  Starting with Firefox 22, all three sizes must be present.
workerURL Optional Obsolete since Gecko 48
The URL of a JavaScript file that defines the social service worker for the service. optional, necessary if using statusURL to provide notifications
sidebarURL Optional Obsolete since Gecko 51
The URL of an HTML file that defines the sidebar used by the service. The manifest must contain at least one of sidebarURL, shareURL, statusURL, markURL.
shareURL
The URL of an HTML file that defines a share endpoint used by the service. required
statusURL Optional Obsolete since Gecko 51
The URL of an HTML file that defines a status or notifications endpoint used by the service. [Status buttons available as of Fx26 or 27] The manifest must contain at least one of sidebarURL, shareURL, statusURL, markURL.
markURL Obsolete since Gecko 51
The URL of an HTML file that defines a social bookmark endpoint used by the service. [Social Bookmarks available as of Fx26] The manifest must contain at least one of sidebarURL, shareURL, statusURL, markURL.
markedIcon Optional Obsolete since Gecko 51
The URL of a 32x32px PNG icon that is shown in the social bookmark toolbar button as the marked state [Social Bookmarks available as of Fx26]  required if using markURL
unmarkedIcon Optional Obsolete since Gecko 51
The URL of a 32x32px PNG icon that is shown in the social bookmark toolbar button as the default or unmarked state [Social Bookmarks available as of Fx26]  required if using markURL
description
A short description of the provider service.
author
An author or company name.
homepageURL
The URL of an HTML page on the providers website that allows users to activate the provider.
version Optional
The release version of this provider; useful for supporting upgrades.

Example

{
  "name": "Example Social Service",
  "iconURL": "/icon.png",
  "icon32URL": "/icon32.png",
  "icon64URL": "/icon64.png",
  "workerURL": "/worker.js",
  "sidebarURL": "/sidebar.htm",
  "shareURL": "/share.htm?url=%{url}",
  "statusURL":"/statusPanel.html",
  "markURL": "/mark.html?url=%{url}",
  "markedIcon": "/unchecked.jpg",
  "unmarkedIcon": "/checked.jpg",
  "description": "A short description of the service.",
  "author": "Your name or company",
  "homepageURL": "/index.html",
  "version": "1.0"
}