“使用 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_uridata-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_callbackdata-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_callbackdata-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"

如果指定 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

如果您需要在父网域及其子网域中显示一键快捷功能,请将父网域传递给此属性,以便使用单个共享状态 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.comlogin.news.example.com)。使用通配符时的注意事项:

  • 模式字符串不能仅包含通配符和顶级域名。例如,https://*.comhttps://*.co.uk 无效;如上所述,"https://*.example.com"example.com 及其子网域匹配。您还可以使用逗号分隔列表来表示 2 个不同的网域。例如,"https://example1.com,https://*.example2.com"example2.com 的网域 example1.comexample2.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="elisa.beckett@gmail.com"

数据高清

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

如需了解详情,请参阅有关 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 帐号登录”的标准按钮 没有可见文本的图标按钮
按钮文字为“使用 Google 帐号登录”。
signup_with
标有“使用 Google 注册”的标准按钮 没有可见文本的图标按钮
按钮文字为“通过 Google 注册”。
continue_with
标有“Continue with Google”的标准按钮 没有可见文本的图标按钮
按钮文字为“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
左侧带有 G 徽标的标准按钮
左对齐 Google 徽标。
center
中央有 G 徽标的标准按钮
将 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": "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 帐号中具有唯一性,并且不得重复使用。请勿使用电子邮件地址作为标识符,因为一个 Google 帐号在不同的时间点可能有多个电子邮件地址。

您可以使用 emailemail_verifiedhd 字段确定 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 选择凭据的方式。