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

引數
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 使用含有 error 屬性的物件呼叫的函式， 如果 GoogleAuth 無法初始化。
傳回
Promise 在 onInit 時執行的 Promise 函式已完成，或因發生初始化錯誤而遭拒。這個函式會呼叫 onInit 函式中傳回的值 (如有)。

錯誤代碼

idpiframe_initialization_failed
無法從 Google 初始化必要的 iframe，例如因不支援的 iframe 環境。details 屬性可針對引發的錯誤提供更多資訊。

gapi.auth2.ClientConfig

這個介面代表 gapi.auth2.init 方法，增加圍繞地圖邊緣的邊框間距。

參數
client_id string 必要。應用程式的用戶端 ID (可在 Google API 控制台中找到) 並建立。
cookie_policy string 要建立登入 Cookie 的網域。URI 是 URI single_host_origin 或 none。預設為 single_host_origin (如未指定)。
scope string 要要求的範圍，以空格分隔字串。如果符合以下情況，此為選用屬性 fetch_basic_profile未設為 false。
fetch_basic_profile boolean 擷取使用者基本個人資料。新增「個人資料」、「電子郵件」和 「openid」要求範圍。如未指定，則為「true」。
hosted_domain string 使用者必須登入的 G Suite 網域。這個 都容易受到客戶修改，因此請務必 所傳回使用者的代管網域資源。使用 GoogleUser.getHostedDomain() 已啟用 用戶端，以及用戶端 ID 權杖中的 hd 憑證附加資訊 伺服器來驗證網域是否符合您的預期。
use_fedcm boolean 選用，預設為 True。啟用或停用 。
ux_mode string 登入流程使用的使用者體驗模式。根據預設，系統會開啟同意聲明流程 就會在彈出式視窗中顯示有效值為 popup 和 redirect。
redirect_uri string 如果使用 ux_mode='redirect'，這個參數可讓您覆寫 會在同意聲明流程結束時使用的預設 redirect_uri。 目前網址去除查詢參數和雜湊值的預設值 redirect_uri 片段。
enable_granular_consent boolean 選用設定。是否要啟用 精細 權限。如果設為 false，代表 Google 提供的 先前建立的 OAuth 用戶端 ID 將停用帳戶權限 2019 年。2019 年期間或之後建立的 OAuth 用戶端 ID 則無效，因為 系統會一律為這些權限啟用更精細的權限
plugin_name string 選用設定。如果設定此值，則在 7 月前建立的新用戶端 ID 自 2022 年 29 月起，您可以使用舊版 Google 平台程式庫。 根據預設，新建立的用戶端 ID 目前無法使用 平台程式庫，必須改用新版 Google 身分 服務程式庫。您可以選擇任何值，也就是描述性名稱，例如 建議使用產品或外掛程式名稱以便識別。 範例：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() 的選項登入使用者。

傳回
Promise 當 Promise 出現時，透過 GoogleUser 例項執行 使用者成功驗證並授予要求的範圍，或因物件拒絕而拒絕 其中包含 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');
傳回
Promise 當 Promise 出現時，透過 GoogleUser 例項執行 使用者成功驗證並授予要求的範圍，或因物件拒絕而拒絕 包含 error 屬性，如果發生錯誤 (請參閱下文，瞭解錯誤代碼)。

錯誤代碼

popup_closed_by_user
使用者在完成登入流程前關閉了彈出式視窗。
access_denied
使用者已拒絕存取所需範圍的權限。
immediate_failed
無法在未提示同意聲明流程的情況下自動選取任何使用者。引發錯誤： 搭配 prompt: 'none' 選項使用 signIn。這個選項不應 但 gapi.auth2.init 會在使用者 登入 Chrome

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 登入流程使用的使用者體驗模式。根據預設，系統會開啟同意聲明流程 就會在彈出式視窗中顯示有效值為 popup 和 redirect。
redirect_uri string 如果使用 ux_mode='redirect'，則可透過這個參數覆寫 同意聲明結束時會使用的預設 redirect_uri 流程預設的 redirect_uri 是目前查詢的未移除網址 參數和雜湊片段

GoogleAuth.signOut()

從應用程式登出目前的帳戶。

傳回
Promise 使用者簽署後要執行的 Promise 。

GoogleAuth.disconnect()

撤銷使用者授予的所有範圍。

GoogleAuth.grantOfflineAccess(options)

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

引數
options gapi.auth2.OfflineAccessOptions 包含參數鍵/值組合的物件。例如： 
{
  scope: 'profile email'
}
傳回
Promise Promise 當使用者授予 將包含授權碼的物件傳遞至 Promise 的執行要求處理常式。 例如： 
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) 方法。

參數
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 參數的函式。 listen 會將 GoogleUser 傳遞給這個函式 每次修改 currentUser 的變更例項。

GoogleUser.getId()

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

傳回
字串 使用者的專屬 ID

GoogleUser.isSignedIn()

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

傳回
布林值 如果使用者已登入，則為「是」

GoogleUser.getHostedDomain()

如果使用者已透過 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 透過重新載入執行的 Promise gapi.auth2.AuthResponse (重新載入) OAuth 權杖建立完成。

gapi.auth2.AuthResponse

呼叫時傳回的回應 GoogleUser.getAuthResponse(includeAuthorizationData) 或 GoogleUser.reloadAuthResponse() 方法。

屬性
access_token string 已授予存取權杖。
id_token string 授予 ID 權杖。
scope string 存取權杖中授予的範圍。
expires_in number 存取 Token 到期之前的秒數。
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)

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

引數
id 顯示登入按鈕的元素 ID。
options 物件，包含用於呈現按鈕的設定。例如： 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
您可以指定下列選項：
參數
範圍 使用者登入時要求的範圍 (預設值： profile)。
寬度 按鈕寬度，以像素為單位 (預設值：120)。
高度 按鈕高度，以像素為單位 (預設值：36)。
長標題 顯示完整標籤，例如「使用 Google 帳戶登入」而非 「登入」(預設值：false)。使用長標題時 應增加按鈕的寬度。
主題 按鈕的顏色主題：light 或 dark (預設：light)。
on 成功 使用者成功登入時要呼叫的回呼函式。 這個函式必須使用一個引數： gapi.auth2.GoogleUser (預設值：無)。
Onfailure 登入失敗時要呼叫的回呼函式。這個函式 不使用引數 (預設：無)。

進階

gapi.auth2.authorize(params, callback)

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

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

  • 您的應用程式只需要要求一次 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，例如由於不支援的 iframe 環境。details 屬性可針對引發的錯誤提供更多資訊。
popup_closed_by_user
使用者在完成登入流程前關閉了彈出式視窗。
access_denied
使用者已拒絕存取所需範圍的權限。
immediate_failed
無法在未提示同意聲明流程的情況下自動選取任何使用者。引發錯誤： 搭配 prompt: 'none' 選項使用 signIn。

gapi.auth2.AuthorizeConfig

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

屬性
client_id string 必填。應用程式的用戶端 ID (可在 Google API 控制台中找到) 並建立。
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 是 URI single_host_origin 或 none。預設為 single_host_origin。
hosted_domain string 使用者必須登入的 G Suite 網域。容易修改 因此請務必確認所傳回使用者的代管網域資源。
login_hint string 在登入流程中預先選取的使用者電子郵件或使用者 ID。這容易會發生 修改內容 (除非使用 prompt: "none")。
include_granted_scopes boolean 是否要求存取權杖 (包含使用者先前授予的所有範圍) 或是僅限目前呼叫中要求的範圍。預設值為 true。
enable_granular_consent boolean 選用設定。是否要啟用 精細 權限。如果設為 false，代表 Google 提供的 先前建立的 OAuth 用戶端 ID 將停用帳戶權限 2019 年。2019 年期間或之後建立的 OAuth 用戶端 ID 則無效，因為 系統會一律為這些權限啟用更精細的權限
plugin_name string 選用設定。如果設定這項政策，2022 年 7 月 29 日前建立的用戶端 ID 就能使用 Google 平台程式庫。根據預設，系統會封鎖新建立的用戶端 ID 必須改用新版 Google 以及 Identity Services 程式庫您可以選擇任何值，當做描述性名稱 例如產品或外掛程式名稱等，方便識別。 範例：plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

傳回給 gapi.auth2.authorize 方法。

屬性
access_token string 已授予存取權杖。只有在 permission 或 token 之前才會顯示 在 response_type 中指定的值。
id_token string 授予 ID 權杖。只有在id_token response_type。
code string 已授予授權碼。只有在code response_type。
scope string 存取權杖中授予的範圍。只有在 permission 或 token 已在 response_type 中指定。
expires_in number 存取 Token 到期之前的秒數。只有在 permission 才會顯示 或 token 是在 response_type 中指定。
first_issued_at number 使用者首次授予要求範圍時的時間戳記。出現以下情況時才會顯示 已在 response_type 中指定 permission 或 token。
expires_at number 存取權杖效期的時間戳記。只有在 permission 才會顯示 或 token 是在 response_type 中指定。
error string 要求失敗時，這個值會包含 錯誤代碼。
error_subtype string 如果要求失敗，這個值也可能包含錯誤代碼的額外資訊 。