我們停止了谷歌登錄在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授權。根據使用的參數,這將打開Google登錄流程的彈出窗口,或嘗試以靜默方式加載請求的響應,而無需用戶進行交互。

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

  • 您的應用程序只需要請求一次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當請求失敗時,它可以包含其他信息,也可以返回錯誤代碼。