Frame hierarchy

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

  • This website embeds an <iframe> with src =

  • This iframe contains an ad - an image with src =

In this example, the image has a frame hierarchy of:



By convention, the first element on the frame hierarchy is the immediate parent frame of the resource.


The Browser Ad-Filtering Solution 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: @@||^$document

This filter allows everything on the domain, 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, but also for $document-type allowing filters that match and

This is critical for correctly implementing the Acceptable Ads allowlists.


The frame hierarchy can be assembled by recursively following content::RenderFrameHost::GetParent() results.

See: FrameHierarchyBuilder

Last updated