PSA: Top-level frame domain matching with declarativeNetRequest rules
Dave Vandyke
Greetings fellow extension developers!
We are excited to announce that as of Chrome 141, we have added support for top-level frame domain matching to the declarativeNetRequest API.
While support for matching requests based on request domain (via the requestDomains and excludedRequestDomains rule conditions) and request initiator domain (via the initiatorDomains and excludedInitiatorDomains rule conditions) already exists, it is sometimes also necessary to match based on the request’s top-level frame domain. For that, we’ve added the new topDomains and excludedTopDomains rule conditions.
To give a concrete example, let’s say the website https://website.example contains an iframe that points to https://third-party.example, and that iframe in turn loads an image from https://images.example. For the image request, the request domain would be images.example, the request initiator domain would be third-party.example, and the top-level frame domain for the request would be website.example.
A rule like this:
{
"id": 1,
"priority": 1,
"condition": {
"resourceTypes": ["image"],
"requestDomains": ["images.example"],
"excludedTopDomains": ["website.example"]
},
"action": {
"type": "block"
}
}
Would allow the image request, since even though the request domain matches, the top-level frame domain exclusion applies. However, should the https://third-party.example page be loaded directly in the browser (instead of via the iframe), the image request would then be blocked.
From Chrome 145, feature detection for the new rule conditions is possible, at least for dynamic/session rules, by using the new RuleConditionKeys enum. For example:
if (chrome.declarativeNetRequest?.RuleConditionKeys?.EXCLUDED_TOP_DOMAINS)
{
/* Logic that makes use of excludedTopDomains */
}
Please give the changes a try, and let us know if you find any bugs!
Cheers, Dave.