webRequest.onBeforeRequest

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

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

addListener(callback, filter, extraInfoSpec)

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

removeListener(listener)

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

hasListener(listener)

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

callback

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

details

object. Детали запроса. Смотрите раздел details для получения дополнительной информации.

Возвращает: webRequest.BlockingResponse. Если "blocking" указано в параметре extraInfoSpec, обработчик события должен вернуть объект BlockingResponse, и может установить либо его свойство cancel, либо его свойство redirectUrl. Начиная с Firefox 52, вместо возврата BlockingResponse, обработчик может вернуть Promise, который разрешается с помощью BlockingResponse. Это позволяет обработчику обрабатывать запрос асинхронно.

filter

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

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

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

• "blocking": сделать запрос синхронным, чтобы вы могли отменить или перенаправить запрос
• "requestBody": включить requestBody в объект 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 этого фрейма, а не 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 будет URL документа в iframe, содержащем ссылку.

parentFrameId

integer. Идентификатор фрейма, содержащего фрейм, отправивший запрос. Устанавливается в -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. True, если прокси будет выполнять разрешение доменных имён на основе предоставленного имени хоста, что означает, что клиент не должен выполнять свой собственный поиск DNS.

failoverTimeout

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

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

object. Содержит данные тела HTTP-запроса. Предоставляется только если extraInfoSpec содержит "requestBody".

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

string. Устанавливается, если при получении данных тела запроса возникли ошибки.

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

object. Этот объект присутствует, если метод запроса POST, а тело представляет собой последовательность пар ключ-значение, закодированных в UTF-8 как "multipart/form-data" или "application/x-www-form-urlencoded".

Это словарь, в котором каждый ключ содержит список всех значений для этого ключа. Например: {'key': ['value1', 'value2']}. Если данные имеют другой тип носителя или если они неверны, объект не присутствует.

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

array webRequest.UploadData. Если метод запроса PUT или POST, и тело ещё не обработано в formData, то этот массив содержит необработанные элементы тела запроса.

requestId

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

tabId

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

thirdParty

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

timeStamp

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

type

webRequest.ResourceType. Тип запрашиваемого ресурса: например, "изображение", "скрипт", "стиль".

url

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

urlClassification

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

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: мета-флаг, объединяющий любые флаги социального отслеживания.

Что касается разрешения DNS при использовании BlockingResponse с OnBeforeRequest: в канале HTTP, onBeforeRequest с блокирующим ответом происходит до разрешения DNS и также до спекулятивного подключения. В других каналах спекулятивное подключение может привести к тому, что запросы DNS будут происходить до onBeforeRequest. Этот порядок не является чем-то, на чём должен полагаться разработчик расширения, так как он может меняться в разных браузерах и от одной версии браузера к другой, не говоря уже об одном канале запросов от другого. Обратитесь к разъяснению проблемы BugZilla, предоставленному разработчиками Mozilla по порядку разрешения DNS

Этот код регистрирует URL каждого запрошенного ресурса, соответствующего шаблону <all_urls>:

function logURL(requestDetails) {
  console.log(`Loading: ${requestDetails.url}`);
}

browser.webRequest.onBeforeRequest.addListener(
  logURL,
  {urls: ["<all_urls>"]}
);

Этот код отменяет запросы изображений, которые выполняются по URL, находящимся под "https://developer.mozilla.org/" (чтобы увидеть эффект, посетите любую страницу MDN, содержащую изображения, например, webRequest):

// match pattern for the URLs to redirect
let pattern = "https://developer.mozilla.org/*";

// cancel function returns an object
// which contains a property `cancel` set to `true`
function cancel(requestDetails) {
  console.log(`Canceling: ${requestDetails.url}`);
  return { cancel: true };
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  cancel,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);

Этот код заменяет все сетевые запросы изображений, которые выполняются по URL, находящимся под "https://developer.mozilla.org/", перенаправлением (чтобы увидеть эффект, посетите любую страницу MDN, содержащую изображения, например, webRequest):

// match pattern for the URLs to redirect
let pattern = "https://developer.mozilla.org/*";

// redirect function
// returns an object with a property `redirectURL`
// set to the new URL
function redirect(requestDetails) {
  console.log(`Redirecting: ${requestDetails.url}`);
  return {
    redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif"
  };
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  redirect,
  {urls:[pattern], types:["image"]},
  ["blocking"]
);

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

// match pattern for the URLs to redirect
let pattern = "https://developer.mozilla.org/*";

// URL we will redirect to
let redirectUrl = "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif";

// redirect function returns a Promise
// which is resolved with the redirect URL when a timer expires
function redirectAsync(requestDetails) {
  console.log(`Redirecting async: ${requestDetails.url}`);
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({ redirectUrl });
    }, 2000);
  });
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  redirectAsync,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);

Другой пример, который перенаправляет все изображения на URL данных:

let pattern = "https://developer.mozilla.org/*";

let image = `
  <svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%">
    <rect style="stroke-width: 10; stroke: #666;" width="100%" height="100%" fill="#d4d0c8" />
    <text transform="translate(0, 9)" x="50%" y="50%" width="100%" fill="#666" height="100%" style="text-anchor: middle; font: bold 10pt 'Segoe UI', Arial, Helvetica, Sans-serif;">Blocked</text>
  </svg>
`;

function listener(details) {
  const redirectUrl = `data:image/svg+xml,${encodeURIComponent(image)}`;
  return { redirectUrl };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);

Вот еще одна версия:

function randomColor() {
  return `#${Math.floor(Math.random()*16777215).toString(16)}`;
}

const pattern = "https://developer.mozilla.org/*";

let image = `
  <svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%">
    <rect width="100%" height="100%" fill="${randomColor()}"/>
  </svg>
`;

function listener(details) {
  const redirectUrl = `data:image/svg+xml,${encodeURIComponent(image)}`;
  return { redirectUrl };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);

• http-response