警告:这些数据是根据 Google 用户数据政策提供的。请查看并遵守该政策。否则,可能会导致项目或帐号被暂停。

“通过 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 中查找和创建。如需了解详情,请参阅下表:

类型 必需 示例
字符串 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_uridata-callback 属性之一。具体取决于以下组件和用户体验模式配置:

  • “使用 Google 帐号登录”按钮 redirect 用户体验模式需要 data-login_uri 属性,该模式会忽略 data-callback 属性。

  • 必须为 Google One 点按和 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 属性。如需了解详情,请参阅下表:

类型 必需 示例
字符串 选填 data-login_uri="https://www.example.com/password_login"

data-native_callback

此属性是 JavaScript 函数的名称,该函数用于处理从浏览器的原生凭据管理器返回的密码凭据。如果您设置了 data-native_login_uri 属性或 data-native_callback 属性,当没有 Google 会话时,JavaScript 库会回退到原生凭据管理器。您不能同时设置 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。如需了解详情,请参阅下表:

类型 必需 示例
布尔值 选填 data-cancel_on_tap_outside="false"

data-prompt_parent_id

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

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

如果指定的 Cookie 具有非空值,则此属性将跳过一次点按。如需了解详情,请参阅下表:

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

data-Nonce

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

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

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

数据上下文

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

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

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

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

data-moment_callback

该属性是提示界面状态通知监听器的函数名称。如需了解详情,请参阅数据类型 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

当用户点按“一键快捷”界面中的 &X39;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

data-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 按钮文字以此属性中设置的语言呈现。

属性类型

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

数据类型

按钮类型。默认值为 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 按钮文字为“继续与 Google 互动”:
标准按钮“使用 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 徽标左对齐:
一个标准按钮,左侧带有 G 徽标
center 使 Google 徽标居中对齐:
标准按钮,带有 G 徽标的中心位置

数据宽度

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

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

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

语言区域

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

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

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

服务器端集成

您的服务器端端点必须处理以下 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"
}

下表列出了 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 凭据的选择方式。