Compare Revisions

The Publicity Stream API

Change Revisions

Revision 78296:

Revision 78296 by 21echoes on

Revision 78297:

Revision 78297 by 21echoes on

The Publicity Stream API
The Publicity Stream API
NeedsContent, NeedsEditorialReview
NeedsContent, NeedsEditorialReview

Revision 78296
Revision 78297
n11      The <em>publicity stream</em>&nbsp;is a web-provided collecn11      The <em>publicity stream</em>&nbsp;is a Mozilla-hosted <a c
>tion of applications that a user can install or has installed. Th>lass=" external" href="" title="http://act
>e applications are presented to a user in a manner conducive to t>">Activity Stream</a> generated by a user's applica
>he browsing, selection, and installation of applications. Applica>tion usage. The publicity stream is provided as a central place f
>tions can be curated with the assistance of our client-side API s>or applications to publicize application usage for the purpose of
>uite, documented here.> notifying a user's friends of the applications which their frien
 >ds are using. It is <em>not</em> meant as a general application m
 >essaging system.
12    </p>
13    <p>
14      We have implemented a prototype store in HTML5 at <code>app
></code>, but future stores could be implemen 
>ted in regular HTML5 sites, potentially with <a class=" external" 
> href=" 
>y">browser extended storage</a>, or as part of a web browser plat 
n20      The application web store API can be enabled by including an17      The publicity API can be enabled by including a javascript 
> javascript library. This library will detect whether native API >library. This library will detect whether native API support is e
>support is enabled by the user's browser, if not it will shim in >nabled by the user's browser, if not it will shim in a pure HTML 
>a pure HTML implementation. [is this still doable?]>implementation. [is this still doable?]
n29      All APIs related to open web applications are accessed unden26      All APIs related to open web applications are accessed unde
>r the <code>navigator.apps</code> object. There are two distinct >r the <code>navigator.apps</code> object.
>types of functions available in the recommendation API: 
n31    <ol>n
32      <li>
33        <p>
34          <strong>Publicity Stream Functions</strong> - related t
>o the social promotion and recommendation of installed applicatio 
>ns - Interesting to stores, self-distributing applications, and d 
35        </p>
36      </li>
37      <li>
38        <p>
39          <strong>Recommendation Engine Functions</strong> - rela
>ted to the curation of applications relevant to the user's needs  
>and the user's and the user's friends' existing apps. Primarily u 
>sed by stores. 
40        </p>
41      </li>
42    </ol>
t132    <h3>t
133      Recommendation Engine API (<code>navigator.apps.recommendat
>ions.*</code>) <a name="recommendation-api" id="recommendation-ap 
134    </h3><a name="recommendation-api" id="recommendation-api"></a
135    <p>
136      The Recommendation Engine API is part of the application st
>ore API which is intended to help stores (or dashboards) list rel 
>evant application recommendations for their users. The API expose 
>s calls based around three recommendation styles: similar applica 
>tions, integrating applications, and socially publicized applicat 
137    </p>
138    <ul>
139      <li style="list-style: none">
140        <a name="recommendation-api" id="recommendation-api"></a>
141      </li>
142      <li>
143        <a name="recommendation-api" id="recommendation-api"></a>
144        <p>
145          <code>getPublicizedApps( onsuccess callback, [ onerror 
>callback ], [ {&nbsp;[ store_apps: &lt;list&gt; ], [ count: &lt;i 
>nt&gt;&nbsp;] } ] )</code> 
146        </p>
147        <p>
148          Publicized apps are applications which friends of the c
>urrent user have installed, are using, and have decided to share  
>activity with the current user. Will pop up a doorhanger to log t 
>he current user into the publicity stream. 
149        </p>
150        <p>
151          <a name="recommendation-api" id="recommendation-api"><s
>trong>onsuccess</strong> is called with a single argument: a list 
> of application manifests which our engine has found to be sharin 
>g activity with the current user, via communication with the</a>  
><a href="/publicity-api" title="publicity-api">Publicity Stream</ 
152        </p>
153        <p>
154          <strong>onerror</strong>&nbsp;is an <a href="#error-obj
>ect">error callback</a> that will be invoked if the installation  
>fails. Possible error codes include: 
155        </p>
156        <ul>
157          <li>
158            <code>denied</code> - if the user does not log in cor
159          </li>
160          <li>
161            <code>permissionDenied</code> - if the site is not al
>lowed to request publicized applications 
162          </li>
163          <li>
164            <code>networkError</code> - if the publicity server i
>s unreachable 
165          </li>
166          <li>
167            <code>invalidOrigin</code>&nbsp;- if the origin or li
>st of store_apps does not point to valid applications 
168          </li>
169        </ul>
170      </li>
171      <li>
172        <p>
173          <code>getSimilarApps( &lt;origin&gt;, onsuccess callbac
>k,&nbsp;[ onerror callback ], [ {&nbsp;[ store_apps: &lt;list&gt; 
> ], [ count: &lt;int&gt; ] } ] )</code> 
174        </p>
175        <p>
176          Similar apps are applications which perform similar tas
>ks, produce and consume similar content, and can be categorized i 
>n the same way. 
177        </p>
178        <p>
179          <code>origin</code> is the origin of the application fo
>r which you want recommendations of similar applications. 
180        </p>
181        <p>
182          <strong>onsuccess</strong> is called with a single argu
>ment: a list of application manifests which our engine has deemed 
> "similar" to the app provided at <code>origin</code> 
183        </p>
184        <p>
185          <strong>onerror</strong> is an <a href="#error-object">
>error callback</a> that will be invoked if the request fails. Pos 
>sible error codes include: 
186        </p>
187        <ul>
188          <li>
189            <code>permissionDenied</code> - if the site is not al
>lowed to request similar applications 
190          </li>
191          <li>
192            <code>networkError</code> - if the recommendation ser
>ver is unreachable 
193          </li>
194          <li>
195            <code>invalidOrigin</code> - if the origin or list of
> store_apps does not point to valid applications 
196          </li>
197        </ul>
198        <p>
199          <strong>store_apps</strong> is a list of applications w
>hich limits the return values to only those within the <strong>st 
>ore_apps</strong> list. This filtering happens prior to any limit 
>ing via <strong>count</strong> 
200        </p>
201        <p>
202          <strong>count</strong> is the number of applications wh
>ich should be returned, with a maximum of [25] and a default of [ 
203        </p>
204        <p>
205          [how to get similar apps that integrate with what i alr
>eady 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)? s 
>hould this call just have integration concerns baked in? what abo 
>ut a NSPredicate-style query-building API?] 
206        </p>
207      </li>
208      <li>
209        <p>
210          <code>getIntegratingApps( &lt;origin&gt;, onsuccess cal
>lback, [ onerror callback ], [ { [ store_apps: &lt;list&gt;&nbsp; 
>], [ count: &lt;int&gt; ] )</code> 
211        </p>
212        <p>
213          Integrating apps are applications which consume content
> created by the specified application or produce content which sa 
>id app can consume (eg., if your application takes pictures with  
>the webcam, flickr would be an integrating app because you can pu 
>blish those pictures to flickr). See the services section in <a h 
>ref="/en/OpenWebApps/The_Manifest" title="en/OpenWebApps/The_Mani 
>fest">the manifest</a> for more details on cross-app communicatio 
>n and integration. 
214        </p>
215        <p>
216          <code>origin</code> is the origin of the application fo
>r which you want recommendations of similar applications. 
217        </p>
218        <p>
219          <strong>onsuccess</strong> is called with a single argu
>ment: a list of application manifests which our engine has found  
>"integrable" with the app provided at <code>origin</code> 
220        </p>
221        <p>
222          <strong>onerror</strong> is an <a href="#error-object">
>error callback</a> that will be invoked if the installation fails 
>. Possible error codes include: [ 
223        </p>
224        <ul>
225          <li>
226            <code>permissionDenied</code> - if the site is not al
>lowed to request integrating applications 
227          </li>
228          <li>
229            <code>networkError</code> - if the recommendations se
>rver is unreachable 
230          </li>
231          <li>
232            <code>invalidOrigin&nbsp;</code>- if the origin or li
>st of store_apps does not point to valid applications 
233          </li>
234        </ul>
235        <p>
236          <strong>store_apps</strong> is a list of applications w
>hich limits the return values to only those within the <strong>st 
>ore_apps</strong> list. This filtering happens prior to any limit 
>ing via <strong>count</strong> 
237        </p>
238        <p>
239          <strong>count</strong> is the number of applications wh
>ich should be returned, with a maximum of [25] and a default of [ 
240        </p>
241      </li>
242      <li>
243        <p>
244          [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] 
245        </p>
246      </li>
247    </ul>
248    <h3>
249      Application Representation <a name="app-object" id="app-obj
250    </h3><a name="app-object" id="app-object"></a>
251    <p>
252      Wherever <em>application objects</em> are returned via the 
>api, they are represented as javascript objects with the followin 
>g fields: 
253    </p>
254    <ul>
255      <li>
256        <code>manifest (object)</code>: The currently stored vers
>ion of the manifest of the application. 
257      </li>
258      <li>
259        <code>origin (string)</code>: The origin of the applicati
>on (scheme, host, and port) 
260      </li>
261      <li>
262        <code>install_data (object)</code>: data provided at the 
>time <code>navigator.apps.install()</code> was invoked. 
263      </li>
264      <li>
265        <code>install_origin (string)</code>: The origin of the s
>ite that triggered the installation of the application. 
266      </li>
267      <li>
268        <code>install_time (integer)</code>: The time that the ap
>plication was installed (generated via Date().getTime, represente 
>d as the number of milliseconds between midnight of January 1st,  
>1970 and the time the app was installed). 
269      </li>
270    </ul>
271    <h3>
272      <a name="app-object" id="app-object">Error Objects</a> <a n
>ame="error-object" id="error-object"></a> 
273    </h3><a name="error-object" id="error-object"></a>
274    <p>
275      Errors are returned via callbacks in the API. Errors are re
>presented as javascript objects with the following properties: 
276    </p>
277    <ul>
278      <li>
279        <code>code (string):</code> A short, english, camel cased
> error code that may be programmatically checked to optimize user 
> facing error displays. 
280      </li>
281      <li>
282        <code>message (string)</code>: A short, english, develope
>r readable sentence that describes the cause of the error in more 
> specifics. Useful for debugging and error logs. 
283      </li>
284    </ul>

Back to History