chrome.identity

說明

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

權限

identity

類型

AccountInfo

屬性

  • id

    字串

    帳戶的專屬 ID。在帳戶的效期內，這個 ID 將維持不變。

AccountStatus

Chrome 84 以上版本

列舉

"SYNC"
表示主要帳戶已啟用同步功能。

"ANY"
指明主要帳戶是否存在 (如果有的話)。

GetAuthTokenResult

Chrome 105 以上版本

屬性

  • grantedScopes

    string[] 選填

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

  • 權杖

    字串 選用

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

InvalidTokenDetails

屬性

  • 權杖

    字串

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

ProfileDetails

Chrome 84 以上版本

屬性

  • accountStatus

    AccountStatus 選用

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

ProfileUserInfo

屬性

  • 電子郵件

    字串

    登入目前個人資料的使用者帳戶電子郵件地址。如果使用者未登入，或是未指定 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 時才會生效。

  • url

    字串

    啟動驗證流程的網址。

方法

clearAllCachedAuthTokens()

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

重設 Identity API 的狀態：

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 106 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getAccounts()

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

擷取 AccountInfo 物件清單，描述設定檔中的帳戶。

getAccounts 僅適用於開發人員版本。

參數

傳回

  • Promise<AccountInfo[]>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getAuthToken()

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

透過 manifest.json 的「oauth2」部分中指定的用戶端 ID 和範圍，取得 OAuth2 存取權杖。

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

為提供優質的使用者體驗，請務必在應用程式中透過使用者介面發出互動式權杖要求，藉此說明授權的用途。否則將導致使用者收到授權要求或 Chrome 登入畫面 (如未登入，且沒有內容)。特別是在應用程式首次啟動時，請勿以互動方式使用 getAuthToken。

注意： 使用回呼呼叫時，此函式不會傳回物件，而是將兩個屬性以個別引數傳回至回呼。

參數

傳回

  • Chrome 105 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getProfileUserInfo()

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

擷取登入設定檔的使用者電子郵件地址和模糊化的 GAIA ID。

需要 identity.email 資訊清單權限。否則，系統會傳回空白結果。

這個 API 與 Identity.getAccounts 有兩項不同。傳回的資訊可供離線查看，且僅適用於商家檔案的主要帳戶。

參數

傳回

  • Promise<ProfileUserInfo>

    Chrome 106 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getRedirectURL()

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

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

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

參數

  • path

    字串 選用

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

傳回

  • 字串

launchWebAuthFlow()

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

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

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

為了提供良好的使用者體驗，請務必讓應用程式中的使用者介面啟動互動式驗證流程，藉此說明授權的用途。如果不這麼做，使用者會收到授權要求，且不會提供任何內容。具體來說，應用程式首次啟動時，請勿啟動互動式驗證流程。

參數

  • 詳細資料

    WebAuthFlowDetails

    WebAuth 流程選項。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (responseUrl?: string)=>void

    • responseUrl

      字串 選用

傳回

  • Promise<string|undefined>

    Chrome 106 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeCachedAuthToken()

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

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

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

參數

  • 詳細資料

    InvalidTokenDetails

    權杖資訊。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 106 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onSignInChanged

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

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