BrowserID Observer API

observer.md

BrowserID "Observer" API

The BrowserID JavaScript API can be used by web pages to implement BrowserID authentication. Implementing BrowserID support consists of:

1. registering callback functions that will be invoked when the user logs in or out via navigator.id.watch()
2. invoking navigator.id.request() when the user clicks a login button on your site.
3. invoking navigator.id.logout() when the user clicks a logout button on your site.

Key Ideas

Typically on the web, login sessions are implemented with cookies and are completely managed by a website. With BrowserID you can continue to implement sessions as you do today, but must take a couple extra steps to synchronize your session with BrowserID. Specifically, you should handle the case where the user logs in or out via BrowserID, while your page is not loaded.

Watching Login State: The navigator.id.watch() function allows you to register javascript functions that will be invoked when users log in or out, which may occur while they're visiting your website, or while it's not even loaded. Each page of your site should call navigator.id.watch() and be prepared to handle asynchronous changes to login state.

Telling BrowserID who is logged in: An important parameter to navigator.id.watch() is loggedInEmail. When supplied, this parameter tells BrowserID whether the current page load is associated with a logged in user. By supplying this parameter, you can speed up your page load by suppressing unnecessary callbacks (and using less CPU and network resources):

• If you supply null, and no user is logged in according to BrowserID, your onlogout callback will not be invoked.
• If you supply an email address and that user is still logged in via BrowserID, your onlogin callback will not be invoked.

Example Code

/* get the email address of currently logged in user from your server */
var emailAddressOfCurrentlyLoggedInUser = ...;

navigator.id.watch({
  loggedInEmail: emailAddressOfCurrentlyLoggedInUser,
  onlogin: function(assertion) {
    // a user has logged in!  now verify the assertion on your server, create a session,
    // and update your UI
  },
  onlogout: function() {
    // a user has logged out!  make a call to your server or redirect the user
    // to tear down the session
  },
  onready: function() {
    // this is called *after* onlogin or onlogout, so you can display the login state
    // and user-specific information.
  }
});

// now let's set up code that will run when the user clicks on the login button
var loginButton = document.querySelector("#loginbutton");
loginButton.onclick = function() {
  navigator.id.request()
};

// and set up code that will run when the user clicks on the logout button
var logoutButton = document.querySelector("#logoutbutton");
logoutButton.onclick = function() {
  navigator.id.logout(); // this will cause `onlogout` to be invoked.
};

API

navigator.id.watch(<options>);

Register callbacks to be notified when the user logs in or out. The option block has the following properties:

• loggedInEmail (optional) - The email address of the currently logged in user. May be a string (email address), or null (indicating no user is logged in). If provided, the onlogin or onlogout callbacks will not be invoked if the users' login state is consistent with the value provided. If omitted or undefined, one of the two callbacks will be invoked on every page load.
• onlogin (required) - A callback that will be invoked and passed a single argument, an assertion, when the user logs in.
• onlogout (required) - A callback that will be invoked when the user logs out.
• onready (optional) - A callback that will always be called once the navigator.id service is initialized (after onlogin or onlogout have been called). By waiting to display UI until this point, you can avoid UI flicker in the case where your session is out of sync with BrowserID.

navigator.id.request(<options>);

Request an identity from the user. This will cause a dialog to be opened to prompt the user for an email address to use to log into the site. This function must be invoked from within a click handler. The argument is an options block which may contain the following properties:

• requiredEmail (optional) - An email address that the user must use to log in. When provided, the user may not select a different address, but may cancel the sign-in.
• privacyURL - URL to site's privacy policy. When provided, a link will be displayed in the sign-in dialog.
• tosURL - URL to site's terms of service. When provided, a link will be displayed in the sign-in dialog.
• oncancel - a callback that will be invoked if the user refuses to share an identity with the site.

navigator.id.logout([callback]);

A function that should be invoked when a user wishes to logout of the current site (for instance, when clicking on an in-content logout button). Will cause the onlogout callback passed to navigator.id.watch() to be invoked.

[DEPRECATED] The optional callback argument will be invoked once the browser has successfully completed the logout.