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

Sign In With Google HTML API reference

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

Element with ID "g_id_onload"

You can put the One Tap data attributes in any visible or invisible elements, such as <div> and <span>. The only requirement is that the element ID is set to g_id_onload. Do not put this ID on multiple elements.

Data attributes

The following table lists the data attributes with their descriptions:

Attribute
data-client_id Your application's client ID
data-auto_select Enables automatic selection.
data-login_uri The URL of your login endpoint
data-callback The JavaScript ID token handler function name
data-native_login_uri The URL of your password credential handler endpoint
data-native_callback The JavaScript password credential handler function name
data-native_id_param The parameter name for the credential.id value
data-native_password_param The parameter name for the credential.password value
data-cancel_on_tap_outside Controls whether to cancel the prompt if the user clicks outside of the prompt.
data-prompt_parent_id The DOM ID of the One Tap prompt container element.
data-skip_prompt_cookie Skips One Tap if the specified cookie has a non-empty value.
data-nonce A random string for ID tokens
data-context The title and words in the One Tap prompt
data-moment_callback The function name of the prompt UI status notification listener
data-state_cookie_domain If you need to call One Tap in the parent domain and its subdomains, pass the parent domain to this attribute so that a single shared cookie is used.
data-allowed_parent_origin The origins that are allowed to embed the intermediate iframe. One Tap will run in the intermediate iframe mode if this attribute presents.
data-intermediate_iframe_close_callback Overrides the default intermediate iframe behavior when users manually close One Tap.

The following sections provide each attribute's type, whether it's required, and an example.

data-client_id

This attribute is your app'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 data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_select

This attribute 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 data-auto_select="true"

data-login_uri

This attribute is the URL of your login endpoint. You are not allowed to set both the data-login_uri and data-callback attributes. See the following table for further information:

Type Required Example
URL Required if data-callback isn't set. data-login_uri="https://example.com/login"

data-callback

This attribute is the name of the JavaScript function that handles the returned ID token. See the following table for further information:

Type Required Example
string Required if data-login_uri isn't set. data-callback="handleToken"

data-native_login_uri

This attribute is the URL of your password credential handler endpoint. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You are not allowed to set both the data-native_callback and data-native_login_uri attributes. See the following table for further information:

Type Required Example
string Optional data-login_uri="https://example.com/password_login"

data-native_callback

This attribute is the name of the JavaScript function that handles the password credential returned from the browser native credential manager. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You are not allowed to set both data-native_callback and data-native_login_uri. See the following table for further information:

Type Required Example
string Optional data-native_callback="handlePasswordCredential"

data-native_id_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.id field. The default name is email. See the following table for further information:

Type Required Example
URL Optional data-native_id_param="user_id"

data-native_password_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.password value. The default name is password. See the following table for further information:

Type Required Example
URL Optional data-native_password_param="pwd"

data-cancel_on_tap_outside

This attribute sets whether or not to cancel the One Tap request if the user clicks outside of 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 data-cancel_on_tap_outside="false"

data-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 data-prompt_parent_id="parent_id"

This attribute skips One Tap if the specified cookie has a non-empty value. See the following table for further information:

Type Required Example
string Optional data-skip_prompt_cookie="SID"

data-nonce

This attribute 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 data-nonce="biaqbm70g23"

data-context

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

Type Required Example
string Optional data-context="use"

The following table lists the available contexts contexts and their descriptions:

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

data-moment_callback

This attribute is the function name of the prompt UI status notification listener. For more information, refer to the data type PromptMomentNotification. See the following table for further information:

Type Required Example
string Optional data-moment_callback="logMomentNotification"

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

Type Required Example
string Optional data-state_cookie_domain="example.com"

data-allowed_parent_origin

The origins that are allowed to embed the intermediate iframe. One Tap will run in the intermediate iframe mode if this attribute presents. See the following table for further information:

Type Required Example
string or string array Optional data-allowed_parent_origin="https://example.com"

The following table lists the supported value types and their descriptions.

Value Types
string A single domain URI. "https://example.com"
string array A list of comma-separated domain URIs. "https://news.example.com,https://local.example.com"

If the value of data-allowed_parent_origin attribute is invalid, the One Tap initialization of the intermediate iframe mode would fail and stop.

data-intermediate_iframe_close_callback

Overrides the default intermediate iframe behavior when users manually close One Tap by tapping on the 'X' button in the One Tap UI. The default behavior is to remove the intermediate iframe from the DOM immediately.

The data-intermediate_iframe_close_callback field takes effect only in intermediate iframe mode. And it has impact only to the intermediate iframe, instead of the One Tap iframe. The One Tap UI is removed before the callback is invoked.

Type Required Example
function Optional data-intermediate_iframe_close_callback='logBeforeClose'

Server-side integration

Your server-side endpoints need to handle the following HTTP POST requests.

The ID token handler endpoint

The ID token handler endpoint processes the ID token that's retrieved by One Tap. Based on the status of the corresponding account, you can sign the user in and either direct them to a sign-up page or direct them to an account-linking page for additional information.

The HTTP POST request contains the following information:

Format Name Description
Cookie g_csrf_token This is a random string, which is changed on each request to the handler endpoint.
Request parameter g_csrf_token This is a string, which is the same as the previous cookie value.
Request parameter credential This is the ID token that's issued by Google.
Request parameter select_by This is how the credential was selected.

The following table lists the possible values for the select_by field. You can use this information for data analysis and more.

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_2tap The credential was just approved by user action after they confirmed their consent in a pop-up window. This is the 2-tap UX on non-Chromium-based browsers.

Password credential handler endpoint

The password credential handler endpoint processes password credentials that are retrieved by the native credential manager.

The HTTP POST request contains the following information:

Format Name Description
Cookie g_csrf_token This is a random string, which is changed on each request to the handler endpoint.
Request parameter g_csrf_token This is a string, which is the same as the previous cookie value.
Request parameter email This is the ID token that's issued by Google.
Request parameter password This is how the credential was selected.