events.UrlFilter

Describes various criteria for filtering URLs. If all of the criteria specified in the filter's properties match the URL, then the filter matches. Filters are often provided to API methods in an Array of UrlFilters. For example, webNavigation listeners can be added with a filter which is an object with a single url property that is an Array of UrlFilters, e.g. {url:[UrlFilter, UrlFilter, …]}. If any filter within the Array of UrlFilters matches, then it is considered a match for the Array. Effectively, the criteria specified within a single filter are AND'ed together, while all of the individual filters within an Array are OR'ed.

All criteria are case sensitive.

Type

Values of this type are objects. They contain the following properties:

However, note that these last two patterns will not match the last component of the hostname, because no implicit dot is added at the end of the hostname. So for example, "org." will match https://borg.com but not https://example.org. To match these patterns, use hostSuffix.

hostContains Optional

string. Matches if the hostname of the URL (without protocol or port – see schemes and ports) contains the given string.

  • To test whether a hostname component starts with "foo", use ".foo". This matches www.foobar.com and foo.com, because an implicit dot is added at the beginning of the hostname.
  • To test whether a hostname component ends with "foo", use "foo.".
  • To test whether a hostname component exactly matches "foo", use ".foo.".
hostEquals Optional

string. Matches if the hostname of the URL is equal to a specified string.

  • Example: "www.example.com" matches http://www.example.com and https://www.example.com/, but not http://example.com/.
hostPrefix Optional

string. Matches if the hostname of the URL starts with a specified string.

hostSuffix Optional

string. Matches if the hostname of the URL ends with a specified string.

  • Example: ".example.com" matches http://www.example.com/, but not http://example.com/.
  • Example: "example.com" matches http://www.example.com/, and http://fakeexample.com/.
pathContains Optional

string. Matches if the path segment of the URL contains a specified string.

pathEquals Optional

string. Matches if the path segment of the URL is equal to a specified string.

pathPrefix Optional

string. Matches if the path segment of the URL starts with a specified string.

pathSuffix Optional

string. Matches if the path segment of the URL ends with a specified string.

queryContains Optional

string. Matches if the query segment of the URL contains a specified string.

queryEquals Optional

string. Matches if the query segment of the URL is equal to a specified string.

queryPrefix Optional

string. Matches if the query segment of the URL starts with a specified string.

querySuffix Optional

string. Matches if the query segment of the URL ends with a specified string.

urlContains Optional

string. Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

urlEquals Optional

string. Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

urlMatches Optional

string. Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number.

  • For example: urlMatches: "^[^:]*:(?://)?(?:[^/]*\\.)?mozilla\\.org/.*$" matches https://mozilla.org/, https://developer.mozilla.org/, but not https://developer.fakemozilla.org/.
originAndPathMatches Optional

string. Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number.

urlPrefix Optional

string. Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

  • Example: "https://developer" matches https://developer.mozilla.org/ and https://developers.facebook.com/.
urlSuffix Optional

string. Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number. Note that an implicit forward slash "/" is added after the host, so "com/" matches https://example.com, but "com" does not.

schemes Optional

array of string. Matches if the scheme of the URL is equal to any of the schemes specified in the array. Because schemes are always converted to lowercase, this should always be given in lowercase or it will never match.

  • Example: ["https"] will match only HTTPS URLs.
ports Optional

array of (integer or (array of integer)). An array which may contain integers and arrays of integers. Integers are interpreted as port numbers, while arrays of integers are interpreted as port ranges. Matches if the port of the URL matches any port number or is contained in any ranges.

  • For example: [80, 443, [1000, 1200]] matches all requests on ports 80, 443, and in the range 1000-1200.

Browser compatibility

BCD tables only load in the browser

Note: This API is based on Chromium's chrome.events API. This documentation is derived from events.json in the Chromium code.