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 必需。应用的客户端 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 在用户登录时提取其基本个人资料信息。将“profile”“email”和“openid”添加到请求的作用域。如果未指定，则为 true。
hosted_domain string 用户必须属于的 G Suite 网域才能登录。此属性很容易被客户端修改，因此请务必验证返回用户的托管网域属性。在客户端上使用 GoogleUser.getHostedDomain()，并在服务器上使用 ID 令牌中的 hd 声明，以验证域名是否符合您的预期。
use_fedcm boolean 可选，默认值为 True。在登录过程中启用或停用浏览器 FedCM API。
ux_mode string 要用于登录流程的用户体验模式。默认情况下，它会在弹出式窗口中打开意见征求流程。有效值为 popup 和 redirect。
redirect_uri string 如果使用 ux_mode='redirect'，则此参数可让您替换将在意见征求流程结束时使用的默认 redirect_uri。默认 redirect_uri 是去除了查询参数和哈希片段的当前网址。
enable_granular_consent boolean 可选。是否启用精细权限。如果设置为 false，系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 账号权限。对 2019 年或之后创建的 OAuth 客户端 ID 没有影响，因为系统始终为这些客户端 ID 启用更精细的权限。
plugin_name string 可选。如果设置了此值，则 2022 年 7 月 29 日之前创建的新客户端 ID 可以使用旧版 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；如果用户已退出登录或 GoogleAuth 对象未初始化，则为 false。

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');
返回
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 要将点击处理脚本附加到的 div 元素的 ID 或引用。
options 包含参数键值对的对象。请参阅 GoogleAuth.signIn()。
onsuccess 登录完成后要调用的函数。
onfailure 在登录失败时调用的函数。

用户

GoogleUser 对象代表一个用户账号。通常，通过调用 GoogleAuth.currentUser.get() 可获取 GoogleUser 对象。

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）。
width 按钮的宽度（以像素为单位，默认为 120）。
高度 按钮的高度（以像素为单位，默认为 36）。
longtitle 显示长标签（例如“使用 Google 账号登录”），而不是“登录”（默认：false）。使用长标题时，您应将按钮的宽度从默认值增加。
主题 按钮的颜色主题：light 或 dark（默认值：light）。
onsuccess 在用户成功登录时调用的回调函数。 此函数必须接受一个参数：gapi.auth2.GoogleUser 的实例（默认值：无）。
失败 要在登录失败时调用的回调函数。此函数不接受任何参数（默认：无）。

高级

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 必需。应用的客户端 ID，可在 Google API 控制台中查找和创建。
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。
enable_granular_consent boolean 可选。是否启用精细权限。如果设置为 false，系统将针对 2019 年之前创建的 OAuth 客户端 ID 停用更细化的 Google 账号权限。对 2019 年或之后创建的 OAuth 客户端 ID 没有影响，因为系统始终为这些客户端 ID 启用更精细的权限。
plugin_name string 可选。如果已设置，则在 2022 年 7 月 29 日之前创建的客户端 ID 可以使用 Google 平台库。默认情况下，新创建的客户端 ID 将被禁止使用平台库，而必须使用较新的 Google Identity 服务库。您可以选择任何值，建议选择描述性名称（例如产品或插件名称），以便于轻松识别。 示例：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 请求失败时，此字段可能会包含与返回的错误代码相关的其他信息。