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.
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:
|
isSkippedMoment() |
Is this notification for a skipped moment? |
getSkippedReason() |
The detailed reason for the skipped moment. Possible values are the following:
|
isDismissedMoment() |
Is this notification for a dismissed moment? |
getDismissedReason() |
The detailed reason for the dismissal. Possible values are the following:
|
getMomentType() |
Return a string for the moment type. Possible values are the following:
|
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": "elisa.g.beckett@gmail.com", // 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 andhd
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>