mozilla

Revision 78297 of The Publicity Stream API

  • Revision slug: The_Publicity_Stream_API
  • Revision title: The Publicity Stream API
  • Revision id: 78297
  • Created:
  • Creator: 21echoes
  • Is current revision? No
  • Comment 48 words added, 1152 words removed

Revision Content

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.

Revision Source

<h3>The Publicity Stream</h3>
<p>The <em>publicity stream</em> is a Mozilla-hosted <a class=" external" href="http://activitystrea.ms" title="http://activitystrea.ms/">Activity Stream</a> 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 <em>not</em> meant as a general application messaging system.</p>
<h3>Accessing the API <a name="accessing-the-api"></a></h3><a name="accessing-the-api">
<p>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?]</p>
<p>The javascript library should be included from:</p>
<pre><code>https://myapps.mozillalabs.com/jsapi/publicity.js</code></pre>
<p>All APIs related to open web applications are accessed under the <code>navigator.apps</code> object.</p>
</a><h3><a name="accessing-the-api">Publicity Stream API (<code>navigator.apps.publicity.*</code>) </a><a name="publicity-api"></a></h3><a name="publicity-api">
<p>The publicity API is exposed as properties on the <code>navigator.apps.publicity</code> object.</p>
</a><ul><a name="publicity-api"> </a><li><a name="publicity-api"> <p><code>publicizeActivity( &lt;activity&gt;, [ { [ onsuccess: &lt;function&gt; ], [ onerror: &lt;function&gt; ] } ]):</code></p> <p>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().</p> <p>example use cases: 'Adam got a high score in Mafia Wars', 'Bethany bought a plane ticket to the Caribbean', etc.</p> </a><p><a name="publicity-api"><code>activity</code> is an <code>object</code>, formatted as per the </a><a href="/activitystrea.ms" title="activitystrea.ms">Activity Streams</a> open specification.</p> <p><strong>onsuccess</strong> is a callback that will be invoked with no arguments if the activity is successfully posted.</p> <p><strong>onerror</strong> is an <a href="#error-object">error callback</a> that will be invoked if the publicity fails. Possible error codes include:</p> <ul> <li><code>denied</code> - if the user refuses to publicize the activity</li> <li><code>permissionDenied</code> - if the publicizing site is not allowed to post to the publicity stream</li> <li><code>networkError</code> - if the publicity server is unreachable</li> <li><code>activityParseError</code> - if the activity contains syntax errors (not proper JSON)</li> <li><code>invalidActivity</code> - if the activity contains semantic errors (i.e. missing required properties)</li> </ul> <p>Finally, the publicizeActivity() function will throw an exception if required arguments are missing, or if unsupported arguments are present.</p> </li> <li> <p><code>getPublicityStream( onsuccess: &lt;function&gt;, { [ onerror: &lt;function&gt; ], [ for_apps: &lt;list&gt; ], [ since: &lt;Date&gt; ], [ before: &lt;Date&gt; ], [ count: &lt;int&gt; ]):</code></p> <p>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 <em>not</em> 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').</p> <p><strong>onsuccess</strong> will be called with a single argument: a json list of the current user's socially relevant app activity in the <a href="/activitystrea.ms" title="activitystrea.ms">Activity Streams</a> open specification.</p> <p><strong>onerror</strong> is an <a href="#error-object">error callback</a> that will be invoked if the installation fails. Possible error codes include:</p> <ul> <li><code>denied</code> - if the user does not log in correctly</li> <li><code>permissionDenied</code> - if the site is not allowed to access the publicity stream</li> <li><code>networkError</code> - if the publicity server is unreachable</li> </ul> <p><strong>for_apps</strong> 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.</p> <p><strong>since</strong> The timestamp of the earliest event you want returned. If not specified, will default to the beginning of the stream.</p> <p><strong>before</strong> The timestamp of the latest event you want returned. If not specified, will default to now.</p> <p><strong>count</strong> 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].</p> </li>
</ul>
Revert to this revision