# 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.