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 One 点按。如需了解详情，请参阅下表：

data-auto_select

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

data-login_uri

此属性是登录端点的 URI。

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

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

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

您的登录端点必须处理包含 credential 参数（正文中包含 ID 令牌值）的 POST 请求。

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

data-callback

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

可以使用 data-login_uri 和 data-callback 属性中的一个。它依赖于以下组件和用户体验模式配置：

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

• 对于 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 属性。如需了解详情，请参阅下表：

data-native_callback

此属性是 JavaScript 函数的名称，该函数用于处理从浏览器的内置凭据管理器返回的密码凭据。如果您设置了 data-native_login_uri 属性或 data-native_callback 属性，当没有 Google 会话时，JavaScript 库会回退到内置的凭据管理器。您不能同时设置 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 令牌使用的一个随机字符串，用于防止重放攻击。如需了解详情，请参阅下表：

随机数的长度受环境支持的最大 JWT 大小以及各个浏览器和服务器 HTTP 大小限制的约束。

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 的来源。如果存在此属性，One Tap 将以中间 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 有影响。在调用回调之前，系统会移除 One Tap 界面。

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

data-itp_support

此字段用于确定是否应在支持智能跟踪防范 (ITP) 的浏览器上启用 升级版一键式用户体验。默认值为 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”的元素

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

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

视觉数据属性

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

属性类型

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

data-type

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

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

类型
standard
icon

data-theme

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

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

主题
outline
filled_blue
filled_black

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 账号或浏览器设置。在加载库时，向 src 指令添加 hl 参数和语言代码，例如：gsi/client?hl=<iso-639-code>。

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

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

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 clicked... 记录到控制台。

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 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 账号中都是唯一的，并且永远不会重复使用。

通过使用 email、email_verified 和 hd 字段，您可以确定 Google 是否托管电子邮件地址并对其具有权威性。如果 Google 是权威机构，则可确认用户是合法账号所有者。

Google 具有权威性的情况：

• email 带有 @gmail.com 后缀，则表示这是 Gmail 账号。
• 如果 email_verified 为 true 且设置了 hd，则表示这是 Google Workspace 账号。

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

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

g_csrf_token

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

select_by

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

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

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

• 在与您的应用分享 ID 令牌凭据之前，用户需要

  • 按下了“确认”按钮以同意分享凭据，或者
  • 之前已授予同意声明，并使用“选择账号”选择了一个 Google 账号。

此字段的值设置为以下类型之一，

州

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

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

密码凭据处理程序端点

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

HTTP POST 请求包含以下信息：