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

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

ProfileUserInfo

屬性

  • 電子郵件

    字串

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

  • id

    字串

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

TokenDetails

屬性

  • 帳戶

    AccountInfo 選用

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

  • enableGranularPermissions

    布林值 選填

    Chrome 87 以上版本

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

  • 互動

    布林值 選填

    擷取權杖時,使用者可能需要登入 Chrome,或核准應用程式要求的範圍。如果互動旗標為 truegetAuthToken 會視需要提示使用者。如果旗標為 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總共可在非互動模式下執行。只有 interactivefalse 時,才會生效。

  • 網址

    字串

    啟動驗證流程的網址。

方法

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 函式。

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

參數

  • 詳細資料

    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 擷取新的權杖。

參數

  • 詳細資料

    權杖資訊。

  • 回呼

    函式 選用

    callback 參數如下所示:

    () => void

傳回

  • 承諾<void>

    Chrome 106 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onSignInChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示:

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