Social service installation

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 with Firefox 23 [TBD, Firefox Nightly at this time].

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",

  // at least one of these must be defined
  "workerURL": baseurl+"/worker.js",
  "sidebarURL": baseurl+"/sidebar.htm",
  "shareURL": baseurl+"/share.html?url=%{url}",

  // status buttons are scheduled for Firefox 26 or 27
  "statusURL": baseurl+"/statusPanel.html",

  // social bookmarks are available in Firefox 26
  "markURL": baseurl+"/mark.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. required
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. required
workerURL
The URL of a JavaScript file that defines the social service worker for the service. optional, necessary if using statusURL to provide notifications
sidebarURL
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 is required.
shareURL
The URL of an HTML file that defines a share endpoint used by the service. [Share available as of Fx23] The manifest must contain at least one of sidebarURL, shareURL, statusURL, markURL is required.
statusURL
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 is required.
markURL
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 is required.
markedIcon
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
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.  required
author
An author or company name.  required
homepageURL
The URL of an HTML page on the providers website that allows users to activate the provider.  required
version
The release version of this provider.  optional, useful for upgrade support
 

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

 

Document Tags and Contributors

Tags:
Contributors to this page: Sheppy, willyaguirre, jswisher, Mixedpuppy
Last updated by: Sheppy,