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