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.grant 離線版 Access(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.離線存取權選項

這個介面代表 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)

監聽目前使用者異動。

GoogleUser.getId()

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

GoogleUser.isSignedIn()

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

GoogleUser.getHostedDomain()

如果使用者是透過 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.grant 離線版 Access(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.authorization(params, callback)

執行一次 OAuth 2.0 授權。視使用的參數而定，這會開啟 Google 登入流程的彈出式視窗，或嘗試在無互動的情況下以靜音方式載入要求的回應。

這個方法的優點包括：

• 您的應用程式只需要求 Google API 端點一次，例如，當使用者第一次登入時，就能載入使用者最愛的 YouTube 影片。
• 您的應用程式有自己的工作階段管理基礎架構，而且只需要使用 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.AuthorizationConfig

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

gapi.auth2.AuthorizationResponse

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