Frame hierarchy is a term coined by eyeo. It represents a list of URLs where each element is embedded by the next one.
As an example, consider:
- A website's main page is https://example.com
- This website embeds an
src = https://iframe.com/content.html
- This iframe contains an ad - an image with
src = https://ads.com/ad.png
In this example, the image
https://ads.com/ad.pnghas a frame hierarchy of:
By convention, the first element on the frame hierarchy is the immediate parent frame of the resource.
The SDK uses the frame hierarchy to establish whether allowing filters exist for parents of a resource.
Consider a blocking filter:
This filter matches the URL of the ad image. When a website loads, a resource classifier will mark the image as an ad and stop the request from leaving the browser.
Now consider an allowing filter:
This filter allows everything on the
example.comdomain, it overrides any blocking filters.
If both filters are present, the resource classifier should allow the ad from this particular frame hierarchy to load. But the same ad loaded from a different frame hierarchy might still be blocked.
The resource classifier searches not only for blocking and allowing filters that match
https://ads.com/ad.png, but also for
$document-type allowing filters that match
This is critical for correctly implementing the Acceptable Ads allowlists.
The frame hierarchy can be assembled by recursively following