Integrate the SDK
In this guide, you'll learn about the different ways you can integrate the eyeo Chromium SDK into your own Chromium-based browser project.
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.
If you use this strategy, you'll fork eyeo's Chromium form, then base your development on our release tag.
Benefits of Strategy 1:
- Safest and most reliable way to integrate eyeo’s Chromium SDK into your browser.
- Full support from eyeo.
- 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 Chromium SDK 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 eyeo Chromium SDK 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.
If you use this strategy, you'll download modules of your choice and apply them to your source code.
Benefits and trade-offs of Strategy 2:
- Access to all major SDK functionalities.
- Apply relevant code only, no internal eyeo testing files (eg. CI pipelines configs).
- Possibility to apply only needed part of our implementation.
- More complex integration strategy than Strategy 1.
Make sure that the base version of Chromium you use in your project matches the eyeo Chromium SDK version you are integrating.
Download modules
The module files are stored in the eyeo Chromium SDK repository inside src/eyeo-patches directory. Identified by a release tag with a
-patches suffix:$ git checkout eyeo-release-113.0.5672.76-v1-patches
Optionally, modules can be downloaded. It won’t require adding eyeo Chromium SDK repository as remote.
$ wget "https://gitlab.com/eyeo/adblockplus/chromium-sdk/-/archive/eyeo-release-113.0.5672.76-v1-patches/chromium-sdk-eyeo-release-113.0.5672.76-v1-patches.zip?path=eyeo_patches" -O chromium-sdk-eyeo-release-113.0.5672.76-v1-patches.zip
Applying the module
Select the module you need.
Base.patch:
- You get eyeo ad-filtering engine with all newest features. No User Interface comes with this module, settings management needs implementation.
- Has to be applied as first module Android_settings.patch:
- Simple Android Settings UI, presented as chromium settings page. Multi-language support provided (strings translations). Extension_api.path:
- Introduces API to manage eyeo ad-filtering settings via extensions. No extension provided.
Eyeo Chromium SDK modules are designed to be applied with
git am command:$ git am eyeo_patches/base.patch
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 Chromium SDK release tag) and apply it to your source code.
Benefits and tradeoffs of Strategy 2:
- Access to all major SDK 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.
Make sure that the base version of Chromium you use in your project matches the eyeo Chromium SDK 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
If you use this strategy, you'll copy eyeo's functionality into your project.
Benefits and tradeoffs of Strategy 3:
- Access to all major SDK 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.
- 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.
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.
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 SDK-related changes, based on top of the corresponding Chromium release.Because eyeo hosts the eyeo Chromium SDK in remote Git repositories, you can find the eyeo Chromium SDK 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 modified 17d ago