webRequest.onHeadersReceived

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

События имеют три функции:

addListener(callback, filter, extraInfoSpec)

Добавляет обработчик к этому событию.

removeListener(listener)

Прекращает прослушивание этого события. Аргумент listener — это обработчик для удаления.

hasListener(listener)

Проверяет, зарегистрирован ли listener для этого события. Возвращает true, если он прослушивает, и false, в противном случае.

callback

Функция, вызываемая при возникновении этого события. Функции передаются следующие аргументы:

details

object. Сведения о запросе. Это включает заголовки ответа, если вы включили "responseHeaders" в extraInfoSpec.

Возвращает: webRequest.BlockingResponse. Если "blocking" указано в параметре extraInfoSpec, обработчик события вернёт объект BlockingResponse, и сможет установить его свойство responseHeaders. В Firefox, возвращаемое значение может быть Promise, который разрешается в объект BlockingResponse.

filter

webRequest.RequestFilter. Набор фильтров, которые ограничивают события, отправляемые этому обработчику.

extraInfoSpec Необязательно

array string. Дополнительные параметры для события. Вы можете передать следующие значения:

• "blocking" для синхронного выполнения запроса, чтобы вы могли изменять заголовки запроса и ответа
• "responseHeaders" для включения заголовков ответа в объект details, переданный обработчику

cookieStoreId

string. Если запрос поступает из вкладки, открытой в контекстном идентитете, идентификатор хранилища cookie контекстного идентитета.

documentUrl

string. URL документа, в котором будет загружен ресурс. Например, если веб-страница по адресу "https://example.com" содержит изображение или iframe, то documentUrl для изображения или iframe будет "https://example.com". Для документа верхнего уровня documentUrl не определено.

frameAncestors

array. Информация для каждого документа в иерархии фреймов до документа верхнего уровня. Первый элемент массива содержит информацию об непосредственном родителе запрашиваемого документа, а последний — об документе верхнего уровня. Если загрузка выполняется для документа верхнего уровня, этот массив пуст.

url

string. URL, с которого загружен документ.

frameId

integer. frameId документа. details.frameAncestors[0].frameId совпадает с details.parentFrameId.

frameId

integer. Ноль, если запрос выполняется в главном фрейме; положительное значение — ID подфрейма, в котором происходит запрос. Если документ (под)фрейма загружается (type равен main_frame или sub_frame), frameId указывает ID этого фрейма, а не внешнего фрейма. Идентификаторы фреймов уникальны в рамках вкладки.

fromCache

boolean. Является ли ответ полученным из кэша на диске.

incognito

boolean. Поступает ли запрос из окна приватного просмотра.

ip

string. IP-адрес сервера, к которому был отправлен запрос. Может быть литеральным IPv6-адресом.

method

string. Стандартный HTTP-метод: например, "GET" или "POST".

originUrl

string. URL ресурса, который спровоцировал запрос. Например, если "https://example.com" содержит ссылку, и пользователь нажимает на неё, то originUrl для получившегося запроса — "https://example.com".

originUrl часто, но не всегда, совпадает с documentUrl. Например, если страница содержит iframe, а iframe содержит ссылку, которая загружает новый документ в iframe, то documentUrl для получившегося запроса — родительский документ iframe, но originUrl — URL документа в iframe, содержащего ссылку.

parentFrameId

integer. ID фрейма, содержащего фрейм, который отправил запрос. Установлено в -1, если родительского фрейма нет.

proxyInfo

object. Это свойство присутствует только если запрос проходит через прокси. Оно содержит следующие свойства:

host

string. Имя хоста сервера прокси.

port

integer. Номер порта сервера прокси.

type

string. Тип сервера прокси. Один из:

• "http": HTTP прокси (или SSL CONNECT для HTTPS)
• "https": HTTP проксирование через TLS-соединение с прокси
• "socks": SOCKS v5 прокси
• "socks4": SOCKS v4 прокси
• "direct": без прокси
• "unknown": неизвестный прокси

username

string. Имя пользователя для сервиса прокси.

proxyDNS

boolean. Истина, если прокси выполнит разрешение доменного имени на основе предоставленного имени хоста, что означает, что клиент не должен выполнять собственный поиск DNS.

failoverTimeout

integer. Таймаут переключения на резервный сервер в секундах. Если соединение с прокси прерывается, прокси не будет использоваться в течение этого периода.

requestId

string. Идентификатор запроса. Идентификаторы запросов уникальны в рамках сессии браузера, поэтому их можно использовать для связи различных событий, связанных с одним и тем же запросом.

responseHeaders Необязательно

webRequest.HttpHeaders. HTTP-заголовки ответа, полученные для этого запроса.

statusCode

integer. Стандартный HTTP-код состояния, возвращённый сервером.

statusLine

string. HTTP-строка состояния ответа или строка 'HTTP/0.9 200 OK' для ответов HTTP/0.9 (то есть для ответов, не имеющих строки состояния).

tabId

integer. Идентификатор вкладки, в которой происходит запрос. Установлено в -1, если запрос не связан с вкладкой.

thirdParty

boolean. Указывает, является ли запрос и его иерархия окон сторонней стороной.

timeStamp

number. Время срабатывания этого события в миллисекундах с момента эпохи.

type

webRequest.ResourceType. Тип запрашиваемого ресурса: например, "image", "script", "stylesheet".

url

string. Цель запроса.

urlClassification

object. Тип отслеживания, связанного с запросом, если он был классифицирован Firefox Tracking Protection. Это объект со следующими свойствами:

firstParty

array strings. Флаги классификации запроса для первой стороны.

thirdParty

array strings. Флаги классификации запроса или иерархии окон сторонних сторон.

Флаги классификации включают:

• fingerprinting и fingerprinting_content: указывает, что запрос участвует в определении характеристик. fingerprinting_content указывает, что запрос загружается из источника, который был обнаружен в определении характеристик, но не считается участвующим в отслеживании, например, поставщик платежных услуг.
• cryptomining и cryptomining_content: аналогично категории определения характеристик, но для ресурсов криптомайнинга.
• tracking, tracking_ad, tracking_analytics, tracking_social, и tracking_content: указывает, что запрос участвует в отслеживании. tracking — любой универсальный запрос отслеживания, суффиксы ad, analytics, social, и content идентифицируют тип трекера.
• any_basic_tracking: мета-флаг, который объединяет любые флаги отслеживания и определения характеристик, за исключением tracking_content и fingerprinting_content.
• any_strict_tracking: мета-флаг, который объединяет любые флаги отслеживания и определения характеристик, включая tracking_content и fingerprinting_content.
• any_social_tracking: мета-флаг, который объединяет любые флаги социального отслеживания.

Этот код устанавливает дополнительный cookie при запросе ресурса с целевого URL:

let targetPage = "https://developer.mozilla.org/en-US/Firefox/Developer_Edition";

// Add the new header to the original array,
// and return it.
function setCookie(e) {
  const setMyCookie = {
    name: "Set-Cookie",
    value: "my-cookie1=my-cookie-value1"
  };
  e.responseHeaders.push(setMyCookie);
  return { responseHeaders: e.responseHeaders };
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookie,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"]
);

Этот код делает то же самое, что и предыдущий пример, за исключением того, что обработчик асинхронный, возвращая Promise, который разрешается новыми заголовками:

const targetPage = "https://developer.mozilla.org/en-US/Firefox/Developer_Edition";

// Return a Promise that sets a timer.
// When the timer fires, resolve the promise with
// modified set of response headers.
function setCookieAsync(e) {
  const asyncSetCookie = new Promise((resolve, reject) => {
    setTimeout(() => {
      const setMyCookie = {
        name: "Set-Cookie",
        value: "my-cookie1=my-cookie-value1"
      };
      e.responseHeaders.push(setMyCookie);
      resolve({ responseHeaders: e.responseHeaders });
    }, 2000);
  });

  return asyncSetCookie;
}

// Listen for onHeaderReceived for the target page.
// Set "blocking" and "responseHeaders".
browser.webRequest.onHeadersReceived.addListener(
  setCookieAsync,
  { urls: [targetPage] },
  ["blocking", "responseHeaders"]
);