Sign In With Google JavaScript API（使用 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，您可以在 Google Cloud 控制台中找到和创建此 ID。如需了解详情，请参阅下表：

auto_select

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

callback

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

login_uri

此属性是登录端点的 URI。

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

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

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

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

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

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

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

credential=ID_TOKEN

native_callback

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

cancel_on_tap_outside

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

prompt_parent_id

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

nonce

此字段是一个随机字符串，ID 令牌会使用它来防止重放攻击。如需了解详情，请参阅下表：

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

上下文

此字段用于更改一键式提示中显示的标题和消息的文本，对 ITP 浏览器没有影响。默认为 signin。

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

下表列出了所有可用情境及其说明：

state_cookie_domain

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

ux_mode

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

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

allowed_parent_origin

允许嵌入中间 iframe 的来源。如果此字段存在，One Tap 将在中间 iframe 模式下运行。如需了解详情，请参阅下表：

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

也支持通配符前缀。例如，"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" 会匹配网域 example1.com、example2.com 以及 example2.com 的子网域
• 通配符网域必须以安全的 https:// 架构开头，因此 "*.example.com" 被视为无效。

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

intermediate_iframe_close_callback

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

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

itp_support

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

login_hint

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

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

高清

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

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

use_fedcm_for_prompt

允许浏览器控制用户登录提示，并协调您网站和 Google 之间的登录流程。默认值为 false。如需了解详情，请参阅迁移到 FedCM 页面。

use_fedcm_for_button

此字段用于确定是否应在 Chrome（桌面版 M125 及更高版本和 Android 版 M128 及更高版本）上使用 FedCM 按钮用户体验。默认为 false。如需了解详情，请参阅下表：

button_auto_select

此字段用于确定是否为 FedCM 按钮流程启用自动选择选项。如果启用此功能，则具有有效 Google 会话的回访用户将自动登录，而无需看到账号选择器提示。默认为 false。您需要在用户选择启用该功能时明确启用按钮自动登录功能。如需了解详情，请参阅下表：

方法：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 数据类型的方法和说明：

数据类型：CredentialResponse

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

凭据

此字段是 ID 令牌，采用 base64 编码的 JSON Web 令牌 (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 账号的全局唯一标识符。仅使用 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

下表列出了 select_by 字段的可能值。所用按钮的类型以及会话和用户意见征求状态用于设置值，

• 用户按下“一键登录”或“使用 Google 账号登录”按钮，或使用了免触摸的“自动登录”流程。

• 系统找到了现有会话，或者用户选择并登录了 Google 账号以建立新会话。

• 在与您的应用分享 ID 令牌凭据之前，用户必须满足以下条件之一：

  • 点按“确认”按钮，同意共享凭据；或者
  • 之前已授予同意，并使用“选择账号”选择了 Google 账号。

此字段的值设置为以下类型之一，

州

只有当用户点击“使用 Google 账号登录”按钮进行登录，并且指定了所点击按钮的 state 属性时，此字段才会定义。此字段的值与您在按钮的 state 属性中指定的值相同。

由于同一网页上可以呈现多个“使用 Google 账号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。因此，您可以使用此 state 字段来确定用户点击了哪个按钮进行登录。

方法：google.accounts.id.renderButton

google.accounts.id.renderButton 方法会在网页中呈现“使用 Google 账号登录”按钮。

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

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

数据类型：GsiButtonConfiguration

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

属性类型

以下部分详细介绍了每种属性的类型以及示例。

类型

按钮类型。默认值为 standard。

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

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

类型
standard
icon

主题

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

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

主题
outline
filled_blue
filled_black

size

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

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

大小
large
medium
small

text

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

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

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

文本
signin_with
signup_with
continue_with
signin

形状

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

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

形状
rectangular
pill
circle
square

logo_alignment

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

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

logo_alignment
left
center

width

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

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

语言区域

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

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

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

click_listener

您可以使用 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 clicked... 记录到控制台。

州

可选，由于同一页面上可以呈现多个“使用 Google 账号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。系统会将同一字符串随 ID 令牌一起返回，以便您确定用户点击了哪个按钮进行登录。

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

数据类型：凭据

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

方法：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)

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

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

数据类型：RevocationResponse

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

成功

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

错误

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