此参考页面介绍了 Sign-In JavaScript API。您可以使用此 API 在网页上显示“一键恢复”提示或“使用 Google 帐号登录”按钮。
方法：google.accounts.id.initialize
google.accounts.id.initialize 方法会根据配置对象初始化“使用 Google 帐号登录”客户端。请参阅该方法的代码示例：
google.accounts.id.initialize(IdConfiguration)
以下代码示例使用 onload 函数实现 google.accounts.id.initialize 方法：
<script>
window.onload = function () {
google.accounts.id.initialize({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: handleCredentialResponse
});
google.accounts.id.prompt();
};
</script>
google.accounts.id.initialize 方法会创建一个“使用 Google 帐号登录”客户端实例，同一网页中的所有模块都可以隐式使用该实例。
- 即使您在同一网页中使用多个模块（例如一键式、个性化按钮、撤消等），也只需调用
google.accounts.id.initialize方法一次。 - 如果您多次调用
google.accounts.id.initialize方法，系统仅会记住并使用上一次调用的配置。
实际上，每次调用 google.accounts.id.initialize 方法时都会重置配置，并且同一网页中的所有后续方法都会立即使用新配置。
数据类型：IdConfiguration
下表列出了 IdConfiguration 数据类型的字段和说明：
| 字段 | |
|---|---|
client_id |
您的应用的客户端 ID |
auto_select |
启用自动选择功能。 |
callback |
用于处理 ID 令牌的 JavaScript 函数。Google One 点按“使用 Google 帐号登录”按钮 popup 用户体验模式会使用此属性。 |
login_uri |
登录端点的网址。“使用 Google 帐号登录”按钮 redirect 用户体验模式会使用此属性。 |
native_callback |
用于处理密码凭据的 JavaScript 函数。 |
cancel_on_tap_outside |
当用户在提示外点击时取消提示。 |
prompt_parent_id |
一键提示容器元素的 DOM ID |
nonce |
ID 令牌的随机字符串 |
context |
点按一下提示中的标题和字词 |
state_cookie_domain |
如果您需要在父网域及其子网域中调用一键快捷功能，请将父级网域传递到此字段，以便使用单个共享 Cookie。 |
ux_mode |
“使用 Google 帐号登录”按钮用户体验流程 |
allowed_parent_origin |
允许嵌入中间 iframe 的来源。如果存在此字段，则点按一次将在中间 iframe 模式下运行。 |
intermediate_iframe_close_callback |
在用户手动关闭一键关闭时，替换默认的中间 iframe 行为。 |
itp_support |
在 ITP 浏览器中启用升级的一键式用户体验。 |
client_id
此字段是您的应用的客户端 ID，可在 Google Developers Console 中找到并创建。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 是 | client_id: "CLIENT_ID.apps.googleusercontent.com" |
自动选择
当只有一个 Google 会话批准过您的应用时，此字段可确定是否自动返回 ID 令牌，而无需任何用户互动。默认值为 false。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 布尔值 | 选填 | auto_select: true |
callback
此字段是 JavaScript 函数，用于处理从一键提示或弹出式窗口返回的 ID 令牌。如果使用 Google 一键式或“使用 Google 帐号登录”按钮 popup 用户体验模式，则此属性是必需的。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 函数 | 对于一键式和 popup 用户体验模式是必需的 |
callback: handleResponse |
login_uri
此属性是您的登录端点的 URI。如果当前页面是登录页面，系统可能会省略凭据；在这种情况下，凭据默认发布到该页面。
当用户点击“使用 Google 帐号登录”按钮并采用重定向用户体验模式时，系统会将 ID 令牌凭据响应发布到您的登录端点。
如需了解详情，请参阅下表：
| 类型 | 选填 | 示例 |
|---|---|---|
| 网址 | 默认为当前网页的 URI 或您指定的值。 仅在设置了 ux_mode: "redirect" 时使用。 |
login_uri="https://www.example.com/login" |
您的登录端点必须处理 POST 请求，且该请求的正文中包含 ID 令牌值。credential
以下是发送到登录端点的请求示例：
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
credential=ID_TOKEN
native_callback
此字段是 JavaScript 函数的名称，该函数用于处理从浏览器的原生凭据管理器返回的密码凭据。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 函数 | 选填 | native_callback: handleResponse |
在点按时取消
此字段用于设置当用户在提示外点击时是否取消一键式请求。默认值为 true。如果将该值设置为 false，则可以将其停用。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 布尔值 | 选填 | cancel_on_tap_outside: false |
提示 ID
此属性用于设置容器元素的 DOM ID。如果未设置，“一键恢复”提示将显示在窗口的右上角。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | prompt_parent_id: 'parent_id' |
Nonce
此字段是 ID 令牌用于防范重放攻击的随机字符串。 如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | nonce: "biaqbm70g23" |
Nonce 长度受限于您的环境支持的 JWT 大小上限，以及各个浏览器和服务器 HTTP 大小限制。
context
此字段用于更改一键提示中的标题和消息文本。 如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | context: "use" |
下表列出了可用的上下文及其说明：
| 背景信息 | |
|---|---|
signin |
“使用 Google 帐号登录” |
signup |
“注册 Google” |
use |
“与 Google 搭配使用” |
state_cookie_domain
如果您需要在父网域及其子网域中显示“一键快捷通知”选项，请将父网域传递到此字段，以便使用单个共享状态 Cookie。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | state_cookie_domain: "example.com" |
UX 模式
使用此字段可设置“使用 Google 帐号登录”按钮的用户体验流程。默认值为 popup。此属性不会影响 OneTap 用户体验。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | ux_mode: "redirect" |
下表列出了可用的用户体验模式及其说明。
| 用户体验模式 | |
|---|---|
popup |
执行弹出式窗口中的登录用户体验流程。 |
redirect |
通过整页重定向执行登录用户体验流程。 |
allow_parent_origin
允许嵌入中间 iframe 的来源。如果此字段存在，一次点击将在中间 iframe 模式下运行。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串或字符串数组 | 选填 | allowed_parent_origin: "https://example.com" |
下表列出了受支持的值类型及其说明。
| 值类型 | ||
|---|---|---|
string |
单个网域 URI。 | &https://example.com |
string array |
网域 URI 数组。 | [“https://news.example.com”、“https://local.example.com”] |
也支持通配符前缀。例如，"https://*.example.com" 会匹配各个级别的 example.com 及其子网域（例如 news.example.com、login.news.example.com）。使用通配符时需要注意的事项：
- 模式字符串不能仅由通配符和顶级域名构成。例如，
https://*.com和https://*.co.uk无效；如上所述，"https://*.example.com"会匹配example.com及其子网域。您也可以使用数组来表示两个不同的网域。例如，["https://example1.com", "https://*.example2.com"]会匹配网域example1.com、example2.com和example2.com的子网域 - 通配符网域必须以安全的 https:// 架构开头。
"*.example.com"将被视为无效。
如果 allowed_parent_origin 字段的值无效，中间 iframe 模式的一键式初始化将失败并停止。
intermediate_iframe_close_callback
当用户点按“一键恢复”界面中的 &X39;X' 按钮以手动关闭“一键”时，覆盖默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。
intermediate_iframe_close_callback 字段仅在中间 iframe 模式下生效。它只会影响中间 iframe，而不是一键式 iframe。在调用回调之前，一键式界面会被移除。
| 类型 | 必需 | 示例 |
|---|---|---|
| 函数 | 选填 | intermediate_iframe_close_callback: logBeforeClose |
itp_support
此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用升级的一键式用户体验。默认值为 false。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 布尔值 | 选填 | itp_support: true |
方法：google.accounts.id.prompt
调用 initialize() 方法后，google.accounts.id.prompt 方法会显示一键式提示或浏览器原生凭据管理器。请参阅该方法的代码示例：
google.accounts.id.prompt(/**
@type{(function(!PromptMomentNotification):void)=} */ momentListener)
通常，prompt() 方法会在网页加载时调用。由于 Google 提供的会话状态和用户设置，因此可能不会显示“一键提示”界面。如需在不同时刻获取有关界面状态的通知，请传递一个函数以接收界面状态通知。
通知会在以下时刻触发：
- 显示时刻：发生在
prompt()方法之后。通知包含布尔值，用于指示是否显示界面。 跳过一刻：当一键提示因自动取消、手动取消或 Google 无法颁发凭据（例如所选会话已退出 Google 帐号）而关闭时，就会发生这种情况。
在这些情况下，我们建议您继续联系下一个身份提供商（如果有）。
忽略时刻：当 Google 成功检索到凭据或用户想要停止凭据检索流程时，就会发生这种情况。例如，当用户开始在您的登录对话框中输入用户名和密码时，您可以调用
google.accounts.id.cancel()方法来关闭“一键恢复”提示并触发关闭时刻。
以下代码示例实现了跳过时刻：
<script>
window.onload = function () {
google.accounts.id.initialize(...);
google.accounts.id.prompt((notification) => {
if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
// continue with another identity provider.
}
});
};
</script>
数据类型：PromptMomentNotification
下表列出了 PromptMomentNotification 数据类型的方法和说明：
| 方法 | |
|---|---|
isDisplayMoment() |
这个通知适用于显示时刻吗？ |
isDisplayed() |
此通知是针对某个显示时刻，还是显示了界面？ |
isNotDisplayed() |
这是针对显示时刻的通知，而界面未显示吗？ |
getNotDisplayedReason() |
界面未显示的详细原因。以下是可能的值：
|
isSkippedMoment() |
此通知是针对跳过的时刻吗？ |
getSkippedReason() |
跳过时刻的详细原因。以下是可能的值：
|
isDismissedMoment() |
这个通知适用于关闭的时刻吗？ |
getDismissedReason() |
电子邮件被拒的详细原因。以下是可能的值：
|
getMomentType() |
返回一个时刻类型。以下是可能的值：
|
数据类型：CredentialResponse
调用 callback 函数时，系统会将 CredentialResponse 对象作为参数传递。下表列出了凭据响应对象中包含的字段：
| 字段 | |
|---|---|
credential |
此字段是返回的 ID 令牌。 |
select_by |
此字段用于设置凭据的选择方式。 |
凭据
此字段是采用 base64 编码的 JSON Web 令牌 (JWT) 字符串的 ID 令牌。
在解码时，JWT 如以下示例所示：
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": "Elisa",
"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"
}
sub 字段包含 Google 帐号的全局唯一标识符。
使用 email、email_verified 和 hd 字段，您可以确定 Google 是否托管电子邮件地址且对电子邮件地址具有权威性。如果 Google 是权威用户，那么目前已知用户是合法的帐号所有者。
Google 具有权威性的情况：
email的后缀为@gmail.com，这是一个 Gmail 帐号。email_verified为 true，且hd已设置，这是一个 G Suite 帐号。
用户无需使用 Gmail 或 G Suite 即可注册 Google 帐号。当 email 不包含 @gmail.com 后缀且不存在 hd 时，Google 不具有权威性，建议使用密码或其他验证方法来验证用户。email_verfied 也可能为 true，因为 Google 最初是在 Google 帐号创建时验证了用户的，但是第三方电子邮件帐号的所有权可能已发生变化。
select_by
下表列出了 select_by 字段的可能值。与会话和用户意见征求状态搭配使用的按钮类型用于设置值，
用户按了“一键登录”或“使用 Google 帐号登录”按钮，或使用了感应式自动登录流程。
找到了现有会话，或者用户选择并登录了 Google 帐号以创建新会话。
在与用户共享应用 ID 令牌凭据之前
- 按确认按钮以同意共享凭据，或
- 之前已表示同意，并使用“选择帐号”来选择 Google 帐号。
此字段的值可设置为以下类型之一：
| 值 | 说明 |
|---|---|
auto |
使用之前已同意共享凭据的现有会话自动登录用户。 |
user |
用户的现有会话之前已经获得用户同意后，按下了“一键恢复”按钮以分享凭据。 |
user_1tap |
已有会话的用户按了“一键恢复”按钮，以表示同意并共享凭据。仅适用于 Chrome v75 及更高版本。 |
user_2tap |
没有现有会话的用户按了“一键恢复”按钮选择帐号，然后按弹出式窗口中的“确认”按钮，以表示同意并共享凭据。适用于非 Chromium 浏览器。 |
btn |
之前已同意的用户通过按“使用 Google 帐号登录”按钮并从“选择帐号”中选择一个 Google 帐号来共享凭据。 |
btn_confirm |
已有会话的用户按了“使用 Google 帐号登录”按钮，然后按了“确认”按钮以表示同意并共享凭据。 |
btn_add_session |
之前未获得同意的用户通过按“使用 Google 帐号登录”按钮来选择 Google 帐号并共享凭据。 |
btn_confirm_add_session |
没有现有会话的用户首先按“使用 Google 帐号登录”按钮来选择 Google 帐号，然后按“确认”按钮以同意和分享凭据。 |
方法：google.accounts.id.renderButton
google.accounts.id.renderButton 方法会在网页上呈现“使用 Google 帐号登录”按钮。
请参阅该方法的代码示例：
google.accounts.id.renderButton(
/** @type{!HTMLElement} */ parent,
/** @type{!GsiButtonConfiguration} */ options
)
数据类型：GsiButtonConfiguration
下表列出了 GsiButtonConfiguration 数据类型的字段和说明：
| 特性 | |
|---|---|
type |
按钮类型：图标或标准按钮。 |
theme |
按钮主题。例如，filled_blue 或 filled_black。 |
size |
按钮大小。例如，小号或大号。 |
text |
按钮文字。例如，“使用 Google 帐号登录”或“使用 Google 注册”。 |
shape |
按钮形状。例如，矩形或圆形。 |
logo_alignment |
Google 徽标对齐方式：左对齐或居中对齐。 |
width |
按钮宽度（以像素为单位）。 |
locale |
如果设置了此属性，则系统会呈现按钮语言。 |
属性类型
以下部分包含有关每个属性类型的详细信息和一个示例。
类型
按钮类型。默认值为 standard。
如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 是 | type: "icon" |
下表列出了可用的按钮类型及其说明：
| 类型 | |
|---|---|
standard |
包含文字或个性化信息的按钮：
|
icon |
不含文字的图标按钮：
|
主题
按钮主题。默认值为 outline。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | theme: "filled_blue" |
下表列出了可用的主题及其说明：
| 主题 | |
|---|---|
outline |
标准按钮主题：
|
filled_blue |
一个蓝色按钮按钮主题：
|
filled_black |
黑色按钮按钮主题：
|
大小
按钮大小。默认值为 large。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | size: "small" |
下表列出了可用的按钮大小及其说明：
| 大小 | |
|---|---|
large |
一个大按钮：
|
medium |
中型按钮：
|
small |
一个小按钮：
|
text
按钮文字。默认值为 signin_with。具有不同 text 属性的图标按钮文字没有视觉差异。唯一的例外是读取文本以实现屏幕可访问性。
如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | text: "signup_with" |
下表列出了可用的按钮文字及其说明：
| 文本 | |
|---|---|
signin_with |
按钮文字为“使用 Google 帐号登录”：
|
signup_with |
按钮文字为“通过 Google 注册”：
|
continue_with |
按钮文字为“Continue with Google”：
|
signin |
按钮文字为“登录”：
|
shape
按钮形状。默认值为 rectangular。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | shape: "rectangular" |
下表列出了可用的按钮形状及其说明：
| 形状 | |
|---|---|
rectangular |
矩形按钮。如果用于 icon 按钮类型，则其与 square 相同。
|
pill |
药丸形状的按钮。如果用于 icon 按钮类型，则它与 circle 相同。
|
circle |
圆形按钮。如果用于 standard 按钮类型，则它与 pill 相同。
|
square |
方形按钮。如果用于 standard 按钮类型，则它与 rectangular 相同。
|
徽标对齐方式
Google 徽标的对齐方式。默认值为 left。此属性仅适用于 standard 按钮类型。如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | logo_alignment: "center" |
下表列出了可用的对齐方式及其说明：
| 徽标对齐方式 | |
|---|---|
left |
左对齐 Google 徽标。
|
center |
将 Google 徽标居中对齐。
|
宽度
最小按钮宽度（以像素为单位）。宽度上限为 400 像素。
如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | width: 400 |
语言区域
按钮文字的预设语言区域。如果此政策未设置，系统会使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此，不同的用户可能会看到不同版本的本地化按钮，而且这些按钮的尺寸可能会有所不同。
如需了解详情，请参阅下表：
| 类型 | 必需 | 示例 |
|---|---|---|
| 字符串 | 选填 | locale: "zh_CN" |
数据类型：凭据
调用 native_callback 函数时，系统会将 Credential 对象作为参数传递。下表列出了对象中包含的字段：
| 字段 | |
|---|---|
id |
识别用户。 |
password |
密码 |
方法：google.accounts.id.disableAutoSelect
当用户退出您的网站时，您需要调用 google.accounts.id.disableAutoSelect 方法，以在 Cookie 中记录状态。这样可以防止出现用户体验死循环。请参阅该方法的以下代码段：
google.accounts.id.disableAutoSelect()
以下代码示例使用 onSignout() 函数实现 google.accounts.id.disableAutoSelect 方法：
<script>
function onSignout() {
google.accounts.id.disableAutoSelect();
}
</script>
方法：google.accounts.id.storeCredential
此方法是浏览器的原生凭据管理器 API 的 store() 方法的简单封装容器。因此，它只能用于存储密码凭据。请参阅该方法的代码示例：
google.accounts.id.storeCredential(Credential, callback)
以下代码示例使用 onSignIn() 函数实现 google.accounts.id.storeCredential 方法：
<script>
function onSignIn() {
let cred = {id: '...', password: '...'};
google.accounts.id.storeCredential(cred);
}
</script>
方法：google.accounts.id.cancel
如果您从依赖方 DOM 中移除提示，则可以取消一键式流程。如果已选择凭据，则取消操作将被忽略。请参阅该方法的代码示例：
google.accounts.id.cancel()
以下代码示例使用 onNextButtonClicked() 函数实现 google.accounts.id.cancel() 方法：
<script>
function onNextButtonClicked() {
google.accounts.id.cancel();
showPasswordPage();
}
</script>
库加载回调：onGoogleLibraryLoad
您可以注册 onGoogleLibraryLoad 回调。加载“使用 Google 帐号登录”JavaScript 库后，系统会通知用户：
window.onGoogleLibraryLoad = () => {
...
};
此回调只是 window.onload 回调的快捷方式。行为没有差异。
以下代码示例实现了 onGoogleLibraryLoad 回调：
<script>
window.onGoogleLibraryLoad = () => {
google.accounts.id.initialize({
...
});
google.accounts.id.prompt();
};
</script>
方法：google.accounts.id.revoke
google.accounts.id.revoke 方法会撤消为指定用户共享 ID 令牌的 OAuth 授权。请参阅该方法的以下代码段：google.accounts.id.revoke(hint, callback)
| 参数 | 类型 | 说明 |
|---|---|---|
hint |
字符串 | 用户的 Google 帐号的电子邮件地址或唯一 ID。该 ID 是凭据载荷的 sub 属性。 |
callback |
函数 | （可选）RevocationResponse 处理程序。 |
以下代码示例展示了如何将 revoke 方法与 ID 配合使用。
google.accounts.id.revoke('1618033988749895', done => {
console.log(done.error);
});
数据类型：RevocationResponse
调用 callback 函数时，系统会将 RevocationResponse 对象作为参数传递。下表列出了撤消响应对象中包含的字段：
| 字段 | |
|---|---|
successful |
此字段是方法调用的返回值。 |
error |
此字段可包含详细的错误响应消息。 |
成功
如果撤消方法调用成功或失败，此字段将设为 true。
错误
此字段是一个字符串值，如果撤消方法调用失败，则其中包含详细的错误消息，如果成功，则未定义未定义。