Google 登入 JavaScript 用戶端參考資料

本參考資料說明瞭您將的 JavaScript 用戶端方法和屬性 將 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 物件就會還原使用者在上一個工作階段中的登入狀態。

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

GoogleAuth.then(onInit, onError)

當 GoogleAuth 物件完整時呼叫 onInit 函式 初始化。如果在初始化時發生錯誤 (可能是在舊版不支援的瀏覽器上發生)， 系統會改為呼叫 onError 函式。

錯誤代碼

idpiframe_initialization_failed

無法從 Google 初始化必要的 iframe，例如因不支援的 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

無法在未提示同意聲明流程的情況下自動選取任何使用者。引發錯誤： 搭配 prompt: 'none' 選項使用 signIn。這個選項不應 但 gapi.auth2.init 會在使用者 登入 Chrome

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

無法在未提示同意聲明流程的情況下自動選取任何使用者。引發錯誤： 搭配 prompt: 'none' 選項使用 signIn。這個選項不得為 但 gapi.auth2.init 會在使用者 登入 Chrome

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.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.grantOfflineAccess(options)

請取得使用者授權，以便離線存取指定範圍。

{
  scope: 'profile email'
}

GoogleUser.disconnect()

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

UI 元素

gapi.signin2.render(id, options)

在使用指定 ID 的元素中算繪登入按鈕。 options 物件指定的設定。

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

進階

gapi.auth2.authorize(params, callback)

執行一次性 OAuth 2.0 授權。視所使用的參數而定，系統會開啟 ，或是嘗試在使用者未進行互動的情況下，自動載入要求的回應。

這種方法的適用情況包括：

• 您的應用程式只需要要求一次 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，例如由於不支援的 iframe 環境。details 屬性可針對引發的錯誤提供更多資訊。

popup_closed_by_user

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

access_denied

使用者已拒絕存取所需範圍的權限。

immediate_failed

無法在未提示同意聲明流程的情況下自動選取任何使用者。引發錯誤： 搭配 prompt: 'none' 選項使用 signIn。

gapi.auth2.AuthorizeConfig

這個介面代表 gapi.auth2.authorize 方法。

gapi.auth2.AuthorizeResponse

傳回給 gapi.auth2.authorize 方法。