“使用 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 一键启用自动选择功能。
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 浏览器上启用升级后的一键式用户体验。
data-login_hint	通过提供用户提示跳过账号选择。
data-hd	按网域限制帐号选择。
data-use_fedcm_for_prompt	允许浏览器控制用户登录提示并在您的网站和 Google 之间协调登录流程。

属性类型

以下部分包含有关每个属性类型的详细信息和一个示例。

数据客户端 ID

此属性是应用的客户端 ID，可以在 Google Cloud 控制台中找到并创建。如需了解详情，请参阅下表：

类型	必需	示例
string	是	data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

此属性决定着是否显示“点按一次”功能。默认值为 true。当此值为 false 时，系统不会显示 Google One 触碰消息。如需了解详情，请参阅下表：

类型	必需	示例
boolean	选填	data-auto_prompt="true"

数据自动选择

此属性用于确定在只有一个 Google 会话批准您的应用的情况下，是否自动返回 ID 令牌（无需任何用户互动）。默认值为 false。如需了解详情，请参阅下表：

类型	必需	示例
boolean	选填	data-auto_select="true"

data-login_uri

此属性是您的登录端点的 URI。

该值必须与 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配；该 URI 已在 API 控制台中配置，且必须符合我们的重定向 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 属性，那么不存在 Google 会话时，JavaScript 库将回退到原生凭据管理器。您不能同时设置 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" 与网域 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。

data-itp_support

此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用 升级后的一键式用户体验。默认值为 false。如需了解详情，请参阅下表：

类型	必需	示例
boolean	选填	data-itp_support="true"

data-login_hint

如果您的应用事先知道应该让哪个用户登录，则可以向 Google 提供登录提示。验证成功后，将跳过账号选择。 接受的值包括：电子邮件地址或 ID 令牌 sub 字段。

如需了解详情，请参阅有关 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 账号登录”按钮时，系统会调用此函数。
data-state	如果设置，该字符串会返回 ID 令牌。

属性类型

以下部分包含有关每个属性类型的详细信息和一个示例。

数据类型

按钮类型。默认值为 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"

data-click_listener

您可以使用 data-click_listener 属性定义点击“使用 Google 帐号登录”按钮时调用的 JavaScript 函数。

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

在此示例中，点击“使用 Google 账号登录”按钮后，控制台会记录以下消息：Sign in with Google button supported...。

data-state

（可选）由于可以在同一个页面上呈现多个“使用 Google 帐号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。该字符串将与 ID 令牌一起返回，以便您识别用户点击哪个按钮进行了登录。

如需了解详情，请参阅下表：

类型	必需	示例
string	选填	data-state="button 1"

服务器端集成

您的服务器端端点必须处理以下 HTTP POST 请求。

ID 令牌处理程序端点

ID 令牌处理程序端点处理 ID 令牌。根据相应帐号的状态，您可以让用户登录，并将用户引导至注册页面或帐号关联页面，以便了解更多信息。

HTTP POST 请求包含以下信息：

形式	名称	说明
Cookie	g_csrf_token	一个随机字符串，随对处理程序端点的每个请求而变化。
请求参数	g_csrf_token	与之前的 Cookie 值 g_csrf_token 相同的字符串。
请求参数	credential	Google 发放的 ID 令牌。
请求参数	select_by	如何选择凭据。
请求参数	state	仅当用户点击“使用 Google 账号登录”按钮进行登录，且已指定该按钮的 state 属性时，系统才会定义此参数。

凭据

解码后，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 具有权威性的情况下，用户被确认是合法的帐号所有者。

Google 具有权威性的情形：

• email 具有 @gmail.com 后缀，这是一个 Gmail 账号。
• email_verified 为 true 且 hd 已设置，则表示这是一个 Google Workspace 帐号。

用户可以在不使用 Gmail 或 Google Workspace 的情况下注册 Google 帐号。 当 email 不包含 @gmail.com 后缀且 hd 不存在时，Google 不具备权威性，建议使用密码或其他质询方法来验证用户。email_verified 也可以是 true，因为 Google 在创建 Google 账号时最初验证了用户，但第三方电子邮件账号的所有权可能已发生变化。

exp 字段显示用于在服务器端验证令牌的到期时间。对于从“使用 Google 帐号登录”功能获取的 ID 令牌，该 1 小时是 1 小时。您需要在到期时间之前验证令牌。请勿使用 exp 管理会话。ID 令牌过期并不意味着用户已退出帐号。您的应用负责用户的会话管理。

select_by

下表列出了 select_by 字段的可能值。与会话和同意情况一起使用的按钮类型用于设置值，

• 用户按下了“一键式”按钮或“使用 Google 账号登录”按钮，或者使用了非接触式自动登录流程。

• 找到了现有会话，或用户选择并登录了 Google 账号以建立新会话。

• 在与您的应用共享 ID 令牌凭据之前，用户需要执行以下任一操作：

  • 按下“确认”按钮以同意共享凭据，或者
  • 并使用“选择账号”来选择 Google 账号。

此字段的值已设为以下类型之一：

值	说明
auto	让用户自动登录已有会话且之前已同意共享凭据的用户。仅适用于不支持 FedCM 的浏览器。
user	一位之前已进行同意参与的现有会话的用户按下了一键式“继续为”按钮以分享凭据。仅适用于不支持 FedCM 的浏览器。
fedcm	用户按下了一键式“继续为”按钮，以使用 FedCM 共享凭据。仅适用于 FedCM 支持的浏览器。
fedcm_auto	让用户自动登录参与了现有会话且之前已同意使用 FedCM 一键共享凭据的用户。仅适用于 FedCM 支持的浏览器。
user_1tap	已有会话的用户按下了一键式“继续为”按钮，以表示同意并共享凭据。仅适用于 Chrome v75 及更高版本。
user_2tap	没有现有会话的用户按一键“继续为”按钮来选择账号，然后按弹出式窗口中的“确认”按钮，以表示同意并共享凭据。适用于非基于 Chromium 的浏览器。
btn	之前参与过现有会话的用户按下了“使用 Google 账号登录”按钮，并从“选择账号”中选择一个 Google 账号来共享凭据。
btn_confirm	已有会话的用户按下了“使用 Google 账号登录”按钮，然后按下“确认”按钮，以表示同意并共享凭据。
btn_add_session	之前未同意参与的现有会话的用户按下了“使用 Google 账号登录”按钮，以选择 Google 账号并共享凭据。
btn_confirm_add_session	没有进行过现有会话的用户首先按下“使用 Google 账号登录”按钮来选择 Google 账号，然后按“确认”按钮来同意并共享凭据。

state

仅当用户点击“使用 Google 账号登录”按钮进行登录，并且指定了被点击的按钮的 data-state 属性时，系统才会定义此参数。此字段的值与您在按钮的 data-state 属性中指定的值相同。

由于同一页面上可以呈现多个“使用 Google 帐号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。因此，您可以使用此 state 参数来识别用户点击了哪个按钮进行登录。

密码凭据处理程序端点

密码凭据处理程序端点会处理原生凭据管理器检索到的密码凭据。

HTTP POST 请求包含以下信息：

形式	名称	说明
Cookie	g_csrf_token	一个随机字符串，随对处理程序端点的每个请求而变化。
请求参数	g_csrf_token	与之前的 Cookie 值 g_csrf_token 相同的字符串。
请求参数	email	Google 发放的 ID 令牌。
请求参数	password	如何选择凭据。

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