What are Web Activities?

Web Activities allow information to be sent between apps.

Practically speaking, Web Activities allow any app or webpage to have the kind of native integration that would typically require privileged API access.

At a high-level, there are 2 sides to Web Activities:

What privileges do I need?

None! Any web app or website can use Web Activities.

This means you can leverage native features, not just in packaged apps, but in web apps, and even websites!

Having secure native feature integration for both packaged and network apps means you can choose the update and delivery model that works best for the content (versioned updates, silent updates or any combination thereof).

What can I do with Web Activities?

Lots of things. Here's an initial list:

How do I call Web Activities from my app?

Let’s say you have an app that needs to get a picture – either from the Gallery, Camera or any other app in Firefox OS that supports that activity. To get one, you can call the pick activity, like this:

var pick = new MozActivity({
   name: "pick",
   data: {
       type: ["image/png", "image/jpg", "image/jpeg"]
   }
});

We specify the name pick and the data to be PNG or JPEG images.

As a user, you choose the app you want to pick an image from. Once you’ve done so, the result will be posted back to the requesting app (Note: the app handling the activity chooses what will be returned).

Like most WebAPIs, a Web Activity has onsuccess and onerror event handlers. In the case of an image/file the onsuccess handler gets a blob. It can then represent the returned image visually in the app:

pick.onsuccess = function () {    
    // Create image and set the returned blob as the src
    var img = document.createElement("img");
    img.src = window.URL.createObjectURL(this.result.blob);

    // Present that image in your app
    var imagePresenter = document.querySelector("#image-presenter");
    imagePresenter.appendChild(img);
};

pick.onerror = function () {
    // If an error occurred or the user canceled the activity
    alert("Can't view the image!");
};

How do I register an app to handle an activity?

There are two ways.

Declaratively, through the manifest file:

{
    "name": "My App",
    "description": "Doing stuff",
    "activities": {
       "view": {
            "filters": {
                "type": "url",
                "url": {
                    "required": true, 
                    "regexp":"/^https?:/"
                }
            }
        }
    }
}

Or via JavaScript (this approach is still in development):

var register = navigator.mozRegisterActivityHandler({
    name: "view", 
    disposition: "inline", 
    filters: {
        type: "image/png"
    }

});


register.onerror = function () {
    console.log("Failed to register activity");
}

...and then handle the activity:

navigator.mozSetMessageHandler("activity", function (a) {
    /*
      Call a.postResult() or a.postError() if
      the activity should return a value    
    */
});

Can I create new web activity types?

Absolutely! An application will be able to create new activities.

For example, an application can register itself as handling the activity foobar. Any other application is able to start the activity foobar.

To prevent naming collision problems, we recommend custom naming to be prefixed with your URL (for example: example.org/foobar).

So, when does an app actually need to be privileged?

Very rarely. For most cases you can use Web Activities and bypass the need for privileged API access.

For example, if your app needs camera access, all you have to do is ask for a photo via an activity. An activity sheet will pop up, and after the user takes the photo, your app will receive it. No privileged access necessary.

What is the difference between Web Activities and Web Intents?

Web Activities is a simplified counter-proposal to Web Intents.

It limits the scope of the API to the following use case: App A wants to delegate an activity to App B.

Web Activities isn't a discovery API or a communication API. Those things happen in the background and are completely transparent to the caller.

Resources