此页面由 Cloud Translation API 翻译。

Google 登录 JavaScript 客户端参考文档

本参考文档介绍了 JavaScript 客户端方法和属性，用于在 Web 应用中实现 Google 登录功能。

如果您在使用此库时遇到任何问题，请向我们的 GitHub 代码库。

身份验证设置

加载 Google API 平台库以创建 gapi 对象：

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

加载平台库后，加载 auth2 库：

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(`params`)

初始化 GoogleAuth 对象。您必须先调用此方法，然后再调用 gapi.auth2.GoogleAuth 的方法。

初始化 GoogleAuth 对象时，您可以为该对象配置 OAuth 2.0 客户端 ID 和要指定的任何其他选项。然后，如果用户已登录，GoogleAuth 对象会恢复用户在上一个会话中的登录状态。

参数
`params`	包含客户端配置数据键值对的对象。请参阅 `gapi.auth2.ClientConfig` 属性。例如： { client_id: 'CLIENT_ID.apps.googleusercontent.com' }

返回
`gapi.auth2.GoogleAuth`	`gapi.auth2.GoogleAuth` 对象。使用 then() 方法获取 Promise 系统会在 `gapi.auth2.GoogleAuth` 对象完成时解析初始化。

GoogleAuth.then(`onInit`、`onError`)

当 GoogleAuth 对象完全加载时，调用 onInit 函数。如果初始化时发生错误（这种情况可能发生在不受支持的旧版浏览器中），而是会调用 onError 函数。

参数
`onInit`	完全使用 `GoogleAuth` 对象调用的函数。
`onError`	使用包含 `error` 属性的对象调用的函数。如果 `GoogleAuth` 未能初始化，则会发生该错误。

返回
Promise	当 `onInit` 时执行的 `Promise` 函数已经完成，如果引发初始化错误，则会被拒绝。它通过 `onInit` 函数返回的值（如果有）。

</ph> 警告：请勿调用 Promise.resolve() 及调用 gapi.auth2.init()。由于返回的 GoogleAuth 对象会实现 then() 方法，那么这将产生无限递归。

错误代码

idpiframe_initialization_failed: 未能从 Google 初始化所需的 iframe，例如，由于不受支持的 iframe 环境details 属性将提供有关所引发错误的更多信息。

gapi.auth2.ClientConfig

代表 gapi.auth2.init 方法。

参数
`client_id`	`string`	必需。应用的客户端 ID，可在 Google API 控制台中找到并创建。
`cookie_policy`	`string`	要为其创建登录 Cookie 的网域。URI、 `single_host_origin` 或 `none`。默认值为 `single_host_origin`（如果未指定）。
`scope`	`string`	要请求的范围，以空格分隔的字符串形式。可选，如果 `fetch_basic_profile` 未设置为 false。
`fetch_basic_profile`	`boolean`	提取用户的基本个人资料信息。添加“个人资料”和“电子邮件”和 'openid'所请求的范围如果未指定，则为 true。
`hosted_domain`	`string`	用户必须属于的 G Suite 网域。这个容易受到客户修改，因此请务必验证所返回用户的托管域属性。使用 GoogleUser.getHostedDomain() 在以及客户端上 ID 令牌中的 `hd` 声明，以验证该网域是否符合您的预期。 <ph type="x-smartling-placeholder"> </ph> 在将此参数与此参数一起使用时，必须请求 `'email'` 范围 `fetch_basic_profile: false`。
`use_fedcm`	`boolean`	可选，默认为 `True`。启用或停用登录期间的浏览器 FedCM API。
`ux_mode`	`string`	用于登录流程的用户体验模式。默认情况下，此操作将打开意见征求流程。有效值为 `popup` 和 `redirect`。
`redirect_uri`	`string`	如果使用 `ux_mode='redirect'`，则此参数可让您替换默认的 `redirect_uri`，将在意见征求流程结束时使用。通过默认 `redirect_uri` 是去除了查询参数和哈希值的当前网址 fragment。
`enable_granular_consent`	`boolean`	可选。是否启用权限。如果设置为 `false`，则 Google 将停用之前创建的 OAuth 客户端 ID 的账号权限 2019 年。对 2019 年或之后创建的 OAuth 客户端 ID 没有影响，因为系统始终会为它们启用更精细的权限
`plugin_name`	`string`	可选。如果设置了此值，则使用 7 月之前创建的新客户端 ID 2022 年 29 月 29 日起，您可以使用旧版 Google 平台库。默认情况下，系统现在禁止新创建的客户端 ID 使用必须改用新版 Google Identity 服务库。您可以选择任意值、描述性名称，如建议使用产品或插件名称进行标识。示例：`plugin_name: 'YOUR_STRING_HERE'`

身份验证

GoogleAuth 是一个单例类，它提供的方法可让用户使用 Google 账号登录、获取用户的当前登录状态、从用户的 Google 个人资料中获取特定数据、请求额外的作用域，以及退出当前账号。

gapi.auth2.getAuthInstance()

返回 GoogleAuth 对象。在调用此方法之前，您必须使用 gapi.auth2.init() 初始化 GoogleAuth 对象。

返回
`gapi.auth2.GoogleAuth`	`gapi.auth2.GoogleAuth` 对象。使用此对象调用 `gapi.auth2.GoogleAuth` 的方法。

GoogleAuth.isSignedIn.get()

返回当前用户是否已登录。

返回
布尔值	`true`如果用户已登录，`false` 用户已退出账号或 `GoogleAuth` 对象未。

GoogleAuth.isSignedIn.listen(listener)

监听当前用户登录状态的变化。

参数
`listener`	一个采用布尔值的函数。`listen()` 张卡券 `true` 传递给此函数；以及 `false`。

GoogleAuth.signIn()

使用为 gapi.auth2.init() 指定的选项让用户登录。

返回
Promise	由 `GoogleUser` 实例完成的 `Promise` 用户成功进行身份验证并授予请求的范围，或通过对象拒绝了身份验证在发生错误时包含 `error` 属性。请参阅以了解错误代码。

错误代码

请参阅 GoogleAuth.signIn(options)。

GoogleAuth.signIn(`options`)

使用指定选项让用户登录。

参数

参数
`options`	是以下任一情况：一个 `gapi.auth2.SignInOptions` 对象包含登录参数的键值对。例如： { scope: 'profile email' } `gapi.auth2.SigninOptionsBuilder` 的实例。对于示例： options = new gapi.auth2.SigninOptionsBuilder(); options.setAppPackageName('com.example.app'); options.setFetchBasicProfile(True); options.setPrompt('select_account'); options.setScope('profile').setScope('email');

options

是以下任一情况：

一个 gapi.auth2.SignInOptions 对象包含登录参数的键值对。例如：
```
{
  scope: 'profile email'
}
```

gapi.auth2.SigninOptionsBuilder 的实例。对于示例：

options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');

返回
Promise	由 `GoogleUser` 实例完成的 `Promise` 用户成功进行身份验证并授予请求的范围，或通过对象拒绝了身份验证如果出现错误，则包含 `error` 属性（请参阅下文，了解错误代码）。

错误代码

popup_closed_by_user: 用户在完成登录流程之前关闭了弹出式窗口。
access_denied: 用户拒绝授予所需范围的权限。
immediate_failed: 在未提示意见征求流程的情况下，系统无法自动选择用户。发生错误将 signIn 与 prompt: 'none' 选项搭配使用。此选项不应因为如果使用 gapi.auth2.init，曾在上一个会话中登录过。

gapi.auth2.SignInOptions

代表 GoogleAuth.signIn(options) 方法结合使用。

参数
`prompt`	`string`	为意见征求流程强制采用特定模式。可选。可能的值包括： <ph type="x-smartling-placeholder"> </ph> `consent` 授权服务器在返回之前提示用户同意将信息提供给应用 `select_account` 授权服务器提示用户选择 Google 账号。这个可让拥有多个账号的用户在多个账号中进行选择当前可能进行过的会话 `none`（不建议）授权服务器不会显示任何身份验证信息或用户意见征求结果屏幕；如果用户尚未通过身份验证，之前未同意请求的范围。由于 `gapi.auth2.init` 会自动将用户登录到（如果之前已登录），调用 `signIn({prompt: 'none'})` 通常会失败。
`scope`	`string`	要请求的范围，为以空格分隔的字符串，位于 `gapi.auth2.init` 参数。如果未设置 `fetch_basic_profile`，则为可选 false。
`ux_mode`	`string`	用于登录流程的用户体验模式。默认情况下，此操作将打开意见征求流程。有效值为 `popup` 和 `redirect`。
`redirect_uri`	`string`	如果使用 `ux_mode='redirect'`，您可以通过此参数替换将在意见征求结束时使用的默认 `redirect_uri` 。默认 `redirect_uri` 是系统从查询中删除的当前网址参数和哈希代码段。

GoogleAuth.signOut()

从应用中退出当前账号。

返回
Promise	用户登录执行时执行的 `Promise` 。

GoogleAuth.disconnect()

撤消用户授予的所有范围。

GoogleAuth.grantOfflineAccess(`options`)

向用户获取离线访问指定范围的权限。

参数
`options`	`gapi.auth2.OfflineAccessOptions` 包含参数键值对的对象。例如： { scope: 'profile email' }

返回
Promise	一个 `Promise`，当用户将请求的范围，并将包含授权代码的对象传递到 `Promise` 的执行方式处理程序。例如： auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; });

错误代码

popup_closed_by_user: 用户在完成意见征求流程之前关闭了弹出式窗口。
access_denied: 用户拒绝授予所需范围的权限。
immediate_failed: 在未提示意见征求流程的情况下，系统无法自动选择用户。发生错误将 signIn 与 prompt: 'none' 选项搭配使用。此选项不应因为如果使用 gapi.auth2.init，曾在上一个会话中登录过。

gapi.auth2.OfflineAccessOptions

代表 GoogleAuth.grantOfflineAccess(options) 方法。

参数
`prompt`	`string`	为意见征求流程强制采用特定模式。可选。可能的值包括： <ph type="x-smartling-placeholder"> </ph> `consent` 授权服务器在返回之前提示用户同意将信息提供给应用 `select_account` 授权服务器提示用户选择 Google 账号。这个可让拥有多个账号的用户在多个账号中进行选择当前可能进行过的会话。 <ph type="x-smartling-placeholder"> </ph> 请注意，`none` 不适用于离线代码流程。
`scope`	`string`	要请求的范围，为以空格分隔的字符串，位于 `gapi.auth2.init` 参数。如果未设置 `fetch_basic_profile`，则为可选 false。

GoogleAuth.attachClickHandler(`container`、`options`、`onsuccess`、`onfailure`)

将登录流程附加到指定容器的点击处理程序。

参数
`container`	要应用到的 `div` 元素的 ID 或对它的引用附加点击处理程序。
`options`	包含参数键值对的对象。请参阅 GoogleAuth.signIn().
`onsuccess`	登录完成后要调用的函数。
`onfailure`	要在登录失败时调用的函数。

用户

GoogleUser 对象表示一个用户账号。 GoogleUser 对象通常通过调用 GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

返回 GoogleUser 对象来代表当前用户请注意，在新初始化的 GoogleAuth 实例，则尚未设置当前用户。使用 currentUser.listen() 方法或 GoogleAuth.then() 以获取初始化的 GoogleAuth 实例。

返回
`GoogleUser`	当前用户

GoogleAuth.currentUser.listen(`listener`)

监听 currentUser 中的更改。

参数
`listener`	一个采用 `GoogleUser` 参数的函数。 `listen` 会向此函数传递 `GoogleUser` 实例。`currentUser`

GoogleUser.getId()

获取用户的唯一 ID 字符串。

不要使用由 getId()，用于将已登录的用户传达给您的后端服务器。而是发送 ID 令牌，可在服务器上安全地验证。

返回
字符串	用户的唯一 ID

GoogleUser.isSignedIn()

如果用户已登录，则返回 true。

返回
布尔值	如果用户已登录，则为 True

GoogleUser.getHostedDomain()

获取用户的 G Suite 域名（如果用户使用 G Suite 账号登录）。

返回
字符串	用户的 G Suite 网域

GoogleUser.getGrantedScopes()

以空格分隔的字符串形式获取用户授予的范围。

返回
字符串	用户授予的范围

GoogleUser.getBasicProfile()

获取用户的个人资料基本信息。

返回
`gapi.auth2.BasicProfile`	您可以检索 `gapi.auth2.BasicProfile` 的属性替换为： <ph type="x-smartling-placeholder"> </ph> BasicProfile.getId() BasicProfile.getName() BasicProfile.getGivenName() BasicProfile.getFamilyName() BasicProfile.getImageUrl() BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

从用户的身份验证会话中获取响应对象。

参数
`includeAuthorizationData`	可选：一个布尔值，用于指定是否始终返回访问令牌范围。默认情况下，在以下情况下不会返回访问令牌和请求的范围： `fetch_basic_profile` 为 true（默认值），且没有额外的范围请求。

返回
`gapi.auth2.AuthResponse`	`gapi.auth2.AuthResponse` 对象。

GoogleUser.reloadAuthResponse()

强制刷新访问令牌，然后针对新的 AuthResponse 返回 Promise。

返回
`Promise`	已执行且已重新加载的 `Promise` `gapi.auth2.AuthResponse`（重新加载完成 OAuth 令牌操作。

gapi.auth2.AuthResponse

调用时返回的响应 GoogleUser.getAuthResponse(includeAuthorizationData) 或 GoogleUser.reloadAuthResponse() 方法。

属性
`access_token`	`string`	已授予的访问令牌。
`id_token`	`string`	授予的 ID 令牌。
`scope`	`string`	在访问令牌中授予的范围。
`expires_in`	`number`	访问令牌到期前经过的秒数。
`first_issued_at`	`number`	用户首次授予所请求范围的时间戳。
`expires_at`	`number`	访问令牌到期的时间戳。

GoogleUser.hasGrantedScopes(`scopes`)

如果用户授予了指定范围，则返回 true。

参数
`scopes`	范围字符串（用空格分隔）。

返回
布尔值	如果范围已授予，则为 true

GoogleUser.grant(`options`)

向用户请求其他范围。

请参阅 GoogleAuth.signIn()，获取以下列表：参数和错误代码。

GoogleUser.grantOfflineAccess(`options`)

向用户获取离线访问指定范围的权限。

参数
`options`	`gapi.auth2.OfflineAccessOptions` 包含参数键值对的对象。例如： { scope: 'profile email' }

GoogleUser.disconnect()

撤消用户为应用授予的所有范围。

界面元素

gapi.signin2.render(`id`, `options`)

使用 options 对象指定的设置。

参数

id 要在其中呈现登录按钮的元素的 ID。

options

一个对象，包含用于呈现按钮的设置。例如：

{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}

您可以指定以下选项：

参数
范围	用户登录时请求的范围（默认值： `profile`）。
width	按钮的宽度，以像素为单位（默认值：`120`）。
高度	按钮的高度，以像素为单位（默认值：`36`）。
长标题	显示较长的标签，如“使用 Google 账号登录”而非 “登录”（默认值：`false`）。使用长标题时您应增加按钮的默认值。
主题	按钮的颜色主题：`light` 或 `dark`（默认值：`light`）。
onsuccess	用户成功登录时调用的回调函数。该函数必须接受一个参数： `gapi.auth2.GoogleUser`（默认值：无）。
失败	要在登录失败时调用的回调函数。此函数不带任何参数（默认：无）。

高级

gapi.auth2.authorize(`params`, `callback`)

执行一次性的 OAuth 2.0 授权。根据所使用的参数，此操作将打开一个弹出到 Google 登录流程，或尝试在不发生用户互动的情况下静默加载请求的响应。

此方法适用的一些用例包括：

例如，您的应用只需请求一次 Google API 端点收藏的 YouTube 视频。
您的应用有自己的会话管理基础架构，并且只需要 ID 令牌一次，用于在后端识别用户。
同一个网页中使用多个客户端 ID。

。 <ph type="x-smartling-placeholder">

</ph> 警告：请勿将此方法与建议的参数一起使用， gapi.auth2.init 和 signIn 流。这是两种不同的行为（gapi.auth2.authorize 授权与针对 gapi.auth2.init/signIn 的身份验证），如果使用，会出现意外问题应用场景

参数
`params`	包含配置数据键值对的对象。请参阅 `gapi.auth2.AuthorizeConfig`：即可配置不同的属性例如： { client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' }
`callback`	使用 `gapi.auth2.AuthorizeResponse` 个对象在请求完成后（成功或失败）。

示例

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

错误代码

idpiframe_initialization_failed: 未能从 Google 初始化所需的 iframe，例如，由于不受支持的 iframe 环境details 属性将详细说明引发的错误。
popup_closed_by_user: 用户在完成登录流程之前关闭了弹出式窗口。
access_denied: 用户拒绝授予所需范围的权限。
immediate_failed: 在未提示意见征求流程的情况下，系统无法自动选择用户。发生错误将 signIn 与 prompt: 'none' 选项搭配使用。

gapi.auth2.AuthorizeConfig

代表 gapi.auth2.authorize 方法结合使用。

属性
`client_id`	`string`	必需。应用的客户端 ID，可在 Google API 控制台中找到并创建。
`scope`	`string`	必需。要请求的范围，以空格分隔的字符串形式。
`response_type`	`string`	以空格分隔的响应类型列表。默认为 `'permission'`。可能出现的值为： <ph type="x-smartling-placeholder"> </ph> `id_token`，用于检索 ID 令牌 `permission`（或 `token`），用于检索访问令牌 `code`，用于检索授权代码
`prompt`	`string`	为意见征求流程强制采用特定模式。可能的值包括： <ph type="x-smartling-placeholder"> </ph> `consent` 授权服务器在返回之前提示用户同意将信息提供给应用 `select_account` 授权服务器提示用户选择 Google 账号。这个可让拥有多个账号的用户在多个账号中进行选择当前可能进行过的会话 `none` 授权服务器不会显示任何身份验证信息或用户意见征求结果屏幕；如果用户尚未通过身份验证，之前未同意请求的范围。如果请求 `code` 作为响应类型，则返回的代码将只有可交换为 `access_token`，而非 `refresh_token`。 <ph type="x-smartling-placeholder"> </ph> 注意：从本质上讲，该库会缓存并自动刷新已获取访问令牌。使用 `prompt: 'none'` 时，大多数情况下没有 HTTP 必须向后端发送请求，才能获取有效令牌。
`cookie_policy`	`string`	要为其创建登录 Cookie 的网域。URI、 `single_host_origin` 或 `none`。默认值为 `single_host_origin`（如果未指定）。
`hosted_domain`	`string`	用户必须属于的 G Suite 网域。这很容易被修改因此请务必验证返回用户的托管域属性。
`login_hint`	`string`	要在登录流程中预先选择的用户的电子邮件或用户 ID。容易受到用户修改的内容（除非使用 `prompt: "none"`）。
`include_granted_scopes`	`boolean`	是否请求包含用户之前授予的所有范围的访问令牌或者仅在当前调用中请求的范围。默认值为 `true`。
`enable_granular_consent`	`boolean`	可选。是否启用权限。如果设置为 `false`，则 Google 将停用之前创建的 OAuth 客户端 ID 的账号权限 2019 年。对 2019 年或之后创建的 OAuth 客户端 ID 没有影响，因为系统始终会为它们启用更精细的权限
`plugin_name`	`string`	可选。如果已设置，则在 2022 年 7 月 29 日之前创建的客户端 ID 可以使用 Google 平台库。默认情况下，新创建的客户端 ID 处于屏蔽状态使用平台库，而必须使用较新的 Identity Services 库。您可以选择任意值、描述性名称（例如产品或插件名称），以方便识别。示例：`plugin_name: 'YOUR_STRING_HERE'`

gapi.auth2.AuthorizeResponse

返回给回调的 gapi.auth2.authorize 方法结合使用。

属性
`access_token`	`string`	已授予的访问令牌。仅当 `permission` 或 `token` 时才存在在 `response_type` 中指定。
`id_token`	`string`	授予的 ID 令牌。仅当在`id_token` `response_type`。
`code`	`string`	已授予的授权代码。仅当在`code` `response_type`。
`scope`	`string`	在访问令牌中授予的范围。仅当 `permission` 或在 `response_type` 中指定了 `token`。
`expires_in`	`number`	访问令牌到期前经过的秒数。仅当 `permission` 时才显示或 `token` 在 `response_type` 中指定。
`first_issued_at`	`number`	用户首次授予所请求范围的时间戳。仅当在 `response_type` 中指定了 `permission` 或 `token`。
`expires_at`	`number`	访问令牌到期的时间戳。仅当 `permission` 时才显示或 `token` 在 `response_type` 中指定。
`error`	`string`	如果请求失败，则包含错误代码。
`error_subtype`	`string`	当请求失败时，此字段可能还会包含错误代码的其他信息返回。

Google 登录 JavaScript 客户端参考文档

身份验证设置

gapi.auth2.init(params)

GoogleAuth.then(onInit、onError)

错误代码

gapi.auth2.ClientConfig

身份验证

gapi.auth2.getAuthInstance()

GoogleAuth.isSignedIn.get()

GoogleAuth.isSignedIn.listen(listener)

GoogleAuth.signIn()

错误代码

GoogleAuth.signIn(options)

错误代码

gapi.auth2.SignInOptions

GoogleAuth.signOut()

GoogleAuth.disconnect()

GoogleAuth.grantOfflineAccess(options)

错误代码

gapi.auth2.OfflineAccessOptions

GoogleAuth.attachClickHandler(container、options、onsuccess、onfailure)

用户

GoogleAuth.currentUser.get()

GoogleAuth.currentUser.listen(listener)

GoogleUser.getId()

GoogleUser.isSignedIn()

GoogleUser.getHostedDomain()

GoogleUser.getGrantedScopes()

GoogleUser.getBasicProfile()

GoogleUser.getAuthResponse(includeAuthorizationData)

GoogleUser.reloadAuthResponse()

gapi.auth2.AuthResponse

GoogleUser.hasGrantedScopes(scopes)

GoogleUser.grant(options)

GoogleUser.grantOfflineAccess(options)

GoogleUser.disconnect()

界面元素

gapi.signin2.render(id, options)

高级

gapi.auth2.authorize(params, callback)

示例

错误代码

gapi.auth2.AuthorizeConfig

gapi.auth2.AuthorizeResponse

gapi.auth2.init(`params`)

GoogleAuth.then(`onInit`、`onError`)

GoogleAuth.signIn(`options`)

GoogleAuth.grantOfflineAccess(`options`)

GoogleAuth.attachClickHandler(`container`、`options`、`onsuccess`、`onfailure`)

GoogleAuth.currentUser.listen(`listener`)

GoogleUser.hasGrantedScopes(`scopes`)

GoogleUser.grant(`options`)

GoogleUser.grantOfflineAccess(`options`)

gapi.signin2.render(`id`, `options`)

gapi.auth2.authorize(`params`, `callback`)