Warning: This data is provided under the Google User Data Policy. Please review and comply with the policy. Failure to do so may result in project suspension or account suspension.

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."

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.

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>

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.

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>