Tech Unblocker

Tag: AdBlock Anatomy

  • [AdBlock Anatomy] Run and Debug AdBlock Locally

    This article is starter of an anatomy series for dissecting AdBlock/AdBlockPlus/uBlockOrigin source code and learn how they work. First let’s start from running and debugging AdBlock locally.

    Note that this article is for eyeo owned browser extension AdBlock and AdBlockPlus.

    Source code

    Luckily, AdBlock main source entry is using NX monorepo, where we can easily see the dependency graph within the repo below.

    However, there are many core features are not within the monorepo, here is a list of important ones:

    • @eyeo/webext-ad-filtering-solution: most important core adblocking features shared across extensions.
    • @eyeo/snippets: eyeo developed special content scripts for element hiding and behavioral intercepting. This repo reflects everything from eyeo official developer document.
    • Filter list: eyeo developed filter list mostly leveraging @eyeo/snippets for enhanced blocking.
    • @adblockinc/rules: an npm package for retrieving, storing and providing filter lists from various sources for use in AdBlock and Adblock Plus.

    Installation

    Now let’s download the main source code and install packages:

    git clone https://gitlab.com/eyeo/extensions/extensions.git
cd extensions
npm install

    In often case if you are using Apple silicon chips, you will often see node-gyp errors like below:

    > npm ERR! gyp ERR! stack Error: `gyp` failed with exit code: 1

    The extensions repo provides some potential fixes, but below commends worked for me:

    python3 -m pip install setuptools
brew install pkg-config cairo pango libpng jpeg giflib librsvg

    Build extension

    Simply run below to build both AdBlock and AdBlockPlus extension:

    npm run build

    Add extensions to Chrome

    • Go to chrome://extensions/.
    • At the top right, turn on Developer mode.
    • Click Load unpacked.
    • Find and select the app or extension folder.
      • e.g. for Chrome AdBlockPlus with Manifest V2, it is located inside /extensions/host/adblockplus/dist/devenv/chrome-mv2

    Now you should be able to see the extension being added and enabled.

    Debugging @eyeo/webext-ad-filtering-solution

    In a lot of cases, the feature you are looking for is mostly in webext-ad-filtering-solution package. This package can be loaded as extension standalone.

    Installation

    git clone https://gitlab.com/eyeo/adblockplus/abc/webext-ad-filtering-solution.git
cd extensions
npm install

    Build and run in watch mode

    You can simply do npm run build, but I found it convenient to use watch mode:

    npx webpack --watch

    The built extensions can be found under dist folder

    • performance-mv2 for Manifest V2
    • performance-mv3 for Manifest V3

    Simply add desired extension to Chrome in dev mode for debugging.

    Debugging background script

    Let’s go to sdk/background/index.js and add some logging:

    ...
export async function start(addonInfo) {
  console.log("start extension");
  ...
}
...

    Then go to chrome://extensions/ and click on Inspect views -> background page (Service worker for Manifest V3 version) under eyeo's WebExtension Ad-Filtering Solution Test Extension.

    You should be able to see start extension log under Console tab. You can try reload extension if not seeing the log.

    Debugging content script

    Let’s go to sdk/content/index.js and add some logging:

    ...
async function initContentFeatures() {
  console.log("initContentFeatures");
  ...
}
...

    Open a new tab and go to any page, then open console and you should be able to see initContentFeatures log.