About GitLab Acceptable Ads

Integrate the Solution

In this guide, you'll learn about the different ways you can integrate the eyeo Browser Ad-Filtering Solution into your own Chromium-based browser project.

Integration strategies

You can integrate eyeo's changes into your own Chromium project in three ways:

  • Strategy 1: Base your product on top of eyeo's changes

  • Strategy 2: Download modules and apply them to your source code

  • Strategy 3: Create a patch with changes and apply it to your source code

  • Strategy 4: Copy eyeo's functionality into your adapation

In the following sections, you'll learn the advantages of each strategy.

eyeo recommends Strategy 1.

Strategy 1: Base your product on top of eyeo's changes

If you use this strategy, you'll fork eyeo's Chromium form, then base your development on our release tag.

Benefits of Strategy 1:

  • It's the safest and most reliable way to integrate eyeo’s Browser Ad-Filtering Solution into your browser.

  • Full support from eyeo.

What you need to do

  • Use eyeo's tagged release commit as the parent of your changes. Begin with a git clone of our fork of Chromium and then add your changes. For more information, following the eyeo Browser Ad-Filtering Solution Quickstart guide, which is based on Strategy 1.

  • Make sure your users are properly informed about ad blocking and Acceptable Ads.

eyeo regularly informs you by email when a new version of the Solution is released. eyeo strives for beta releases for every Chromium version one week before the Chromium stable cut and official releases for odd Chromium releases within ten business days of the Chromium stable release.

Strategy 2: Download modules and apply them to your source code

If you use this strategy, you'll download modules of your choice and apply them to your source code.

Benefits and tradeoffs of Strategy 2:

  • Access to all major Solution functionalities.

  • Apply relevant code only, no internal eyeo testing files (for example, CI pipelines and configs).

  • Possibility to apply only needed part of our implementation.

  • More complex integration strategy than Strategy 1.

What you need to do

Make sure that the base version of Chromium you use in your project matches the Browser Ad-Filtering Solution version you are integrating.

Download modules

The module files are stored in the eyeo Browser Ad-Filtering Solution repository inside src/eyeo-modules directory. Identified by a release tag with a -modules suffix:

$ git checkout eyeo-release-113.0.5672.76-v1-modules

Optionally, modules can be downloaded. It won’t require adding eyeo's Browser Ad-Filtering Solution repository as remote.

$ wget "https://gitlab.com/eyeo/adblockplus/chromium-sdk/-/archive/eyeo-release-113.0.5672.76-v1-modules/chromium-sdk-eyeo-release-113.0.5672.76-v1-modules.zip?path=eyeo_modules" -O chromium-sdk-eyeo-release-113.0.5672.76-v1-modules.zip

Applying the module

Choose the modules that are relevant to your needs. Be aware that certain modules require the presence of other modules to be successfully applied.

base.patch:

  • This module provides the core Eyeo ad-filtering engine with all the latest features.

  • Note that it does not include a User Interface, and settings management needs to be implemented separately.

  • It must be applied as the first module.

chrome_integration.patch:

  • This module contains the necessary code for integrating our ad-filtering engine with the Chromium browser.

This module depends on base.patch

webview_integration.patch:

  • This module contains the necessary code for integrating our ad-filtering engine with Chromium WebView component.

This module depends on base.patch

android_api.patch:

  • This module provides the Android Java API for interacting with our ad-filtering engine.

This module can be applied either on chrome_integration.patch or webview_integration.patch

android_settings.patch:

  • This module introduces a simple Android Settings UI, presented as a Chromium settings page.

  • It supports multi-language translations for strings.

This module depends on android_api.patch applied on chrome_integration.patch

extension_api.patch:

  • This module introduces an API for managing Eyeo ad-filtering settings via extensions.

  • Note that it does not include an extension.

This module depends on chrome_integration.patch

content_shell.patch:

  • This module introduces an integration for the content layer.

  • This is just support for specific build target, no other module depends on it.

This module depends on base.patch

eyeo Browser Ad-Filtering Solution modules are designed to be applied with git am command:

$ git am eyeo_modules/base.patch
Strategy 3: create a patch with changes and apply it to your source code

If you use this strategy, you'll check out eyeo's fork of Chromium, generate a patch file (as a diff between the pure Chromium release tag and the eyeo Browser Ad-Filtering Solution release tag) and apply it to your source code.

Benefits and tradeoffs of Strategy 3:

  • Access to all major Solution functionalities

  • Higher risk of conflicts between eyeo and partner changes and more complicated resolution

  • More complex integration strategy than Strategy 1

  • Some information may get lost, which reduces eyeo's ability to provide support.

What you need to do

Make sure that the base version of Chromium you use in your project matches the eyeo Browser Ad-Filtering Solution version you are integrating.

Generating the patch

The diff file is generated with access to eyeo's git Chromium fork repository as a branch diff:

$ git diff 113.0.5672.76 eyeo-release-113.0.5672.76-v1 > ../eyeo-release-113.0.5672.76-v1.diff

Applying the patch

Run the following command to apply the patch:

$ git apply ../eyeo-release-113.0.5672.76-v1.diff
Strategy 4: copy eyeo's functionality into your adaption

If you use this strategy, you'll copy eyeo's functionality into your project.

Benefits and tradeoffs of Strategy 4:

  • Access to all major Solution functionalities.

  • Higher risk of conflicts between eyeo and partner changes and more complicated resolution.

  • More complex integration strategy than Strategies 1 and 2.

  • Additional information gets lost, which reduces our ability to provide support.

Strategy 3, the least safe approach, limits eyeo's ability to debug or support any issues.

What you need to do

  • Track the changed files and apply the changes one-by-one.

  • Copy and integrate all tracked changes.

  • Make sure that your integration supports all the filter options, UI elements and user counting features as required by your contract with eyeo.

You'll also need to ensure that user counting and all required ad filtering and whitelisting features work.

About automation

If you decide to automate the steps to copy eyeo's functionality into your adaptation, remember to:

  • Write the script files that automate the steps.

  • Update the scripts when branch/tag naming agreements are changed or the release flow is changed.

As with any automated, consider whether the time saved will compensate for the efforts to write and test the automation scripts. eyeo can help you decide, so reach out to us with any questions.

eyeo's versioning scheme

For an example Chromium release tag of 113.0.5672.76, eyeo's release tag would be eyeo-release-113.0.5672.76-v1.diff. This tag would contain all Solution-related changes, based on top of the corresponding Chromium release.

Because eyeo hosts the Browser Ad-Filtering Solution in remote Git repositories, you can find the Solution release for each version:

$ git ls-remote --tags https://gitlab.com/eyeo/adblockplus/chromium-sdk
$ git tag | grep release-103
eyeo-release-113.0.5672.76-v1

Usually, one release tag is available for each major Chromium version. Patch releases may also be available if eyeo finds a critical bug in the release.

Last updated