“使用 Google 帐号登录”HTML API 参考文档

本参考页面介绍了“使用 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="[e-mail]"

数据高清

如果用户有多个帐号，并且只应使用其 Workspace 帐号登录，请使用此 ID 向 Google 提供域名提示。验证成功后，帐号选择期间显示的用户帐号将仅限于提供的网域。通配符值：* 仅向用户提供 Workspace 帐号，在选择帐号时排除消费者帐号 ([e-mail])。

如需了解详情，请参阅有关 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	按钮文字为“使用 Google 帐号登录”。
signup_with	按钮文字为“通过 Google 注册”。
continue_with	按钮文字为“Continue with Google”。
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	左对齐 Google 徽标。
center	将 Google 徽标居中对齐。

数据宽度

按钮最小宽度（以像素为单位）。可用宽度上限为 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": "[e-mail]", // 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	选择凭据的方式。

注意 ：您可以使用数据属性更改 email 和 password 参数名称。