此参考页面介绍了 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 一键式登录和“使用 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 中找到并创建。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 是 | client_id: "CLIENT_ID.apps.googleusercontent.com" |
自动选择
如果某个 Google 会话之前已批准您的应用,那么此字段用于确定是否无需任何用户互动即可自动返回 ID 令牌。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 选填 | auto_select: true |
callback
此字段是 JavaScript 函数,用于处理一键提示或弹出式窗口返回的 ID 令牌。如果使用 Google 一键快捷功能或“使用 Google 帐号登录”按钮,popup
用户体验模式为必需属性。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
函数 | 对于一键快捷操作和 popup 用户体验模式是必需的 |
callback: handleResponse |
login_uri
此属性是您的登录端点的 URI。
该值必须与您在 API 控制台中配置的 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全匹配,并且必须符合我们的重定向 URI 验证规则。
如果当前页面是您的登录页,则可以省略此属性,在这种情况下,凭据默认会发布到此页面。
当用户点击“使用 Google 帐号登录”按钮并使用重定向用户体验模式时,系统会将 ID 令牌凭据响应发布到登录端点。
如需了解详情,请参阅下表:
类型 | 选填 | 示例 |
---|---|---|
网址 | 默认为当前页面的 URI 或您指定的值。 仅在已设置 ux_mode: "redirect" 时使用。 |
login_uri="https://www.example.com/login" |
您的登录端点必须处理正文中包含 ID 令牌值的 credential
键的 POST 请求。
以下是向登录端点发出的请求示例:
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 |
Cancel_on_tap_outside
此字段旨在设置用户在点击提示后是否取消一键式请求。默认值为 true
。如果将该值设置为 false
,则可以将其停用。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 选填 | cancel_on_tap_outside: false |
提示 ID
此属性用于设置容器元素的 DOM ID。如果未设置,则“一键”提示会显示在窗口右上角。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | prompt_parent_id: 'parent_id' |
nonce
此字段是 ID 令牌用于防范重放攻击的随机字符串。 如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | nonce: "biaqbm70g23" |
Nonce 长度受限于您的环境支持的 JWT 大小上限,以及单独的浏览器和服务器 HTTP 大小限制。
context
此字段用于更改“一键恢复”提示中的标题和消息文本。 如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | context: "use" |
下表列出了可用的上下文及其说明:
背景信息 | |
---|---|
signin |
“使用 Google 帐号登录” |
signup |
“使用 Google 帐号注册” |
use |
“在 Google 产品和服务中使用” |
state_cookie_domain
如果您需要在父网域及其子网域中显示“一键快捷通知”,请将父网域传递给此字段,以便使用单个共享状态 Cookie。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | state_cookie_domain: "example.com" |
用户体验模式
使用此字段可设置“使用 Google 帐号登录”按钮所使用的用户体验流程。默认值为 popup
。此属性对 OneTap 用户体验没有影响。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | 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
及其子网域。您也可以使用数组来表示 2 个不同的网域。例如,["https://example1.com", "https://*.example2.com"]
会匹配网域example1.com
、example2.com
和example2.com
的子网域 - 通配符域名必须以安全的 https:// 架构开头。
"*.example.com"
会被视为无效。
如果 allowed_parent_origin
字段的值无效,则中间 iframe 模式的一键式初始化将失败并停止。
intermediate_iframe_close_callback
当用户点按“点按一次”界面中的“X”按钮手动关闭“一键”时,替换默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。
intermediate_iframe_close_callback
字段仅在中间 iframe 模式下生效。它只会影响中间 iframe,而不是一键式 iframe。在调用回调之前,一键式界面会被移除。
类型 | 必需 | 示例 |
---|---|---|
函数 | 选填 | intermediate_iframe_close_callback: logBeforeClose |
itp_support
此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用
升级的一键式用户体验。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 选填 | 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 |
此字段用于设置凭据的选择方式。 |
凭据
此字段是 ID 令牌,采用 base64 编码的 JSON 网络令牌 (JWT) 字符串。
进行解码时,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
,这是 Google Workspace 帐号。
用户可在不使用 Gmail 或 Google Workspace 的情况下注册 Google 帐号。当 email
不包含 @gmail.com
后缀且 hd
不存在时,Google 不具有权威性,建议使用密码或其他质询方法验证用户。email_verfied
也可能为 true,因为 Google 最初是在创建 Google 帐号时验证用户身份的,但随后,第三方电子邮件帐号的所有权可能发生了变化。
exp
字段会显示有效期,以便您在服务器端验证令牌。
从“使用 Google 帐号登录”功能中获取的 ID 令牌为 1 小时。您需要在到期时间之前验证令牌。您不应使用 exp
进行会话管理,ID 令牌过期并不表示该用户已退出帐号。您的应用负责对用户进行会话管理。
选择依据
下表列出了 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 |
如果设置此标记,系统会呈现按钮语言。 |
click_listener |
如果已设置,则在点击“使用 Google 帐号登录”按钮时,系统会调用此函数。 |
属性类型
以下部分包含有关每个属性类型的详细信息以及示例。
type
按钮类型。默认值为 standard
。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 是 | type: "icon" |
下表列出了可用的按钮类型及其说明:
类型 | |
---|---|
standard |
包含文字或个性化信息的按钮:
![]() ![]() |
icon |
不带文字的图标按钮:
![]() |
主题
按钮主题。默认值为 outline
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | theme: "filled_blue" |
下表列出了可用的主题及其说明:
主题 | |
---|---|
outline |
标准按钮主题:
![]() ![]() ![]() |
filled_blue |
蓝色按钮按钮主题:
![]() ![]() ![]() |
filled_black |
黑色按钮按钮主题:
![]() ![]() ![]() |
大小
按钮大小。默认值为 large
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | size: "small" |
下表列出了可用的按钮尺寸及其说明:
大小 | |
---|---|
large |
一个大按钮:
![]() ![]() ![]() |
medium |
中等尺寸按钮:
![]() ![]() |
small |
小按钮:
![]() ![]() |
text
按钮文字。默认值为 signin_with
。具有不同 text
属性的图标按钮文字没有任何视觉差异。唯一的例外情况是读取文本以访问屏幕。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | text: "signup_with" |
下表列出了可用的按钮文字及其说明:
文字 | |
---|---|
signin_with |
按钮文本为“使用 Google 帐号登录”:
![]() ![]() |
signup_with |
按钮文字为“通过 Google 注册”:
![]() ![]() |
continue_with |
按钮文字为“使用 Google 继续”:
![]() ![]() |
signin |
按钮文字为“登录”:
![]() ![]() |
shape
按钮的形状。默认值为 rectangular
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | shape: "rectangular" |
下表列出了可用的按钮形状及其说明:
形状 | |
---|---|
rectangular |
矩形按钮。如果用于 icon 按钮类型,则等同于 square 。![]() ![]() ![]() |
pill |
药丸形状的按钮。如果用于 icon 按钮类型,则等同于 circle 。![]() ![]() ![]() |
circle |
圆形按钮。如果用于 standard 按钮类型,则等同于 pill 。![]() ![]() ![]() |
square |
方形按钮。如果用于 standard 按钮类型,则等同于 rectangular 。![]() ![]() ![]() |
徽标对齐方式
Google 徽标的对齐方式。默认值为 left
。此属性仅适用于 standard
按钮类型。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | logo_alignment: "center" |
下表列出了可用的对齐方式及其说明:
徽标对齐方式 | |
---|---|
left |
左对齐 Google 徽标。
![]() |
center |
将 Google 徽标居中对齐。
![]() |
width
最小按钮宽度(以像素为单位)。宽度上限为 400 像素。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | width: 400 |
语言区域
可选。使用指定的语言区域显示按钮文本,否则默认设置为用户的 Google 帐号或浏览器设置。在加载库时,向 src 指令添加 hl
参数和语言代码,例如:gsi/client?hl=<iso-639-code>
。
如果未设置,系统会使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此,不同的用户可能会看到不同版本的本地化按钮,而且可能会看到不同的大小。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 选填 | locale: "zh_CN" |
click_listener
您可以使用 click_listener
属性来定义在用户点击“使用 Google 帐号登录”按钮时调用的 JavaScript 函数。
google.accounts.id.renderButton(document.getElementById("signinDiv"), { theme: 'outline', size: 'large', click_listener: onClickHandler }); function onClickHandler(){ console.log("Sign in with Google button clicked...") }
在上面的示例中,用户点击“使用 Google 帐号登录”按钮时,系统会将日志消息“点击登录 Google 按钮...”记录到控制台中。
数据类型:凭据
调用 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 |
string | 用户 Google 帐号的电子邮件地址或唯一 ID。该 ID 是凭据载荷的 sub 属性。 |
callback |
函数 | 可选的 RevocationResponse 处理程序。 |
以下代码示例展示了如何将 revoke
方法和 Id 搭配使用。
google.accounts.id.revoke('1618033988749895', done => { console.log(done.error); });
数据类型:RevocationResponse
调用 callback
函数时,系统会将 RevocationResponse
对象作为参数传递。下表列出了撤消响应对象中包含的字段:
字段 | |
---|---|
successful |
此字段是方法调用的返回值。 |
error |
此字段包含详细的错误响应消息。 |
成功
如果撤消方法调用成功或失败,此字段将设置为 true。
error
此字段是字符串值,如果撤消方法调用失败,则包含详细的错误消息。如果成功,则未定义。