“使用 Google 帐号登录”HTML API 参考文档

本参考页面介绍了“使用 Google 账号登录”HTML 数据属性 API。您可以使用该 API 在网页上显示“一键快捷功能”提示或“使用 Google 账号登录”按钮。

ID 为“g_id_onload”的元素

您可以在任何可见或不可见的元素(如 <div><span>)中放入“使用 Google 帐号登录”数据属性。唯一的要求是将元素 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 Developers Console 中找到并创建。如需了解详情,请参阅下表:

类型 必需 示例
字符串 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 函数的名称。如需了解详情,请参阅下表:

类型 必需 示例
字符串 如果未设置 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 属性,则 JavaScript 库会在没有 Google 会话时回退到原生凭据管理器。请勿同时设置 data-native_callbackdata-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_callbackdata-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。如需了解详情,请参阅下表:

类型 必需 示例
boolean 选填 data-cancel_on_tap_outside="false"

data-prompt_parent_id

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

类型 必需 示例
字符串 选填 data-prompt_parent_id="parent_id"

如果指定的 Cookie 的值不为空,则此属性会跳过一键快捷功能。如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-skip_prompt_cookie="SID"

数据 Nonce

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

类型 必需 示例
字符串 选填 data-nonce="biaqbm70g23"

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

数据上下文

此属性会更改一键式提示中显示的标题和消息文本。如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-context="use"

下表列出了可用的上下文及其说明:

背景信息
signin “使用 Google 账号登录”
signup “使用 Google 账号注册”
use “与 Google 搭配使用”

数据时刻回调

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

如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-moment_callback="logMomentNotification"

HTML API 不支持命名空间中的 JavaScript 函数。而应使用不带命名空间的全局 JavaScript 函数。例如,使用 mylibCallback 而不是 mylib.callback

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

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

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

类型 必需 示例
字符串。可以是电子邮件地址或 ID 令牌中的 sub 字段值。 选填 data-login_hint="elisa.beckett@gmail.com"

数据层

当用户拥有多个帐号且应仅使用其 Workspace 帐号登录时,可使用此方式向 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。 如需了解详情,请参阅下表:

类型 必需 示例
字符串 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 帐号登录”的标准按钮 没有可见文本的图标按钮
按钮文字为“使用 Google 账号登录”。
signup_with
一个标有“使用 Google 账号注册”的标准按钮 没有可见文本的图标按钮
按钮文字为“使用 Google 账号注册”。
continue_with
一个标记为“Continue with Google”的标准按钮 没有可见文本的图标按钮
按钮文字为“Continue with Google”。
signin
一个标记为“Sign in”(登录)的标准按钮 没有可见文本的图标按钮
按钮文字为“登录”。

数据形状

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

类型 必需 示例
字符串 选填 data-shape="rectangular"

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

形状
rectangular
矩形标准按钮 矩形图标按钮 矩形个性化按钮
矩形按钮。如果用于 icon 按钮类型,则与 square 相同。
pill
药丸形状的标准按钮 药丸形状的图标按钮 药丸形状的个性化按钮
药丸形状按钮。如果用于 icon 按钮类型,则该参数与 circle 相同。
circle
圆形标准按钮 圆形图标按钮 圆形个性化按钮
圆形按钮。如果用于 standard 按钮类型,则其与 pill 相同。
square
方形标准按钮 方形图标按钮 方形个性化按钮
方形按钮。如果用于 standard 按钮类型,则其与 rectangular 相同。

数据徽标对齐

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

类型 必需 示例
字符串 选填 data-logo_alignment="center"

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

logo_alignment
left
左侧带有 G 徽标的标准按钮
左对齐 Google 徽标。
center
一个中间带有 G 徽标的标准按钮
居中对齐 Google 徽标。

数据宽度

最小按钮宽度(以像素为单位)。可用宽度上限为 400 像素。

如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-width=400

数据语言区域

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

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

如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-locale="zh_CN"

click_listener

您可以使用 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 帐号登录”按钮后,控制台会记录以下消息:Sign in with Google button requested...

服务器端集成

您的服务器端端点必须处理以下 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_verified 也可以是 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 Google 发放的此 ID 令牌。
请求参数 password 如何选择凭据。