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