我们停止了谷歌登录在JavaScript平台的图书馆网络。对于认证和用户登录,使用新的谷歌身份服务的SDK两种网络Android的替代。

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配置的不同属性,请参见gapi.auth2.ClientConfig 。例如:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
退货
gapi.auth2.GoogleAuth gapi.auth2.GoogleAuth对象。使用then()方法来获取Promise,该Promise将在gapi.auth2.GoogleAuth对象完成初始化之后得到解决。

GoogleAuth.then( onInitonError

GoogleAuth对象完全初始化后,调用onInit函数。如果在初始化时引发错误(这可能在旧的不受支持的浏览器中发生),则将调用onError函数。

争论
onInit完全初始化后,使用GoogleAuth对象调用的函数。
onError如果GoogleAuth初始化失败,则该函数使用包含error属性的对象进行调用。
退货
承诺一个Promise ,当被满足onInit功能已经完成,如果有人提出一个初始化错误而被拒绝。它使用onInit函数的返回值(如果有)进行解析。

错误代码

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

gapi.auth2.ClientConfig

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

参数
client_id string必需的。在Google Developers Console中找到并创建的应用的客户端ID。
cookie_policy string要为其创建登录Cookie的域。可以是URI, single_host_originnone 。如果未指定,则默认为single_host_origin
scope string请求的范围,以空格分隔的字符串。如果未将fetch_basic_profile设置为false, fetch_basic_profile可选。
fetch_basic_profile boolean登录时获取用户的基本个人资料信息。将“个人资料”,“电子邮件”和“ openid”添加到请求的范围。如果未指定,则为true。
hosted_domain string用户必须属于的G Suite域才能登录。客户端可能会对其进行修改,因此请确保验证返回用户的托管域属性。在客户端上使用GoogleUser.getHostedDomain() ,并在服务器上的ID令牌中使用hd声明,以验证该域是否符合您的期望。
ux_mode string用于登录流程的UX模式。默认情况下,它将在弹出窗口中打开同意流。有效值为popupredirect
redirect_uri string如果使用ux_mode='redirect' ,则此参数允许您覆盖将在同意流程结束时使用的默认redirect_uri 。默认的redirect_uri是去除了查询参数和哈希片段的当前URL。

验证

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()指定的选项gapi.auth2.init()用户。

退货
承诺用户成功进行身份验证并授予请求的范围时, GoogleUser实例会实现的Promise ,如果发生error则使用包含error属性的对象拒绝该Promise (有关错误代码,请参见下文)。

错误码

请参阅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');
退货
承诺用户成功进行身份验证并授予请求的范围时, GoogleUser实例会实现的Promise ,如果发生error则使用包含error属性的对象拒绝该Promise (有关错误代码,请参见下文)。

错误码

popup_closed_by_user
用户在完成登录流程之前关闭了弹出窗口。
access_denied
用户拒绝了对所需范围的许可。
immediate_failed
在不提示同意流程的情况下,无法自动选择任何用户。使用带prompt: 'none' 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 stringgapi.auth2.init参数中定义的范围之外,以空格分隔的字符串请求的范围。如果fetch_basic_profile未设置为false, fetch_basic_profile可选。
ux_mode string用于登录流程的UX模式。默认情况下,它将在弹出窗口中打开同意流。有效值为popupredirect
redirect_uri string如果使用ux_mode='redirect' ,则此参数允许您覆盖将在同意流程结束时使用的默认redirect_uri 。默认的redirect_uri是去除了查询参数和哈希片段的当前URL。

GoogleAuth.signOut()

从应用程序中注销当前帐户。

退货
承诺用户注销后完成的Promise

GoogleAuth.disconnect()

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

GoogleAuth.grantOfflineAccess( options

获得用户的许可以脱机访问指定的作用域。

争论
options一个包含参数的键值对的gapi.auth2.OfflineAccessOptions对象。例如:
{
  scope: 'profile email'
}
退货
承诺Promise当用户授予所请求的范围,使含有所述授权码到一个对象,它被满足Promise的履行处理程序。例如:
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

错误代码

popup_closed_by_user
用户在完成同意流程之前关闭了弹出窗口。
access_denied
用户拒绝了对所需范围的许可。
immediate_failed
如果不提示同意流程,则不会自动选择任何用户。使用带prompt: 'none' signIn时出现错误prompt: 'none'选项。不需要使用此选项,因为如果在上一个会话期间先前登录,那么gapi.auth2.init将自动登录用户。

gapi.auth2.OfflineAccessOptions

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

参数
prompt string强制同意流的特定模式。可选的。
可能的值为:
  • consent
    授权服务器在将信息返回给应用程序之前提示用户同意。
  • select_account
    授权服务器提示用户选择一个Google帐户。这允许具有多个帐户的用户在他们可能具有当前会话的多个帐户中进行选择。
scope stringgapi.auth2.init参数中定义的范围之外,以空格分隔的字符串请求的范围。如果fetch_basic_profile未设置为false, fetch_basic_profile可选。

GoogleAuth.attachClickHandler( containeroptionsonsuccessonfailure

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

争论
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)

从用户的auth会话中获取响应对象。

争论
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用空格分隔的范围字符串。
退货
布尔型如果范围被授予则为真

GoogleUser.grant( options

向用户请求其他范围。

有关参数列表和错误代码,请参见GoogleAuth.signIn()

GoogleUser.grantOfflineAccess( options

获得用户的许可以脱机访问指定的作用域。

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

GoogleUser.disconnect()

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

UI元素

gapi.signin2.render( idoptions

使用options对象指定的设置,在具有给定ID的元素中呈现登录按钮。

争论
id呈现登录按钮的元素的ID。
options包含用于呈现按钮的设置的对象。例如:
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
您可以指定以下选项:
参数
范围用户登录时请求的范围(默认: profile )。
宽度按钮的宽度(以像素为单位)(默认值: 120 )。
高度按钮的高度(以像素为单位)(默认值: 36 )。
长标题显示长标签,例如“使用Google登录”,而不是“登录”(默认值: false )。使用长标题时,应从默认按钮的宽度开始增加其宽度。
主题按钮的颜色主题: lightdark (默认值: light )。
成功用户成功gapi.auth2.GoogleUser要调用的回调函数。此函数必须带有一个参数: gapi.auth2.GoogleUser的实例(默认值:无)。
失败登录失败时要调用的回调函数。此函数不带任何参数(默认值:无)。

先进的

gapi.auth2.authorize( paramscallback

执行一次OAuth 2.0授权。根据使用的参数,这将打开Goog​​le登录流程的弹出窗口,或尝试以静默方式加载请求的响应,而无需用户进行交互。

该方法有用的一些用例包括:

  • 您的应用程序只需要请求一次Google API终结点,例如,在用户首次登录时加载用户喜欢的YouTube视频。
  • 您的应用程序具有自己的会话管理基础结构,并且只需要一次ID令牌即可在后端识别用户。
  • 在同一页面中使用了多个客户端ID。
争论
params包含配置数据的键值对的对象。有关gapi.auth2.AuthorizeConfig配置的不同属性,请参见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
在不提示同意流程的情况下,无法自动选择任何用户。使用带prompt: 'none' signIn时出现错误prompt: 'none'选项。

gapi.auth2.AuthorizeConfig

表示gapi.auth2.authorize方法的不同配置参数的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_originnone 。如果未指定,则默认为single_host_origin
hosted_domain string用户必须属于的G Suite域才能登录。客户端可能会对其进行修改,因此请确保验证返回用户的托管域属性。
login_hint string要在登录流程中预先选择的用户的电子邮件或用户ID。除非出现prompt: "none" ,否则用户很容易对此进行修改。
include_granted_scopes boolean是请求访问令牌,它包括用户先前授予应用程序的所有范围,还是仅请求当前调用中请求的范围。默认为true

gapi.auth2.AuthorizeResponse

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

特性
access_token string授予的访问令牌。仅当在response_type中指定了permissiontoken时才存在。
id_token string授予的ID令牌。只有存在,如果id_token在指定response_type
code string授权码已授予。仅当在response_type中指定了code时才存在。
scope string访问令牌中授予的范围。仅当在response_type中指定了permissiontoken时才存在。
expires_in number直到访问令牌过期的秒数。仅当在response_type中指定了permissiontoken时才存在。
first_issued_at number用户首次授予所请求范围的时间戳。仅当在response_type中指定了permissiontoken时才存在。
expires_at number访问令牌到期的时间戳。仅当在response_type中指定了permissiontoken时才存在。
error string当请求失败时,其中包含错误代码
error_subtype string当请求失败时,它可以包含其他信息,也可以返回错误代码。