我們即將 停用 Google 登入 Google Web Designer 網頁版程式庫。但 2023 年 3 月 31 日的淘汰日期過後即無法下載。請改用新版網頁版 Google 身分識別服務。
根據預設,新建立的用戶端 ID 現在會遭到封鎖,無法使用舊版平台程式庫,現有的用戶端 ID 則不受影響。凡是在 2022 年 7 月 29 日前建立的用戶端 ID,都可以設定 ‘plugin_name` 來啟用 Google Platform 程式庫。

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() 方法取得 Promise,系統會在 gapi.auth2.GoogleAuth 物件完成初始化時予以解決。

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 必填。 在 Google Developers Console 中找到並建立應用程式的用戶端 ID。
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.getHostedDomain()用戶端hd在伺服器的 ID 憑證中聲明擁有權,藉此驗證該網域是否符合您的預期。
ux_mode string 用於登入流程的使用者體驗模式。根據預設,系統會在彈出式視窗中開啟同意聲明流程。有效值為 popupredirect
redirect_uri string 如使用 ux_mode='redirect',這個參數可讓您覆寫在同意聲明流程結尾使用的預設 redirect_uri。預設值 redirect_uri 是移除查詢參數與雜湊片段的目前網址。
plugin_name string 選用,設定這個值之後,在 2022 年 7 月 29 日前建立的新用戶端 ID 都可以使用舊版 Google Platform 程式庫。 根據預設,新建立的用戶端 ID 會遭到封鎖,無法使用平台程式庫,而必須改用新版 Google Identity 服務程式庫。您可以選擇任何值,建議使用具有描述性的名稱 (例如產品或外掛程式名稱),以便識別。 範例: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使用者登入後false使用者登出時GoogleAuth無法初始化物件。

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
在未提示使用者同意流程的情況下,您無法自動選取任何使用者。使用 signIn 搭配 prompt: '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.grant 離線版 Access(options)

請使用者取得相關權限,以便離線存取指定範圍。

引數
options 包含參數/值組合參數的 gapi.auth2.OfflineAccessOptions 物件。例如:
{
  scope: 'profile email'
}
傳回
定情 使用者授予要求範圍時執行的 Promise,會將包含授權碼的物件傳送至 Promise 的 fulfillment 處理常式。 例如:
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) 方法的不同設定參數。

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

GoogleAuth.attachClickHandler(containeroptionsonsuccessonfailure)

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

引數
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)

監聽目前使用者異動。

引數
listener 可採用 GoogleUser 參數的函式。 listen 會在修改 currentUser 的每個變更中傳送此函式的 GoogleUser 例項。

GoogleUser.getId()

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

傳回
字串 使用者的專屬 ID

GoogleUser.isSignedIn()

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

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

GoogleUser.getHostedDomain()

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

傳回
字串 使用者的 G Suite 網域

GoogleUser.getGrantedScopes()

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

傳回
字串 使用者授予的範圍

GoogleUser.getBasicProfile()

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

傳回
gapi.auth2.BasicProfile 您可以透過下列方式擷取 gapi.auth2.BasicProfile 的屬性:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getLetnName()
  • 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.grant 離線版 Access(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)。
寬度 按鈕的寬度 (以像素為單位,預設值:120)。
高度 按鈕的高度 (以像素為單位,預設為 36)。
Longtitle 顯示較長的標籤,例如「使用 Google 帳戶登入」,而非「登入」(預設:false)。使用長標題時,應增加按鈕預設寬度。
主題 按鈕的顏色主題:lightdark (預設值:light)。
Onsuccess 使用者成功登入後所呼叫的回呼函式。 這個函式必須採用一個引數:gapi.auth2.GoogleUser 的執行個體 (預設值:無)。
失敗 登入失敗時呼叫的回呼函式。這個函式不需要引數 (預設值:無)。

進階

gapi.auth2.authorization(params, callback)

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

這個方法的優點包括:

  • 您的應用程式只需要求 Google API 端點一次,例如,當使用者第一次登入時,就能載入使用者最愛的 YouTube 影片。
  • 您的應用程式有自己的工作階段管理基礎架構,而且只需要使用 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
在未提示使用者同意流程的情況下,您無法自動選取任何使用者。使用 signIn 搭配 prompt: 'none' 選項時引發錯誤。

gapi.auth2.AuthorizationConfig

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

屬性
client_id string Required。在 Google Developers Console 中找到並建立應用程式的用戶端 ID。
scope string Required。要求的範圍 (以空格分隔的字串)。
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 Platform 程式庫。根據預設,新建立的用戶端 ID 會遭到封鎖,無法使用平台資料庫,而必須改用新版 Google Identity 服務程式庫。您可以選擇任何值,建議使用具有描述性的名稱 (例如產品或外掛程式名稱),以便識別。 範例:plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizationResponse

將回應傳回 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 要求失敗時,系統可能也會一併傳回錯誤代碼的額外資訊。