The Publicity Stream API

The Publicity Stream

The publicity stream is a Mozilla-hosted Activity Stream generated by a user's application usage. The publicity stream is provided as a central place for applications to publicize application usage for the purpose of notifying a user's friends of the applications which their friends are using. It is not meant as a general application messaging system.

Accessing the API

The publicity API can be enabled by including a javascript library. This library will detect whether native API support is enabled by the user's browser, if not it will shim in a pure HTML implementation. [is this still doable?]

The javascript library should be included from:

https://myapps.mozillalabs.com/jsapi/publicity.js

All APIs related to open web applications are accessed under the navigator.apps object.

Publicity Stream API (navigator.apps.publicity.*)

The publicity API is exposed as properties on the navigator.apps.publicity object.

• publicizeActivity( <activity>, [ { [ onsuccess: <function> ], [ onerror: <function> ] } ]):

  Applications should call this method when an user-initiated activity deemed attractive to potential consumers occurs. This spawns a doorhanger which allows the user to specify which users can view the activity, and (following successful login and authorization with the stream server) registers the activity in a stream at [ADDRESS]. This stream can be pulled down by getPublicityStream() and helps determine the results for getUserRecommendedApps().

  example use cases: 'Adam got a high score in Mafia Wars', 'Bethany bought a plane ticket to the Caribbean', etc.

  activity is an object, formatted as per the FIXME: deadLinkActivity Streams open specification.

  onsuccess is a callback that will be invoked with no arguments if the activity is successfully posted.

  onerror is an error callback that will be invoked if the publicity fails. Possible error codes include:

  • denied - if the user refuses to publicize the activity
  • permissionDenied - if the publicizing site is not allowed to post to the publicity stream
  • networkError - if the publicity server is unreachable
  • activityParseError - if the activity contains syntax errors (not proper JSON)
  • invalidActivity - if the activity contains semantic errors (i.e. missing required properties)

  Finally, the publicizeActivity() function will throw an exception if required arguments are missing, or if unsupported arguments are present.

• getPublicityStream( onsuccess: <function>, { [ onerror: <function> ], [ for_apps: <list> ], [ since: <Date> ], [ before: <Date> ], [ count: <int> ]):

  Provides a means for a web store to receive a list of the current user's socially relevant app activity by being called from an origin which hosts a web store. It is not recommended that applications consume the publicity stream in any way (please use your own server for any in-app social aspects). It is suggested that the list be processed and condensed into an attractive, cohesive format for users (eg., multiple tweets show as 'Adam tweeted 4 times').

  onsuccess will be called with a single argument: a json list of the current user's socially relevant app activity in the FIXME: deadLinkActivity Streams open specification.

  onerror is an error callback that will be invoked if the installation fails. Possible error codes include:

  • denied - if the user does not log in correctly
  • permissionDenied - if the site is not allowed to access the publicity stream
  • networkError - if the publicity server is unreachable

  for_apps is a json list of apps that this store has (each represented as its origin URL), so that stream events not relating to applications in a given presentation context can be excluded from the return value. If null or an empty list is passed, events for all apps are returned.

  since The timestamp of the earliest event you want returned. If not specified, will default to the beginning of the stream.

  before The timestamp of the latest event you want returned. If not specified, will default to now.

  count The maximum number of events to return, with preference given to more recent events [make this preference its own parameter?]. If not specified, will default to [25].