IdentityManager.watch()

Summary

This function registers callbacks that respond to a Persona user logging in or out.

Syntax

navigator.id.watch({
  loggedInUser: 'bob@example.org',
  onlogin: function(assertion) {
    // A user has logged in! Here you need to:
    // 1. Send the assertion to your backend for verification and to create a session.
    // 2. Update your UI.
  },
  onlogout: function() {
    // A user has logged out! Here you need to:
    // Tear down the user's session by redirecting the user or making a call to your backend.
  }
});

Parameters

loggedInUser Optional

This parameter tells Persona what you believe about the user's state. It may be a string, null, or undefined.

A string indicates that you believe the user is currently logged in to your site, and the value of the string is that user's case-sensitive email address. A literal null indicates that you do not believe the user is logged in. Omitting the value or setting it to undefined means you do not know if the user is logged in or not.

Persona always believes that a user wants to be logged in or does not want to be logged in to your site. Persona compares the value of loggedInUser to its belief, and invokes the appropriate callback to harmonize the two states:

loggedInUser	Persona's State	Callback
null	"foo@example.com"	onlogin()
undefined	"foo@example.com"	onlogin()
"bar@example.com"	"foo@example.com"	onlogin()
"foo@example.com"	"foo@example.com"	none
null	null	none
"foo@example.com"	null	onlogout()
undefined	null	onlogout()

Note that Persona may automatically call either onlogin or onlogout when your page loads, but not both. If loggedInUser is set to foo@example.com, but Persona believes bar@example.com should be logged in, only onlogin will be called. It will have an assertion for bar@example.com as its first parameter.

onlogin

A function which will be invoked and passed a single argument, an assertion, when the user logs in. This function should send the assertion to the site's backend for verification. If verification succeeds, the backend should establish a session for the user and the function should update the UI as appropriate.

onlogout Optional

A function that will be invoked, without any arguments, when the user logs out. This should tear down the user's session by making a call to the site's backend, or by redirecting the user.

If onlogout is not provided, the session management provided by the Observer API will be disabled. Only onready and onlogin will be invoked, and onlogin will only be invoked in response to a user's attempt to login (it will not be invoked automatically if the user has logged in before).

onready Optional

A function that will be invoked when the user agent is initialized and able to process calls to id.request and id.logout. The onready callback will be invoked immediately after any automatic invocations of onlogin, onlogout, or onmatch. By waiting to display UI until onready is called, relying parties can avoid UI flicker in cases where the user agent's preferred state is out of sync with the site's session.

Note that onready will not be invoked after calls to id.request or id.logout.  It is the punctuation mark that concludes the conversation started by watch.

Example

navigator.id.watch({
  loggedInUser: currentUser, // This is email of current user logged into your site
  onlogin: function(assertion) {
    $.ajax({ // This example uses jQuery, but you can use whatever you'd like
      type: 'POST',
      url: '/auth/login', // This is a URL on your website.
      data: {assertion: assertion}
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(xhr, status, err) {
        navigator.id.logout();
        alert("Login failure: " + err);
      }
    });
  },
  onlogout: function() {
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // This is a URL on your website.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(xhr, status, err) { alert("Logout failure: " + err); }
    });
  }
});

Specification

Not included in any specification.

See also

• BrowserID
• navigator.id
• navigator.id.logout()
• navigator.id.request()