Web Activities

Web activities are currently enabled on Firefox OS only, and the full specification is available on WikiMo.

Activities

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

Registering an App as an activity handler

App authors can build an app that will handle one or more activities. That means that the app will be callable by another app to perform some specific actions defined by the activity. For example, let's pretend we want to build a photo manager. It could be used by another application to pick a photo. As an activity handler our app will become part of the other application's workflow.

Register an activity

There is currently only one way to register an app as an activity handler: declaring it in the app manifest.

App manifest (a.k.a. declaration registration)

We have to use the app manifest to express that our app is expected to handle an activity as in this example:

{
  // Other App Manifest related stuff
  // Activity registration
  "activities": {
    // The name of the activity to handle (here "pick")
    "pick": {
      "href": "./pick.html",
      "disposition": "inline",
      "filters": {
        "type": ["image/*","image/jpeg","image/png"]
      },
      "returnValue": true
    }
  }
}

Dynamic registration

There are plans to let an app register itself dynamically by using the navigator object. However, this API is not available yet. See bug 775181 to follow the work about that specific API.

Activity handler description

href

When another app or Web page initiates an activity that is supported by this app, if this app is chosen to perform the activity, this specifies the page that will be opened. It will be opened in the manner specified by the disposition property.

Note: The URL of this page is restricted by the rules of the same origin policy.

disposition Optional

Specifies how the page specified in href is presented when an activity is invoked. The value, if specified, must be one of the following (if omitted, defaults to window):

• window - The page handling the activity is opened in a new "window" (on a mobile device this view will replace the original app that requested the activity). The page must call navigator.mozSetMessageHandler() for each activity it supports and subsequently execute the activity for which it receives a message.
• inline - The page that handles the activity will open in an overlay (on a mobile device this will be rendered in a popup over the original app that requested the activity). Subsequent behavior is exactly the same as if disposition were window.

returnValue Optional

States if the activity will return a value or not. If an application doesn't plan to return a value, the UA may send a success event as soon as an application has been picked. If a value is expected, the activity handler must call MozActivityRequestHandler.postResult() if the activity is successful or MozActivityRequestHandler.postError() if the activity fails (where MozActivityRequestHandler is the type of the first argument provided to the function specified within mozSetMessageHandler by the activity handler). The success or error event will be respectively fired after postResult or postError has been called by the activity handler.

filters Optional

A dictionary where each property of which specifies a filter. These filters will be applied while determining apps suitable for handling a given activity. Filter names are free-form text and should mirror data properties' names from MozActivityOptions. Filters' values are either a basic value (string or number), an array of basic values, or a filter definition object. An activity will be considered as able to handle an activity only if the filters are all satisfied.

The way filters are handled depend on each filter value:

• If the filter value is a basic value, the corresponding MozActivityOptions.data property is optional but if the property exist it must have the same value as the one provided by the filter.
• If the filter value is an array of basic values, the corresponding MozActivityOptions.data property is optional but if the property exists its value must be equal to one of the values available in the array provided by the filter.
• If the filter value is a filter definition object, the filter will be satisfied if the corresponding MozActivityOptions.data property follows the rules defined by the object. A filter definition object can have the following properties:
  • required: A boolean that indicates if the corresponding MozActivityOptions.data property must exist (true) or not (false).
  • value: A basic value or an array of basic value. The corresponding MozActivityOptions.data property value must be equal to one of the values defined in the filter.
  • min: If the expected value is a number, the corresponding MozActivityOptions.data property value must be greater than or equal to that value.
  • max: If the expected value is a number, the corresponding MozActivityOptions.data property value must be lesser than or equal to that value.
  • pattern: A string pattern following the JavaScript regular expression syntax. The corresponding MozActivityOptions.data property value must match that pattern. This is supported in Firefox OS from v1.2.
  • patternFlags: If the pattern property is used, this property can be used to provide some extra regular expression flag such as i or g. This is supported in Firefox OS from v1.2.
  • regexp: A string containing a regexp litteral following the JavaScript regular expression syntax. The corresponding MozActivityOptions.data property value must match that pattern. In contrary to the pattern flag, this can match only part of the value, therefore you must use the metacharacters ^ and $ to respectively match the start and the end of the string. This is supported in Firefox OS v1.0 and v1.1 only. Therefore you're advised to use both pattern and regexp.

Handle an activity

Once our application is declared as an activity handler, we have to make it concrete by performing some actions when receiving an activity request from another app.

To handle the activity, we have to register a function that will perform all the necessary actions. To do so, we need to set a message handler with navigator.mozSetMessageHandler(), specifically assigned to the 'activity' message (and not the name of the activity). A MozActivityRequestHandler object is passed as an argument of the activity handler function.

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  // Do something to handle the activity
});

As the activity handler function is performing an action, it will use the activity request to retrieve information about the activity and to send back an answer if necessary.

The app that calls the activity has to provide some data (see below). This data can be reached through the request's source properties which is a MozActivityOptions object. This object provides the name of the activity call and the associated data.

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  var option = activityRequest.source;
  if (option.name === "pick") {
    // Do something to handle the activity
  }
});

Once we have performed all the actions to handle the activity, we can call the request's postResult() method to send the result back to the app that delegated the activity.

If something goes wrong we can call the request's postError() method to send back an error message about the activity.

navigator.mozSetMessageHandler('activity', function(activityRequest) {
  var option = activityRequest.source;
  if (option.name === "pick") {
    // Do something to handle the activity
    ...
    // Send back the result
    if (picture) {
      activityRequest.postResult({
        type: picture.type,
        blob: picture
      });
    } else {
      activityRequest.postError("Unable to provide a picture");
    }
  }
});

Be aware that you need to have returnValue: true set in your manifest file to return a result (see manifest activities for more information.) If there is no result to return, then you should just use window.close() to get rid of the handling window.

Starting an activity

On the other side of Web Activities, there are apps that want to delegate an activity to our app. To perform such delegation, the apps have to call an activity by instantiating a MozActivity object. Such objects are nothing less than DOMRequest objects that allow to wait for any response from the activity handler. As soon as the object is constructed, the activity is started, and the UI is shown to the user as soon as possible.

var activity = new MozActivity({
  // Ask for the "pick" activity
  name: "pick",
  // Provide the data required by the filters of the activity
  data: {
    type: "image/jpeg"
  }
});
activity.onsuccess = function() {
  var picture = this.result;
  console.log("A picture has been retrieved");
};
activity.onerror = function() {
  console.log(this.error);
};

Further information: contact retrieval

In Firefox OS 1.3 and below, picking contacts is handled like like:

switch (this.activityDataType) {
  case 'webcontacts/tel':
    type = 'contact';
    dataSet = theContact.tel;
    noDataStr = _('no_contact_phones');
    break;
  case 'webcontacts/contact':
    type = 'number';
    dataSet = theContact.tel;
    noDataStr = _('no_contact_phones');
    break;
  case 'webcontacts/email':
    type = 'email';
    dataSet = theContact.email;
    noDataStr = _('no_contact_email');
    break;
}

If you want a persons name and telephone number you can then use:

var pick = new MozActivity({
  name: "pick",
  data: {
    type: "webcontacts/contact"
  }
});
pick.onsuccess = function () {
  console.log("got contact");
  var contact = this.result;
  if( contact ){
    console.log( "Name " + contact.name + " number "+ contact.number );
  }
};

In Firefox OS 2.0+ we added a field that if you use webcontacts/contact you can get the whole contact:

var pick = new MozActivity({
  name: "pick",
  data: {
    type: "webcontacts/contact",
    fullContact: "true"
  }
});

This returns is a Contact Object, which you can use the properties of directly:

pick.onsuccess = function (Contact) {
  console.log( "Name " + Contact.name + " number "+ Contact.number );
};

Firefox OS activities

Gaia, the native interface for Firefox OS, provides many built-in applications that define basic activities. Those activities are the following:

type: "photos"

target: "device"

type: "webtelephony/number",
number: { 
  regexp: "^[\\d\\s+#*().-]{0,50}$"
}

type: "webcontacts/contact"

type: "mail"

type: "websms/sms",
number: {
  regexp: "^[\\w\\s+#*().-]{0,50}$"
}

type: "webcontacts/contact"

type: [
  "image/jpeg",
  "image/png",
  "image/gif",
  "image/bmp"
]

type: [
  "audio/mpeg",
  "audio/ogg",
  "audio/mp4"
]

type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

type: ["image/*", "image/jpeg"]

type: [
  "webcontacts/contact",
  "webcontacts/email"
]

type: [
  "webcontacts/contact",
  fullContact: "true"
]

type: ["photos", "videos"]

type: "url",
url: {
  required:true,
  regexp:/^https?:/
}

number: 1

type: "image/*"

type: "url"
url: {
  required: true,
  regexp: /^https?:.{1,16384}$/
}

type: "url",
url: {
  required:true,
  regexp: "^mailto:"
}

type: "application/pdf"

type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

type: "webcontacts/contact"

Firefox for Android activities

Firefox for Android 32+ allows installed webapps using the WebappRT to launch native Android intents via Web Activities. For security reasons, only explicitly mapped activities / intents are supported. Those activities are the following:

type: "webtelephony/number",
number: "+11234567890"

type: "image/jpeg",
uri: "http://mozilla.org/image.jpg"

type: "image/jpeg"

type: "text/plain",
text: "my message"

type: "text/html",
html_text: "<strong>my</strong> message"

type: "url",
url: "http://mozilla.org/"

type: "url",
uri: "mailto:user@mozilla.org"

Specification

Web Activities is not part of any specification. However, it has some overlap with the proposed Web Intents specification. Mozilla actually proposed Web Activities as a counter proposal to Web Intents. For more information about this, see discussion on the Web Intents Task Force ML.

See also

• MozActivity
• MozActivityRequestHandler
• MozActivityOptions
• navigator.mozSetMessageHandler()
• Introducing Web Activities
• Firefox OS Image Uploader Sample App