chrome.identity

說明

使用 chrome.identity API 取得 OAuth2 存取權杖。

權限

identity

類型

AccountInfo

屬性

  • id

    字串

    帳戶的專屬 ID。在帳戶效期內，這個編號不會改變。

AccountStatus

Chrome 84 以上版本

列舉

"SYNC"
指定已為主要帳戶啟用同步功能。

「ANY」
指定主要帳戶 (如果有的話) 的存在。

GetAuthTokenResult

Chrome 105 以上版本

屬性

  • grantedScopes

    string[] 選填

    已授予擴充功能的 OAuth2 範圍清單。

  • token

    string optional

    與要求相關聯的特定權杖。

InvalidTokenDetails

屬性

  • token

    字串

    應從快取中移除的特定權杖。

ProfileDetails

Chrome 84 以上版本

屬性

  • accountStatus

    AccountStatus 選用

    主要帳戶登入設定檔的狀態，應傳回其 ProfileUserInfo。預設為「SYNC」帳戶狀態。

ProfileUserInfo

屬性

  • 電子郵件

    字串

    登入目前設定檔的使用者帳戶電子郵件地址。如果使用者未登入，或未指定 identity.email 資訊清單權限，則為空白。

  • id

    字串

    帳戶的專屬 ID。在帳戶效期內，這個編號不會改變。如果使用者未登入，或未指定 identity.email 資訊清單權限 (在 M41 以上版本)，則為空白。

TokenDetails

屬性

  • 帳戶

    AccountInfo 選用

    應傳回其權杖的帳戶 ID。如未指定，則函式將使用 Chrome 設定檔的帳戶 (如果有的話)：同步帳戶 (如果有的話)，或第一個 Google 網路帳戶。

  • enableGranularPermissions

    布林值 選填

    Chrome 87 以上版本

    enableGranularPermissions 旗標可讓擴充功能提前開啟精細的權限同意畫面，並個別授予或拒絕要求的權限。

  • 互動

    布林值 選填

    擷取權杖時，使用者可能需要登入 Chrome，或核准應用程式要求的範圍。如果互動旗標為 true，getAuthToken 會視需要提示使用者。如果旗標為 false 或省略，則每當需要提示時，getAuthToken 就會傳回失敗。

  • 範圍

    string[] 選填

    要求 OAuth2 範圍的清單。

    如果 scopes 欄位存在，則會覆寫 manifest.json 指定的範圍清單。

WebAuthFlowDetails

屬性

  • abortOnLoadForNonInteractive

    布林值 選填

    Chrome 113 以上版本

    是否要在網頁載入後，針對非互動要求終止 launchWebAuthFlow。這個參數不會影響互動流程。

    如果設為 true (預設值)，資料流會在網頁載入後立即終止。如果設為 false，則只有在 timeoutMsForNonInteractive 通過後，資料流才會終止。使用 JavaScript 在網頁載入後執行重新導向的識別資訊提供者非常實用。

  • 互動

    布林值 選填

    是否以互動模式啟動驗證流程。

    由於部分驗證流程可能會立即重新導向至結果網址，因此 launchWebAuthFlow 會隱藏網頁檢視畫面，直到首次導覽系統重新導向到最終到達網址，或完成載入即將顯示的網頁為止。

    如果 interactive 旗標為 true，當網頁載入完成時，就會顯示視窗。如果旗標為 false 或省略，當初始導覽未完成流程時，launchWebAuthFlow 會傳回錯誤。

    如果是使用 JavaScript 重新導向的流程，則可將 abortOnLoadForNonInteractive 與設定 timeoutMsForNonInteractive 一起設為 false，讓網頁有機會執行任何重新導向。

  • timeoutMsForNonInteractive

    編號 選填

    Chrome 113 以上版本

    系統允許的時間上限 (以毫秒為單位)，launchWebAuthFlow總共可在非互動模式下執行。只有 interactive 為 false 時，才會生效。

  • 網址

    字串

    啟動驗證流程的網址。

方法

clearAllCachedAuthTokens()

Promise Chrome 87 以上版本 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

重設 Identity API 的狀態：

  • 從權杖快取中移除所有 OAuth2 存取權杖
  • 移除使用者帳戶偏好設定
  • 在所有驗證流程中取消使用者授權

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 106 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAccounts()

Promise 開發人員版 
chrome.identity.getAccounts(
  callback?: function,
)

擷取 AccountInfo 物件清單，說明設定檔中顯示的帳戶。

只有開發人員版本支援 getAccounts。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (accounts: AccountInfo[]) => void

傳回

  • Promise&lt;AccountInfo[]&gt;

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAuthToken()

Promise 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

使用 manifest.json 部分 指定的用戶端 ID 和範圍取得 OAuth2 存取權杖。oauth2

Identity API 會將存取權杖快取在記憶體中，因此可以在需要權杖時，以非互動方式呼叫 getAuthToken。權杖快取會自動處理到期時間。

為提供良好的使用者體驗，應用程式的使用者介面會啟動重要的互動式權杖要求，並說明授權的用途。如果不這樣做，將會導致使用者收到授權要求，或者在未登入且沒有內容的情況下，使用者會看到 Chrome 登入畫面。請特別注意，請勿在應用程式首次啟動時以互動方式使用 getAuthToken。

注意： 透過回呼呼叫時，此函式會傳回兩個屬性，做為傳遞至回呼的個別引數，而不是傳回物件。

參數

傳回

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getProfileUserInfo()

Promise 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

擷取登入個人資料的使用者電子郵件地址，以及經過模糊處理的 GAIA ID。

必須具備 identity.email 資訊清單權限。否則，系統會傳回空白結果。

這個 API 與 Identity.getAccounts 有兩個不同。傳回的資訊可以離線瀏覽，而且只適用於設定檔的主要帳戶。

參數

傳回

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
)

產生要在 launchWebAuthFlow 中使用的重新導向網址。

產生的網址會符合以下模式：https://<app-id>.chromiumapp.org/*。

參數

  • 路徑

    string optional

    附加至產生的網址結尾的路徑。

傳回

  • 字串

launchWebAuthFlow()

Promise 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

在指定網址啟動驗證流程。

這個方法會啟動網頁檢視畫面，並導覽至供應器驗證流程中的第一個網址，透過非 Google 識別資訊提供者驗證流程。當供應商重新導向至符合模式 https://<app-id>.chromiumapp.org/* 的網址時，視窗將會關閉，最終重新導向網址會傳遞至 callback 函式。

為提供良好的使用者體驗，應用程式的使用者介面會啟動重要的互動式驗證流程，並說明授權的用途。如未提供這項資訊，使用者將會收到沒有背景資訊的授權要求。請特別注意，請勿在應用程式首次啟動時啟動互動式驗證流程。

參數

  • 詳細資料

    WebAuthFlowDetails

    WebAuth 流程選項，

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (responseUrl?: string) => void

    • responseUrl

      string optional

傳回

  • Promise<字串 |未定義>

    Chrome 106 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

removeCachedAuthToken()

Promise 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

從 Identity API 的憑證快取中移除 OAuth2 存取權杖。

如果發現存取權杖無效，則應傳送該憑證至 removeCachedAuthToken，將其從快取中移除。接著，應用程式可能會使用 getAuthToken 擷取新的權杖。

參數

  • 詳細資料

    InvalidTokenDetails

    權杖資訊。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 106 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

在使用者設定檔中的帳戶登入狀態變更時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (account: AccountInfo, signedIn: boolean) => void