navigator.id.watch

  • Revision slug: DOM/navigator.id.watch
  • Revision title: navigator.id.watch
  • Revision id: 311283
  • Created:
  • Creator: Enaeseth
  • Is current revision? No
  • Comment Update code sample to account for parameter rename

Revision Content

{{ DomRef() }}

{{ non-standard_header() }}

Note: Support for this function is not yet built into any browsers. Websites using Persona must include the polyfill library in their pages.

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_inline() }}
NOTE: This parameter was renamed from loggedInEmail in early September. Both names will continue to work for the time being, but code should be changed to use loggedInUser instead.
The email address of the currently logged in user. This should be a string containing the user's email address if the website believes that a user is currently logged in, or null otherwise. If the website is unsure, this should be set to undefined or omitted.
Persona compares its knowledge of the local user to the value of loggedInEmail to determine which callback—onlogin, onlogout, or none at all—to automatically invoke when your page loads. If loggedInEmail is undefined or omitted, Persona will invoke either onlogin or onlogout, depending on whether or not a local user should be logged in to your site. These callbacks are not invoked automatically if both BrowserID and loggedInEmail agree on the local user's state.
Note that Persona may automatically call either onlogin or onlogout when your page loads, but not both. If loggedInEmail 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
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.

Example

Example needed.

Specification

Not included in any specification.

See also

  • BrowserID
  • {{domxref("navigator.id")}}
  • {{domxref("navigator.id.logout()")}}
  • {{domxref("navigator.id.request()")}}

Revision Source

<p>{{ DomRef() }}</p>
<p>{{ non-standard_header() }}</p>
<div class="note">
  <strong>Note:</strong> Support for this function is not yet built into any browsers. Websites using Persona must include the <a href="https://login.persona.org/include.js" title="https://login.persona.org/include.js">polyfill library</a> in their pages.</div>
<h3 id="Summary" name="Summary">Summary</h3>
<p>This function registers callbacks that respond to a <a href="/en-US/docs/BrowserID" title="BrowserID">Persona</a> user logging in or out.</p>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre class="brush:js;">
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.
  }
});
</pre>
<h4 id="Parameters">Parameters</h4>
<dl>
  <dt>
    <code>loggedInUser </code>{{ optional_inline() }}</dt>
  <dd>
    <strong>NOTE: </strong>This parameter was renamed from <code>loggedInEmail</code> in early September. Both names will continue to work for the time being, but code <strong>should</strong> be changed to use <code>loggedInUser</code> instead.</dd>
  <dd>
    The email address of the currently logged in user. This should be a string containing the user's email address if the website believes that a user is currently logged in, or <code>null</code> otherwise. If the website is unsure, this should be set to <code>undefined</code> or omitted.</dd>
  <dd>
    Persona compares its knowledge of the local user to the value of <code>loggedInEmail</code> to determine which callback—<code>onlogin</code>, <code>onlogout</code>, or none at all—to automatically invoke when your page loads. If <code>loggedInEmail</code> is <code>undefined</code> or omitted, Persona <em>will</em> invoke either <code>onlogin</code> or <code>onlogout</code>, depending on whether or not a local user should be logged in to your site. These callbacks are not invoked automatically if both BrowserID and <code>loggedInEmail</code> agree on the local user's state.</dd>
  <dd>
    Note that Persona may automatically call <em>either</em> <code>onlogin</code> or <code>onlogout</code> when your page loads, but not <em>both</em>. If <code>loggedInEmail</code> is set to <code><span class="link-mailto">foo@example.com</span></code>, but Persona believes <code><span class="link-mailto">bar@example.com</span></code> should be logged in, only <code>onlogin</code> will be called. It will have an assertion for <code><span class="link-mailto">bar@example.com</span></code> as its first parameter.</dd>
  <dt>
    <code>onlogin</code></dt>
  <dd>
    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.</dd>
  <dt>
    <code>onlogout</code></dt>
  <dd>
    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.</dd>
</dl>
<h3 id="Example" name="Example">Example</h3>
<p>Example needed.</p>
<h3 id="Specification" name="Specification">Specification</h3>
<p>Not included in any specification.</p>
<h3 id="See_also">See also</h3>
<ul>
  <li><a href="/en/BrowserID" title="BrowserID">BrowserID</a></li>
  <li>{{domxref("navigator.id")}}</li>
  <li>{{domxref("navigator.id.logout()")}}</li>
  <li>{{domxref("navigator.id.request()")}}</li>
</ul>
Revert to this revision