Google 登录 HTML API 参考文档

此参考页面介绍了“使用 Google 账号登录”HTML 数据属性 API，该 API 用于在网页上显示“使用 Google 账号登录”按钮或一键登录提示。

ID 为“g_id_onload”的元素

您可以将“使用 Google 账号登录”数据属性放在任何可见或不可见的元素中，例如 <div> 和 <span>。唯一的要求是将元素 ID 设置为 g_id_onload。请勿将此 ID 用于多个元素。

数据特性

下表列出了数据属性及其说明：

属性类型

以下各部分详细介绍了每种属性类型，并提供了一个示例。

data-client_id

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

data-color_scheme

此字段是应用于一键登录提示的配色方案。如需了解详情，请参阅下表：

下表列出了可用的配色方案及其说明。

data-auto_prompt

此属性决定是否显示一键快捷功能。默认值为 true。如果此值为 false，则不会显示 Google 一键登录。如需了解详情，请参阅下表：

data-auto_select

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

data-login_uri

此属性是登录端点的 URI。

该值必须与您在 Google Auth Platform 中配置的 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全一致，并且必须符合我们的重定向 URI 验证规则。

如果当前页面是您的登录页面，则可以省略此属性，在这种情况下，凭据默认会发布到此页面。

如果未定义回调函数，并且用户点击了“使用 Google 账号登录”或“一键快捷登录”按钮，或者发生了自动登录，则 ID 令牌凭证响应会发布到您的登录端点。

您的登录端点必须处理 POST 请求，这些请求的正文中包含一个 credential 参数，该参数的值为 ID 令牌。

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

data-callback

此属性是用于处理返回的 ID 令牌的 JavaScript 函数的名称。如需了解详情，请参阅下表：

可能会使用 data-login_uri 和 data-callback 属性之一。它取决于以下组件和用户体验模式配置：

• data-login_uri 属性是“使用 Google 账号登录”按钮 redirect 用户体验模式所必需的，该模式会忽略 data-callback 属性。

• 对于 Google One Tap 和 Google 登录按钮 popup 用户体验模式，必须设置这两个属性中的一个。如果同时设置了这两项，则 data-callback 属性具有更高的优先级。

HTML API 不支持命名空间内的 JavaScript 函数。 请改用不带命名空间的全局 JavaScript 函数。例如，使用 mylibCallback 而不是 mylib.callback。

回调函数会接收一个 CredentialResponse 对象作为参数。如需详细了解可能的响应值，请参阅 CredentialResponse。

data-native_login_uri

此属性是密码凭据处理程序端点的网址。如果您设置了 data-native_login_uri 属性或 data-native_callback 属性，则在没有 Google 会话时，JavaScript 库会回退到内置 Credential Manager。您不能同时设置 data-native_callback 和 data-native_login_uri 属性。如需了解详情，请参阅下表：

data-native_callback

此属性是 JavaScript 函数的名称，该函数用于处理从浏览器内置 Credential Manager 返回的密码凭据。如果您设置了 data-native_login_uri 属性或 data-native_callback 属性，则在没有 Google 会话时，JavaScript 库会回退到内置 Credential Manager。您不能同时设置 data-native_callback 和 data-native_login_uri。如需了解详情，请参阅下表：

HTML API 不支持命名空间内的 JavaScript 函数。 请改用不带命名空间的全局 JavaScript 函数。例如，使用 mylibCallback 而不是 mylib.callback。

data-native_id_param

将密码凭据提交到密码凭据处理程序端点时，您可以为 credential.id 字段指定参数名称。默认名称是 email。如需了解详情，请参阅下表：

data-native_password_param

将密码凭据提交到密码凭据处理程序端点时，您可以为 credential.password 值指定参数名称。默认名称是 password。如需了解详情，请参阅下表：

data-cancel_on_tap_outside

此属性用于设置当用户点击提示以外的位置时，是否取消一键快捷请求。默认值为 true。如需停用此功能，请将该值设置为 false。如需了解详情，请参阅下表：

data-prompt_parent_id

此属性用于设置容器元素的 DOM ID。如果未设置，一键快捷提示会显示在窗口的右上角。如需了解详情，请参阅下表：

data-skip_prompt_cookie

使用 Cookie 控制一键快捷提示的显示。如果此属性指定的 Cookie 具有非空值，则系统不会显示提示。如需了解详情，请参阅下表：

data-nonce

此属性是 ID 令牌用于防止重放攻击的随机字符串。如需了解详情，请参阅下表：

Nonce 长度受限于您的环境支持的 JWT 大小上限，以及各个浏览器和服务器的 HTTP 大小限制。

data-essential_claims

此属性是一个字符串，用于请求在 Google 返回的 ID 令牌中包含其他声明。如需查看 Google 接受的声明的完整列表，请参阅支持的声明。

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

data-context

此字段会更改一键快捷提示中显示的标题和消息的文本，对 ITP 浏览器没有影响。默认为 signin。

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

下表列出了所有可用上下文及其说明：

data-moment_callback

此属性是提示界面状态通知监听器的函数名称。如需了解详情，请参阅数据类型 PromptMomentNotification。

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

HTML API 不支持命名空间内的 JavaScript 函数。 请改用不带命名空间的全局 JavaScript 函数。例如，使用 mylibCallback 而不是 mylib.callback。

data-state_cookie_domain

如果您需要在父网域及其子网域中显示一键快捷功能，请将父网域传递给此属性，以便使用单个共享状态 Cookie。如需了解详情，请参阅下表：

data-ux_mode

此属性用于设置“使用 Google 账号登录”按钮使用的用户体验流程。默认值为 popup。此属性对一键登录用户体验没有影响。如需了解详情，请参阅下表：

下表列出了可用的用户体验模式及其说明。

data-allowed_parent_origin

允许嵌入中间 iframe 的源。如果此属性存在，一键快捷功能会在中间 iframe 模式下运行。如需了解详情，请参阅下表：

下表列出了支持的值类型及其说明。

如果 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 及其所有子网域匹配。使用逗号分隔列表来表示两个不同的网域。例如，"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。一键快捷登录界面会在调用回调之前移除。

HTML API 不支持命名空间内的 JavaScript 函数。 请改用不带命名空间的全局 JavaScript 函数。例如，使用 mylibCallback 而不是 mylib.callback。

data-itp_support

此字段决定了是否应在支持智能跟踪预防 (ITP) 的浏览器上启用升级版一键快捷 UX。默认值为 false。如需了解详情，请参阅下表：

data-login_hint

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

如需了解详情，请参阅 login_hint 的 OpenID Connect 文档。

data-hd

如果用户有多个账号，但应仅使用其 Workspace 账号登录，请使用此选项向 Google 提供域名提示。如果成功，则在账号选择期间显示的用户账号仅限于提供的网域。通配符值：* 仅向用户提供 Workspace 账号，并在账号选择期间排除个人用户账号 (user@gmail.com)。

如需了解详情，请参阅 hd 的 OpenID Connect 文档。

data-use_fedcm_for_prompt

允许浏览器控制用户登录提示，并协调您的网站与 Google 之间的登录流程。默认值为 false。如需了解详情，请参阅迁移到 FedCM 页面。

data-use_fedcm_for_button

此字段决定了是否应在 Chrome（桌面版 M125+ 和 Android 版 M128+）上使用 FedCM 按钮用户体验。默认值为 false。如需了解详情，请参阅下表：

data-button_auto_select

此字段用于确定是否为 FedCM 按钮流程启用自动选择选项。如果启用，系统会自动让具有有效 Google 会话的回访用户登录，而不会显示账号选择器提示。默认为 false。您需要在选择启用发布期间明确启用按钮自动登录。如需了解详情，请参阅下表：

具有“g_id_signin”类的元素

如果您将 g_id_signin 添加到元素的 class 属性中，该元素会呈现为“使用 Google 账号登录”按钮。

您可以在同一页面上呈现多个“使用 Google 账号登录”按钮。每个按钮都可以有自己的视觉设置。这些设置由以下数据属性定义。

视觉数据属性

下表列出了视觉数据属性及其说明：

属性类型

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

data-type

按钮类型。默认值为 standard。如需了解详情，请参阅下表：

下表列出了所有可用的按钮类型及其说明：

类型
standard
icon

data-theme

按钮主题。默认值为 outline。如需了解详情，请参阅下表：

下表列出了可用的主题及其说明：

主题	示例	规格
outline		填充：#FFFFFF 描边：#747775 | 1px | 内部 字体：#1F1F1F | Roboto Medium | 14/20 个性化：#1F1F1F | Roboto | Medium 12/14 | Regular 11/13
filled_blue		填充：#0B57D0 描边：#OB57D0 | 1 像素 | 内部 字体：#FFFFFF | Google Sans Medium | 14/20 个性化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13
filled_black		填充：#202124 描边：#OB57D0 | 1px | 内部 字体：#FFFFFF | Google Sans Medium | 14/20 个性化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13
outline_dark		填充：#131314 描边：#8E918F | 1px | 内部 字体：#FFFFFF | Google Sans Medium | 14/20 个性化：#FFFFFF | Roboto | Medium 12/14 | Regular 11/13

data-size

按钮大小。默认值为 large。如需了解详情，请参阅下表：

下表列出了可用的按钮尺寸及其说明。

大小
large
medium
small

data-text

按钮文字。默认值为 signin_with。具有不同 data-text 属性的图标按钮的文本没有视觉差异。唯一的例外情况是，为了实现屏幕无障碍功能而朗读文本。

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

下表列出了可用的按钮文字及其说明：

文本
signin_with
signup_with
continue_with
signin

data-shape

按钮形状。默认值为 rectangular。如需了解详情，请参阅下表：

下表列出了可用的按钮形状及其说明：

形状
rectangular
pill
circle
square

data-logo_alignment

Google 徽标的对齐方式。默认值为 left。此属性仅适用于 standard 按钮类型。如需了解详情，请参阅下表：

下表列出了可用的对齐方式及其说明：

logo_alignment
left
center

data-width

按钮的最小宽度（以像素为单位）。宽度上限为 400 像素。

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

data-locale

可选。使用指定的语言区域显示按钮文本，否则默认使用用户的 Google 账号或浏览器设置。加载库时，将 hl 参数和语言代码添加到 src 指令中，例如：gsi/client?hl=<iso-639-code>。

如果未设置，则使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此，不同的用户可能会看到不同版本的本地化按钮，并且尺寸可能也不同。

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

data-click_listener

您可以使用 data-click_listener 属性定义一个 JavaScript 函数，以便在用户点击“使用 Google 账号登录”按钮时调用。

  <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 账号登录”按钮时，系统会将消息已点击“使用 Google 账号登录”按钮…记录到控制台。

data-state

可选，因为可以在同一页面上呈现多个“使用 Google 账号登录”按钮，所以您可以为每个按钮分配一个唯一的字符串。系统会返回相同的字符串以及 ID 令牌，以便您识别用户点击了哪个按钮进行登录。

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

服务器端集成

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

ID 令牌处理程序端点

ID 令牌处理程序端点会处理 ID 令牌。根据相应账号的状态，您可以让用户登录，并将其定向到注册页面或账号关联页面，以获取更多信息。客户端必须忽略无法识别的响应参数。

向登录端点发送的请求示例：

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

HTTP POST 请求包含以下信息：

凭据

解码后，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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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 creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

客户端必须忽略无法识别的 JWT 声明。

sub 字段是 Google 账号的全局唯一标识符。仅使用 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_verified也可能为 true，因为 Google 最初在创建 Google 账号时验证了用户，但第三方电子邮件账号的所有权可能自此发生了变化。

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

g_csrf_token

防伪状态令牌。这是由 gsi/client 库创建的跨站请求伪造 (CSRF) 令牌。POST 载荷正文中包含一个随机值，该值既作为 Cookie，也作为请求参数。如果在服务器上处理请求时这两个值不匹配，则应将请求视为无效。

州

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

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

密码凭证处理程序端点

密码凭证处理程序端点会处理内置凭证管理器检索到的密码凭证。

HTTP POST 请求包含以下信息：