我们 即将停用适用于网页的 Google 登录 JavaScript 平台库。此库将于 2023 年 3 月 31 日弃用后停止下载。请改用新版网页版 Google Identity Services。
现在，系统会禁止新创建的客户端 ID 使用旧版平台库，现有的客户端 ID 不受影响。在 2022 年 7 月 29 日之前创建的新客户端 ID 可以设置 `plugin_name` 以允许使用 Google 平台库。

Google 登录 JavaScript 客户端参考文档

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

如果您在使用该库时遇到任何问题，请向我们的 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() 方法获取在 gapi.auth2.GoogleAuth 对象完成初始化后解析的 Promise。

GoogleAuth.then(onInit, onError)

在 GoogleAuth 对象完全初始化后，调用 onInit 函数。如果在初始化过程中引发了错误（这种情况可能会在不受支持的旧版浏览器中发生），则会调用 onError 函数。

参数
onInit 完全初始化时，使用 GoogleAuth 对象调用的函数。
onError 如果 GoogleAuth 初始化失败，则使用包含 error 属性的对象调用的函数。
返回值
Promise 在 onInit 函数完成时执行，或者在发生初始化错误时被拒的 Promise。它使用 onInit 函数返回的值进行解析（如果有）。

错误代码

idpiframe_initialization_failed
未能初始化来自 Google 的所需 iframe，例如，环境不受支持。details 属性会提供关于引发的错误的详细信息。

gapi.auth2.ClientConfig

表示 gapi.auth2.init 方法的不同配置参数的接口。

参数
client_id string 必需。在 Google Developers Console 中找到并创建的应用的客户端 ID。
cookie_policy string 要为其创建登录 Cookie 的网域。URI、single_host_origin 或 none。如果未指定，则默认为 single_host_origin。
scope string 要请求的范围（以空格分隔的字符串）。如果 fetch_basic_profile 未设置为 false，则该属性为可选属性。
fetch_basic_profile boolean 获取用户登录时的基本个人资料信息。将“profile”、“email”和“openid”添加到请求的范围内。如果未指定，则为 True。
hosted_domain string 用户必须登录的 G Suite 网域。这很容易被客户端修改，因此请务必验证返回用户的托管网域属性。使用 GoogleUser.getHostedDomain()在客户端上，以及hd验证 ID 令牌是否符合您的预期。
ux_mode string 用于登录流程的用户体验模式。默认情况下，它会在弹出式窗口中打开意见征求流程。有效值为 popup 和 redirect。
redirect_uri string 如果使用 ux_mode='redirect'，此参数可让您替换将在用户意见征求流程结束时使用的默认 redirect_uri。默认 redirect_uri 是去除查询参数和哈希代码段的当前网址。
plugin_name string 可选。如果您设置了此值，2022 年 7 月 29 日之前创建的新客户端 ID 就可以使用较旧的 Google 平台库。 默认情况下，新创建的客户端 ID 现在会被屏蔽，无法使用平台库，而必须使用较新的 Google Identity Services 库。您可以选择任何值，建议采用描述性名称，例如产品或插件名称。 示例：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 接受布尔值的函数。listen() 会在用户登录时向此函数传递 true，并在用户退出时传递 false。

GoogleAuth.signIn()

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

返回值
Promise 一个Promise该规则通过GoogleUser用户成功进行身份验证并授予所请求的范围，或者使用包含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');
返回值
Promise 一个Promise该规则通过GoogleUser用户成功进行身份验证并授予所请求的范围，或者使用包含error属性（参见下文中的错误代码）。

错误代码

popup_closed_by_user
用户在完成登录流程之前关闭了弹出式窗口。
access_denied
用户拒绝了对所需范围的权限。
immediate_failed
不提示用户，就无法自动选择用户。将 signIn 与 prompt: 'none' 选项搭配使用时引发的错误。该选项不应被使用，因为 gapi.auth2.init 会在之前会话中自动登录用户。

gapi.auth2.SignInOptions

表示 GoogleAuth.signIn(options) 方法的不同配置参数的接口。

参数
prompt string 对意见征求流程强制实施特定模式。可选。
可能的值包括：
  • 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 对意见征求流程强制实施特定模式。可选。
可能的值包括：
  • consent
    授权服务器会在将信息返回到应用之前提示用户。
  • select_account
    授权服务器会提示用户选择 Google 帐号。这样，拥有多个帐号的用户便可从他们可能拥有当前会话的多个帐号中选择。
scope string 要请求的范围（以空格分隔的字符串表示），在 gapi.auth2.init 参数中定义的范围之上。如果 fetch_basic_profile 未设置为 false，则该属性为可选属性。

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

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

参数
container ID 或对div附加点击处理程序的元素。
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 会在修改 currentUser 的每次更改时向该函数传递 GoogleUser 实例。

GoogleUser.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 的属性：
  • 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 在重新加载 OAuth 令牌时通过重新加载的 gapi.auth2.AuthResponse 实现的 Promise。

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 要在其中呈现登录按钮的元素 ID。
options 包含用于呈现该按钮的设置的对象。例如： 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
您可以指定以下选项：
参数
范围 用户登录时请求的范围（默认值：profile）。
宽度 按钮的宽度，以像素为单位（默认值：120）。
高度 按钮的高度，以像素为单位（默认值：36）。
长标题 显示长标签，例如“使用 Google 帐号登录”，而不是“登录”（默认：false）。使用长标题时，应将按钮的宽度增加到默认值。
主题 按钮的颜色主题：light 或 dark（默认值：light）。
onsuccess 在用户成功登录时调用的回调函数。 该函数必须接受一个参数：gapi.auth2.GoogleUser 的实例（默认值：none）。
onfailure 登录失败时调用的回调函数。此函数不接受任何参数（默认值：无）。

高级

gapi.auth2.Authorize（params、callback）

执行 OAuth 2.0 一次性授权。根据所使用的参数，这会打开 Google 登录流程的弹出式窗口，或尝试在不发出用户互动的情况下以静默方式加载请求的响应。

此方法很有用的一些用例包括：

  • 您的应用只需请求一次 Google API 端点，例如，在用户首次登录时加载他们喜爱的 YouTube 视频。
  • 您的应用有自己的会话管理基础架构，并且只需要使用一次 ID 令牌在后端识别用户。
  • 同一个网页中使用多个客户端 ID。
参数
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，例如，环境不受支持。details 属性会提供关于引发的错误的详细信息。
popup_closed_by_user
用户在完成登录流程之前关闭了弹出式窗口。
access_denied
用户拒绝了对所需范围的权限。
immediate_failed
不提示用户，就无法自动选择用户。将 signIn 与 prompt: 'none' 选项搭配使用时引发错误。

gapi.auth2.AuthorizeConfig

表示 gapi.auth2.authorize 方法的不同配置参数的接口。

属性
client_id string 必需。在 Google Developers Console 中找到并创建的应用的客户端 ID。
scope string 必需。要请求的范围（以空格分隔的字符串）。
response_type string 以空格分隔的响应列表。默认为 'permission'。可能的值包括：
  • id_token，用于检索 ID 令牌
  • permission（或 token），用于检索访问令牌
  • code，用于检索授权代码
prompt string 对意见征求流程强制实施特定模式。可能的值包括：
  • consent
    授权服务器会在将信息返回到应用之前提示用户。
  • select_account
    授权服务器会提示用户选择 Google 帐号。这样，拥有多个帐号的用户便可从他们可能拥有当前会话的多个帐号中选择。
  • none
    授权服务器不会显示任何身份验证或用户同意屏幕；如果用户尚未通过身份验证并且之前未同意所请求的范围，则会返回错误。
    如果请求 code 作为响应类型，则只能用 access_token 而不是 refresh_token 交换返回的代码。
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。
plugin_name string 可选。如果设置此参数，那么在 2022 年 7 月 29 日之前创建的客户端 ID 可以使用 Google 平台库。默认情况下，新创建的客户端 ID 将无法使用平台库，而必须使用较新的 Google 身份服务库。您可以选择任意值，建议采用描述性名称，例如产品或插件名称。 示例：plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

返回给 gapi.auth2.authorize 方法回调的响应。

属性
access_token string 已授予访问令牌。仅当在 response_type 中指定了 permission 或 token 时才存在。
id_token string 授予的 ID 令牌。仅当 response_type 中指定了 id_token 时才存在。
code string 已授权代码。仅当 response_type 中指定了 code 时才存在。
scope string 访问令牌中授予的范围。仅当在 response_type 中指定了 permission 或 token 时才存在。
expires_in number 距离访问令牌到期的秒数。仅当 response_type 中指定了 permission 或 token 时才存在。
first_issued_at number 用户首次授予请求的范围的时间戳。仅当在 response_type 中指定了 permission 或 token 时才存在。
expires_at number 访问令牌到期的时间戳。仅当 response_type 中指定了 permission 或 token 时才存在。
error string 请求失败时，此字段包含错误代码。
error_subtype string 请求失败时，其中可能包含对返回的错误代码的额外信息。