Non-Existent Item Values

In all tested browsers that support localStorage, a call to localStorage.getItem for an item that does not exist returns null. In Firefox (versions <= 13), a call to localStorage.<non_existent_item_name> will return null as well.

// val === null in all tested browsers
var val = localStorage.getItem(“non_existent”);

// val === undefined in most browsers, in Firefox <= v13, val === null
var val = localStorage.non_existent;

Firefox’s discrepency has been fixed in Firefox 14, which is in the Aurora Channel at the time of writing this article.

Using the `in` Operator on Non-Existent Items

Both Firefox (versions <= 13) and Opera fail using the `in` operator. Opera appears to always misreport an item as being `in` localStorage. Firefox will report an item as being `in` localStorage after the item is removed using removeItem. Firefox will correctly update its state when the page is reloaded.

// Opera always returns true.  All other browsers return false.
var hasItem = “non_existent” in localStorage;

localStorage.firstItem = “someValue”;

// hasItem will be false in Firefox <= v13 after delete
delete localStorage.firstItem;
var hasItem = "firstItem" in localStorage;

localStorage.secondItem = "newValue";

// hasItem will be true in Firefox <= v13 after removeItem
localStorage.removeItem("secondItem");
var hasItem = "secondItem" in localStorage;

localStorage.hasOwnProperty

Since `in` appears to be a no-go for a subset of browsers, perhaps localStorage.hasOwnProperty could help out. It turns out that IE8 does not support hasOwnProperty on localStorage. Opera returns true for every property that is queried.

// IE8 excepts with `TypeError: Object doesn't support this property or method`
// Opera returns true
var hasItem = localStorage.hasOwnProperty("undefined_item")

Removing Items – delete vs localStorage.removeItem

The entire impetus for this post started in a code review where I saw an author do a mistake that I have been bitten by in the past – removing items from localStorage using the `delete` operator. Unfortunately, IE8 will throw an exception if the item being deleted is not already in localStorage.

localStorage.item = "value";

// The first delete will work everywhere
delete localStorage.item;

// IE8 will throw `TypeError: Object doesn't support this property or method`
delete localStorage.item;

This is a problem, because it is not possible to reliably query whether an item is in localStorage in all browsers. As noted above, both Firefox and Opera can return true using the `in` operator and IE8 and Opera both fail using localStorage.hasOwnProperty.

What About Mobile?

Mobile Safari on iOS 5.1 and the Default Android browser on Honeycomb have passed all the tests. The current Mobile Firefox (Fennec) reports the same failures as Firefox 12/13.

Where Are The Tests?

The below JSFiddle contains the tests that I used.

One of my pet peeves with working with Javascript objects is that there is no native way to read from or write to an arbitrary location in a Javascript object tree without first checking whether each internal node in the tree exists. It is easy to operate on a single object, but working with a tree necessitates boilerplate work. What do I mean by this?

Say an object “data” exists that represents the root node of a tree of data. Assume this tree is already pre-populated from a web service API call. The current user’s name needs written to a specific location in the tree, then the data is passed on to another function that shows the data on the screen.

This would be easy if the user’s name could be set at “data.username”, but the template is expecting user related data to live under the “data.user” namespace, with the name being at “data.user.name”.

At first thought, this should be easy, write:

data.user = { name: "Billy Jim Bob" };

But what if data.user already existed and contained a field “userid”? The user’s userid is now lost. Uh oh. So we modify this to:

// data initially contains data.user.userid = 1;
// create new user object only if needed (in this case it is not)
data.user = data.user || {};

// do the interesting work.
data.user.name = "Billy Jim Bob";

// data.user now contains two fields, name, userid.

Fair enough, not too much code. But what if this was taken a step further, what if name was further split into first, middle, and last, all under the data.user.name node?

// Boilerplate for each internal node to create the node
// only if needed.
data.user = data.user || {};
data.user.name = data.user.name || {};

// Actual work on the leaf nodes
data.user.name.first = "Billy";
data.user.name.middle = "Jim";
data.user.name.last = "Bob";

That two lines of boilerplate shouldn’t be necessary.

To read from an arbitrary location in a tree requires a different sort of boilerplate – a try/catch to avoid a TypeError when trying to read an item from an undefined object.

// data.user.address may or may not exist at this point.

try {
   var streetAddress = data.user.address.street;
}
catch(e) {
   // try/catch is used to avoid a TypeError if
   // address is not defined.
}

Why can’t this be easy?

The Solution?

I am working on two micro-libraries to simplify this, but I am not sure if I have an optimal interface yet. The first, called easierObject, is to work with normal Javascript objects. The second is for working with localStorage and is called easierStorage.

The APIs are modeled after localStorage, using setItem, getItem and removeItem.

// Rewrite of full name example
data = new easierObject(data);
user.setItem("user", "name", "first", "Billy");
user.setItem("user", "name", "middle", "Jim");
user.setItem("user", "name", "last", "Bob");

Only one line of boilerplate, but at the same time, this seems just as verbose.

Reading an arbitrary location is very similar:

var firstName = data.getItem("user", "name", "first");

A Better API?

Instead of separating the name of each node, another possible approach is to have a single name field with each node name separated by a period – in keeping with normal Javascript notation.

data.setItem("user.name.first", "Billy");
data.setItem("user.name.middle", "Jim");
data.setItem("user.name.last", "Bob");

var firstName = data.getItem("user.name.first");

This seems a far easier to grok, but it prevents users from having node names that contain periods. Is this an acceptable restriction? What if there was a special sequence “\.” that specified “this is not a separator”?

Direction

So obviously it is still a work in progress.

The code lives on GitHub at https://github.com/stomlinson/easierObject.

Any thoughts on a good way to go?

The silly reason I have not been writing is because I added my blog to Planet Mozilla and then became very self-conscious. Planet is a Mozilla hosted feed aggregation service about other Mozillians. While there are no hard rules as to what can be posted to Planet blogs, posts are generally Mozilla project related. When I first submitted my feed URL to Planet, I submitted the URL for my entire site not knowing that WordPress could namespace feeds based on category. Since I did not want my random projects, code snippets or ideas cluttering up everyone’s feed, I self-censored and stopped writing non-Mozilla related posts. This is a failure in more ways than I have fingers.

Enough of that.

I sorted out the feed thing. Now that I know WordPress can namespace feeds, I have updated my Planet feed to only include posts in the Mozilla category. Why didn’t I do this earlier?

Mary user tested our current sign up flow with people who had never used BrowserID. The results were eye opening. Users are doing things we suspected may cause problems, but we did not realize the extent of the confusion we were witnessing.

The core problem is that users get lost once they verify their email with BrowserID. No clear indication is given for how to return to the original site being signing up to. Sometimes users close the original site, sometimes they open the verification page in a new window, sometimes they start on mobile and finish on their desktop, sometimes they do everything we expect but don’t realize the original site is still open in another tab. All users see after completing the new user flow is some text that says (paraphrased) “You have finished signing up to BrowserID…. You may now close this window.”

Clearly, we have to do better.

Lloyd Hilaiel came up with some initial ideas outlined in the GitHub Tracking Issue. Skinny (Crystal) took these ideas and ran. She’s got UX talent. The changes she suggested were so obvious it was like “duh, how did we not think of this before?” But then again, it’s easy to say that in retrospect – the process for coming up with a smooth flow is anything but smooth.

Lloyd and Skinny’s initial suggestion was to use some browser trickery to get the user back to the initial site once they have completed the verification step.

If the original site is still open, we can use a window.alert to return focus to its tab. This works in Firefox, Chrome and Safari – neither Opera nor IE play nicely. Mobile browsers universally show the alert message, but fail to return the user to the correct tab.

If the original site is no longer open, we can redirect the verification tab back to the original site. Overall this offers a much better experience, but still leaves a huge hole – if we have to redirect the current tab to the original site, currently we have no way of indicating to that site that the user is now logged in. We think we have a solution to this using DOM events. I did a quick proof of concept on this last night and will post a video once something more concrete is available.

These simple changes boosted our conversion rates quite a bit. Skinny then took the flow and made it even smoother. She thought “why not enter the password inside the dialog?” Brilliant – when the user opens the verification link from their email, they have no additional work to do – all they have to do is worry about logging in.

BrowserID New User Verification Flow Experiments Screencast from Shane Tomlinson on Vimeo.

Both of these flows can be tried with right now. This is experimental work made for user testing and feedback – these flows should not even be considered alpha quality.

Flow 1 – https://feature385.myfavoritebeer.org/ – window.alert if original site is still open or redirect to original site if closed.

Flow 2 – https://feature1000.myfavoritebeer.org/ – Same as flow 1 with initial password entry inside the dialog.

Note, for these experiments we are using “hacksign.in” as our test version of “browserid.org” – you are not being hacked. Both domains are running in separate environments, so you will have to create an account on each.

I will be continue hacking on these flows over the next couple of weeks. Additional user tests will be done. We are going to keep refining until we get it right. Any and all feedback is welcomed and encouraged.

Check it out, see what you think.

Want to get involved?

• Check out the code on GitHub.
• Message our mailing list at dev-identity@lists.mozilla.org or sign up to receive daily updates.
• Come see what we are up to in the Identity group or visit us on IRC in the #identity channel on irc.mozilla.org.

We’d love to hear from you about how we can make this better!

The goals for providing profile information in BrowserID are:

1. Allow the user to enter their profile information once.
2. Provide profile information to sites through a DOM API that can be implemented by browsers.
3. Keep the user in control over what data is released.

Our approach is to start simple and grow after we gain feedback. The feature as I have implemented it only has two fields, a name and a user’s photo. By starting with only two fields, we can start to get feedback on UX and what user’s perceptions are in relation to this data.

For sites to get the information, they will have to explicitly request which fields they are interested in. The user will then be shown the BrowserID dialog and will have the ability to deselect fields they do not wish to share. This is useful in situations where a site may request a user’s name, email address and photo, but the user is only comfortable supplying their name and email address.

A video on how this early prototype works:

BrowserID Profile Screencast from Shane Tomlinson on Vimeo.

Again, this is early days yet, but please help us make profile information in BrowserID rock! Message our mailing list at dev-identity@lists.mozilla.org or sign up to receive daily updates. Come see what we are up to in the Identity group or visit us on IRC in the #identity channel on irc.mozilla.org.

Hi all,
A quick update to say that I am releasing the WordPress Plugin to support Browser Sign In. The repository for the code can be found on GitHub. The clone link is git://github.com/stomlinson/browser_sign_in_wordpress.git.

As an example of how to implement the Sessions API, I am including the initial version of the code.

<?php
/*Plugin Name: Browser Sign In
Plugin URI: http://www.shanetomlinson.com
Description: Supports the Sessions API produced my Mozilla Labs.
Version: 0.0.1
Author: Shane Tomlinson
Author URI: http://www.shanetomlinson.com
License: MPL 1.1, GPL 2.0, LGPL 2.1
*/

function set_sessions() {
    echo "
        <script type='text/javascript'>
          var doc = window.document;
          // Do not blow up non-supporting browsers.
          if(navigator.id && doc.addEventListener) {\n ";

    if(is_user_logged_in()) {
        global $userdata;
        get_currentuserinfo();
        echo "
            navigator.id.sessions = [ { email: '" . $userdata->user_login . "'} ];

            // The user is logged in, we only really need to listen for the
            // logout event
            doc.addEventListener('logout', function() {
                navigator.id.sessions = undefined;
                doc.location.href = '" . wp_logout_url() . "';
            }, false);\n";
    } else {
        echo "
            // The user is not logged in, we only have to listen for the login
            // event from the browser.
            navigator.id.sessions = [];
            doc.addEventListener('login', function() {
                doc.location.href = '" . wp_login_url() . "';
            }, false);\n";
    }

        echo "
          }
        </script>";
}

add_action('wp_head', 'set_sessions');
add_action('admin_head', 'set_sessions');

?>

The plugin can be found on the WordPress Plugins listing site under Browser Sign In.

With the introduction of BrowserID, Mozilla is beginning a big push towards securing and simplifying the management of the user’s identity.

The Problem

Up to this point, browsers have played a very small role in helping users sign in, sign out, and see their session information for the current site. We think that by providing a single place within the browser to perform these functions, we can offer a streamlined user experience.

To do this, we need a little help from sites themselves.

The Solution – Introducing the Sessions API!

By using the Sessions API, sites indicate their willingness to work with the browser to help manage and display session information.

High Level Flow

We want the user to have a single location with which to do all of their session management. Currently, we are using a small portion of the URL bar next to the favicon as the focal point for this process. Once a site has indicated that it supports the Sessions API, a “Sign In” button will be displayed. If the user clicks on this button, the user will be logged in via the site’s authentication facilities. Once the user is logged in, a button with their current session information will replace the “Sign In” button. The user can click on their username to see more session information as well as to sign out. Pressing the “Sign Out” button will trigger the site’s sign out mechanism. The session information will be reset and display the “Sign In” button again.

The API

Below is a walk through of how the Session API can be used for a static site.

Indicating Support

First off, the site has to indicate that it supports the Session API. Supporting the Session API means that it both sets sessions information and responds to the `login` and `logout` events.

/**
* Indicate support for the Sessions API by setting
* navigator.id.sessions to an empty array.  Browser will
* display a "Sign-In" button in a conspicuous place.
*/
if(navigator.id) {
  navigator.id.sessions = [];
}

Setting navigator.id.sessions to an empty array indicates support. Notice that all code examples are wrapped in the “if(navigator.id) { /* code here */ }” block. This is so that we do not cause errors on browsers that do not yet support the API.

When a site indicates that it supports the Sessions API, a button will be displayed in the URL bar.

Login event

If the user presses the “Sign In” button, a (drum roll) `login` DOM event on the page’s document is triggered. To handle this, a `login` event handler must be registered on the window’s document. When `login` is triggered, the site should take appropriate action such as redirect to a login page or call BrowserID.

if(navigator.id) {
/**
* Listen for the login event.  Take appropriate action to log the
* user in once the event is triggered.
*/
  ...

  // `login` is triggered whenever the user clicks "Sign In"
  // from within their browser.
  document.addEventListener("login", function(event) {
    // Redirect to login page, call BrowserID, etc.
    document.location.href = ...;
  }, false);
}

Setting a Session

Once the user is logged in, the site should set the session information to be displayed in the browser. Session information should be set as soon as possible when the user lands at the page following the login page, preferably before the `load` event is triggered.

If session information is set, the user’s current login name will be displayed in the URL bar providing a visual link between the site and the user’s identity.

/**
* Indicate the user is logged in, not bound to any cookie.
* navigator.id.sessions will have to be updated on every page load.
* Browser will show the user's current login name where the
* "Sign-In" button was.
*/
if(navigator.id) {
  navigator.id.sessions = [{
      email: "stomlinson@mozilla.com"
  }];
}

Using the above method of setting the sessions, the session information MUST be set on every subsequent page load or else the previous page’s session information will be removed on the new page’s `load` event. While session information can be set at any time, it is recommended to set it before the window `load` event to avoid flicker.

Using Sessions with Bindings

To avoid setting session information on every page, all you have to do is bind the session information to a cookie. If a session is bound to a cookie, as long as no new session information is set and the cookie value remains the same, the session will be considered active.

An important caveat to the above is that the cookie information bound to an exact match domain name. This means that if the original session information was set at http://foo.com, but the user is now at http://mail.foo.com, the cookie binding will be ignored and the session information must be set again.

/**
* Indicate the user is logged in, bind session to a cookie.
* Session will remain valid until the value of the cookie
* changes, navigator.id.sessions is updated, or user
* changes domains.
*/
if(navigator.id) {
  navigator.id.sessions = [{
    email: "stomlinson@mozilla.com",
    bound_to: {
      type: "cookie",
      cookie_name: "SID"
    }
  }];
}

Logout event

If there is session information set, the site should then listen for the `logout` event. The `logout` event is triggered on the document whenever the user selects the “Sign Out” button from within the browser.

if(navigator.id) {
...

/**
* `logout` event is triggered whenever the user selects the
* Sign Out button from within their browser.
*/
  document.addEventListener("logout", function(event) {
    // redirect to logout page
    document.location.href = ...;
  }, false);
}

Resetting the Session Information

Once the user has logged out, the sessions information should be reset so that the user’s previous session is no longer displayed in the browser.

/**
* Clear the session information, display "Sign-In" button.
*/
if(navigator.id) {
  navigator.id.sessions = [];
}

/**
* Putting it all together.
*/
if(navigator.id) {
  // indicate support
  navigator.id.sessions = [];

  // user logged in, no cookies
  navigator.id.sessions = [{ email: "stomlinson@mozilla.com" }];

  // user logged in, bound to cookie named SID.
  navigator.id.sessions = [{
    email: "stomlinson@mozilla.com",
    bound_to: {
      type: "cookie",
      cookie_name: "SID"
    }
  }];

  document.addEventListener("login", function(event) {
    // redirect to login page
    document.location.href = ...;

    // ... or ...

    // call BrowserID!
    navigator.id.getVerifiedEmail(function(assertion) {
      // send to server to verify, get email address
    });
  }, false);

  document.addEventListener("logout", function(event) {
    // redirect to logout page
    document.location.href = ...;
  }, false);
}

Plugin

We have a plugin! I have been hard at work getting a Sessions API plugin ready for Firefox and an *experimental* version is ready! The plugin supports Firefox 4+ through to the current Aurora. The screen shots above were all taken with Nightly. A pre-built XPI can be found on GitHub which can be installed directly.

Bugs (Yes, they do exist)

The most important bug right now is when first opening Firefox with multiple instances, only the last instance opened will have Sessions support. This will be addressed very soon.

Secondly, there are some visual inconsistencies with the Windows version. I did not realize until too late that the styling of the favicon button was different in Windows than OSX.

Seeing The API and Addon in Action

You can see this in action either on this site (registration required) or on http://myfavoritebeer.org. myfavoritebeer.org has the added bonus of being integrated with BrowserID!

Future Directions

Shortly in the future we want to support the ability to switch between multiple sessions – ala Google. We are also looking at having the notion of “passive” and “active” sessions, but this has not yet been completely defined. The addon is going to integrate directly with BrowserID providing the user with a seamless login experience. Session and identity management are working their way into the browser more and more, and we think this is a good thing from both ease of use and security perspectives. Soon, instead of logging into individual sites, you are going to be logging into your browser which will then take care of 90% of the rest of the work.

Conclusion

So things are pretty awesome, slowly we are bringing the user’s identity into the browser and providing a single place for the user to go for all of their session management tools. We are providing a mechanism for the user to instantly know who they are currently signed in as. We are working towards providing support for multiple sessions and being able to easily switch between two logins. We integrate well with BrowserID.

Sure there are some rough spots, this is still an experimental product. That is where you come in. We need feedback. We need people to install the addon and tell us what they think. We need sites to implement the API and tell us where their pain points are and what can be changed, improved, added and removed. If you are so inclined, you can even fork the repo and submit pull requests. I have rarely been submitted a pull request that I didn’t like (who is going to turn down free work?). This should be community driven.

Interested?

Get the addon from GitHub or AMO.
Reach me directly at stomlinson@mozilla.com.
Subscribe to the identity mailing list.
Join us on IRC at #identity @irc.mozilla.org.

I am using cURL to do the actual verification, the only thing that baffles me is how the response to the cURL request gets returned as the value of the GET request that calls this code. Any suggestions/reasons would be greatly appreciated!

<?php 

Class BrowserIDVerify {
  public static function login($audience, $assertion) {
    $url = "https://browserid.org/verify";
    $data = array(
      'audience'=>$audience,
      'assertion'=>$assertion
    );
    return BrowserIDVerify::do_post_request($url, $data);
  }

  private static function do_post_request($url, $data) {
    $data_string = http_build_query($data);

    $ch = curl_init();
    curl_setopt($ch,CURLOPT_URL,$url);
    curl_setopt($ch,CURLOPT_POST,count($data));
    curl_setopt($ch,CURLOPT_POSTFIELDS,$data_string);
    $result = curl_exec($ch);
    $info = curl_getinfo($ch);

    curl_close($ch);

    // If anybody could explain to me how/why the result gets returned
    // as the response to the initial GET request that calls this code,
    // I'd be very grateful.
    return '';
  }

}

?>

As Paul points out in the closing line of his article – “This project will fundamentally change and improve the way we build applications on the web today for our users.” His words perfectly describe how we are feeling at Mozilla as well. Change is coming, and the change is going to be nothing short of revolutionary.

If you have not read anything on the purpose of Web Intents/Activities, Mike Hanson from Mozilla has a very thorough article outlining the need for service discovery in web applications. Paul has written an excellent introduction on how intents can solve these issues. Ben from Mozilla shows a demo of what can be done using the New York Times and Flickr as an example.

The Problem – Lack of Flexibility, Cluttered Interfaces

To explain the problem, I’ll continue with the example that Paul mentions.

Imagine that you are a developer writing an image editing web app at “imageeditor.com”. You want to allow the user to select a photo to edit, perform some sort of modification, and then save the image. But, you want the user to be able to select a photo that is stored on either SmugMug, Picassa, Flickr, Instagram, or on their hard drive. Using current technologies a button is presented to import a photo from each of these potential services, whether the user has an account there or not. In this scenario five buttons are displayed, when the user may only be interested in one. The extra buttons clutter up the interface, increase cognitive load on the user, and in the end may not even provide the user actually uses – perhaps all their photos are stored on Facebook. So, as the app developer, you add a new button for Facebook. Now there are 6 buttons displayed. Another user tomorrow requests a button for Google+. This madness is referred to as the NASCAR effect. There has to be a simpler way.

Let’s Simplify

From a user’s perspective, a better way is to present the user with one button – “Get Photo”. Pressing this button then presents the user with a list of services that are actually relevant to them. The user selects the photo from their site of choice and finally the photo data is returned to the image editing application.

From the developer’s perspective, a better way is to write code once and only once. As a developer, I do not want to add a new button every time a new image storage application comes online. As a developer, I do not want to have to write login routines nor store OAuth information for a myriad of services. I want things to be clean, usable, secure, and automatic. As a developer, I want to say “the user needs an image”, and let the rest of the work be taken care of for me.

A pipe dream? Thankfully, no.

The coming model is going to change all of this. Instead of every site having to build out/provide/include every necessary component, a page will be able to request information and functionality that is provided by a third-party app. What does this mean? The concept is simple. Currently, every component that a site needs must be built by the app developer or included from a third party library. Services and Intents aim to change this, instead of having to directly include code to provide a component, the app can ask the browser if any installed third party applications provide the necessary component.

The Coming Reality – Installable Apps and Web Activities/Intents

Both Mozilla and Google are working to make this a reality, and sooner than you think.

The idea that both companies have is that you should be able to “install” a web app into the browser. These apps are nothing more than standard HTML5 pages, pages that use open, standards based HTML5 technologies that you are already using today. The difference is that these pages provide some extra information that allows the browser to handle them as installed applications.

These apps can either provide or consume bits of functionality, for instance maybe an installed Flickr app provides functionality to get an image. When a second app needs to get an image, it can ask the browser to get it an image. The browser, knowing that the Flickr app is both installed and can provide images, uses it to get image data. If multiple apps are installed that provide image data, a dialog showing only the services that the user cares about is presented asking them to select from the list.

Where can this be used? The possibilities are endless, but common scenarios include “Share with”, file retrieval/save, “save to calendar”, contact list management, and profile management. Imagine having one definitive profile that can be used to feed profile information to all other apps requesting this information.

The Mozilla Open Web Apps API

Note, this API *IS* going to change. Both Mozilla and Google are working hard to create a common interface.

So far, Mozilla’s take on using a service is slightly different than Google’s, but both companies are hard at work trying to find a common API that is optimal from both a user and developer perspective.

Mozilla Labs is rapidly piecing together the OpenWebApps plugin for Firefox that provides native browser functionality for their proposed API. Unfortunately for us at Mozilla, not the entire world runs Firefox. For browsers that support a minimum of the HTML5 window.postMessage and localStorage, there is a polyfill that can be used to provide the same functionality. The polyfill can be included directly from https://myapps.mozillalabs.com/jsapi/include.js

The Mozilla API is documented on MDN. Getting Started gives a very good introduction into the goals of the project. The window.navigator object is augmented to provide the app API under:

navigator.apps.*

Application Manifest

The first portion of a web app that a developer will care about is the manifest. The application manifest is a completely separate beast than the W3C offline application manifest, but they can be used together.

The application manifest is a JSON object that provides the information necessary to install and run the app. It includes things like application name, author name, author page, as well as a list of services that the application “provides,” and may include in the coming months a list of services that the application “consumes.” More on what it means to provide or consume services later.

Application Installation

As an app developer, you are going to want users to install your app. To do this, the navigator.apps.install function must be called, generally this is done from a button press. Calling this will cause the browser to ask the user whether they want to install your app. If the user approves, your application’s manifest will be requested and the app will be installed.

This call takes the form of (taken from MDN):

navigator.apps.install({
    url: "http://path.to/my/example.webapp",  /* path to the manifest */
    onsuccess: installCallback,
    onerror: errorCallback
});

So that you don’t annoy users, before presenting them with an install button, you can call navigator.apps.amInstalled to check whether your app is installed or not.

/* Check if the current page is installed as an app */
navigator.apps.amInstalled(callback);

MDN provides information on many other functions, but these are mainly of interest to Dashboards and Stores.

Service Invocation

The most important feature not yet outlined in MDN relates to service invocation. This goes back to a photo editing site requesting a photo.

Earlier, I mentioned the notions of service providers and service consumers. What do these mean? In this scenario, “imageeditor.com” is the consumer of a service, the service of getting a photo. Flickr, Picassa, or SmugMug are providers of a service, the service of giving a photo. There is the notion of a mediator as well, this is normally taken care of by the browser.

Continuing with our example, this is how service invocation works:

1. imageedit.com is the consumer. The site makes a request to invoke a service, we will call the service “image.get.”
2. The mediator (normally the browser) sees that a service invocation request came from imageeditor.com, it looks in its list of installed applications for any that provide “image.get.” It sees that the user has Flickr and Picassa installed. The mediator asks the user to choose one of these, or to cancel the request. Cancelling effectively denies access to imageeditor.com to make use of the service. For this example, assume the user selects Flickr.
3. Flickr is the provider. The Flickr app is informed that a request has been made for “image.get,” without ever knowing which app/site the request came from. The Flickr app then presents the user with an interface where the user can select an image. Once the user selects an image, it then sends the image data back to the mediator who proxies the data back to the originating app.

An important thing to know is that Flickr and imageedit.com know nothing of each other unless they explicitly share this information. imageedit.com knows that it requested and received a photo. Flickr knows that somebody requested a photo so it sent one.

The name of the service, “image.get” must be agreed upon by the two applications for the invocation to happen. At this point there is no standards organization or process to decide on names and it is hoped that these will develop naturally and de facto standards will emerge.

Provider Side – Back to the Manifest

For an app to be discovered by the mediator, it must declare which services that it provides. Mozilla’s proposal is to have this declaration take place in the application manifest. Services are still experimental so their declarations are placed under the “experimental” section. The exact form of this is still under heavy development and will likely change.

"experimental": {
    "services": {
        "service_name": {
            "endpoint": uri
        }
    }
}

An example of this for our Flickr provider could be:

"experimental": {
    "services": {
        "image.get": "/service_imageGet.html"
    }
}

What this means is that with the Flickr app installed, it can provide the service “image.get”. “/service_imageGet.html” on the application’s server will be called to complete the task whenever another app requests “image.get”.

Setting Up Communication

Within “/service_imageGet.html” there has to be logic that says how to handle the service invocation. At the moment, this too is under heavy development and being cleaned up. For a provider to register which function to call within the provider page, it must register a handler for the service. This is done using navigator.apps.services.registerHandler.

The form of the call is:

navigator.apps.services.registerHandler(serviceName, serviceHint, callback);

More concretely:

navigator.apps.services.registerHandler('image.get', 'getImage',
    function(args, callback) {
        // get image, place into imageData;
        var imageData = getImageData();
        callback({image: imageData});
    }
);

Consumer Side – Invoking a Service

For a consumer site or app to request to use a service, it uses navigator.app.invokeService. The form of the call is:

/**
* Request to use a service
* @param {string} serviceName - name of the service to invoke
* @param {object} callData (optional) - optional data to pass to service provider
* @param {function} onSuccess - function to call on success.
* @param {function} onFailure - function to call on failure.
*/
navigator.apps.invokeService({
    serviceName,
    callData,
    onSuccess,
    onFailure
});

In our example, imageeditor.com wants an image that it can edit. It uses navigator.apps.invokeService:

navigator.apps.invokeService({
    "image.get", null,
    function(data) {
        // handle success case.
        // data.image will be the imageData returned from above.
    },
    function(data) {
        // handle failure case
    }
});

Conclusion

So there it is, an overview of what is coming down the line. Unfortunately, at the moment, I don’t have personally written examples of all of this in action. Mozilla Labs has an example application page that shows how app installation and manifests work. The Mozilla account on GitHub has several examples that can be run, most importantly is the site/tests directory in openwebapps and the openwebapps-photosite-connector.

Shorter posts with more detail are planned as these APIs are solidified. These posts will have fuller explanations and examples.

Finally, I agree with Paul, these new technologies are going to fundamentally change the webapps ecosphere as we know it – it is an exciting time to be a developer. See you soon!