“通过 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 浏览器中启用升级的一键式用户体验。

属性类型

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

数据客户端 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": "[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"
}

下表列出了 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	如何选择凭据。

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