mozilla

Revision 78296 of The Publicity Stream API

  • Revision slug: The_Publicity_Stream_API
  • Revision title: The Publicity Stream API
  • Revision id: 78296
  • Created:
  • Creator: 21echoes
  • Is current revision? No
  • Comment page created, 1537 words added
Tags: 

Revision Content

The Publicity Stream

The publicity stream is a web-provided collection of applications that a user can install or has installed. The applications are presented to a user in a manner conducive to the browsing, selection, and installation of applications. Applications can be curated with the assistance of our client-side API suite, documented here.

We have implemented a prototype store in HTML5 at appstore.mozillalabs.com, but future stores could be implemented in regular HTML5 sites, potentially with browser extended storage, or as part of a web browser platform.

Accessing the API

The application web store 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/recommendations.js

All APIs related to open web applications are accessed under the navigator.apps object. There are two distinct types of functions available in the recommendation API:

  1. Publicity Stream Functions - related to the social promotion and recommendation of installed applications - Interesting to stores, self-distributing applications, and dashboards.

  2. Recommendation Engine Functions - related to the curation of applications relevant to the user's needs and the user's and the user's friends' existing apps. Primarily used by stores.

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

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

Recommendation Engine API (navigator.apps.recommendations.*)

The Recommendation Engine API is part of the application store API which is intended to help stores (or dashboards) list relevant application recommendations for their users. The API exposes calls based around three recommendation styles: similar applications, integrating applications, and socially publicized applications.

  • getPublicizedApps( onsuccess callback, [ onerror callback ], [ { [ store_apps: <list> ], [ count: <int> ] } ] )

    Publicized apps are applications which friends of the current user have installed, are using, and have decided to share activity with the current user. Will pop up a doorhanger to log the current user into the publicity stream.

    onsuccess is called with a single argument: a list of application manifests which our engine has found to be sharing activity with the current user, via communication with the Publicity Stream.

    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 request publicized applications
    • networkError - if the publicity server is unreachable
    • invalidOrigin - if the origin or list of store_apps does not point to valid applications
  • getSimilarApps( <origin>, onsuccess callback, [ onerror callback ], [ { [ store_apps: <list> ], [ count: <int> ] } ] )

    Similar apps are applications which perform similar tasks, produce and consume similar content, and can be categorized in the same way.

    origin is the origin of the application for which you want recommendations of similar applications.

    onsuccess is called with a single argument: a list of application manifests which our engine has deemed "similar" to the app provided at origin

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

    • permissionDenied - if the site is not allowed to request similar applications
    • networkError - if the recommendation server is unreachable
    • invalidOrigin - if the origin or list of store_apps does not point to valid applications

    store_apps is a list of applications which limits the return values to only those within the store_apps list. This filtering happens prior to any limiting via count

    count is the number of applications which should be returned, with a maximum of [25] and a default of [15].

    [how to get similar apps that integrate with what i already have (ie, i'm looking at a thing that works with to-dos, but not with RTM, and i wanna find something that works with RTM)? should this call just have integration concerns baked in? what about a NSPredicate-style query-building API?]

  • getIntegratingApps( <origin>, onsuccess callback, [ onerror callback ], [ { [ store_apps: <list> ], [ count: <int> ] )

    Integrating apps are applications which consume content created by the specified application or produce content which said app can consume (eg., if your application takes pictures with the webcam, flickr would be an integrating app because you can publish those pictures to flickr). See the services section in the manifest for more details on cross-app communication and integration.

    origin is the origin of the application for which you want recommendations of similar applications.

    onsuccess is called with a single argument: a list of application manifests which our engine has found "integrable" with the app provided at origin

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

    • permissionDenied - if the site is not allowed to request integrating applications
    • networkError - if the recommendations server is unreachable
    • invalidOrigin - if the origin or list of store_apps does not point to valid applications

    store_apps is a list of applications which limits the return values to only those within the store_apps list. This filtering happens prior to any limiting via count

    count is the number of applications which should be returned, with a maximum of [25] and a default of [15].

  • [the three above recommendation API calls may all want already_owned as an optional argument, so that the server doesn't needlessly return apps that the user already has]

Application Representation

Wherever application objects are returned via the api, they are represented as javascript objects with the following fields:

  • manifest (object): The currently stored version of the manifest of the application.
  • origin (string): The origin of the application (scheme, host, and port)
  • install_data (object): data provided at the time navigator.apps.install() was invoked.
  • install_origin (string): The origin of the site that triggered the installation of the application.
  • install_time (integer): The time that the application was installed (generated via Date().getTime, represented as the number of milliseconds between midnight of January 1st, 1970 and the time the app was installed).

Error Objects

Errors are returned via callbacks in the API. Errors are represented as javascript objects with the following properties:

  • code (string): A short, english, camel cased error code that may be programmatically checked to optimize user facing error displays.
  • message (string): A short, english, developer readable sentence that describes the cause of the error in more specifics. Useful for debugging and error logs.

Revision Source

<h3>The Publicity Stream</h3>
<p>The <em>publicity stream</em> is a web-provided collection of applications that a user can install or has installed. The applications are presented to a user in a manner conducive to the browsing, selection, and installation of applications. Applications can be curated with the assistance of our client-side API suite, documented here.</p>
<p>We have implemented a prototype store in HTML5 at <code>appstore.mozillalabs.com</code>, but future stores could be implemented in regular HTML5 sites, potentially with <a class=" external" href="http://wiki.mozilla.org/Labs/Apps/Browser_Native_Repository">browser extended storage</a>, or as part of a web browser platform.</p>
<h3>Accessing the API <a name="accessing-the-api"></a></h3><a name="accessing-the-api">
<p>The application web store 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/recommendations.js</code></pre>
<p>All APIs related to open web applications are accessed under the <code>navigator.apps</code> object. There are two distinct types of functions available in the recommendation API:</p>
<ol> <li> <p><strong>Publicity Stream Functions</strong> - related to the social promotion and recommendation of installed applications - Interesting to stores, self-distributing applications, and dashboards.</p> </li> <li> <p><strong>Recommendation Engine Functions</strong> - related to the curation of applications relevant to the user's needs and the user's and the user's friends' existing apps. Primarily used by stores.</p> </li>
</ol>
</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>
<h3>Recommendation Engine API (<code>navigator.apps.recommendations.*</code>) <a name="recommendation-api"></a></h3><a name="recommendation-api">
<p>The Recommendation Engine API is part of the application store API which is intended to help stores (or dashboards) list relevant application recommendations for their users. The API exposes calls based around three recommendation styles: similar applications, integrating applications, and socially publicized applications.</p>
</a><ul><a name="recommendation-api"> </a><li><a name="recommendation-api"> <p><code>getPublicizedApps( onsuccess callback, [ onerror callback ], [ { [ store_apps: &lt;list&gt; ], [ count: &lt;int&gt; ] } ] )</code></p> <p>Publicized apps are applications which friends of the current user have installed, are using, and have decided to share activity with the current user. Will pop up a doorhanger to log the current user into the publicity stream.</p> </a><p><a name="recommendation-api"><strong>onsuccess</strong> is called with a single argument: a list of application manifests which our engine has found to be sharing activity with the current user, via communication with the </a><a href="/publicity-api" title="publicity-api">Publicity Stream</a>.</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 request publicized applications</li> <li><code>networkError</code> - if the publicity server is unreachable</li> <li><code>invalidOrigin</code> - if the origin or list of store_apps does not point to valid applications</li> </ul> </li> <li> <p><code>getSimilarApps( &lt;origin&gt;, onsuccess callback, [ onerror callback ], [ { [ store_apps: &lt;list&gt; ], [ count: &lt;int&gt; ] } ] )</code></p> <p>Similar apps are applications which perform similar tasks, produce and consume similar content, and can be categorized in the same way.</p> <p><code>origin</code> is the origin of the application for which you want recommendations of similar applications.</p> <p><strong>onsuccess</strong> is called with a single argument: a list of application manifests which our engine has deemed "similar" to the app provided at <code>origin</code></p> <p><strong>onerror</strong> is an <a href="#error-object">error callback</a> that will be invoked if the request fails. Possible error codes include:</p> <ul> <li><code>permissionDenied</code> - if the site is not allowed to request similar applications</li> <li><code>networkError</code> - if the recommendation server is unreachable</li> <li><code>invalidOrigin</code> - if the origin or list of store_apps does not point to valid applications</li> </ul> <p><strong>store_apps</strong> is a list of applications which limits the return values to only those within the <strong>store_apps</strong> list. This filtering happens prior to any limiting via <strong>count</strong></p> <p><strong>count</strong> is the number of applications which should be returned, with a maximum of [25] and a default of [15].</p> <p>[how to get similar apps that integrate with what i already have (ie, i'm looking at a thing that works with to-dos, but not with RTM, and i wanna find something that works with RTM)? should this call just have integration concerns baked in? what about a NSPredicate-style query-building API?]</p> </li> <li> <p><code>getIntegratingApps( &lt;origin&gt;, onsuccess callback, [ onerror callback ], [ { [ store_apps: &lt;list&gt; ], [ count: &lt;int&gt; ] )</code></p> <p>Integrating apps are applications which consume content created by the specified application or produce content which said app can consume (eg., if your application takes pictures with the webcam, flickr would be an integrating app because you can publish those pictures to flickr). See the services section in <a href="/en/OpenWebApps/The_Manifest" title="en/OpenWebApps/The_Manifest">the manifest</a> for more details on cross-app communication and integration.</p> <p><code>origin</code> is the origin of the application for which you want recommendations of similar applications.</p> <p><strong>onsuccess</strong> is called with a single argument: a list of application manifests which our engine has found "integrable" with the app provided at <code>origin</code></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>permissionDenied</code> - if the site is not allowed to request integrating applications</li> <li><code>networkError</code> - if the recommendations server is unreachable</li> <li><code>invalidOrigin </code>- if the origin or list of store_apps does not point to valid applications</li> </ul> <p><strong>store_apps</strong> is a list of applications which limits the return values to only those within the <strong>store_apps</strong> list. This filtering happens prior to any limiting via <strong>count</strong></p> <p><strong>count</strong> is the number of applications which should be returned, with a maximum of [25] and a default of [15].</p> </li> <li> <p>[the three above recommendation API calls may all want already_owned as an optional argument, so that the server doesn't needlessly return apps that the user already has]</p> </li>
</ul>
<h3>Application Representation <a name="app-object"></a></h3><a name="app-object">
<p>Wherever <em>application objects</em> are returned via the api, they are represented as javascript objects with the following fields:</p>
<ul> <li><code>manifest (object)</code>: The currently stored version of the manifest of the application.</li> <li><code>origin (string)</code>: The origin of the application (scheme, host, and port)</li> <li><code>install_data (object)</code>: data provided at the time <code>navigator.apps.install()</code> was invoked.</li> <li><code>install_origin (string)</code>: The origin of the site that triggered the installation of the application.</li> <li><code>install_time (integer)</code>: The time that the application was installed (generated via Date().getTime, represented as the number of milliseconds between midnight of January 1st, 1970 and the time the app was installed).</li>
</ul>
</a><h3><a name="app-object">Error Objects </a><a name="error-object"></a></h3><a name="error-object">
<p>Errors are returned via callbacks in the API. Errors are represented as javascript objects with the following properties:</p>
<ul> <li><code>code (string):</code> A short, english, camel cased error code that may be programmatically checked to optimize user facing error displays.</li> <li><code>message (string)</code>: A short, english, developer readable sentence that describes the cause of the error in more specifics. Useful for debugging and error logs.</li>
</ul></a>
Revert to this revision