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

在不顯示同意聲明流程的情況下，系統不會自動選取任何使用者。搭配 prompt: 'none' 選項使用 signIn 時，發生錯誤。請勿使用此選項，因為 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

在不顯示同意聲明流程的情況下，系統不會自動選取任何使用者。搭配 prompt: 'none' 選項使用 signIn 時，發生錯誤。請勿使用此選項，因為 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.getHostedDomain()

如果使用者的 G Suite 帳戶已登入，即可取得 G Suite 網域。

GoogleUser.getGrantedScopeScopes()

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

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.authorization(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 方法回呼的回應。