本頁面由 Cloud Translation API 翻譯而成。

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` 函式傳回的值 (如果有的話)。

警告：請勿呼叫 Promise.resolve()，並且與 gapi.auth2.init() 的結果類似。由於傳回的 GoogleAuth 物件會實作可自行解析的 then() 方法，因此會建立無限遞迴。

錯誤代碼

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_origin` 或 `none`。如未指定，則預設值為 `single_host_origin`。
`scope`	`string`	要求的範圍，以空格分隔的字串。如果 `fetch_basic_profile` 未設為 false，則為選用欄位。
`fetch_basic_profile`	`boolean`	在使用者登入時擷取其基本個人資料。將「profile」、「email」和「openid」新增至要求的範圍。若未指定，則為「是」。
`hosted_domain`	`string`	使用者必須登入的 G Suite 網域。用戶端可能會修改這項設定，因此請務必驗證傳回使用者的代管網域資源。在用戶端上使用 GoogleUser.getHostedDomain()，並在伺服器上的 ID 權杖中使用 `hd` 憑證附加資訊，以驗證符合預期的網域。搭配使用這個參數與 `fetch_basic_profile: false` 時，必須要求 `'email'` 範圍。
`ux_mode`	`string`	用於登入流程的使用者體驗模式。根據預設，系統會在彈出式視窗中開啟同意聲明流程。有效值為 `popup` 和 `redirect`。
`redirect_uri`	`string`	如果使用 `ux_mode='redirect'`，這個參數可讓您覆寫同意聲明流程結束時要使用的預設 `redirect_uri`。預設的 `redirect_uri` 是目前去除的查詢參數和雜湊片段網址。
`plugin_name`	`string`	選用設定。如果設定這個值，2022 年 7 月 29 日前建立的新用戶端 ID 即可使用舊版 Google 平台資料庫。根據預設，新建立的用戶端 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`；如果使用者已登出，或 `GoogleAuth` 物件未初始化，則為 `false`。

GoogleAuth.isSignedIn.listen(listener)

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

引數
`listener`	接受布林值的函式。使用者登入時，`listen()` 會將 `true` 傳遞至這個函式，使用者登出時則傳遞 `false`。

GoogleAuth.signIn()

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

傳回
承諾	當使用者成功驗證及授予要求的範圍時，此 `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');

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` 完成了 `GoogleUser` 執行個體；如果發生錯誤，則會以包含 `error` 屬性的物件拒絕 (請參閱下方錯誤代碼)。

錯誤代碼

popup_closed_by_user: 使用者在完成登入流程前關閉了彈出式視窗。
access_denied: 使用者拒絕了所需範圍的權限。
immediate_failed: 如未提示同意流程，系統就無法自動選取任何使用者。搭配 prompt: 'none' 選項使用 signIn 時發生錯誤。不應使用這個選項，因為如果先前已在先前工作階段中登入，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`	用於登入流程的使用者體驗模式。根據預設，系統會在彈出式視窗中開啟同意聲明流程。有效值為 `popup` 和 `redirect`。
`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: 如未提示同意流程，系統就無法自動選取任何使用者。搭配 prompt: 'none' 選項使用 signIn 時發生錯誤。不應使用這個選項，因為如果先前已在先前工作階段中登入，gapi.auth2.init 會自動將使用者登入。

gapi.auth2.OfflineAccessOptions

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

參數
`prompt`	`string`	強制為同意聲明流程強制執行特定模式。選用。可能的值如下： `consent` 授權伺服器會先提示使用者同意，再將資訊傳回應用程式。 `select_account` 授權伺服器會提示使用者選取 Google 帳戶。這樣一來，擁有多個帳戶的使用者就能在目前工作階段的多個帳戶中選取。請注意，`none` 不適用於離線程式碼流程。
`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 字串。

請勿使用 getId() 傳回的 Google ID 將目前登入的使用者傳送到後端伺服器。請改為傳送 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.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`)。使用長標題時，建議您從預設增加按鈕的寬度。
主題	按鈕的顏色主題：`light` 或 `dark` (預設值：`light`)。
on 成功	使用者成功登入時要呼叫的回呼函式。這個函式必須採用一個引數：`gapi.auth2.GoogleUser` 的執行個體 (預設值：無)。
onfailure	登入失敗時要呼叫的回呼函式。這個函式不會使用任何引數 (預設值：無)。

進階

gapi.auth2.Authorization(`params`, `callback`)

執行一次性 OAuth 2.0 授權。視使用的參數而定，這會在 Google 登入流程中開啟彈出式視窗，或嘗試在沒有使用者互動的情況下，直接載入要求的回應。

這個方法非常實用：

您的應用程式只需要要求 Google API 端點一次，例如在使用者第一次登入時載入喜愛的 YouTube 影片。
應用程式擁有自己的工作階段管理基礎架構，而且只需要使用一次 ID 權杖即可在後端識別使用者。
同一個頁面中使用多個用戶端 ID。

警告：請勿在建議的 gapi.auth2.init 和 signIn 流程中使用這個方法。這有兩種不同的行為 (gapi.auth2.authorize 授權與 gapi.auth2.init/signIn 驗證)，如果在相同的應用程式中使用，會遇到非預期的問題。

引數
`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.AuthorizeConfig

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

屬性
`client_id`	`string`	必備。在 Google Developers Console 中找到並建立應用程式的用戶端 ID。
`scope`	`string`	必備。要求的範圍，以空格分隔的字串。
`response_type`	`string`	以空格分隔的回應類型清單。預設為 `'permission'`。可能的值包括： `id_token`，用於擷取 ID 權杖 `permission` (或 `token`) 擷取存取權杖 `code`：擷取授權碼
`prompt`	`string`	強制為同意聲明流程強制執行特定模式。可能的值包括： `consent` 授權伺服器會先提示使用者同意，再將資訊傳回應用程式。 `select_account` 授權伺服器會提示使用者選取 Google 帳戶。這樣一來，擁有多個帳戶的使用者就能在目前工作階段的多個帳戶中選取。 `none` 授權伺服器不會顯示任何驗證或使用者同意畫面；如果使用者尚未通過驗證，且先前尚未同意要求的範圍，則傳回錯誤。如果要求 `code` 做為回應類型，則傳回的程式碼只能用來交換 `access_token`，而不是 `refresh_token`。注意：實際上，程式庫會快取並自動重新整理最近一次取得的存取權杖。在大多數情況下，使用 `prompt: 'none'` 時，不需要向後端發出 HTTP 要求，即可取得有效的權杖。
`cookie_policy`	`string`	要建立登入 Cookie 的網域。URI、`single_host_origin` 或 `none`。如未指定，則預設值為 `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` 中指定了 `permission` 或 `token` 時，才會顯示。
`id_token`	`string`	已授予 ID 權杖。只有在 `response_type` 中指定 `id_token` 時，才會顯示。
`code`	`string`	已授予授權碼。只有在 `response_type` 中指定 `code` 時，才會顯示。
`scope`	`string`	在存取權杖中授予的範圍。只有在 `response_type` 中指定 `permission` 或 `token` 時，才會顯示。
`expires_in`	`number`	存取權杖過期的秒數。只有在 `response_type` 中指定 `permission` 或 `token` 時，才會顯示。
`first_issued_at`	`number`	使用者首次授予要求範圍的時間戳記。只有在 `response_type` 中指定 `permission` 或 `token` 時，才會顯示。
`expires_at`	`number`	存取權杖的到期時間。只有在 `response_type` 中指定 `permission` 或 `token` 時，才會顯示。
`error`	`string`	要求失敗時，會包含錯誤代碼。
`error_subtype`	`string`	如果要求失敗，此訊息可能包含系統傳回的錯誤代碼的其他資訊。

Google 登入 JavaScript 用戶端參考資料

驗證設定

gapi.auth2.init(params)

GoogleAuth.then(onInit, onError)

錯誤代碼

gapi.auth2.ClientConfig

驗證

gapi.auth2.getAuthInstance()

GoogleAuth.isSignedIn.get()

GoogleAuth.isSignedIn.listen(listener)

GoogleAuth.signIn()

錯誤代碼

GoogleAuth.signIn(options)

錯誤代碼

gapi.auth2.SignInOptions

GoogleAuth.signOut()

GoogleAuth.disconnect()

GoogleAuth.grantOfflineAccess(options)

錯誤代碼

gapi.auth2.OfflineAccessOptions

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

使用者

GoogleAuth.currentUser.get()

GoogleAuth.currentUser.listen(listener)

GoogleUser.getId()

GoogleUser.isSignedIn()

GoogleUser.getHostedDomain()

GoogleUser.getGrantedScopes()

GoogleUser.getBasicProfile()

GoogleUser.getAuthResponse(includeAuthorizationData)

GoogleUser.reloadAuthResponse()

gapi.auth2.AuthResponse

GoogleUser.hasGrantedScopes(scopes)

GoogleUser.grant(options)

GoogleUser.grantOfflineAccess(options)

GoogleUser.disconnect()

UI 元素

gapi.signin2.render(id, options)

進階

gapi.auth2.Authorization(params, callback)

範例

錯誤代碼

gapi.auth2.AuthorizeConfig

gapi.auth2.AuthorizeResponse

gapi.auth2.init(`params`)

GoogleAuth.then(`onInit`, `onError`)

GoogleAuth.signIn(`options`)

GoogleAuth.grantOfflineAccess(`options`)

GoogleAuth.AttachClickHandler(`container`, `options`, `onsuccess`, `onfailure`)

GoogleAuth.currentUser.listen(`listener`)

GoogleUser.hasGrantedScopes(`scopes`)

GoogleUser.grant(`options`)

GoogleUser.grantOfflineAccess(`options`)

gapi.signin2.render(`id`, `options`)

gapi.auth2.Authorization(`params`, `callback`)