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"],
);

浏览器兼容性