Beneath are basic questions which will be asked by a developer wanting to use BrowserID. They are arranged in order of importance. For each question there are two answers which represent the two competing API proposals (nicknamed the garfield and odie proposals).

At a high level, how do I implement BrowserID support on my webpage?

BOTH garfield and odie APIs are the same:

You need to add a button to your site that, once clicked, will make a javascript call to prompt the user for and identity. You need to call a function at the time your site loads to check to see if a user is already (persistently logged in). Finally, these client side functions provide you with an assertions that you must implement a little bit of server logic to verify.

What do I do in my handler to invoke BrowserID when the presses sign in?

garfield

navigator.id.getVerifiedEmail({ immediate: false }, function(assertion) {
  // assertion is undefined on failure, else success.
});

odie

navigator.id.promptUser(function(assertion) {
    // assertion is undefined on failure, else success.
});

How do I enable the 'keep me signed in' feature?

common

In both APIs you must opt into the persistent behavior by adding a persistent property to the options on the function above, and you must add a function call to your page at page load time to check if the user is already signed in.

garfield

navigator.id.getVerifiedEmail({ immediate: true }, function(assertion) {
   // assertion is undefined on failure, else success.
});

odie

navigator.id.getCurrent(function(assertion) {
   // assertion is undefined on failure, else success.
});

Do I have to do anything special when the user clicks logout?

common

Yes! You have to tell BrowserID that the user is logging out in order to clear their 'keep me signed in' preference.

garfield

navigator.id.setVerifiedEmailOptions({ persistent: false }, function() {
    // at the time this function is called, the change has been made
});

odie

navigator.id.logout(function() {
    // at the time this function is called, the user has been logged out.
});

If I want to force a user to log in only with a specific email, what do I do?

garfield

When you call getVerifiedEmail (both with the immediate flag true at page load, and with the immediate flag false at sign in click time), you should add a requiredEmail property to the options block.

odie

Two things:

1. When you call promptUser() you should add a requiredEmail property to the options block.
2. When you call getCurrent() you should add a check to see if the assertion available is associated with the email address you require.