本参考页面介绍了“使用 Google 帐号登录”HTML 数据属性 API。您可以使用该 API 在网页上显示“一键快捷”提示或“使用 Google 帐号登录”按钮。
ID 为“g_id_onload”的元素
您可以将“使用 Google 帐号登录”数据属性放在任何可见或不可见的元素中,例如 <div>
和 <span>
。唯一的要求是元素 ID 设置为 g_id_onload
。不要将此 ID 放置在多个元素上。
数据特性
下表列出了数据属性及其说明:
属性 | |
---|---|
data-client_id |
您的应用的客户端 ID |
data-auto_prompt |
显示 Google One 点按屏幕。 |
data-auto_select |
启用 Google One Tap 自动选择功能。 |
data-login_uri |
登录端点的网址 |
data-callback |
JavaScript ID 令牌处理程序函数名称 |
data-native_login_uri |
密码凭据处理程序端点的网址 |
data-native_callback |
JavaScript 密码凭据处理程序函数名称 |
data-native_id_param |
credential.id 值的参数名称 |
data-native_password_param |
credential.password 值的参数名称 |
data-cancel_on_tap_outside |
控制当用户在提示之外点击时是否取消提示。 |
data-prompt_parent_id |
一键式提示容器元素的 DOM ID |
data-skip_prompt_cookie |
如果指定 Cookie 的值非空,则跳过一键式操作。 |
data-nonce |
ID 令牌的随机字符串 |
data-context |
一键式提示中的标题和字词 |
data-moment_callback |
提示界面状态通知监听器的函数名称 |
data-state_cookie_domain |
如果您需要在父网域及其子网域中调用 One Tap,请将父网域传递给此属性,以便使用单个共享 Cookie。 |
data-ux_mode |
“使用 Google 帐号登录”按钮的用户体验流程 |
data-allowed_parent_origin |
可以嵌入中间 iframe 的来源。如果存在此属性,则一键快捷功能会在中间 iframe 模式下运行。 |
data-intermediate_iframe_close_callback |
当用户手动关闭一键快捷功能时,覆盖默认的中间 iframe 行为。 |
data-itp_support |
在 ITP 浏览器上启用升级的一键式用户体验。 |
data-login_hint |
通过提供用户提示跳过帐号选择。 |
data-hd |
按网域限制帐号选择。 |
data-use_fedcm_for_prompt |
允许浏览器控制用户的登录提示,并在您的网站与 Google 之间协调登录流程。 |
属性类型
以下部分包含有关每个属性类型的详细信息和一个示例。
数据客户端 ID
该属性是应用的客户端 ID,您可以在 Google Developers Console 中找到并创建该 ID。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 是 | data-client_id="CLIENT_ID.apps.googleusercontent.com" |
data-auto_prompt(数据自动提示)
此属性决定着是否显示“点按一下”。默认值为 true
。此值为 false
时,不显示 Google One 点按通知。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 可选 | data-auto_prompt="true" |
data-auto_select
此属性用于确定如果只有一个 Google 会话批准了您的应用,是否在无任何用户互动的情况下自动返回 ID 令牌。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 可选 | data-auto_select="true" |
data-login_uri
此属性是您的登录端点的 URI。
该值必须与您在 API 控制台中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配,且必须符合我们的重定向 URI 验证规则。
如果当前页面是您的登录页面,则可以省略此属性,在这种情况下,凭据会默认发布到此页面。
如果没有定义回调函数,并且用户点击了“使用 Google 帐号登录”或“一键登录”按钮,或者系统发生了自动签名,则 ID 令牌凭据响应会发布到您的登录端点。
如需了解详情,请参阅下表:
类型 | 可选 | 示例 |
---|---|---|
网址 | 默认值为当前页面的 URI,或您指定的值。 如果设置了 data-ux_mode="popup" 和 data-callback ,系统会忽略此参数。 |
data-login_uri="https://www.example.com/login" |
登录端点必须处理包含 credential
键且正文中含有 ID 令牌值的 POST 请求。
以下是对登录端点的示例请求:
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
credential=ID_TOKEN
data-callback
此属性是处理返回的 ID 令牌的 JavaScript 函数的名称。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 如果未设置 data-login_uri ,则为必需。 |
data-callback="handleToken" |
可以使用 data-login_uri
和 data-callback
属性中的一个。它依赖于以下组件和用户体验模式配置:
“使用 Google 帐号登录”按钮
redirect
用户体验模式需要使用data-login_uri
属性,该模式会忽略data-callback
属性。必须为 Google 一键和 Google 登录按钮
popup
用户体验模式设置这两个属性中的一个。如果同时设置了两者,则data-callback
属性的优先级更高。
HTML API 不支持命名空间中的 JavaScript 函数。而是应使用不带命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
而非 mylib.callback
。
data-native_login_uri
此属性是密码凭据处理程序端点的网址。如果您设置了 data-native_login_uri
属性或 data-native_callback
属性,那么,在没有 Google 会话的情况下,JavaScript 库将回退到原生凭据管理器。请勿同时设置 data-native_callback
和 data-native_login_uri
属性。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-login_uri="https://www.example.com/password_login" |
data-native_callback
此属性是 JavaScript 函数的名称,用于处理从浏览器的原生凭据管理器返回的密码凭据。如果您设置了 data-native_login_uri
属性或 data-native_callback
属性,则 JavaScript 库会在没有 Google 会话时回退到原生凭据管理器。您不能同时设置 data-native_callback
和 data-native_login_uri
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-native_callback="handlePasswordCredential" |
HTML API 不支持命名空间中的 JavaScript 函数。而是应使用不带命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
而非 mylib.callback
。
data-native_id_param
将密码凭据提交到密码凭据处理程序端点时,您可以为 credential.id
字段指定参数名称。默认名称为 email
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
网址 | 可选 | data-native_id_param="user_id" |
data-native_password_param
将密码凭据提交到密码凭据处理程序端点时,您可以为 credential.password
值指定参数名称。默认名称为 password
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
网址 | 可选 | data-native_password_param="pwd" |
data-cancel_on_tap_outside
此属性用于设置当用户在提示之外点击时,是否取消一键快捷请求。默认值为 true
。如需停用该功能,请将值设置为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 可选 | data-cancel_on_tap_outside="false" |
data-prompt_parent_id
此属性用于设置容器元素的 DOM ID。如果未设置,窗口右上角会显示“一键快捷”提示。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-prompt_parent_id="parent_id" |
data-skip_prompt_cookie
如果指定 Cookie 的值不为空,此属性会跳过一键快捷功能。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-skip_prompt_cookie="SID" |
数据 Nonce
此属性是 ID 令牌用于防范重放攻击的随机字符串。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-nonce="biaqbm70g23" |
Nonce 长度受您的环境支持的 JWT 大小上限以及单个浏览器和服务器 HTTP 大小限制。
数据上下文
此属性会更改一键式提示中显示的标题和消息的文本。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-context="use" |
下表列出了可用的上下文及其说明:
上下文 | |
---|---|
signin |
“使用 Google 帐号登录” |
signup |
“通过 Google 注册” |
use |
“通过 Google 使用” |
数据时刻回调
此属性是提示界面状态通知监听器的函数名称。如需了解详情,请参阅数据类型 PromptMomentNotification
。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-moment_callback="logMomentNotification" |
HTML API 不支持命名空间中的 JavaScript 函数。而是应使用不带命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
而非 mylib.callback
。
data-state_cookie_domain
如果您需要在父网域及其子网域中显示一键快捷功能,请将父网域传递给此属性,以便使用单个共享状态 Cookie。 如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-state_cookie_domain="example.com" |
data-ux_mode
此属性用于设置“使用 Google 帐号登录”按钮使用的用户体验流程。默认值为 popup
。此属性对一键式用户体验没有任何影响。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-ux_mode="redirect" |
下表列出了可用的用户体验模式及其说明。
用户体验模式 | |
---|---|
popup |
在弹出式窗口中执行登录用户体验流程。 |
redirect |
通过完整页面重定向执行登录用户体验流程。 |
data-allowed_parent_origin
可以嵌入中间 iframe 的来源。如果存在此属性,则一键快捷功能会在中间 iframe 模式下运行。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串或字符串数组 | 可选 | data-allowed_parent_origin="https://example.com" |
下表列出了支持的值类型及其说明。
值类型 | ||
---|---|---|
string |
单个网域 URI。 | “https://example.com” |
string array |
以英文逗号分隔的网域 URI 列表。 | "https://news.example.com,https://local.example.com" |
如果 data-allowed_parent_origin
属性的值无效,中间 iframe 模式的一键初始化将会失败并停止。
系统也支持通配符前缀。例如,"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"
与example2.com
的网域example1.com
、example2.com
及子网域匹配 - 通配符域名必须以安全的 https:// 架构开头,因此
"*.example.com"
被视为无效。
data-intermediate_iframe_close_callback
当用户通过点按一键式界面中的“X”按钮手动关闭一键关闭时,覆盖默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。
data-intermediate_iframe_close_callback
字段仅在中间 iframe 模式下有效。它只会影响中间 iframe,而不是一键式 iframe。在调用回调之前,系统会移除一键快捷界面。
类型 | 必需 | 示例 |
---|---|---|
function | 可选 | data-intermediate_iframe_close_callback="logBeforeClose" |
HTML API 不支持命名空间中的 JavaScript 函数。而是应使用不带命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
而非 mylib.callback
。
data-itp_support
此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用
升级后的一键式用户体验。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
boolean | 可选 | data-itp_support="true" |
data-login_hint
如果您的应用事先知道应该登录哪个用户,则可以向 Google 提供登录提示。如果操作成功,系统会跳过帐号选择。 接受的值包括电子邮件地址或 ID 令牌子字段。
如需了解详情,请参阅有关
login_hint
的 OpenID Connect 文档。
类型 | 必需 | 示例 |
---|---|---|
字符串。可以是电子邮件地址或 ID 令牌中的 sub 字段值。 |
可选 | data-login_hint="elisa.beckett@gmail.com" |
数据高清
如果用户有多个帐号,并且只应使用其 Workspace 帐号登录,请使用此 ID 向 Google 提供域名提示。验证成功后,帐号选择期间显示的用户帐号将仅限于提供的网域。通配符值:*
仅向用户提供 Workspace 帐号,在选择帐号时排除消费者帐号 (user@gmail.com)。
如需了解详情,请参阅有关
hd
的 OpenID Connect 文档。
类型 | 必需 | 示例 |
---|---|---|
字符串。完全限定域名或 *。 | 可选 | data-hd="*" |
data-use_fedcm_for_prompt
允许浏览器控制用户的登录提示,并在您的网站与 Google 之间协调登录流程。默认值为 false。如需了解详情,请参阅迁移到 FedCM 页面。
类型 | 必需 | 示例 |
---|---|---|
boolean | 可选 | data-use_fedcm_for_prompt="true" |
包含类“g_id_signin”的元素
如果您向元素的 class
属性添加 g_id_signin
,该元素会呈现为“使用 Google 帐号登录”按钮。
您可以在同一网页上呈现多个“使用 Google 帐号登录”按钮。每个按钮都可以有自己的视觉设置。这些设置由以下数据属性定义。
可视化数据属性
下表列出了可视化数据属性及其说明:
属性 | |
---|---|
data-type |
按钮类型:图标或标准按钮。 |
data-theme |
按钮主题。例如,filled_blue 或 filled_black。 |
data-size |
按钮大小。例如,“小”或“大”。 |
data-text |
按钮文字。例如,“使用 Google 帐号登录”或“使用 Google 注册”。 |
data-shape |
按钮形状。例如,矩形或圆形。 |
data-logo_alignment |
Google 徽标对齐方式:左对齐或居中。 |
data-width |
按钮宽度(以像素为单位)。 |
data-locale |
按钮文本以此属性中设置的语言呈现。 |
data-click_listener |
如果设置了此参数,当用户点击“使用 Google 帐号登录”按钮时,系统会调用此函数。 |
属性类型
以下部分包含有关每个属性类型的详细信息和一个示例。
数据类型
按钮类型。默认值为 standard
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 是 | data-type="icon" |
下表列出了可用的按钮类型及其说明:
类型 | |
---|---|
standard |
![]() ![]() |
icon |
![]() |
data-theme
按钮主题。默认值为 outline
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-theme="filled_blue" |
下表列出了可用的主题及其说明:
主题 | |
---|---|
outline |
![]() ![]() ![]() |
filled_blue |
![]() ![]() ![]() |
filled_black |
![]() ![]() ![]() |
data-size
按钮大小。默认值为 large
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-size="small" |
下表列出了可用的按钮大小及其说明。
大小 | |
---|---|
large |
![]() ![]() ![]() |
medium |
![]() ![]() |
small |
![]() ![]() |
数据-文本
按钮文字。默认值为 signin_with
。对于具有不同 data-text
属性的图标按钮,文本看上去没有区别。唯一的例外情况是读取文本以便提供屏幕无障碍功能。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-text="signup_with" |
下表列出了可用的按钮文本及其说明:
文字 | |
---|---|
signin_with |
![]() ![]() |
signup_with |
![]() ![]() |
continue_with |
![]() ![]() |
signin |
![]() ![]() |
数据形状
按钮形状。默认值为 rectangular
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-shape="rectangular" |
下表列出了可用的按钮形状及其说明:
形状 | |
---|---|
rectangular |
![]() ![]() ![]() icon 按钮类型,则效果与 square 相同。
|
pill |
![]() ![]() ![]() icon 按钮类型,则其作用与 circle 相同。
|
circle |
![]() ![]() ![]() standard 按钮类型,则其作用与 pill 相同。
|
square |
![]() ![]() ![]() standard 按钮类型,则其作用与 rectangular 相同。
|
数据徽标对齐
Google 徽标的对齐方式。默认值为 left
。此属性仅适用于 standard
按钮类型。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-logo_alignment="center" |
下表列出了可用的对齐方式及其说明:
logo_alignment | |
---|---|
left |
![]() |
center |
![]() |
数据宽度
按钮最小宽度(以像素为单位)。可用宽度上限为 400 像素。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-width=400 |
数据语言区域
可选。使用指定的语言区域显示按钮文字,否则默认显示用户的 Google 帐号或浏览器设置。加载库时,将 hl
参数和语言代码添加到 src 指令中,例如:gsi/client?hl=<iso-639-code>
。
如果未设置此政策,系统会使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此,不同的用户可能会看到不同版本的本地化按钮,并且可能会看到不同的大小。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
string | 可选 | data-locale="zh_CN" |
click_listener
您可以使用 click_listener
属性定义一个 JavaScript 函数,使其在用户点击“使用 Google 帐号登录”按钮时调用。
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 帐号登录”按钮... 消息。
服务器端集成
您的服务器端端点必须处理以下 HTTP POST
请求。
ID 令牌处理程序端点
ID 令牌处理程序端点处理 ID 令牌。根据相应帐号的状态,您可以让用户登录,并将用户引导至注册页面或帐号关联页面,以便了解更多信息。
HTTP POST
请求包含以下信息:
形式 | 名称 | 说明 |
---|---|---|
Cookie | g_csrf_token |
一个随机字符串,该字符串会随着对处理程序端点的每个请求而变化。 |
请求参数 | g_csrf_token |
与之前的 Cookie 值 g_csrf_token 相同的字符串 |
请求参数 | credential |
Google 签发的 ID 令牌。 |
请求参数 | select_by |
选择凭据的方式。 |
凭据
解码时,ID 令牌将如下所示:
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" }
sub
字段是 Google 帐号的全局唯一标识符。仅将 sub
字段用作用户的标识符,因为它在所有 Google 帐号中具有唯一性,并且不得重复使用。请勿使用电子邮件地址作为标识符,因为一个 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 令牌,需等待一小时。您需要在到期时间之前验证令牌。请勿使用 exp
进行会话管理。ID 令牌过期并不意味着用户退出登录。您的应用负责用户的会话管理。
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 帐号,然后按“确认”按钮同意并共享凭据。 |
密码凭据处理程序端点
密码凭据处理程序端点会处理原生凭据管理器检索到的密码凭据。
HTTP POST
请求包含以下信息:
形式 | 名称 | 说明 |
---|---|---|
Cookie | g_csrf_token |
一个随机字符串,该字符串会随着对处理程序端点的每个请求而变化。 |
请求参数 | g_csrf_token |
与之前的 Cookie 值 g_csrf_token 相同的字符串。 |
请求参数 | email |
此 ID 令牌,由 Google 签发。 |
请求参数 | password |
选择凭据的方式。 |