本參考資料說明您將用於在網頁應用程式中導入 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,該 Promise 會在 gapi.auth2.GoogleAuth 物件完成初始化時解析。 |
GoogleAuth.then(onInit, onError)
在 GoogleAuth
物件完全初始化時呼叫 onInit 函式。如果在初始化期間發生錯誤 (這可能發生在舊的、不支援的瀏覽器中),系統會改為呼叫 onError 函式。
引數 | |
---|---|
onInit |
在 GoogleAuth 物件完成初始化時,系統會使用該物件呼叫的函式。 |
onError |
如果 GoogleAuth 無法初始化,則會使用含有 error 屬性的物件呼叫函式。 |
傳回 | |
---|---|
Promise | onInit 函式完成時會執行的 Promise ,如果發生初始化錯誤,則會遭到拒絕。它會與 onInit 函式 (如有) 傳回的值一起解析。 |
錯誤代碼
idpiframe_initialization_failed
-
由於環境不支援,因此無法初始化 Google 的必要 iframe。
details
屬性會提供有關錯誤的更多資訊。
gapi.auth2.ClientConfig
代表 gapi.auth2.init
方法的不同設定參數介面。
參數 | ||
---|---|---|
client_id |
string |
必填。應用程式的用戶端 ID,可在 Google API 控制台中找到並建立。 |
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」新增至要求的範圍。如果未指定,則為 True。 |
hosted_domain |
string |
使用者必須屬於的 G Suite 網域,才能登入。這項屬性很容易遭客戶修改,因此請務必驗證傳回使用者的代管網域資源。在用戶端上使用 GoogleUser.getHostedDomain(),以及伺服器上 ID 權杖中的 hd 要求,驗證網域是否符合預期。 |
use_fedcm |
boolean |
選用,預設為 True 。在登入期間啟用或停用瀏覽器 FedCM API 的使用。 |
ux_mode |
string |
登入流程使用的使用者體驗模式。根據預設,系統會在彈出式視窗中開啟同意聲明流程。有效值為 popup 和 redirect 。 |
redirect_uri |
string |
如果使用 ux_mode='redirect' ,您可以透過這個參數覆寫同意聲明流程結尾時會使用的預設 redirect_uri 。預設 redirect_uri 是目前的網址,已移除查詢參數和雜湊片段。 |
enable_granular_consent |
boolean |
選用設定。是否啟用精細權限。如果設為 false ,則會停用 2019 年前建立的 OAuth 用戶端 ID 中較精細的 Google 帳戶權限。對於 2019 年後建立的 OAuth 用戶端 ID 沒有影響,因為這些 ID 一律會啟用更精細的權限。 |
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 例項執行的 Promise ;如果發生錯誤,則會使用包含 error 屬性的物件拒絕。如要瞭解錯誤代碼,請參閱下一節。 |
錯誤代碼
請參閱「GoogleAuth.signIn(options)
」。
GoogleAuth.signIn(options)
使用指定選項登入使用者。
引數 | |
---|---|
options |
以下兩者之一:
|
傳回 | |
---|---|
Promise | 當使用者成功驗證並授予所要求的範圍時,系統會使用 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 |
強制同意聲明流程採用特定模式。選填。 可能的值如下:
|
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
-
如果未顯示同意流程,則無法自動選取使用者。搭配使用
signIn
與prompt: 'none'
選項時引發錯誤。您不應使用這個選項,因為如果先前已在上一個工作階段中登入,gapi.auth2.init
會自動將使用者登入。
gapi.auth2.OfflineAccessOptions
代表
GoogleAuth.grantOfflineAccess(options)
方法的不同設定參數的介面。
參數 | ||
---|---|---|
prompt |
string |
強制同意聲明流程採用特定模式。選填。 可能的值如下:
|
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 會在每次變更 currentUser 時,將此函式傳遞至 GoogleUser 例項。 |
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 的屬性:
|
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 }
|
進階
gapi.auth2.authorize(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
-
如果未顯示同意流程,則無法自動選取使用者。使用
signIn
搭配prompt: 'none'
選項時發生錯誤。
gapi.auth2.AuthorizeConfig
代表 gapi.auth2.authorize
方法不同設定參數的介面。
屬性 | ||
---|---|---|
client_id |
string |
必填。應用程式的用戶端 ID (可在 Google API 控制台中找到) 並建立。 |
scope |
string |
必填。要要求的範圍,以空格分隔的字串表示。 |
response_type |
string |
以空格分隔的回應類型清單。預設為 'permission' 。可能的值如下:
|
prompt |
string |
強制同意聲明流程採用特定模式。可能的值包括:
|
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 。 |
enable_granular_consent |
boolean |
選用設定。是否啟用精細權限。如果設為 false ,則會停用 2019 年前建立的 OAuth 用戶端 ID 中較精細的 Google 帳戶權限。2019 年期間或之後建立的 OAuth 用戶端 ID 不會受到任何影響,因為系統一律會為這類 ID 啟用更精細的權限。 |
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 |
在要求失敗時,這可能會包含錯誤代碼的其他資訊,該代碼也會一併傳回。 |