“通过 Google JavaScript API 登录”参考文档

本参考页面介绍了 Sign-In JavaScript API。您可以使用此 API 在网页上显示“一键登录”提示或“使用 Google 帐号登录”按钮。

方法：google.accounts.id.initialize

google.accounts.id.initialize 方法会根据配置对象初始化“使用 Google 帐号登录”客户端。请参阅该方法的以下代码示例：

google.accounts.id.initialize(IdConfiguration)

以下代码示例使用 onload 函数实现 google.accounts.id.initialize 方法：

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

google.accounts.id.initialize 方法会创建一个“使用 Google 帐号登录”客户端实例，可供同一网页中的所有模块隐式使用。

• 即使您在同一网页中使用多个模块（如一键快捷功能、个性化按钮、撤消等），也只需调用 google.accounts.id.initialize 方法一次。
• 如果您多次调用 google.accounts.id.initialize 方法，则系统只会记住和使用上次调用中的配置。

实际上，每次调用 google.accounts.id.initialize 方法时，您都会重置配置，同一网页中的所有后续方法都会立即使用新配置。

数据类型：IdConfiguration

下表列出了 IdConfiguration 数据类型的字段和说明：

字段
client_id	您的应用的客户端 ID
auto_select	启用自动选择。
callback	处理 ID 令牌的 JavaScript 函数。Google 一键登录和“使用 Google 帐号登录”按钮 popup 用户体验模式会使用此属性。
login_uri	登录端点的网址。“使用 Google 帐号登录”按钮 redirect用户体验模式会使用此属性。
native_callback	处理密码凭据的 JavaScript 函数。
cancel_on_tap_outside	如果用户在提示范围之外点击，则取消提示。
prompt_parent_id	一键式提示容器元素的 DOM ID
nonce	ID 令牌的随机字符串
context	一键式提示中的标题和字词
state_cookie_domain	如果您需要在父网域及其子网域中调用 One Tap，请将父网域传递给此字段，以便使用单个共享 Cookie。
ux_mode	“使用 Google 帐号登录”按钮的用户体验流程
allowed_parent_origin	可以嵌入中间 iframe 的来源。如果存在此字段，则会在中间 iframe 模式下运行一键快捷功能。
intermediate_iframe_close_callback	当用户手动关闭一键快捷功能时，覆盖默认的中间 iframe 行为。
itp_support	在 ITP 浏览器上启用升级的一键式用户体验。
login_hint	通过提供用户提示跳过帐号选择。
hd	按网域限制帐号选择。
use_fedcm_for_prompt	允许浏览器控制用户的登录提示，并在您的网站与 Google 之间协调登录流程。

client_id

此字段是应用的客户端 ID，您可以在 Google Developers Console 中找到并创建该 ID。如需了解详情，请参阅下表：

类型	必需	示例
string	是	client_id: "CLIENT_ID.apps.googleusercontent.com"

自动选择

此字段用于确定在仅有一个 Google 会话之前批准了您的应用的情况下，系统是否会在没有任何用户互动的情况下自动返回 ID 令牌。默认值为 false。如需了解详情，请参阅下表：

类型	必需	示例
boolean	可选	auto_select: true

callback

此字段是一个 JavaScript 函数，用于处理从一键快捷提示或弹出式窗口返回的 ID 令牌。如果使用的是“Google 一键登录”或“使用 Google 帐号登录”按钮 popup 用户体验模式，则必须提供此属性。如需了解详情，请参阅下表：

类型	必需	示例
function	对于一键快捷功能和popup用户体验模式而言是必需的	callback: handleResponse

login_uri

此属性是您的登录端点的 URI。

该值必须与您在 API 控制台中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配，且必须符合我们的重定向 URI 验证规则。

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

当用户点击“使用 Google 帐号登录”按钮并使用重定向用户体验模式时，ID 令牌凭据响应会发布到您的登录端点。

如需了解详情，请参阅下表：

类型	可选	示例
网址	默认值为当前页面的 URI，或您指定的值。 仅在已设置 ux_mode: "redirect" 时使用。	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

native_callback

此字段是 JavaScript 函数的名称，用于处理从浏览器的原生凭据管理器返回的密码凭据。如需了解详情，请参阅下表：

类型	必需	示例
function	可选	native_callback: handleResponse

cancel_on_tap_outside

此字段用于设置如果用户点击提示以外的位置，是否取消一键快捷请求。默认值为 true。如果将该值设置为 false，您可以停用该功能。如需了解详情，请参阅下表：

类型	必需	示例
boolean	可选	cancel_on_tap_outside: false

提示父级 ID

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

类型	必需	示例
string	可选	prompt_parent_id: 'parent_id'

nonce

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

类型	必需	示例
string	可选	nonce: "biaqbm70g23"

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

context

此字段会更改一键式提示中的标题和消息文本。如需了解详情，请参阅下表：

类型	必需	示例
string	可选	context: "use"

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

上下文
signin	“使用 Google 帐号登录”
signup	“通过 Google 注册”
use	“通过 Google 使用”

state_cookie_domain

如果您需要在父网域及其子网域中显示 One Tap，请将父网域传递给此字段，以便使用单个共享状态 Cookie。如需了解详情，请参阅下表：

类型	必需	示例
string	可选	state_cookie_domain: "example.com"

ux_mode

使用此字段可设置“使用 Google 帐号登录”按钮使用的用户体验流程。默认值为 popup。此属性对 OneTap 用户体验没有任何影响。如需了解详情，请参阅下表：

类型	必需	示例
string	可选	ux_mode: "redirect"

下表列出了可用的用户体验模式及其说明。

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

allow_parent_origin

可以嵌入中间 iframe 的来源。如果存在此字段，则一键快捷功能会在中间 iframe 模式下运行。如需了解详情，请参阅下表：

类型	必需	示例
字符串或字符串数组	可选	allowed_parent_origin: "https://example.com"

下表列出了支持的值类型及其说明。

值类型
string	单个网域 URI。	"https://example.com"
string array	网域 URI 数组。	["https://news.example.com", "https://local.example.com"]

系统也支持通配符前缀。例如，"https://*.example.com" 会在各个级别匹配 example.com 及其子网域（例如 news.example.com、login.news.example.com）。使用通配符时的注意事项：

• 模式字符串不能仅包含通配符和顶级域名。例如，https://*.com 和 https://*.co.uk 无效；如上所述，"https://*.example.com" 与 example.com 及其子网域匹配。您还可以使用数组来表示两个不同的网域。例如，["https://example1.com", "https://*.example2.com"] 与 example2.com 的网域 example1.com、example2.com 及子网域匹配
• 通配符域名必须以安全的 https:// 架构开头，因此 "*.example.com" 被视为无效。

如果 allowed_parent_origin 字段的值无效，中间 iframe 模式的一键初始化将会失败并停止。

intermediate_iframe_close_callback

当用户通过点按一键式界面中的“X”按钮手动关闭一键关闭时，覆盖默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。

intermediate_iframe_close_callback 字段仅在中间 iframe 模式下生效。它只会影响中间 iframe，而不是一键式 iframe。在调用回调之前，系统会移除一键快捷界面。

类型	必需	示例
function	可选	intermediate_iframe_close_callback: logBeforeClose

itp_support

此字段用于确定是否应在支持智能反跟踪 (ITP) 的浏览器上启用 升级后的一键式用户体验。默认值为 false。如需了解详情，请参阅下表：

类型	必需	示例
boolean	可选	itp_support: true

登录提示

如果您的应用事先知道应该登录哪个用户，则可以向 Google 提供登录提示。如果操作成功，系统会跳过帐号选择。 接受的值包括电子邮件地址或 ID 令牌 sub 字段值。

如需了解详情，请参阅 OpenID Connect 文档中的 login_hint 字段。

类型	必需	示例
字符串、电子邮件地址或 ID 令牌 sub 字段中的值。	可选	login_hint: 'elisa.beckett@gmail.com'

高清

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

如需了解详情，请参阅 OpenID Connect 文档中的 hd 字段。

类型	必需	示例
字符串。完全限定域名或 *。	可选	hd: '*'

使用_fedcm_for_prompt

允许浏览器控制用户的登录提示，并在您的网站与 Google 之间协调登录流程。默认值为 false。

类型	必需	示例
boolean	可选	use_fedcm_for_prompt: true

方法：google.accounts.id.prompt

在调用 initialize() 方法后，google.accounts.id.prompt 方法会显示一键快捷提示或浏览器原生凭据管理器。请参阅该方法的以下代码示例：

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

通常，系统会在网页加载时调用 prompt() 方法。由于 Google 端的会话状态和用户设置，因此可能不会显示一键式提示界面。如需获取有关不同时刻的界面状态的通知，请传递一个函数来接收界面状态通知。

通知会在以下时刻触发：

• 显示时刻：发生在调用 prompt() 方法之后。通知包含一个布尔值，用于指示是否显示界面。

• 已跳过 - 当自动取消、手动取消或 Google 无法颁发凭据时（例如，当所选会话已退出 Google 帐号）时，会发生这种情况。

  在这些情况下，我们建议您继续联系下一个身份提供方（如果有）。

• 已忽略的时刻：当 Google 成功检索凭据或用户想要停止凭据检索流程时，会发生这种情况。例如，当用户开始在登录对话框中输入用户名和密码时，您可以调用 google.accounts.id.cancel() 方法来关闭一键快捷提示并触发关闭时刻。

以下代码示例实现了跳过的时刻：

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

数据类型：PromptMomentNotification

下表列出了 PromptMomentNotification 数据类型的方法和说明：

方法
isDisplayMoment()	此通知是否旨在展示广告？
isDisplayed()	此通知是否为显示时机，以及界面是否显示？
isNotDisplayed()	此通知是否为显示时刻，而不显示界面？
getNotDisplayedReason()	界面未显示的详细原因。以下是可能的值： browser_not_supported invalid_client missing_client_id opt_out_or_no_session secure_http_required suppressed_by_user unregistered_origin unknown_reason
isSkippedMoment()	此通知是针对跳过的时刻吗？
getSkippedReason()	跳过某些片段的详细原因。以下是可能的值： auto_cancel user_cancel tap_outside issuing_failed
isDismissedMoment()	此通知是针对已关闭的时刻吗？
getDismissedReason()	详细的忽略原因。以下是可能的值： credential_returned cancel_called flow_restarted
getMomentType()	针对时刻类型返回一个字符串。以下是可能的值： display skipped dismissed

数据类型：CredentialResponse

调用 callback 函数时，系统会将 CredentialResponse 对象作为参数传递。下表列出了凭据响应对象中包含的字段：

字段
credential	此字段是返回的 ID 令牌。
select_by	此字段用于设置凭据的选择方式。

凭据

此字段是采用 base64 编码的 JSON Web 令牌 (JWT) 字符串形式的 ID 令牌。

解码后，JWT 将如以下示例所示：

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": "Elisa",
  "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 帐号的全局唯一标识符。

您可以使用 email、email_verified 和 hd 字段确定 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 字段的可能值。与会话和同意情况结合使用的按钮类型用于设置值。

• 用户按下了“一键快捷”按钮或“使用 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 帐号，然后按“确认”按钮同意并共享凭据。

方法：google.accounts.id.renderButton

google.accounts.id.renderButton 方法会在您的网页中显示“使用 Google 帐号登录”按钮。

请参阅该方法的以下代码示例：

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

数据类型：GsiButtonConfiguration

下表列出了 GsiButtonConfiguration 数据类型的字段和说明：

属性
type	按钮类型：图标或标准按钮。
theme	按钮主题。例如，filled_blue 或 filled_black。
size	按钮大小。例如，“小”或“大”。
text	按钮文字。例如，“使用 Google 帐号登录”或“使用 Google 注册”。
shape	按钮形状。例如，矩形或圆形。
logo_alignment	Google 徽标对齐方式：左对齐或居中。
width	按钮宽度（以像素为单位）。
locale	如果设置了该属性，则呈现按钮语言。
click_listener	如果设置了此项，则当用户点击“使用 Google 帐号登录”按钮时，系统会调用此函数。

属性类型

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

类型

按钮类型。默认值为 standard。

如需了解详情，请参阅下表：

类型	必需	示例
string	是	type: "icon"

下表列出了可用的按钮类型及其说明：

类型
standard
icon

主题

按钮主题。默认值为 outline。如需了解详情，请参阅下表：

类型	必需	示例
string	可选	theme: "filled_blue"

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

主题
outline
filled_blue
filled_black

大小

按钮大小。默认值为 large。如需了解详情，请参阅下表：

类型	必需	示例
string	可选	size: "small"

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

大小
large
medium
small

文本

按钮文字。默认值为 signin_with。如果图标按钮具有不同的 text 属性，其文本在视觉上没有区别。唯一的例外情况是朗读文本以便于访问屏幕。

如需了解详情，请参阅下表：

类型	必需	示例
string	可选	text: "signup_with"

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

文字
signin_with
signup_with
continue_with
signin

shape

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

类型	必需	示例
string	可选	shape: "rectangular"

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

形状
rectangular
pill
circle
square

徽标对齐

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

类型	必需	示例
string	可选	logo_alignment: "center"

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

徽标对齐
left
center

width

按钮最小宽度（以像素为单位）。宽度上限为 400 像素。

如需了解详情，请参阅下表：

类型	必需	示例
string	可选	width: "400"

语言区域

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

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

如需了解详情，请参阅下表：

类型	必需	示例
string	可选	locale: "zh_CN"

点击监听器

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

数据类型：凭据

调用 native_callback 函数时，会将 Credential 对象作为参数传递。下表列出了该对象中包含的字段：

字段
id	标识用户。
password	密码

方法：google.accounts.id.disableAutoSelect

当用户退出您的网站时，您需要调用 google.accounts.id.disableAutoSelect 方法以在 Cookie 中记录状态。这样可以防止用户体验死循环。请参阅该方法的以下代码段：

google.accounts.id.disableAutoSelect()

以下代码示例使用 onSignout() 函数实现 google.accounts.id.disableAutoSelect 方法：

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

方法：google.accounts.id.storeCredential

此方法是浏览器原生凭据管理器 API 的 store() 方法的封装容器。因此，它只能用于存储密码凭据。请参阅该方法的以下代码示例：

google.accounts.id.storeCredential(Credential, callback)

以下代码示例使用 onSignIn() 函数实现 google.accounts.id.storeCredential 方法：

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

方法：google.accounts.id.cancel

如果您从依赖方 DOM 中移除提示，可以取消一键式流程。如果已经选择了凭据，则系统会忽略取消操作。请参阅该方法的以下代码示例：

google.accounts.id.cancel()

以下代码示例使用 onNextButtonClicked() 函数实现 google.accounts.id.cancel() 方法：

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

库加载回调：onGoogleLibraryLoad

您可以注册一个 onGoogleLibraryLoad 回调。系统会在“使用 Google 帐号登录” JavaScript 库加载完成后通知它：

window.onGoogleLibraryLoad = () => {
    ...
};

此回调只是 window.onload 回调的快捷方式。行为方面没有差异。

以下代码示例实现了 onGoogleLibraryLoad 回调：

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

方法：google.accounts.id.revoke

google.accounts.id.revoke 方法可撤消用于共享指定用户的 ID 令牌的 OAuth 授权。请参阅该方法的以下代码段：javascript google.accounts.id.revoke(login_hint, callback)

参数	类型	说明
login_hint	string	用户 Google 帐号的电子邮件地址或唯一 ID。该 ID 是凭据载荷的 sub 属性。
callback	function	（可选）RevocationResponse 处理程序。

以下代码示例展示了如何使用带有 ID 的 revoke 方法。

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

数据类型：RevocationResponse

调用 callback 函数时，系统会将 RevocationResponse 对象作为参数传递。下表列出了撤消响应对象中包含的字段：

字段
successful	此字段是方法调用的返回值。
error	此字段可以选择包含详细的错误响应消息。

成功

此字段是一个布尔值，如果撤消方法调用成功，则设为 true，失败时设为 false。

error

此字段是一个字符串值，如果撤消方法调用失败，则包含详细的错误消息，如果撤消方法调用成功，则未定义。