Google 登入 JavaScript 用戶端參考資源

本參考資料說明用來在網頁應用程式中導入 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 物件會還原使用者在上一個工作階段的登入狀態。

{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}

GoogleAuth.then(onInit, onError)

在 GoogleAuth 物件完全初始化時呼叫 onInit 函式。如果在初始化時引發錯誤 (這個問題可能會在舊版瀏覽器中發生)，系統會改為呼叫 onError 函式。

錯誤代碼

idpiframe_initialization_failed

舉例來說，由於環境不受支援，系統無法從 Google 初始化必要的 iframe。details 屬性會針對引發的錯誤提供更多資訊。

gapi.auth2.ClientConfig

代表 gapi.auth2.init 方法不同設定參數的介面。

驗證

GoogleAuth 是一種單例模式類別，可選擇讓使用者以 Google 帳戶登入、取得使用者目前的登入狀態、從使用者的 Google 個人資料取得特定資料、要求其他範圍，以及登出目前的帳戶。

gapi.auth2.getAuthInstance()

傳回 GoogleAuth 物件。您必須先使用 gapi.auth2.init() 初始化 GoogleAuth 物件，才能呼叫此方法。

GoogleAuth.isSignedIn.get()

傳回目前使用者是否已登入。

GoogleAuth.isSignedIn.listen(listener)

監聽目前使用者登入狀態的變更。

GoogleAuth.signIn()

以 gapi.auth2.init() 指定的選項登入使用者。

錯誤代碼

查看《GoogleAuth.signIn(options)》。

GoogleAuth.signIn(options)

使用指定選項登入使用者。

錯誤代碼

popup_closed_by_user

使用者在完成登入流程前關閉彈出式視窗。

access_denied

使用者拒絕授予所需範圍的權限。

immediate_failed

必須提示同意流程才能自動選取使用者。將 signIn 與 prompt: 'none' 選項搭配使用時引發錯誤。不需要使用這個選項，因為 gapi.auth2.init 會在先前在上一個工作階段登入的使用者自動登入。

gapi.auth2.SignInOptions

代表 GoogleAuth.signIn(options) 方法不同設定參數的介面。

GoogleAuth.signOut()

從應用程式登出目前的帳戶。

GoogleAuth.disconnect()

撤銷使用者授予的所有範圍。

GoogleAuth.grantOfflineAccess(options)

必須取得使用者的許可，才能離線存取指定範圍。

{
  scope: 'profile email'
}

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) 方法不同設定參數的介面。

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

將登入流程附加至指定容器的點擊處理常式。

使用者

GoogleUser 物件代表一個使用者帳戶，GoogleUser 物件通常透過呼叫 GoogleAuth.currentUser.get() 取得。

GoogleAuth.currentUser.get()

傳回代表目前使用者的 GoogleUser 物件。請注意，在新初始化的 GoogleAuth 執行個體中，尚未設定目前的使用者。請使用 currentUser.listen() 方法或 GoogleAuth.then() 取得初始化的 GoogleAuth 執行個體。

GoogleAuth.currentUser.listen(listener)

監聽 currentUser 中的變更。

GoogleUser.getId()

取得使用者的專屬 ID 字串。

GoogleUser.isSignedIn()

如果使用者已登入，則傳回 true。

GoogleUser.getHostDomain()

取得使用者的 G Suite 網域 (如果使用者是透過 G Suite 帳戶登入)。

GoogleUser.getGrantedScopes()

取得使用者以空格分隔字串的形式授予的範圍。

GoogleUser.getBasicProfile()

取得使用者的基本個人資料。

GoogleUser.getAuthResponse(includeAuthorizationData)

從使用者的驗證工作階段取得回應物件。

GoogleUser.reloadAuthResponse()

強制重新整理存取權杖，然後傳回新 AuthResponse 的 Promise。

gapi.auth2.AuthResponse

呼叫 GoogleUser.getAuthResponse(includeAuthorizationData) 或 GoogleUser.reloadAuthResponse() 方法時傳回的回應。

GoogleUser.hasGrantedScopes(scopes)

如果使用者授予指定範圍，則傳回 true。

GoogleUser.grant(options)

向使用者要求其他範圍。

如需參數清單和錯誤代碼，請參閱 GoogleAuth.signIn()。

GoogleUser.grantOfflineAccess(options)

必須取得使用者的許可，才能離線存取指定範圍。

{
  scope: 'profile email'
}

GoogleUser.disconnect()

撤銷使用者為應用程式授予的所有範圍。

UI 元素

gapi.signin2.render(id, options)

使用 options 物件指定的設定，在具有指定 ID 的元素中轉譯登入按鈕。

{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}

進階

gapi.auth2.authorized(params, callback)

執行一次性 OAuth 2.0 授權。視使用的參數而定，這會開啟 Google 登入流程彈出式視窗，或嘗試以無訊息方式載入要求的回應，使用者無須進行互動。

此方法很實用的部分用途包括：

• 應用程式只需要要求 Google API 端點一次，例如在使用者首次登入時載入使用者喜愛的 YouTube 影片。
• 應用程式擁有自己的工作階段管理基礎架構，且只需要 ID 權杖一次就能識別後端中的使用者。
• 同一個頁面中會使用多個用戶端 ID。

{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}

範例

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 方法不同設定參數的介面。

gapi.auth2.AuthorizeResponse

系統傳回 gapi.auth2.authorize 方法回呼的回應。