webRequest.onSendHeaders

語法

browser.webRequest.onSendHeaders.addListener(
  listener,             // function
  filter,               //  object
  extraInfoSpec         //  optional array of strings
)
browser.webRequest.onSendHeaders.removeListener(listener)
browser.webRequest.onSendHeaders.hasListener(listener)

事件有三個函式

addListener(listener, filter, extraInfoSpec)

向此事件新增監聽器。

removeListener(listener)

停止監聽此事件。listener 引數是要移除的監聽器。

hasListener(listener)

檢查 listener 是否已為此事件註冊。如果正在監聽，則返回 true，否則返回 false。

addListener 語法

引數

監聽器

當此事件發生時呼叫的函式。該函式將傳遞此引數

details

object。有關請求的詳細資訊。有關更多資訊，請參閱 details 部分。

filter

webRequest.RequestFilter。一個過濾器，限制傳送給此監聽器的事件。

extraInfoSpec 可選

string 型別的 array。事件的額外選項。您只能在此處傳遞一個值

• "requestHeaders"：在傳遞給監聽器的 details 物件中包含請求頭

額外物件

details

cookieStoreId

string。如果請求來自上下文身份中開啟的標籤頁，則為上下文身份的 cookie 儲存 ID。有關更多資訊，請參閱使用上下文身份。

documentUrl

string。資源將載入到的文件的 URL。例如，如果“https://example.com”上的網頁包含影像或 iframe，則影像或 iframe 的 documentUrl 將是“https://example.com”。對於頂級文件，documentUrl 未定義。

frameId

integer。如果請求發生在主框架中，則為 0；如果請求發生在子框架中，則為正數，表示子框架的 ID。如果（子）框架的文件已載入（type 為 main_frame 或 sub_frame），則 frameId 表示此框架的 ID，而不是外層框架的 ID。框架 ID 在標籤頁內是唯一的

incognito

boolean。請求是否來自隱私瀏覽視窗。

method（方法）

string。標準 HTTP 方法：例如，“GET”或“POST”。

originUrl

string。觸發請求的資源的 URL。例如，如果“https://example.com”包含一個連結，並且使用者點選該連結，則生成請求的 originUrl 為“https://example.com”。

originUrl 通常但不總是與 documentUrl 相同。例如，如果一個頁面包含一個 iframe，並且 iframe 包含一個將新文件載入到 iframe 中的連結，則生成請求的 documentUrl 將是 iframe 的父文件，但 originUrl 將是包含連結的 iframe 中文件的 URL。

parentFrameId

integer。包含傳送請求的幀的父幀的 ID。如果沒有父幀，則設定為 -1。

proxyInfo

object。此屬性僅在請求透過代理時存在。它包含以下屬性：

主機

string。代理伺服器的主機名。

port

integer。代理伺服器的埠號。

type

string。代理伺服器的型別。以下之一：

• "http"：HTTP 代理（或 HTTPS 的 SSL CONNECT）
• "https"：透過 TLS 連線到代理的 HTTP 代理
• "socks"：SOCKS v5 代理
• "socks4"：SOCKS v4 代理
• "direct"：無代理
• "unknown"：未知代理

username

string。代理服務的使用者名稱。

proxyDNS

boolean。如果代理將根據提供的主機名執行域名解析，這意味著客戶端不應自行進行 DNS 查詢，則為 True。

failoverTimeout

integer。故障轉移超時（秒）。如果代理連線失敗，在此期間將不再使用該代理。

requestId

string。請求的 ID。請求 ID 在瀏覽器會話中是唯一的，因此您可以使用它們來關聯與同一請求相關的不同事件。

requestHeaders 可選

webRequest.HttpHeaders。與此請求一起發出的 HTTP 請求頭。

tabId

integer。請求發生所在標籤頁的 ID。如果請求與標籤頁無關，則設定為 -1。

thirdParty

boolean。指示請求及其內容視窗層次結構是否是第三方。

timeStamp

number。此事件觸發的時間，以紀元以來的毫秒數表示。

type

webRequest.ResourceType。正在請求的資源型別：例如，“image”、“script”、“stylesheet”。

url

string。請求的目標。

urlClassification

object。如果請求被Firefox 跟蹤保護分類，則與請求關聯的跟蹤型別。這是一個包含以下屬性的物件：

firstParty

array 型別的 string。請求的第一方分類標誌。

thirdParty

array 型別的 string。請求或其視窗層次結構的第三方分類標誌。

分類標誌包括：

• fingerprinting 和 fingerprinting_content：表示請求涉及指紋識別（“發現指紋識別的來源”）。
  • fingerprinting 表示該域屬於指紋識別和跟蹤類別。此類域的示例包括希望將配置檔案與訪問使用者關聯的廣告商。
  • fingerprinting_content 表示該域屬於指紋識別類別但不屬於跟蹤類別。此類域的示例包括使用指紋識別技術識別訪問使用者以進行反欺詐目的的支付提供商。
• cryptomining 和 cryptomining_content：類似於指紋識別類別，但用於加密挖礦資源。
• tracking、tracking_ad、tracking_analytics、tracking_social 和 tracking_content：表示請求涉及跟蹤。tracking 是任何通用跟蹤請求，ad、analytics、social 和 content 字尾標識跟蹤器的型別。
• emailtracking 和 emailtracking_content：表示請求涉及跟蹤電子郵件。
• any_basic_tracking：一個元標誌，結合了跟蹤和指紋識別標誌，不包括 tracking_content 和 fingerprinting_content。
• any_strict_tracking：一個元標誌，結合了所有跟蹤和指紋識別標誌。
• any_social_tracking：一個元標誌，結合了所有社交跟蹤標誌。

您可以在 disconnect.me 網站上找到有關跟蹤器型別的更多資訊。content 字尾表示跟蹤並提供內容的跟蹤器。阻止它們可以保護使用者，但也可能導致網站損壞或元素無法顯示。

示例

此程式碼會記錄在向目標 匹配模式 傳送請求時將傳送的所有 cookie。

// The target match pattern
let targetPage = "*://*.google.ca/*";

// Log cookies sent with this request
function logCookies(e) {
  for (const header of e.requestHeaders) {
    if (header.name === "Cookie") {
      console.log(header.value);
    }
  }
}

// Listen for onSendHeaders, and pass
// "requestHeaders" so we get the headers
browser.webRequest.onSendHeaders.addListener(
  logCookies,
  { urls: [targetPage] },
  ["requestHeaders"],
);

瀏覽器相容性