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

“通过 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>

数据类型: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 使用”

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

类型 是否必须提供 示例
字符串 选填 state_cookie_domain: "example.com"

ux_mode

使用此字段可设置“使用 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.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" 将被视为无效。

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

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

您可以使用 emailemail_verifiedhd 字段来确定 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

下表列出了 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 如果已设置,则呈现按钮语言。

属性类型

下面几部分介绍了有关每个属性类型的详细信息和一个示例。

类型

按钮类型。默认值为 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 按钮文字为“通过 Google 继续”:
signin 按钮文字为“登录”:

形状

按钮的形状。默认值为 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 徽标居中对齐。

宽度

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

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

类型 是否必须提供 示例
字符串 选填 width: 400

语言区域

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

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

类型 是否必须提供 示例
字符串 选填 locale: "zh_CN"

数据类型:凭据

调用 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 处理程序。

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

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

数据类型:RevocationResponse

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

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

成功

此字段的值是一个布尔值,如果撤消方法调用成功或失败,则设置为 false。

错误

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