說明
使用 chrome.identity API 取得 OAuth2 存取權杖。
權限
identity類型
AccountInfo
屬性
-
id
字串
帳戶的專屬 ID。這個 ID 在帳戶存續期間不會變更。
AccountStatus
列舉
「SYNC」
指定為主要帳戶啟用同步功能。
"ANY"
指定主要帳戶是否存在 (如果有的話)。
GetAuthTokenResult
屬性
-
grantedScopes
string[] 選填
授予擴充功能的 OAuth2 範圍清單。
-
token
字串 選填
與要求相關聯的特定權杖。
InvalidTokenDetails
屬性
-
token
字串
應從快取中移除的特定權杖。
ProfileDetails
屬性
-
accountStatus
登入設定檔的主要帳戶狀態，應傳回其
ProfileUserInfo。預設為SYNC帳戶狀態。
ProfileUserInfo
屬性
-
電子郵件
字串
登入目前設定檔的使用者帳戶電子郵件地址。如果使用者未登入，或未指定
identity.email資訊清單權限，則為空白。 -
id
字串
帳戶的專屬 ID。這個 ID 在帳戶存續期間不會變更。如果使用者未登入，或 (在 M41 以上版本中) 未指定
identity.email資訊清單權限，則會留空。
TokenDetails
屬性
-
帳戶
AccountInfo 選填
要傳回權杖的帳戶 ID。如未指定，函式會使用 Chrome 設定檔中的帳戶：同步帳戶 (如有)，或第一個 Google 網頁帳戶。
-
enableGranularPermissions
布林值 選填
Chrome 87 以上版本 Chrome 148 起為 browser.*enableGranularPermissions旗標可讓擴充功能提早選擇加入精細權限同意畫面，使用者可在該畫面中個別授予或拒絕要求的權限。 -
互動
布林值 選填
擷取權杖時，使用者可能需要登入 Chrome，或核准應用程式要求的範圍。如果互動式標記為
true，getAuthToken會視需要提示使用者。如果旗標為false或省略，則每當需要提示時，getAuthToken都會傳回失敗。 -
範圍
string[] 選填
要要求的 OAuth2 範圍清單。
如果
scopes欄位存在，則會覆寫 manifest.json 中指定的範圍清單。
WebAuthFlowDetails
屬性
-
abortOnLoadForNonInteractive
布林值 選填
Chrome 113 以上版本 Chrome 148 起為 browser.*是否要在載入網頁後，終止非互動式要求的
launchWebAuthFlow。這項參數不會影響互動式流程。如果設為
true(預設)，流程會在網頁載入後立即終止。如果設為false，流程只會在timeoutMsForNonInteractive通過後終止。如果識別資訊提供者使用 JavaScript 在網頁載入後執行重新導向，這項功能就非常實用。 -
互動
布林值 選填
是否要在互動模式下啟動驗證流程。
由於某些驗證流程可能會立即重新導向至結果網址，因此
launchWebAuthFlow會隱藏其網頁檢視，直到第一次導覽重新導向至最終網址，或完成載入要顯示的網頁。如果
interactive旗標為true，系統會在載入網頁完成時顯示視窗。如果標記為false或省略，則初始導覽未完成流程時，launchWebAuthFlow會傳回錯誤。如果流程使用 JavaScript 重新導向，可將
abortOnLoadForNonInteractive設為false，並設定timeoutMsForNonInteractive，讓網頁有機會執行任何重新導向。 -
timeoutMsForNonInteractive
數字 選填
Chrome 113 以上版本 Chrome 148 起為 browser.*launchWebAuthFlow在非互動模式下執行的總時間上限，以毫秒為單位。只有在interactive為false時才會生效。 -
網址
字串
啟動授權流程的網址。
方法
clearAllCachedAuthTokens()
browser.identity.clearAllCachedAuthTokens(): Promise<void>
重設 Identity API 的狀態：
- 從權杖快取中移除所有 OAuth2 存取權杖
- 移除使用者的帳戶偏好設定
- 撤銷使用者在所有驗證流程中的授權
傳回
-
承諾<void>
Chrome 106 以上版本 Chrome 148 起為 browser.*傳回 Promise，在狀態清除後解析。
getAccounts()
browser.identity.getAccounts(): Promise<AccountInfo[]>
擷取 AccountInfo 物件清單，說明設定檔中的帳戶。
getAccounts 僅適用於開發人員版。
傳回
-
Promise<AccountInfo[]>
getAuthToken()
browser.identity.getAuthToken(
details?: TokenDetails,
): Promise<GetAuthTokenResult>
使用 manifest.json 的 oauth2 部分中指定的用戶端 ID 和範圍，取得 OAuth2 存取權杖。
Identity API 會將存取權杖快取在記憶體中，因此每當需要權杖時，可以非互動方式呼叫 getAuthToken。權杖快取會自動處理到期問題。
為提供良好的使用者體驗，請務必透過應用程式中的 UI 發出互動式權杖要求，並說明授權用途。否則使用者會收到授權要求，或在未登入時看到 Chrome 登入畫面，但不知道原因。具體來說，請勿在應用程式首次啟動時，以互動方式使用 getAuthToken。
注意：使用回呼呼叫時，這個函式不會傳回物件，而是將這兩個屬性做為個別引數傳回給回呼。
參數
-
詳細資料
TokenDetails 選用
權杖選項。
傳回
-
Promise<GetAuthTokenResult>
Chrome 105 以上版本 Chrome 148 以上版本為 browser.*傳回 Promise，其會解析為資訊清單指定的 OAuth2 存取權杖，或在發生錯誤時拒絕。自 Chrome 87 起，系統會填入
grantedScopes參數。如果可用，這個參數會包含與傳回權杖對應的已授予範圍清單。
getProfileUserInfo()
browser.identity.getProfileUserInfo(
details?: ProfileDetails,
): Promise<ProfileUserInfo>
擷取登入設定檔的使用者電子郵件地址和經過模糊處理的 GAIA ID。
需要 identity.email 資訊清單權限。否則會傳回空白結果。
這個 API 與 identity.getAccounts 有兩點不同。傳回的資訊可離線使用，且僅適用於設定檔的主要帳戶。
參數
-
詳細資料Chrome 84 以上版本 Chrome 148 以上版本的瀏覽器。*
個人資料選項。
傳回
-
Promise<ProfileUserInfo>
Chrome 106 以上版本 Chrome 148 起為 browser.*傳回 Promise，其會解析為主要 Chrome 帳戶的
ProfileUserInfo，或如果具有指定details的帳戶不存在，則傳回空白ProfileUserInfo。
getRedirectURL()
browser.identity.getRedirectURL(
path?: string,
): string
產生要在 launchWebAuthFlow 中使用的重新導向網址。
產生的網址符合 https://<app-id>.chromiumapp.org/* 模式。
參數
-
路徑
字串 選填
附加至所產生網址結尾的路徑。
傳回
-
字串
launchWebAuthFlow()
browser.identity.launchWebAuthFlow(
details: WebAuthFlowDetails,
): Promise<string | undefined>
在指定網址啟動驗證流程。
這個方法會啟動網頁檢視畫面，並導向至供應商驗證流程中的第一個網址，藉此啟用非 Google Identity 的驗證流程。當供應商重新導向至符合 https://<app-id>.chromiumapp.org/* 模式的網址時，視窗會關閉，最終重新導向網址會傳遞至 callback 函式。
為提供良好的使用者體驗，請務必在應用程式中透過 UI 啟動互動式驗證流程，說明授權用途。否則使用者會收到沒有背景資訊的授權要求。具體來說，請勿在應用程式首次啟動時，啟動互動式驗證流程。
參數
-
詳細資料
WebAuth 流程選項。
傳回
-
Promise<string | undefined>
Chrome 106 以上版本 Chrome 148 起為 browser.*傳回 Promise，其解析結果為重新導向回應用程式的網址。
removeCachedAuthToken()
browser.identity.removeCachedAuthToken(
details: InvalidTokenDetails,
): Promise<void>
從 Identity API 的權杖快取中移除 OAuth2 存取權杖。
如果發現存取權杖無效，應將其傳遞至 removeCachedAuthToken，從快取中移除。應用程式接著可以使用 getAuthToken 擷取新的權杖。
參數
-
詳細資料
權杖資訊。
傳回
-
承諾<void>
Chrome 106 以上版本 Chrome 148 起為 browser.*傳回 Promise，在權杖從快取中移除時解析。
事件
onSignInChanged
browser.identity.onSignInChanged.addListener(
callback: function,
)
使用者設定檔中的帳戶登入狀態變更時觸發。
參數
-
callback
函式
callback參數如下：(account: AccountInfo, signedIn: boolean) => void
-
帳戶
-
signedIn
布林值
-