IdentityManager.watch()

Not native
This feature is not built into all browsers. To use it reliably, you'll need to include a JavaScript library in your page as a polyfill. You can include the library from https://login.persona.org/include.js.

Summary

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

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

onlogoutOptional

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

onreadyOptional

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.