Account Chooser API

The AccountChooser software consists of several JavaScript resources compiled together into ac.js and typically retrieved from https://accountchooser.com/ac.js. This document describes how the operations of ac.js may be controlled by a Web developer.

ac.js should be invoked in the head of an HTML document using a <script> element. Do not use self-closing elements; your call to ac.js should be followed by a </script> element, even though there is nothing between the values. The operations of ac.js depend on the URL from which it is served, and JavaScript configuration variables in the accountchooser.CONFIG object.

The following is an example of script elements invoking ac.js and setting configuration variables:

<script type="text/javascript" 
	src="https://www.accountchooser.com/ac.js">
</script>
<script type="text/javascript"> 
	accountchooser.CONFIG = { 
	// Sets the home-page URL to "/top" 
	homeUrl: '/top', 
 
	// Instructs ac.js to offer storage of an account via 
	// accountchooser.com 
	storeAccount: { 
		email: 'santa@example.com', 
		displayName: 'Santa Claus' 
	} 
}; 
</script>

Configuration variables in accountchooser.CONFIG can be used to set values of configuration parameters, and to launch ac.js actions.

1. Configuration Parameters

name type default value description
loginUrl string '/account-login' Login URL.
signupUrl string '/account-create' Signup URL.
userStatusUrl string '/account-status' User status URL.
homeUrl string '/' Home page URL.
siteEmailId string 'email' Email input field ID (HTML “id=” attribute value) in the signup and login forms.
sitePasswordId string 'password' Password input field ID in the signup and login forms
siteDisplayNameId string 'displayName' Display name input field ID in the signup form. Can be set to null or empty if your signup form does not need the user's name.
sitePhotoUrlId string 'photoUrl' Profile photo URL input field ID in the signup form. Can be set to null or empty if your signup form does not need the user's profile picture.
mode string N/A Mode for the current page. The possible values are 'login' and 'signup'. ac.js normally sets the mode by checking the current URL against the loginUrl and signupUrl parameters, but this parameter may be used to override that behavior.
uiConfig object N/A Values to use in customizing the appearance of the AccountChooser page. See details below in Section 3.
language string 'en' The display language of the AccountChooser page. Supported languages are listedhere.
providers list of strings N/A List of supported Identity Providers, usually given by top-level domain name, for example “facebook.com”.

2. Actions

name param type description
storeAccount object The presence of this field causes ac.js to redirect the browser to accountchooser.com and invite the user to store his or her account, with the fields prepopulated using the object fields. At least the "email" field should be provided.

The page in which the script element is embedded will not be displayed. Whatever action the user takes, the browser is redirected back to homeUrl.

An example call:

accountchooser.CONFIG.storeAccount = { 
	email: 'santa@example.com', 
	displayName: 'Santa Claus' 
} 

Other optional fields which may be provided are 'displayName', 'photoUrl' and 'providerId'.

3. User Interface Customization

The value of the uiConfig parameter is an object which may be used to customize the user interface. Here’s an example, which includes all the possible field names:

accountchooser.CONFIG.uiConfig = { 
	title: 'Sign in to Example.com', 
	favicon: 'http://example.com/favicon.ico', 
	branding: 'http://example.com/branding/ac-blurb.html' 
} 

Any subset of these fields may be provided. The following rules apply:

  1. ac.js uses the “title” text in the <title> of the AccountChooser page.
  2. For security reasons, these must be absolute not relative URLs.
  3. The “branding” resource must be served with Content-type text/html
  4. The AccountChooser software will sanitize the “branding” resource using the Caja Compiler, taking obvious precautions such as removing JavaScript-related vulnerabilities; this should be simple, straightforward descriptive text and graphics.
  5. Since these are cross-origin resources, you must arrange for them to be served with the proper Cross-Origin Resource Sharing (CORS) HTTP headers. For example:
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, OPTIONS
    Access-Control-Max-Age: 86400
    And, if the server receives an OPTIONS request:
    Access-Control-Allow-Credentials: true

4. Work flow

The functions ac.js provides are best described in theQuick AccountChooser Integration Guide. When ac.js is loaded, it determines which action to take as follows:

If an the storeAccount action is specified, this takes precedence. Otherwise, if the mode is 'login' (either as explicitly set using the 'mode' parameter, or because the page URL matches the value of the 'loginUrl' parameter), it attempts to use AccountChooser to select an existing account, visit the userStatusUrl page to see if the account is known, and end up assisting either with login or new-account creation.