navigator.id.watch

  • Revision slug: Web/API/navigator.id.watch
  • Revision title: navigator.id.watch
  • Revision id: 411171
  • Created:
  • Creator: Callahad
  • Is current revision? No
  • Comment Document onready

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() }}
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 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
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.
onmatch {{ optional_inline() }}
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.

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
  • {{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>
    This parameter tells Persona what you believe about the user's state. It may be a string, <code>null</code>, or <code>undefined</code>.</dd>
  <dd>
    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 email address. A literal <code>null</code> indicates that you do not believe the user is logged in. Omitting the value or setting it to <code>undefined</code> means you do not know if the user is logged in or not.</dd>
  <dd>
    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 <code>loggedInUser</code> to its belief, and invokes the appropriate callback to harmonize the two states:</dd>
  <dd>
    <table align="center">
      <thead>
        <tr>
          <th scope="col">loggedInUser</th>
          <th scope="col">Persona's State</th>
          <th scope="col">Callback</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><code>null</code></td>
          <td>"foo@example.com"</td>
          <td><code>onlogin()</code></td>
        </tr>
        <tr>
          <td><code>undefined</code></td>
          <td>"foo@example.com"</td>
          <td><code>onlogin()</code></td>
        </tr>
        <tr>
          <td>"bar@example.com"</td>
          <td>"foo@example.com"</td>
          <td><code>onlogin()</code></td>
        </tr>
        <tr>
          <td>"foo@example.com"</td>
          <td>"foo@example.com"</td>
          <td style="text-align: center;"><em>none</em></td>
        </tr>
        <tr>
          <td><code>null</code></td>
          <td><code>null</code></td>
          <td style="text-align: center;"><em>none</em></td>
        </tr>
        <tr>
          <td>"foo@example.com"</td>
          <td><code>null</code></td>
          <td><code>onlogout()</code></td>
        </tr>
        <tr>
          <td><code>undefined</code></td>
          <td><code>null</code></td>
          <td><code>onlogout()</code></td>
        </tr>
      </tbody>
    </table>
  </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>loggedInUser</code>&nbsp;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>
  <dt>
    <code>onmatch</code> {{ optional_inline() }}</dt>
  <dd>
    A function that will be invoked when the user agent is initialized and able to process calls to <code>id.request</code> and <code>id.logout</code>. The onready callback will be invoked immediately after any automatic invocations of <code>onlogin</code>, <code>onlogout</code>, or <code>onmatch</code>. By waiting to display UI until <code>onready</code> 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.</dd>
</dl>
<h3 id="Example" name="Example">Example</h3>
<div class="container">
  <pre class="brush: js">
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></pre>
</div>
<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