Google One Tap JavaScript API reference

This reference describes the One Tap JavaScript API, which you use to display the One Tap prompt on your web pages.

Method: google.accounts.id.initialize

The google.accounts.id.initialize method initializes the One Tap prompt or the browser native credential manager based on the configuration object. See the following code example of the method:

google.accounts.id.initialize(IdConfiguration)

The following code example implements the google.accounts.id.initialize method with an onload function:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: '<var>YOUR_GOOGLE_CLIENT_ID</var>',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

Data type: IdConfiguration

The following table lists the fields and descriptions of the IdConfiguration data type:

Field
client_id	Your application's client ID
auto_select	Enables automatic selection.
callback	The JavaScript function to handle ID tokens.
native_callback	The JavaScript function to handle password credentials.
cancel_on_tap_outside	Cancels the prompt if the user clicks outside the prompt.
prompt_parent_id	The DOM ID of the One Tap prompt container element.
nonce	A random string for ID tokens
context	The title and words in the One Tap prompt
state_cookie_domain	If you need to call One Tap in the parent domain and its subdomains, pass the parent domain to this field so that a single shared cookie is used.

client_id

This field is your application's client ID, which is found and created in the Google Developers Console. See the following table for further information:

Type	Required	Example
string	Yes	client_id: "CLIENT_ID.apps.googleusercontent.com"

auto_select

This field determines whether an ID token should be automatically returned without any user interaction, if there's only one Google session has approved your app before. The default value is false. See the following table for further information:

Type	Required	Example
boolean	Optional	auto_select: true

callback

This field is the JavaScript function that handles the ID token returned from the One Tap prompt. See the following table for further information:

Type	Required	Example
function	Optional	callback: handleResponse

native_callback

This field is the name of the JavaScript function that handles the password credential returned from the browser's native credential manager. See the following table for further information:

Type	Required	Example
function	Optional	native_callback: handleResponse

cancel_on_tap_outside

This field sets whether or not to cancel the One Tap request if a user clicks outside the prompt. The default value is true. You can disable it by setting the value to false. See the following table for further information:

Type	Required	Example
boolean	Optional	cancel_on_tap_outside: false

prompt_parent_id

This attribute sets the DOM ID of the container element. If not set, the One Tap prompt will be displayed at the top right corner of the window. See the following table for further information:

Type	Required	Example
string	Optional	prompt_parent_id: 'parent_id'

nonce

This field is a random string used by the ID token to prevent replay attacks. See the following table for further information:

Type	Required	Example
string	Optional	nonce: "biaqbm70g23"

context

This field changes the words of the title and messages in the One Tap prompt. See the following table for further information:

Type	Required	Example
string	Optional	context: "use"

The following table lists the available contexts and their descriptions:

Context
signin	"Sign in with Google."
signup	"Sign up with Google."
use	"Use with Google."

state_cookie_domain

If you need to display One Tap in the parent domain and its subdomains, pass the parent domain to this field so that a single shared state cookie is used. See the following table for further information:

Type	Required	Example
string	Optional	state_cookie_domain: "example.com"

Method: google.accounts.id.prompt

The google.accounts.id.prompt method displays the One Tap prompt or the browser native credential manager after the initialize() method has been invoked. See the following code example of the method:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

Normally, the prompt() method is called on page load. Due to the session status and user settings on the Google side, the One Tap prompt UI might not be displayed. To get notified on the UI status on different moments, you can pass a function to receive UI status notifications.

Notifications are fired on the following moments:

• Display moment: This occurs after the prompt() method is called. The notification contains a boolean value to indicate whether the UI is displayed or not.

• Skipped moment: This occurs when the One Tap prompt is closed by an auto cancel, a manual cancel, or when Google fails to issue a credential, such as if the selected session has signed out of Google.

  In these cases, it's recommended that you continue on to the next identity providers, if there are any.

• Dismissed moment: This occurs when a credential is successfully retrieved by Google or a user wants to stop the credential retrieval flow. For example, on your login dialog, when the user begins to input their username and password, you can call the google.accounts.id.cancel() method to close the One Tap prompt and trigger a dismissed moment.

  Warning: When on a dismissed moment, do not try any of the next identity providers.

The following code example implements the skipped moment:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

Note: You won’t get notified for the display, skipped, or dismissed moments of the native credential manager UI since we have no control over it.

Data type: PromptMomentNotification

The following table lists methods and descriptions of the PromptMomentNotification data type:

Method
isDisplayMoment()	Is this notification for a display moment?
isDisplayed()	Is this notification for a display moment, and the UI is displayed?
isNotDisplayed()	Is this notification for a display moment, and the UI isn't displayed?
getNotDisplayedReason()	The detailed reason why the UI is not displayed. Possible values are the following: browser_not_supported invalid_client missing_client_id opt_out_or_no_session secure_http_required suppressed_by_user unregistered_origin unknown_reason
isSkippedMoment()	Is this notification for a skipped moment?
getSkippedReason()	The detailed reason for the skipped moment. Possible values are the following: auto_cancel user_cancel tap_outside issuing_failed
isDismissedMoment()	Is this notification for a dismissed moment?
getDismissedReason()	The detailed reason for the dismissal. Possible values are the following: credential_returned cancel_called flow_restarted
getMomentType()	Return a string for the moment type. Possible values are the following: display skipped dismissed

Data type: CredentialResponse

When your callback function is invoked, a CredentialResponse object is passed as the parameter. The following table lists the fields that are contained in the credential response object:

Field
credential	This field is the returned ID token.
select_by	This field sets how the credential was selected.
client_id	This field sets the OAuth client ID.

credential

This field is the ID token as a base64-encoded JSON Web Token (JWT) string.

When decoded, the JWT looks like the following example:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "[e-mail]", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

The sub field contains a globally unique identifier for the Google account.

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verfied can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

select_by

The following are the possible values for the select_by field. This information can be used for data analysis.

Value
auto	The credential wasn't selected by user interaction.
user	The credential was selected by user action.
user_1tap	The credential was just approved by user action with 1-Tap. This only applies to Chrome v75 and higher.
user_2taps	The credential was just approved by user action after they confirmed their consent in a pop-up window. This is what's known as the 2-tap UX on non-Chromium-based browsers.

client_id

This field is the OAuth client ID.

Data type: Credential

When your native_callback function is invoked, a Credential object is passed as the parameter. The following table lists the fields contained in the object:

Field
id	Identifies the user
password	The password

Method: google.accounts.id.disableAutoSelect

When the user signs out of your website, you need to call the method google.accounts.id.disableAutoSelect to record the status in cookies, so as to prevent a UX dead loop. See the following code snippet of the method:

google.accounts.id.disableAutoSelect()

The following code example implements the google.accounts.id.disableAutoSelect method with an onSignout() function:

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

Method: google.accounts.id.storeCredential

A simple wrapper for the store() method of the browser native credential manager API. Therefore, it can only be used to store a password credential. See the following code example of the method:

google.accounts.id.storeCredential(Credential, callback)

The following code example implements the google.accounts.id.storeCredential method with an onSignIn() function:

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

Method: google.accounts.id.cancel

You can cancel the One Tap flow by removing the prompt from the relying party DOM. The cancel operation is ignored if a credential has already been selected. See the following code example of the method:

google.accounts.id.cancel()

The following code example implements the google.accounts.id.cancel() method with an onNextButtonClicked() function:

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

Library load callback: onGoogleLibraryLoad

You can register an onGoogleLibraryLoad callback, which is notified after the One Tap JavaScript library is loaded:

window.onGoogleLibraryLoad = () => {
    ...
};

This callback is just a shortcut for the window.onload callback. There are no behavior differences.

The following code example implements an onGoogleLibraryLoad callback:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>