“通过 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 方法时都会重置配置，并且同一网页中的所有后续方法都会立即使用新配置。

警告 ：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	如果您需要在父网域及其子网域中调用一键快捷功能，请将父网域传递给此字段，以便使用单个共享 Cookie。
ux_mode	“使用 Google 帐号登录”按钮的用户体验流程
allowed_parent_origin	允许嵌入中间 iframe 的来源。如果此字段存在，一键将在中间 iframe 模式下运行。
intermediate_iframe_close_callback	当用户手动关闭一键快捷功能时，替换默认的中间 iframe 行为。
itp_support	在 ITP 浏览器中启用升级的一键式用户体验。

client_id

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

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

自动选择

如果某个 Google 会话之前已批准您的应用，那么此字段用于确定是否无需任何用户互动即可自动返回 ID 令牌。默认值为 false。如需了解详情，请参阅下表：

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

callback

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

类型	必需	示例
函数	对于一键快捷操作和 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"

您的登录端点必须处理正文中包含 ID 令牌值的 credential 键的 POST 请求。

以下是向登录端点发出的请求示例：

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

credential=ID_TOKEN

注意 ：使用 JavaScript API 时，Google One 点按和“使用 Google 帐号登录”按钮 popup 用户体验模式的响应只能返回到 callback JavaScript 函数。如果响应必须自动提交到 login_uri，请尝试使用 HTML API。

native_callback

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

类型	必需	示例
函数	选填	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

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

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

用户体验模式

使用此字段可设置“使用 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 及其子网域。您也可以使用数组来表示 2 个不同的网域。例如，["https://example1.com", "https://*.example2.com"] 会匹配网域 example1.com、example2.com 和 example2.com 的子网域
• 通配符域名必须以安全的 https:// 架构开头。"*.example.com" 会被视为无效。

注意 ：与 HTML API 不同，对于 allowed_parent_origin 字段，以逗号分隔的 URI 的字符串无效。请改用 JavaScript 数组对象。

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

intermediate_iframe_close_callback

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

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

类型	必需	示例
函数	选填	intermediate_iframe_close_callback: logBeforeClose

itp_support

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

类型	必需	示例
boolean	选填	itp_support: 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	此字段用于设置凭据的选择方式。

凭据

此字段是 ID 令牌，采用 base64 编码的 JSON 网络令牌 (JWT) 字符串。

进行解码时，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": "[e-mail]", // 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 令牌为 1 小时。您需要在到期时间之前验证令牌。您不应使用 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 帐号登录”按钮时，系统会调用此函数。

属性类型

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

type

按钮类型。默认值为 standard。

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

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

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

类型
standard	包含文字或个性化信息的按钮：
icon	不带文字的图标按钮：

主题

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

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

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

主题
outline	标准按钮主题：
filled_blue	蓝色按钮按钮主题：
filled_black	黑色按钮按钮主题：

大小

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

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

下表列出了可用的按钮尺寸及其说明：

大小
large	一个大按钮：
medium	中等尺寸按钮：
small	小按钮：

text

按钮文字。默认值为 signin_with。具有不同 text 属性的图标按钮文字没有任何视觉差异。唯一的例外情况是读取文本以访问屏幕。

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

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

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

文字
signin_with	按钮文本为“使用 Google 帐号登录”：
signup_with	按钮文字为“通过 Google 注册”：
continue_with	按钮文字为“使用 Google 继续”：
signin	按钮文字为“登录”：

shape

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

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

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

形状
rectangular	矩形按钮。如果用于 icon 按钮类型，则等同于 square。
pill	药丸形状的按钮。如果用于 icon 按钮类型，则等同于 circle。
circle	圆形按钮。如果用于 standard 按钮类型，则等同于 pill。
square	方形按钮。如果用于 standard 按钮类型，则等同于 rectangular。

徽标对齐方式

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

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

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

徽标对齐方式
left	左对齐 Google 徽标。
center	将 Google 徽标居中对齐。

width

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

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

类型	必需	示例
string	选填	width: 400

语言区域

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

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

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

类型	必需	示例
string	选填	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 帐号登录”按钮时，系统会将日志消息“点击登录 Google 按钮...”记录到控制台中。

数据类型：凭据

调用 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 授权。请参阅该方法的代码段：google.accounts.id.revoke(hint, callback)

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

以下代码示例展示了如何将 revoke 方法和 Id 搭配使用。

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

要点 ：调用此方法会撤消之前通过“使用 Google 帐号登录”客户端库授予的所有 OAuth2 范围。

数据类型：RevocationResponse

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

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

成功

如果撤消方法调用成功或失败，此字段将设置为 true。

error

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