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 物件會還原使用者在上一個工作階段的登入狀態。

引數
params 包含用戶端設定資料鍵/值組合的物件。如要瞭解其他可設定屬性的資訊,請參閱 gapi.auth2.ClientConfig。例如:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
傳回
gapi.auth2.GoogleAuth gapi.auth2.GoogleAuth 物件。使用 then() 方法取得 gapi.auth2.GoogleAuth 物件完成初始化時已完成的 Promise。

GoogleAuth.then(onInit, onError)

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

引數
onInit 在完全初始化時,透過 GoogleAuth 物件呼叫的函式。
onError 如果 GoogleAuth 無法初始化,請使用包含 error 屬性的物件呼叫函式。
傳回
承諾 onInit 函式完成時執行的 Promise,或因引發初始化錯誤而遭到拒絕。它會使用 onInit 函式傳回的值 (如果有的話) 進行解析。

錯誤代碼

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

gapi.auth2.ClientConfig

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

參數
client_id string 必要。應用程式的用戶端 ID,可在 Google Developers Console 中找到和建立。
cookie_policy string 要建立登入 Cookie 的網域。URI、single_host_originnone。如未指定,則預設值為 single_host_origin
scope string 要求的範圍,以空格分隔的字串表示。如果 fetch_basic_profile 未設為 false,則為選用元素。
fetch_basic_profile boolean 在使用者登入時擷取使用者的基本個人資料資訊。將「profile」、「email」和「openid」新增至要求的範圍。如果未指定,則為 true。
hosted_domain string 使用者登入的 G Suite 網域。用戶端容易修改,因此請務必驗證傳回使用者的代管網域資源。在用戶端上使用 GoogleUser.getManagedDomain(),並且在伺服器上 ID 權杖中使用 hd 憑證驗證是否符合預期。
ux_mode string 登入流程使用的使用者體驗模式。根據預設,系統會在彈出式視窗中開啟同意聲明流程。有效值為 popupredirect
redirect_uri string 如果使用 ux_mode='redirect',您可以透過這個參數覆寫同意聲明流程結束時,會使用的預設 redirect_uri。預設的 redirect_uri 是目前去除查詢參數和雜湊片段的網址。
plugin_name string (選填) 如果設定了這個值,就能在 2022 年 7 月 29 日前建立的新用戶端 ID 可以使用舊版 Google 平台資料庫。根據預設,新建的用戶端 ID 現已禁止使用平台程式庫,必須改用新版 Google Identity Services 程式庫。您可以選擇任何值,或是採用描述性名稱 (例如產品或外掛程式名稱),方便識別。範例:plugin_name: 'YOUR_STRING_HERE'

驗證

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

gapi.auth2.getAuthInstance()

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

傳回
gapi.auth2.GoogleAuth gapi.auth2.GoogleAuth 物件。使用這個物件呼叫 gapi.auth2.GoogleAuth 的方法。

GoogleAuth.isSignedIn.get()

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

傳回
布林值 如果使用者已登入,則為 true;如果使用者登出或 GoogleAuth 物件未初始化,則為 false

GoogleAuth.isSignedIn.listen(listener)

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

引數
listener 接受布林值的函式。當使用者登入時,listen() 會將 true 傳遞至此函式,並在使用者登出時傳遞 false

GoogleAuth.signIn()

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

傳回
承諾 使用者成功驗證並授予要求的範圍時,這是透過 GoogleUser 執行個體執行的 Promise,如果發生錯誤,則會拒絕包含 error 屬性的物件 (錯誤代碼請參閱下文)。

錯誤代碼

查看《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 屬性的物件 (錯誤代碼請參閱下文)。

錯誤代碼

popup_closed_by_user
使用者在完成登入流程前關閉彈出式視窗。
access_denied
使用者拒絕授予所需範圍的權限。
immediate_failed
必須提示同意流程才能自動選取使用者。將 signInprompt: 'none' 選項搭配使用時引發錯誤。不需要使用這個選項,因為 gapi.auth2.init 會在先前在上一個工作階段登入的使用者自動登入。

gapi.auth2.SignInOptions

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

參數
prompt string 強制執行同意聲明流程的特定模式。選用。
可能的值如下:
  • consent
    授權伺服器會先提示使用者表示同意,再將資訊傳回應用程式。
  • select_account
    授權伺服器會提示使用者選取 Google 帳戶。這樣一來,擁有多個帳戶的使用者就能從目前擁有工作階段的多個帳戶中選擇。
  • none (不建議採用)
    授權伺服器不會顯示任何驗證或使用者同意畫面。如果使用者尚未通過驗證,且先前從未同意存取要求的範圍,則授權伺服器將傳回錯誤。
    由於 gapi.auth2.init 會自動讓使用者登入應用程式,因此呼叫 signIn({prompt: 'none'}) 通常會失敗。
scope string 要求的範圍,以空格分隔字串的形式顯示在 gapi.auth2.init 參數中定義的範圍之上。如果 fetch_basic_profile 未設為 false,則為選用欄位。
ux_mode string 登入流程使用的使用者體驗模式。根據預設,系統會在彈出式視窗中開啟同意聲明流程。有效值為 popupredirect
redirect_uri string 如果使用 ux_mode='redirect',您可以透過這個參數覆寫同意聲明流程結束時,會使用的預設 redirect_uri。預設的 redirect_uri 是目前去除查詢參數和雜湊片段的網址。

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
必須提示同意流程才能自動選取使用者。將 signInprompt: 'none' 選項搭配使用時引發錯誤。不需要使用這個選項,因為 gapi.auth2.init 會在先前在上一個工作階段登入的使用者自動登入。

gapi.auth2.OfflineAccessOptions

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

參數
prompt string 強制執行同意聲明流程的特定模式。選用。
可能的值如下:
  • consent
    授權伺服器會先提示使用者表示同意,再將資訊傳回應用程式。
  • select_account
    授權伺服器會提示使用者選取 Google 帳戶。這樣一來,擁有多個帳戶的使用者就能從目前擁有工作階段的多個帳戶中選擇。
scope string 要求的範圍,以空格分隔字串的形式顯示在 gapi.auth2.init 參數中定義的範圍之上。如果 fetch_basic_profile 未設為 false,則為選用欄位。

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

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

引數
container 要附加點擊處理常式的 div 元素 ID 或參照。
options 包含參數鍵/值組合的物件。請參閱 GoogleAuth.signIn()
onsuccess 登入完成後要呼叫的函式。
onfailure 登入失敗時要呼叫的函式。

使用者

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

GoogleAuth.currentUser.get()

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

傳回
GoogleUser 目前的使用者

GoogleAuth.currentUser.listen(listener)

監聽 currentUser 中的變更。

引數
listener 採用 GoogleUser 參數的函式。每當修改 currentUser 時,listen 都會將這個函式傳送至 GoogleUser 執行個體。

GoogleUser.getId()

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

傳回
字串 使用者的專屬 ID

GoogleUser.isSignedIn()

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

傳回
布林值 如果使用者已登入,則為 True

GoogleUser.getHostDomain()

取得使用者的 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)

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

引數
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 以空格分隔的範圍字串。
傳回
布林值 如果已授予範圍,則為 True

GoogleUser.grant(options)

向使用者要求其他範圍。

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

GoogleUser.grantOfflineAccess(options)

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

引數
options 包含參數鍵/值組合的 gapi.auth2.OfflineAccessOptions 物件。例如:
{
  scope: 'profile email'
}

GoogleUser.disconnect()

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

UI 元素

gapi.signin2.render(id, options)

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

引數
id 要顯示登入按鈕的元素 ID。
options 包含顯示按鈕設定的物件。舉例來說:
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
您可以指定下列選項:
參數
範圍 使用者登入時要求的範圍 (預設值:profile)。
width 按鈕的寬度 (以像素為單位,預設值為 120)。
height 按鈕的高度 (以像素為單位,預設值為 36)。
Longtitle 顯示「使用 Google 帳戶登入」等長標籤,而非「登入」(預設值:false)。使用長標題時,請提高按鈕的寬度。
主題 按鈕的顏色主題:lightdark (預設值:light)。
失敗 使用者成功登入時要呼叫的回呼函式。這個函式必須採用一個引數:gapi.auth2.GoogleUser 的執行個體 (預設:無)。
失敗 登入失敗時要呼叫的回呼函式。這個函式不使用任何引數 (預設:無)。

進階

gapi.auth2.authorized(params, callback)

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

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

  • 應用程式只需要要求 Google API 端點一次,例如在使用者首次登入時載入使用者喜愛的 YouTube 影片。
  • 應用程式擁有自己的工作階段管理基礎架構,且只需要 ID 權杖一次就能識別後端中的使用者。
  • 同一個頁面中會使用多個用戶端 ID。
引數
params 包含設定資料鍵/值組合的物件。如要瞭解其他可設定屬性的資訊,請參閱 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
必須提示同意流程才能自動選取使用者。將 signInprompt: 'none' 選項搭配使用時引發錯誤。

gapi.auth2.AuthorizeConfig

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

屬性
client_id string 必備。應用程式的用戶端 ID,可在 Google Developers Console 中找到和建立。
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
plugin_name string (選填) 如果已設定,在 2022 年 7 月 29 日前建立的用戶端 ID 即可使用 Google 平台資料庫。根據預設,新建立的用戶端 ID 無法使用平台程式庫,必須改用新版 Google Identity 服務程式庫。您可以選擇任何值,或是採用描述性名稱 (例如產品或外掛程式名稱),方便識別。範例:plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

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

屬性
access_token string 已授予存取權杖。只有在 response_type 中指定 permissiontoken 時,才會顯示這個屬性。
id_token string 已授予 ID 權杖。只有在 response_type 中指定 id_token 時,才會顯示這個屬性。
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 要求失敗時,這個值也可能包含系統傳回的錯誤代碼的額外資訊。