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

使用 Google HTML API 参考登录

此参考页面介绍了使用 Google HTML 数据属性登录 API。您可以使用 API 在您的网页上显示一键提示或使用 Google 登录按钮。

ID 为“g_id_onload”的元素

您可以在任何可见或不可见元素,如把在与谷歌的数据属性<div><span>唯一的要求是该元件ID被设置为g_id_onload 。不要将此 ID 放在多个元素上。

数据属性

下表列出了数据属性及其说明:

属性
data-client_id您的应用程序的客户端 ID
data-auto_prompt显示谷歌一键。
data-auto_select在 Google One Tap 上启用自动选择。
data-login_uri您的登录端点的 URL
data-callback JavaScript ID 令牌处理函数名称
data-native_login_uri您的密码凭证处理程序端点的 URL
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 One Tap 提示容器元素的DOM ID
data-skip_prompt_cookie如果指定的 cookie 具有非空值,则跳过一次点击。
data-nonce ID 令牌的随机字符串
data-context One Tap 提示中的标题和单词
data-moment_callback提示UI状态通知监听器的函数名
data-state_cookie_domain如果您需要在父域及其子域中调用 One Tap,请将父域传递给此属性,以便使用单个共享 cookie。
data-ux_mode使用 Google 按钮登录的用户体验流程
data-allowed_parent_origin允许嵌入中间 iframe 的来源。如果此属性存在,One Tap 将在中间 iframe 模式下运行。
data-intermediate_iframe_close_callback当用户手动关闭 One Tap 时,覆盖默认的中间 iframe 行为。

属性类型

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

数据客户端_id

此属性是您的应用程序的客户端 ID,可在 Google Developers Console 中找到并创建该 ID。有关详细信息,请参阅下表:

类型必需的例子
细绳是的data-client_id="CLIENT_ID.apps.googleusercontent.com"

数据自动提示

该属性决定是否显示一键。默认值是true 。当这个值是谷歌的一个水龙头将不会显示false 。有关详细信息,请参阅下表:

类型必需的例子
布尔值可选的data-auto_prompt="true"

数据自动选择

如果只有一个 Google 会话批准了您的应用程序,则此属性确定是否在没有任何用户交互的情况下自动返回 ID 令牌。默认值是false 。有关详细信息,请参阅下表:

类型必需的例子
布尔值可选的data-auto_select="true"

数据登录_uri

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

当未定义回调函数并且用户单击“使用 Google 登录”或“一键登录”按钮或发生自动签名时,ID 令牌凭据响应将发布到您的登录端点。

有关详细信息,请参阅下表:

类型可选的例子
网址默认为当前页面的 URI,或您指定的值。
当被忽略的data-ux_mode="popup"data-callback设置。
data-login_uri="https://www.example.com/login"

您的登录端点必须处理包含POST请求credential与体内的ID令牌值的关键。

以下是对您的登录端点的示例请求:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

数据回调

此属性是处理返回的 ID 令牌的 JavaScript 函数的名称。有关详细信息,请参阅下表:

类型必需的例子
细绳如果需要的data-login_uri未设置。 data-callback="handleToken"

其中的data-login_uridata-callback属性可能被使用。这取决于以下组件和 UX 模式配置:

  • data-login_uri属性是必需的在与谷歌按钮redirect UX模式,而忽略了data-callback属性。

  • 其中这两个属性必须为谷歌一个水龙头和谷歌登录按钮来设置popup UX模式。如果两者都设置时, data-callback属性具有更高的优先级。

HTML API 不支持命名空间中的 JavaScript 函数。相反,使用没有命名空间的全局 JavaScript 函数。例如,使用mylibCallback代替mylib.callback

data-native_login_uri

此属性是您的密码凭据处理程序端点的 URL。如果设置无论是data-native_login_uri属性或data-native_callback属性,JavaScript库回落到原始凭据管理器时,没有谷歌的会话。你不允许设置两个data-native_callbackdata-native_login_uri属性。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-login_uri="https://www.example.com/password_login"

数据-native_callback

此属性是处理从浏览器的本机凭据管理器返回的密码凭据的 JavaScript 函数的名称。如果设置无论是data-native_login_uri属性或data-native_callback属性,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"

数据cancel_on_tap_outside

此属性设置如果用户在提示之外单击,是否取消 One Tap 请求。默认值是true 。要禁用它,将值设置为false 。有关详细信息,请参阅下表:

类型必需的例子
布尔值可选的data-cancel_on_tap_outside="false"

数据提示_parent_id

此属性设置容器元素的 DOM ID。如果未设置,则窗口右上角会显示一键提示。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-prompt_parent_id="parent_id"

如果指定的 cookie 具有非空值,则此属性会跳过 One Tap。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-skip_prompt_cookie="SID"

数据随机数

此属性是 ID 令牌用于防止重放攻击的随机字符串。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-nonce="biaqbm70g23"

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

数据上下文

此属性更改 One Tap 提示中显示的标题和消息的文本。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-context="use"

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

语境
signin “使用谷歌登录”
signup “使用谷歌注册”
use “与谷歌一起使用”

数据时刻_回调

该属性是提示UI状态通知监听器的函数名。有关详细信息,请参阅数据类型PromptMomentNotification 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-moment_callback="logMomentNotification"

HTML API 不支持命名空间中的 JavaScript 函数。相反,使用没有命名空间的全局 JavaScript 函数。例如,使用mylibCallback代替mylib.callback

如果您需要在父域及其子域中显示 One Tap,请将父域传递给此属性,以便使用单个共享状态 cookie。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-state_cookie_domain="example.com"

数据-ux_mode

此属性设置“使用 Google 登录”按钮使用的 UX 流程。默认值是popup 。此属性对 One Tap UX 没有影响。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-ux_mode="redirect"

下表列出了可用的 UX 模式及其说明。

用户体验模式
popup在弹出窗口中执行登录 UX 流程。
redirect通过整页重定向执行登录 UX 流程。

data-allowed_pa​​rent_origin

允许嵌入中间 iframe 的来源。如果此属性存在,One Tap 将在中间 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.com和子域的example2.com
  • 通配符域必须以安全的 https:// 方案开头。 "*.example.com"将被视为无效。

data-intermediate_iframe_close_callback

当用户通过点击 One Tap UI 中的“X”按钮手动关闭 One Tap 时,覆盖默认的中间 iframe 行为。默认行为是立即从 DOM 中删除中间 iframe。

data-intermediate_iframe_close_callback字段只需要在中间的iframe模式的效果。而且它只影响中间 iframe,而不是 One Tap iframe。在调用回调之前删除一键用户界面。

类型必需的例子
功能可选的data-intermediate_iframe_close_callback='logBeforeClose'

HTML API 不支持命名空间中的 JavaScript 函数。相反,使用没有命名空间的全局 JavaScript 函数。例如,使用mylibCallback代替mylib.callback

具有类“g_id_signin”的元素

如果添加g_id_signin到元素的class属性,元素呈现为在与谷歌按钮。

您可以在同一页面上呈现多个“使用 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一个没有文字的图标按钮:

数据主题

按钮主题。默认值是outline 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-theme="filled_blue"

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

主题
outline标准按钮主题:
一个白色背景的标准按钮一个白色背景的图标按钮一个白色背景的个性化按钮
filled_blue蓝色填充按钮主题:
蓝色背景的标准按钮蓝色背景的图标按钮蓝色背景的个性化按钮
filled_black黑色填充按钮主题:
黑色背景的标准按钮黑色背景的图标按钮黑色背景的个性化按钮

数据大小

按钮大小。默认值是large 。有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-size="small"

下表列出了可用的按钮大小及其说明。

尺寸
large一个大按钮:
一个大的标准按钮一个大图标按钮一个大的、个性化的按钮
medium一个中等大小的按钮:
中等标准按钮中等图标按钮
small一个小按钮:
一个小按钮一个小图标按钮

数据文本

按钮文本。默认值是signin_with 。有针对具有不同的图标按钮的文本,没有视觉上的差异data-text属性。唯一的例外是当为了屏幕可访问性而读取文本时。

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-text="signup_with"

下表列出了可用的按钮文本及其说明:

文本
signin_with按钮文本为“使用 Google 登录”:
标有“使用 Google 登录”的标准按钮一个没有可见文本的图标按钮
signup_with按钮文字是“Sign up with Google”:
标有“使用 Google 注册”的标准按钮一个没有可见文本的图标按钮
continue_with按钮文字是“Continue with Google”:
标有“继续使用 Google”的标准按钮一个没有可见文本的图标按钮
signup_with按钮文本为“登录”:
标有“登录”的标准按钮一个没有可见文本的图标按钮

数据形状

按钮形状。默认值是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"

下表列出了可用的路线及其说明:

logo_alignment
left左对齐 Google 徽标:
左侧带有 G 标志的标准按钮
center居中对齐 Google 徽标:
中央带有 G 标志的标准按钮

数据宽度

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

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-width=400

数据区域

按钮文本的预设语言环境。如果未设置,则使用浏览器的默认区域设置或 Google 会话用户的首选项。因此,不同的用户可能会看到不同版本的本地化按钮,并且可能具有不同的大小。

有关详细信息,请参阅下表:

类型必需的例子
细绳可选的data-locale="zh_CN"

服务器端集成

服务器端的端点必须处理好以下几个HTTP POST请求。

ID 令牌处理程序端点

ID 令牌处理程序端点处理 ID 令牌。根据相应帐户的状态,您可以登录用户并将他们定向到注册页面或将他们定向到帐户链接页面以获取更多信息。

在HTTP POST请求中包含以下信息:

格式姓名描述
曲奇饼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具有现有会话的用户按下 One Tap 'Continue as' 按钮以授予同意并共享凭据。仅适用于 Chrome v75 及更高版本。
user_2tap没有现有会话的用户按下 One Tap 'Continue as' 按钮选择一个帐户,然后按下弹出窗口中的 Confirm 按钮以授予同意并共享凭据。适用于非基于 Chromium 的浏览器。
btn具有先前同意的现有会话的用户按下“使用 Google 登录”按钮并从“选择帐户”中选择一个 Google 帐户以共享凭据。
btn_confirm具有现有会话的用户按下“使用 Google 登录”按钮并按下“确认”按钮以授予同意并共享凭据。
btn_add_session先前未授予同意的现有会话的用户按下“使用 Google 登录”按钮选择 Google 帐户并共享凭据。
btn_confirm_add_session没有现有会话的用户首先按“使用 Google 登录”按钮选择 Google 帐户,然后按“确认”按钮同意并共享凭据。

密码凭证处理程序端点

密码凭证处理程序端点处理本机凭证管理器检索的密码凭证。

在HTTP POST请求中包含以下信息:

格式姓名描述
曲奇饼g_csrf_token随对处理程序端点的每个请求而更改的随机字符串。
请求参数g_csrf_token一个字符串,这是一样的前一个cookie值, g_csrf_token
请求参数email Google 颁发的此 ID 令牌。
请求参数password如何选择凭据。