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 to installed code running on Firefox for Android, and is intended for use by Firefox for Android Webapps in Firefox for Android 32+.
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 ororg.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 towindow
):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 callnavigator.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 ifdisposition
werewindow
.
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 orMozActivityRequestHandler.postError()
if the activity fails (whereMozActivityRequestHandler
is the type of the first argument provided to the function specified withinmozSetMessageHandler
by the activity handler). The success or error event will be respectively fired afterpostResult
orpostError
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 fromMozActivityOptions
. 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 correspondingMozActivityOptions.data
property must exist (true
) or not (false
).value
: A basic value or an array of basic value. The correspondingMozActivityOptions.data
property value must be equal to one of the values defined in the filter.min
: If the expected value is a number, the correspondingMozActivityOptions.data
property value must be greater than or equal to that value.max
: If the expected value is a number, the correspondingMozActivityOptions.data
property value must be lesser than or equal to that value.pattern
: A string pattern following the JavaScript regular expression syntax. The correspondingMozActivityOptions.data
property value must match that pattern. This is supported in Firefox OS from v1.2.patternFlags
: If thepattern
property is used, this property can be used to provide some extra regular expression flag such asi
org
. This is supported in Firefox OS from v1.2.regexp
: A string containing a regexp litteral following the JavaScript regular expression syntax. The correspondingMozActivityOptions.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 bothpattern
andregexp
.
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.
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); };
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:
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. |
type: "mail" |
Used when an app wants to send a new Email. The e-mail app can parse mailto URI strings provided as either a "url" or "URI" property. Attachments can be provided by populating parallel "blobs" and "filenames" arrays where then nth filename corresponds to the nth blob. |
||
SMS |
type: "websms/sms", number: { regexp: "^[\\w\\s+#*().-]{0,50}$" } |
Used when an app wants to send an SMS. | |
nfc-ndef-discovered | n/a | None | Used when an app wants to exchange data/tags with an app on another device. |
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 |
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" ] as of Firefox OS 2.0, you can specify a fullContact: "true" field to return a complete contact object that you can access the properties of directly: type: [ "webcontacts/contact", fullContact: "true" ] |
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. |
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 |
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. |
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:
MozActivity | Android Intent | ||||
---|---|---|---|---|---|
Name | Expected Data | Action | Extras | MIME | URI |
dial |
type: "webtelephony/number", number: "+11234567890" |
DIAL |
tel:+11234567890 |
||
open |
type: "image/jpeg", uri: "http://mozilla.org/image.jpg" |
VIEW |
image/jpeg |
http://mozilla.org/image.jpg |
|
pick |
type: "image/jpeg" |
GET_CONTENT |
image/jpeg |
||
send |
type: "text/plain", text: "my message" |
SEND |
TEXT: "my message" |
text/plain |
|
type: "text/html", html_text: "<strong>my</strong> message" |
SEND |
HTML_TEXT: "<strong>my</strong> message" |
text/html |
||
view |
type: "url", url: "http://mozilla.org/" |
VIEW |
http://mozilla.org/ |
||
type: "url", uri: "mailto:user@mozilla.org" |
VIEW |
mailto:user@mozilla.org |
Note: As of Firefox 41, Firefox for Android also supports loading of Android URI Intents. See bug 851693.
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.