Skip to content

Step by step documentation for fixing visible ads

Jump to bottom
cqx931 edited this page Aug 25, 2020 · 1 revision
  1. Is the ad a video ad?
  • If yes, go to step 2
  • If no, go to step 5
  1. Video ad
  • Is it visible when using ublock?
  • If no, continue to step 3.
  • If yes, then this is not an ADN-specific problem (though we may want to fix it anyway), continue to step 4.
  1. Block Adn-allowed requests
  • Open the logger and look for an blue-color entry(adnauseam-allowed)
  • Continue to step 5
  1. Block general requests
  • Open the logger and look for entries without background colors.
  • Follow step 5 and try to block requests that seem suspicious to you(they are most likely script or xhr requests).
  1. Hide with blocking rules
  • Try to block one request at a time using dynamic URL filtering rules, then refresh the page by hitting the refresh button.
  • If it works, use static network filters dialog box to assist you to write a static blocking rule. Once you are done, unblock the request from dynamic filtering and test your static blocking rule. If you can verify that the static rule works as well, add it to adnauseam.txt.
  1. Is it an image ad?
  • Some ads might look like image ad but they are not. You can double check whether an ad is a true image ad by right click on it and check it with "inspect element". If you can find an image file either in html or css(background image), go to step 7 [Image Ad]. If there is no image to be collected, or if it is composed of multiple small images, go to step 8 [Dynamic Ad]
  1. Image Ad
  • Try to first hide an image ad with cosmetic filters, continue to step 9
  • If the ad is hidden but not collected, please refer to this page for more guidance on ad collection
  • If under very rare cases, the annoying image ad can't be hidden using cosmetic filters no matter how hard you try, you still have the option to block it by following step 3.
  1. Text ads or Dynamic Ad
  • These ads can't be collected with cosmetic filters and you can either hide them by creating cosmetic filters(see step 9), or try to block it by following step 3.
  • Most of the time, we don't collect ads under this category other than common search engine text ads(see textads.js). But if it's visible on popular websites or if it's a very common ad type that appears across multiple sites, please refer to this FAQ if you want to create custom filters for text or hybrid ad.
  1. Hide with cosmetic rules
  • Cosmetic rules are similar to element selectors in javascript or jquery. For example, if there is an ad image inside an element with the class attribute 'adImage'. Adding a rule like ##.adImage will hide such an element. Typically we want to add cosmetic rules that are specific to the site we are working on example.com##.adImage. In principle, this is better because a general cosmetic filters (one applied to every site) might hide non-ad content on other websites and this is very difficult to properly test.
  • There are a number of tools you can use to help create cosmetic filters. If you're new to this, start with uBlock Origin's element picker(right click/block element), or you can always use the browser inspector. Sometimes uBlock's DOM inspector could also be helpful to identify the all the elements where cosmetic filters are triggered.
  • Once you have identified a rule using one of the tools above, you should test it by adding it to "Dashboard/My filters" in AdNauseam's settings and then click the button "Apply changes".
  • Refresh the web page you are testing and check whether the ad has been successfully hidden.
  • If it is not hidden, then you may need to adjust your cosmetic filter rule. Double-check the syntax or try to write an alternative rule using other class names, ids, or attributes. If none of these work, you might consider going to step 5 and checking whether there are "adn-allowed" javascript requests that make these ads difficult to hide with a cosmetic filter. Please keep in mind that we prioritize ad hiding over ad blocking, as long as we can collect the ad. But if ad collection is somehow not possible for certain ad types, we will then consider blocking it when cosmetic filters are not working.
  • Once the new rule is working as expected, you can then submit it for inclusion in AdNauseam itself. Do this by adding it the AdNauseam filter list and then making a 'Pull Request' on github (or if you don't know how to do this, simply send the rule, with a brief description, to adnauseam-at-rednoise.org).
  • More information on how to write your own cosmetic filters can be found here
  • In addition to basic cosmetic filters, as described above, you can also hide elements with procedural cosmetic filters. Procedural cosmetic filters are useful when there is no obvious id/class to target, but rather CSS attributes or more advanced selectors that relies on certain hierarchy of the Dom structure. It can be used on top of a plain CSS selector and supports more advanced element selection. It allows you to select a parent based on its child subject:has(arg), the textual contentsubject:has-text(needle), or even the CSS attribute subject:matches-css(arg). The syntax for this type of filter can be found here.

Element Selection Principles

a. The element should contain both the target URL (usually an <a> tag) and the image (the ad content). b. Try to collapse the ad (also hide extra wrapper with height)
c. The selectors should be specific to the site

<div class="adWrapper banner">
  <div>
    <a href="#">
      <img class="adImage">
    </a>
  </div>
</div>

Consider the DOM structure above as an example. We generally don't want to try and hide the image only, as AdNauseam (specifically the ad-clicking function) also need the ad's target URL. So in this case, the <a> tag would be the minimal DOM element with which we could hide the image and provide enough information for AdNauseam to collect and later click the ad. (Principle a.)

However, online ads are often hidden within layers and layers of wrappers. And sometimes these wrappers include CSS styles that set a fixed height. In these cases, we need to target the outermost wrapper, so that any extra blank space can be removed from the page. Another reason we generally target the wrapper instead of the <a> tag is that wrappers usually come with specific classes or ids, while it's less common for <a> tags to have those. (Principle b.)

Once we have decided the element we want to hide, we will need to choose the best selectors to write the cosmetic rule. In our example, the ad wrapper can be targeted by .banner and .adWrapper. Because .banner class is very common and we don't want to hide other banner images that are not advertisements, it's safer to write the following cosmetic rule example.com##.adWrapper. (Principle c.)

IFrames

<div class="adContainer">
  <iframe>
    <iframe>
      <div class="adWrapper banner">
        <div>
          <a href="#" id="adLink">
            <img class="adImage">
          </a>
        </div>
      </div>
    </iframe>
  <iframe>
</div>

Iframes are very common for online ads and in general they can be hidden following the principles described above. But there are extra factors you should take into consideration when writing cosmetic rules for ads in iframes:

d. The scope for Content Scripts Content Scripts are injected into each page as it loads. However, an iframe is not considered to be a part of the parent page. So any Content Scripts for the page needs to be re-injected into each iframe on each page.

In the example above, you will need to identify the innermost iframe and focus on ".adWrapper.banner" for our cosmetic filter in order to have access to the ad-content. A cosmetic rule targeting ".adContainer" might still be necessary, in order to eliminate blank space, but that rule alone is not enough for AdNauseam to properly collect the ad.

Wiki home

Clone this wiki locally