Web Activities

  • Revision slug: WebAPI/Web_Activities
  • Revision title: Web Activities
  • Revision id: 365243
  • Created:
  • Creator: MarkGiffin
  • Is current revision? No
  • Comment

Revision Content

Web activities define a way for applications to delegate an activity to another (usually user-chosen) application. Web activities have some overlap with Web Intents.

Web activities are currently only enabled on Firefox OS. Until this page is complete you can refer to WebActivities.

Activities

An activity is something a user wants to do like pick an image, send an e-mail, etc. App authors will want to define an app that can handle an activity or that delegate to an activity.

Registering an app as an activity handler

Register an activity

In this case, you want your app to be used by other apps to take care of a part of their workflow. There are two ways to register an app as an actvity handler: declaring it in the app manifest and registering it dynamically.

App manifest (a.k.a declaration registration)

In the app manifest you express that your app is expected to handle an activity as in this example:

{
  "name": "Inc Activity",
  "description": "+1",
  "launch_path": "./index.html",
  "activities": {
    "increment": {
      "filters": {
        "type": "text"
      },
      "href": "./index.html",
      "disposition": "window"
    }
  }
}

Dynamic registration

This has not been implemented yet. See {{bug("775181")}} to track the status of this bug.

var r = navigator.mozRegisterActivityHandler(activityHandlerDescription);

Activity handler description

href
can be used to register an activity handler in another page. Needs to be same origin.
disposition
could be window or inline for the moment. window means it will show a new window/tab. inline means it will be shown above the current content. This is only a hint for the UA.
returnValue
the UA might want to know if the activity will return a value. For the basic activities (view, edit, etc.) the UA knows that but we need that at least for proprietary activities.
This seems to be needed to be able to send a success or error event when appropriate. If an application doesn't return a value, the UA might want to send a success event as soon as an application has been picked. If a value is expected, this event will have to wait postResult() to be called. Note that UA is expected to send an error event at some point if neither postError nor postResult are called. For example, if the user leaves the application (close the tab on desktop or goes back to the homescreen on a mobile device).
filters
this object should mirror data from ActivityOptions but the values for each fields can be an Array of string, a string or a regexp. An activity will be considered as able to handle an activity only if the filters are all satisfied. An array means OR for each items. If there is no filter value for a field, that means it is always satisfied. 

Unregister and check if an activity is registered

This has not been implemented yet. See {{bug("775181")}} to track the status of this bug.

navigator.mozUnregisterActivityHandler(activityHandlerDescription);
var bool = navigator.mozIsActivityHandlerRegistered(activityHandlerDescription);

In both cases, an activity is identified by an activity handler description. The values of the different fields are used to identify the activity handler. Rules for what makes 2 handlers the same are still unclear.

Handle an activity

In this part you want to handle the activity, that is, perform some actions when recieving an activity request from another app.

navigator.mozSetMessageHandler('activity', function(req) {
  req.source;
  // do something
  req.postResult(result);
});

You need to set a message handler specifically to the 'activity' message (and not the name of the activity). An ActivityRequestHandler object is passed as an argument of the activity handler.

ActivityRequestHandler

interface ActivityRequestHandler {
  void postResult(any result);
  void postError(DOMString error);
  readonly attribute ActivityOptions source;
};

Call postResult() when you're doing handling the activity and want to send the result back to the app that delegated the activity. Call postError() to indicate an error occured when handling the activity.

source is a {name, data} object in which the name is the activity name and data is an object containing the data passed as Activity argument.

Using an activity

In this case, you want your app to delegate an activity to another app.

var a = new MozActivity({ name: "increment", data: {a:1, b:"blah"} });
a.onsuccess = function() { console.log('Increment user', "Activity launched and succeeded") };
a.onerror = function() { console.log('Increment user', "Activity error ", this.error.message, this.error.name) };

The call to the MozActivity() constructor triggers the activity and synchronously returns a DOMRequest.

See also

List of available activities (separate between built-in and other)

Revision Source

<p>Web activities define a way for applications to delegate an activity to another (usually user-chosen) application. Web activities have some overlap with <a href="http://www.w3.org/TR/web-intents/" title="http://www.w3.org/TR/web-intents/">Web Intents</a>.</p>
<p>Web activities are currently only enabled on Firefox OS. Until this page is complete you can refer to <a href="https://wiki.mozilla.org/WebAPI/WebActivities" title="https://wiki.mozilla.org/WebAPI/WebActivities">WebActivities</a>.</p>
<h2 id="Activities">Activities</h2>
<p>An activity is something a user wants to do like pick an image, send an e-mail, etc. App authors will want to define an app that can handle an activity or that delegate to an activity.</p>
<h2 id="Registering_an_app_as_an_activity_handler">Registering an app as an activity handler</h2>
<h3 id="Register_an_activity">Register an activity</h3>
<p>In this case, you want your app to be used by other apps to take care of a part of their workflow.&nbsp;There are two ways to register an app as an actvity handler: declaring it in the app manifest and registering it dynamically.</p>
<h4 id="App_manifest_(a.k.a_declaration_registration)">App manifest (a.k.a declaration registration)</h4>
<p>In the app manifest you express that your app is expected to handle an activity as in this example:</p>
<pre class="brush: js">
{
  "name": "Inc Activity",
  "description": "+1",
  "launch_path": "./index.html",
  "activities": {
    "increment": {
      "filters": {
        "type": "text"
      },
      "href": "./index.html",
      "disposition": "window"
    }
  }
}
</pre>
<h4 id="Dynamic_registration">Dynamic registration</h4>
<p>This has not been implemented yet. See {{bug("775181")}} to track the status of this bug.</p>
<pre class="brush: js">
var r = navigator.mozRegisterActivityHandler(activityHandlerDescription);
</pre>
<h4 id="Activity_handler_description">Activity handler description</h4>
<dl>
  <dt>
    href</dt>
  <dd>
    can be used to register an activity handler in another page. Needs to be same origin.</dd>
</dl>
<dl>
  <dt>
    disposition</dt>
</dl>
<dl>
  <dd>
    could be <i>window</i> or <i>inline</i> for the moment. <i>window</i> means it will show a new window/tab. <i>inline</i> means it will be shown above the current content. This is only a hint for the UA.</dd>
</dl>
<dl>
  <dt>
    returnValue</dt>
  <dd>
    the UA might want to know if the activity will return a value. For the basic activities (view, edit, etc.) the UA knows that but we need that at least for proprietary activities.</dd>
  <dd>
    This seems to be needed to be able to send a <i>success</i> or <i>error</i> event when appropriate. If an application doesn't return a value, the UA might want to send a <i>success</i> event as soon as an application has been picked. If a value is expected, this event will have to wait <i>postResult()</i> to be called. Note that UA is expected to send an <i>error</i> event at some point if neither <i>postError</i> nor <i>postResult</i> are called. For example, if the user leaves the application (close the tab on desktop or goes back to the homescreen on a mobile device).</dd>
</dl>
<dl>
  <dt>
    filters</dt>
  <dd>
    this object should mirror <i>data</i> from <i>ActivityOptions</i> but the values for each fields can be an Array of string, a string or a regexp. An activity will be considered as able to handle an activity only if the filters are all satisfied. An array means OR for each items. If there is no filter value for a field, that means it is always satisfied.&nbsp;</dd>
</dl>
<h3 id="Unregister_and_check_if_an_activity_is_registered">Unregister and check if an activity is registered</h3>
<p>This has not been implemented yet. See {{bug("775181")}} to track the status of this bug.</p>
<pre class="brush: js" style="font-size: 14px;">
navigator.mozUnregisterActivityHandler(activityHandlerDescription);
var bool = navigator.mozIsActivityHandlerRegistered(activityHandlerDescription);
</pre>
<p>In both cases, an activity is identified by an activity handler description. The values of the different fields are used to identify the activity handler. Rules for what makes 2 handlers the same are still unclear.</p>
<h3 id="Handle_an_activity">Handle an activity</h3>
<p>In this part you want to handle the activity, that is, perform some actions when recieving an activity request from another app.</p>
<pre class="brush: js">
navigator.mozSetMessageHandler('activity', function(req) {
  req.source;
  // do something
  req.postResult(result);
});</pre>
<p>You need to set a message handler specifically to the <code>'activity'</code> message (and not the name of the activity). An <code>ActivityRequestHandler</code>&nbsp;object is passed as an argument of the activity handler.</p>
<h4 id="ActivityRequestHandler">ActivityRequestHandler</h4>
<pre class="brush: js">
interface ActivityRequestHandler {
  void postResult(any result);
  void postError(DOMString error);
  readonly attribute ActivityOptions source;
};</pre>
<p>Call <code>postResult()</code>&nbsp;when you're doing handling the activity and want to send the result back to the app that delegated the activity. Call <code>postError()</code> to indicate an error occured when handling the activity.</p>
<p><code>source</code> is a <code>{name, data}</code> object in which the <code>name</code> is the activity name and <code>data</code> is an object containing the data passed as Activity argument.</p>
<h2 id="Using_an_activity">Using an activity</h2>
<p>In this case, you want your app to delegate an activity to another app.</p>
<pre class="brush: js" id=".C2.A0">
var a = new MozActivity({ name: "increment", data: {a:1, b:"blah"} });
a.onsuccess = function() { console.log('Increment user', "Activity launched and succeeded") };
a.onerror = function() { console.log('Increment user', "Activity error ", this.error.message, this.error.name) };
</pre>
<p>The call to the&nbsp;<code>MozActivity()</code> constructor triggers the activity and synchronously returns a <a href="/en-US/docs/DOM/DOMRequest" title="/en-US/docs/DOM/DOMRequest">DOMRequest</a>.</p>
<h2 id="See_also">See also</h2>
<p>List of available activities (separate between built-in and other)</p>
Revert to this revision