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.
Syntax
JavaScript
Copy Code
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
, orundefined
. - 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 toundefined
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
oronlogout
when your page loads, but not both. IfloggedInUser
is set tofoo@example.com
, but Persona believesbar@example.com
should be logged in, onlyonlogin
will be called. It will have an assertion forbar@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.
Ifonlogout
is not provided, the session management provided by the Observer API will be disabled. Onlyonready
andonlogin
will be invoked, andonlogin
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
andid.logout
. The onready callback will be invoked immediately after any automatic invocations ofonlogin
,onlogout
, oronmatch
. By waiting to display UI untilonready
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 toid.request
orid.logout
. It is the punctuation mark that concludes the conversation started bywatch
.
Example
JavaScript
Copy Code
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); } }); } })<code class="js plain">;</code>
Specification
Not included in any specification.
See also
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/identitymanager/watch