本参考页面介绍了“使用 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 一键式自动选择功能。 |
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 |
如果您需要在父网域及其子网域中调用“一键快捷指令”,请将父级网域传递到此属性,以便使用一个共享 Cookie。 |
data-ux_mode |
“使用 Google 帐号登录”按钮的用户体验流程 |
data-allowed_parent_origin |
允许嵌入中间 iframe 的来源。如果存在此属性,则点按一次将在中间 iframe 模式下运行。 |
data-intermediate_iframe_close_callback |
当用户手动关闭“一键快捷通知”时,替换默认的中间 iframe 行为。 |
data-itp_support |
在 ITP 浏览器中启用升级的一键式用户体验。 |
属性类型
以下部分包含有关每个属性类型的详细信息和示例。
数据客户端 ID
此属性是您的应用的客户端 ID,可在 Google Developers Console 中找到并创建此 ID。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 是 | data-client_id="CLIENT_ID.apps.googleusercontent.com" |
data-auto_prompt
此属性决定是否显示“点按一次”。默认值为 true
。当此值为 false
时,系统不会显示 Google One 的点按操作。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
布尔值 | 选填 | data-auto_prompt="true" |
数据自动选择
如果只有一个 Google 会话批准了您的应用,此属性可决定是否在不进行任何用户交互的情况下自动返回 ID 令牌。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
布尔值 | 选填 | data-auto_select="true" |
data-login_uri
此属性是登录端点的 URI。如果当前页面是您的登录页面,则可以省略,在这种情况下,凭据默认发布到该页面。
如果未定义回调函数,并且用户点击了“使用 Google 帐号登录”或“点按一下”按钮,或者系统进行了自动签名,则 ID 令牌凭据响应会发布到您的登录端点。
如需了解详情,请参阅下表:
类型 | 选填 | 示例 |
---|---|---|
网址 | 默认为当前页面的 URI 或您指定的值。 设置 data-ux_mode="popup" 和 data-callback 后,系统会忽略此参数。 |
data-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
data-callback
此属性是用于处理返回的 ID 令牌的 JavaScript 函数的名称。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 如果未设置 data-login_uri ,则必须提供此值。 |
data-callback="handleToken" |
可以使用 data-login_uri
和 data-callback
属性之一。具体取决于以下组件和用户体验模式配置:
“使用 Google 帐号登录”按钮的
redirect
用户体验模式需要data-login_uri
属性,该模式会忽略data-callback
属性。必须为 Google One Tap 和 Google 登录按钮
popup
用户体验模式设置这两个属性之一。如果二者都设置,data-callback
属性的优先级较高。
HTML API 不支持命名空间中的 JavaScript 函数。请改为使用不含命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
,而不是 mylib.callback
。
data-native_login_uri
该属性是密码凭据处理程序端点的网址。如果您设置了 data-native_login_uri
属性或 data-native_callback
属性,则 JavaScript 库将在没有 Google 会话时回退到原生凭据管理器。您不能同时设置 data-native_callback
和 data-native_login_uri
属性。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | 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
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | 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
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
布尔值 | 选填 | data-cancel_on_tap_outside="false" |
data-prompt_parent_id
该属性用于设置容器元素的 DOM ID。如果未设置,则“一键恢复”提示会显示在窗口的右上角。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-prompt_parent_id="parent_id" |
data-skip_prompt_cookie
如果指定的 Cookie 具有非空值,则此属性会跳过“一键恢复”。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-skip_prompt_cookie="SID" |
数据 Nonce
此属性是 ID 令牌使用的随机字符串,用于防止重放攻击。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-nonce="biaqbm70g23" |
Nonce 长度不超过您的环境支持的 JWT 大小上限,以及各个浏览器和服务器 HTTP 大小限制。
数据上下文
此属性会更改“一键提示”中显示的标题和消息的文本。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-context="use" |
下表列出了可用的上下文及其说明:
背景信息 | |
---|---|
signin |
“使用 Google 帐号登录” |
signup |
“通过 Google 注册” |
use |
“在 Google 产品和服务中使用” |
data-moment 回调
该属性是提示界面状态通知监听器的函数名称。如需了解详情,请参阅数据类型 PromptMomentNotification
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-moment_callback="logMomentNotification" |
HTML API 不支持命名空间中的 JavaScript 函数。请改为使用不含命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
,而不是 mylib.callback
。
data-state_cookie_domain
如果您需要在父网域及其子网域中显示一键快捷指令,请将父级网域传递到此属性,以便使用单个共享状态 Cookie。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-state_cookie_domain="example.com" |
data-ux_mode 模式
此属性可设置“使用 Google 帐号登录”按钮的用户体验流程。默认值为 popup
。此属性对一键式用户体验没有影响。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | 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"
会匹配网域example1.com
、example2.com
和example2.com
的子网域 - 通配符网域必须以安全 https:// 架构开头。
"*.example.com"
将被视为无效。
data-intermediate_iframe_close_callback
在用户点按“一键快捷”界面中的“X”按钮手动关闭“一键快捷通知”时,替换默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。
data-intermediate_iframe_close_callback
字段仅在中间 iframe 模式下生效。它只会影响中间 iframe,而不是“一键式”iframe。一键恢复界面会在调用回调之前移除。
类型 | 必需 | 示例 |
---|---|---|
函数 | 选填 | data-intermediate_iframe_close_callback="logBeforeClose" |
HTML API 不支持命名空间中的 JavaScript 函数。请改为使用不含命名空间的全局 JavaScript 函数。例如,使用 mylibCallback
,而不是 mylib.callback
。
数据-itp_support
此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用升级的一键式用户体验。默认值为 false
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
布尔值 | 选填 | data-itp_support="true" |
类为“g_id_signin”的元素
如果您将 g_id_signin
添加到元素的 class
属性中,该元素会呈现为“使用 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
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 是 | data-type="icon" |
下表列出了可用的按钮类型及其说明:
类型 | |
---|---|
standard |
包含文本或个性化信息的按钮:
![]() ![]() |
icon |
不含文本的图标按钮:
![]() |
data-theme
按钮主题。默认值为 outline
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-theme="filled_blue" |
下表列出了可用的主题及其说明:
主题 | |
---|---|
outline |
标准按钮主题:
![]() ![]() ![]() |
filled_blue |
蓝色按钮按钮主题:
![]() ![]() ![]() |
filled_black |
黑色填充按钮主题:
![]() ![]() ![]() |
data-size
按钮大小。默认值为 large
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-size="small" |
下表列出了可用的按钮大小及其说明。
大小 | |
---|---|
large |
一个大按钮:
![]() ![]() ![]() |
medium |
中型按钮:
![]() ![]() |
small |
一个小按钮:
![]() ![]() |
数据文本
按钮文字。默认值为 signin_with
。具有不同 data-text
属性的图标按钮文本没有视觉差异。唯一的例外是,为获得屏幕无障碍功能而读取文本时。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-text="signup_with" |
下表列出了可用的按钮文字及其说明:
文字 | |
---|---|
signin_with |
按钮文本为“使用 Google 帐号登录”:
![]() ![]() |
signup_with |
按钮文字为“通过 Google 注册”:
![]() ![]() |
continue_with |
按钮文本为“Continue with Google”:
![]() ![]() |
signin |
按钮文本为“登录”:
![]() ![]() |
数据形状
按钮形状。默认值为 rectangular
。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-shape="rectangular" |
下表列出了可用的按钮形状及其说明:
形状 | |
---|---|
rectangular |
矩形按钮。如果用于 icon 按钮类型,则与 square 相同。![]() ![]() ![]() |
pill |
药丸形状按钮。如果用于 icon 按钮类型,则等同于 circle 。
![]() ![]() ![]() |
circle |
圆形按钮。如果用于 standard 按钮类型,则等同于 pill 。
![]() ![]() ![]() |
square |
方形按钮。如果用于 standard 按钮类型,则等同于 rectangular 。
![]() ![]() ![]() |
data-logo_alignment
Google 徽标的对齐方式。默认值为 left
。此属性仅适用于 standard
按钮类型。如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-logo_alignment="center" |
下表列出了可用的对齐方式及其说明:
徽标对齐方式 | |
---|---|
left |
左对齐 Google 徽标:
![]() |
center |
使 Google 徽标居中对齐:
![]() |
数据宽度
最小按钮宽度(以像素为单位)。最大宽度为 400 像素。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-width=400 |
数据语言区域
按钮文本的预设语言区域。如果未设置,则使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此,不同的用户可能会看到不同版本的本地化按钮,而且这些按钮的尺寸可能会有所不同。
如需了解详情,请参阅下表:
类型 | 必需 | 示例 |
---|---|---|
字符串 | 选填 | data-locale="zh_CN" |
点击监听器
您可以使用 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 帐号登录按钮...消息记录到控制台中。
服务器端集成
您的服务器端端点必须处理以下 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" }
下表列出了 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 |
Google 签发的此 ID 令牌。 |
请求参数 | password |
如何选择凭据。 |