Google 登录 JavaScript 客户端参考文档

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

本参考文档介绍了 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(onInitonError)

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

参数
onInit 完全使用 GoogleAuth 对象调用的函数 。
onError 使用包含 error 属性的对象调用的函数。 如果 GoogleAuth 未能初始化,则会发生该错误。
返回
Promise onInit 时执行的 Promise 函数已经完成,如果引发初始化错误,则会被拒绝。它通过 onInit 函数返回的值(如果有)。
<ph type="x-smartling-placeholder">

错误代码

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_originnone。默认值为 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">
use_fedcm boolean 可选,默认为 True。启用或停用 登录期间的浏览器 FedCM API。
ux_mode string 用于登录流程的用户体验模式。默认情况下,此操作将打开意见征求流程 。有效值为 popupredirect
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');
返回
Promise GoogleUser 实例完成的 Promise 用户成功进行身份验证并授予请求的范围,或通过对象拒绝了身份验证 如果出现错误,则包含 error 属性(请参阅下文,了解错误代码)。

错误代码

popup_closed_by_user
用户在完成登录流程之前关闭了弹出式窗口。
access_denied
用户拒绝授予所需范围的权限。
immediate_failed
在未提示意见征求流程的情况下,系统无法自动选择用户。发生错误 将 signInprompt: '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 用于登录流程的用户体验模式。默认情况下,此操作将打开意见征求流程 。有效值为 popupredirect
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
在未提示意见征求流程的情况下,系统无法自动选择用户。发生错误 将 signInprompt: '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">
scope string 要请求的范围,为以空格分隔的字符串,位于 gapi.auth2.init 参数。如果未设置 fetch_basic_profile,则为可选 false。

GoogleAuth.attachClickHandler(containeroptionsonsuccessonfailure)

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

参数
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 字符串。

返回
字符串 用户的唯一 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)。使用长标题时 您应增加按钮的默认值。
主题 按钮的颜色主题:lightdark(默认值:light)。
onsuccess 用户成功登录时调用的回调函数。 该函数必须接受一个参数: gapi.auth2.GoogleUser(默认值:无)。
失败 要在登录失败时调用的回调函数。此函数 不带任何参数(默认:无)。

高级

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

gapi.auth2.authorize(params, callback)

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

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

  • 例如,您的应用只需请求一次 Google API 端点 收藏的 YouTube 视频。
  • 您的应用有自己的会话管理基础架构,并且只需要 ID 令牌一次,用于在后端识别用户。
  • 同一个网页中使用多个客户端 ID。
。 <ph type="x-smartling-placeholder">
参数
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
在未提示意见征求流程的情况下,系统无法自动选择用户。发生错误 将 signInprompt: '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">
cookie_policy string 要为其创建登录 Cookie 的网域。URI、 single_host_originnone。默认值为 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 已授予的访问令牌。仅当 permissiontoken 时才存在 在 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 时才显示 或 tokenresponse_type 中指定。
first_issued_at number 用户首次授予所请求范围的时间戳。仅当 在 response_type 中指定了 permissiontoken
expires_at number 访问令牌到期的时间戳。仅当 permission 时才显示 或 tokenresponse_type 中指定。
error string 如果请求失败,则包含 错误代码
error_subtype string 当请求失败时,此字段可能还会包含错误代码的其他信息 返回。