“通过 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 One 点按和“使用 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 中找到并创建一个。如需了解详情，请参阅下表：

类型	必需	示例
字符串	是	client_id: "CLIENT_ID.apps.googleusercontent.com"

自动选择

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

类型	必需	示例
布尔值	选填	auto_select: true

callback

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

类型	必需	示例
函数	对于一键式体验和 popup 用户体验模式是必需的	callback: handleResponse

login_uri

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

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

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

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

native_callback

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

类型	必需	示例
函数	选填	native_callback: handleResponse

在外点按取消

此字段会设置用户是否在提示外点击时取消一键式请求。默认值为 true。如果将值设置为 false，则可以停用该标记。如需了解详情，请参阅下表：

类型	必需	示例
布尔值	选填	cancel_on_tap_outside: false

提示 ID

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

类型	必需	示例
字符串	选填	prompt_parent_id: 'parent_id'

nonce

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

类型	必需	示例
字符串	选填	nonce: "biaqbm70g23"

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

context

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

类型	必需	示例
字符串	选填	context: "use"

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

背景信息
signin	“使用 Google 帐号登录”
signup	“通过 Google 注册”
use	“在 Google 产品和服务中使用”

state_cookie_domain

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

类型	必需	示例
字符串	选填	state_cookie_domain: "example.com"

UX 模式

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

类型	必需	示例
字符串	选填	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" 将被视为无效。

如果 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 支持

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

类型	必需	示例
布尔值	选填	itp_support: true

方法：google.accounts.id.prompt

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

 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 已设置，这是一个 G Suite 帐号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 帐号。如果 email 不包含 @gmail.com 后缀，且不存在 hd，则 Google 不具有权威性，建议使用密码或其他质询方法验证用户。email_verfied 也可能为 true，因为 Google 最初是在 Google 帐号创建时验证的，但第三方电子邮件帐号的所有权可能已更改。

选择依据

下表列出了 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。

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

类型	必需	示例
字符串	是	type: "icon"

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

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

主题

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

类型	必需	示例
字符串	选填	theme: "filled_blue"

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

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

大小

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

类型	必需	示例
字符串	选填	size: "small"

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

大小
large	一个大按钮：
medium	中型按钮：
small	一个小按钮：

text

按钮文字。默认值为 signin_with。具有不同 text 属性的图标按钮文本没有视觉差异。唯一的例外是，为获得屏幕无障碍功能而读取文本时。

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

类型	必需	示例
字符串	选填	text: "signup_with"

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

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

shape

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

类型	必需	示例
字符串	选填	shape: "rectangular"

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

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

徽标对齐方式

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

类型	必需	示例
字符串	选填	logo_alignment: "center"

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

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

width

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

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

类型	必需	示例
字符串	选填	width: 400

语言区域

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

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

类型	必需	示例
字符串	选填	locale: "zh_CN"

点击监听器

您可以使用 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	字符串	用户的 Google 帐号的电子邮件地址或唯一 ID。ID 是凭据凭据的 sub 属性。
callback	函数	（可选）RevocationResponse 处理程序。

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

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

数据类型：RevocationResponse

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

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

成功

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

错误

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