Web Activities

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

This API is available on Firefox or Firefox OS for installed or higher privileged applications.

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

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.

Note: Any application can register itself as an activity handler for any existing activity or create its own activity. In both cases it's done the same way within the app manifest. However, when creating a new activity, it is considered best practice to avoid activities' name collisions by prefixing the name of the new activity with a URL (e.g., example.org/myActivity or org.example.myActivity ).

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(picture);
    } else {
      activityRequest.postError("Unable to provide a picture");
    }
  }
});

Note: UA is expected to send an error anyway at some point if neither postError nor postResult() are called--for example, if the user leaves the application (closes the tab on desktop or goes back to the home screen on a mobile device).

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);
};

Firefox OS activities

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

Name Application Expected Data (filters) Comments
browse Gallery
type: "photos"
 
configure Settings
target: "device"
 
costcontrol/balance Costcontrol None  
costcontrol/data_usage Costcontrol None  
costcontrol/telephony Costcontrol None  
dial Communication
type: "webtelephony/number",
number: { 
  regexp:/^[\\d\\s+#*().-]{0,50}$/
}
Used when an app wants to pass a phone call.
new Communication
type: "webcontacts/contact"
Used when an app wants to create a new contact entry.
Email
type: "mail"
 
SMS
type: "websms/sms",
number: {
  regexp:/^[\\w\\s+#*().-]{0,50}$/
}
Used when an app wants to send an SMS.
open Communication
type: "webcontacts/contact"
 
Gallery
type: [
  "image/jpeg",
  "image/png",
  "image/gif",
  "image/bmp"
]
 
Music
type: [
  "audio/mpeg",
  "audio/ogg",
  "audio/mp4"
]
 
Video
type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

Also expect a blob property which is a Blob object.

Used when an app wants to display a video (the view activity allows to do the same).
pick Camera, Gallery, Wallpaper
type: ["image/*", "image/jpeg"]
Used when an app wants to get a picture.
Communication
type: [
  "webcontacts/contact",
  "webcontacts/email"
]
Used when an app wants to retrieve some contact information or an e-mail.
record Camera
type: ["photos", "videos"]
Used when an app wants to record some video.
save-bookmark Homescreen
type: "url",
url: {
  required:true,
  regexp:/^https?:/
}
 
share Bluetooth
number: 1
 
Email, Wallpaper
type: "image/*"
Used when an app wants to share an image.
view Browser
type: "url"
url: {
  required: true,
  regexp: /^https?:.{1,16384}$/
}
Used when an app wants to open a URL.
Email
type: "url",
url: {
  required:true,
  regexp:/^mailto:/
}
 
PDFs
type: "application/pdf"
Used when an app wants to display the content of a PDF document.
Video
type: [
  "video/webm",
  "video/mp4",
  "video/3gpp",
  "video/youtube"
]

Also expect a url property which is a string.

Used when an app wants to display a video (the open activity allows to do the same).
update Communication
type: "webcontacts/contact"
Used when an app wants to update a contact.

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

Document Tags and Contributors

Last updated by: chrisdavidmills,