Testing
On this page, you'll find key information you'll need to test your integration.
Android
Desktop
If you chose to use the default Settings UI, you will find it in the lower part of Chromium's Settings pane. It contains the following settings:
- 1.Ad blocking: Enable/Disable ad filtering for the entire browser. Toggling this button off also disables all other menu options.
- 2.Filter lists: Select which filter lists are installed.
- 3.Acceptable Ads: Enable/Disable Acceptable Ads. When this switch is enabled, the browser shows Acceptable Ads.
- 4.Allowlist: Maintain a list of domains on which ad filtering is disabled. No ads will be hidden or blocked on these domains.
The desktop integration has no settings UI. You can install the eyeo Chromium Settings web extension if you want to change the settings.
Follow these steps to install the extension:
- 1.Clone the extension repository:
git clone [email protected]:eyeo/distpartners/eyeo-chromium-settings-web-extension.git
- 2.Open the eyeo Chromium SDK desktop browser.
- 3.Go to
chrome://extensions/
- 4.Enable Developer mode.
- 5.Select
Load Unpacked.
- 6.Select
src
directory of this repository.
The extension provides similar options to the Android Settings UI.
Android
Desktop
Advanced users or QA/Testers can unlock
More Blocking Options
by toggling the Ad blocking
switch 10 times.In this menu, you can add or remove the following:
- Custom filter lists, like
https://abptestpages.org/en/abp-testcase-subscription.txt
- Custom filters, like
||abptestpages.org/testfiles/document/*
Custom filters and custom filter lists can break website rendering. Discourage regular users from changing these settings.
You can test the desktop integration with the web extension. You can control the extension manually, or using a URL with the following parameters:
chrome-extension://enhmmofhlghlobfiihniipglbbnjbigl/index.html?function=value
. For more on functions, refer to the eyeo Chromium Settings Web Extension.You can add or remove (through URL):
- Custom filter lists, like
chrome-extension://enhmmofhlghlobfiihniipglbbnjbigl/index.html?installSubscription=https://abptestpages.org/en/abp-testcase-subscription.txt
- Custom filters, like
chrome-extension://enhmmofhlghlobfiihniipglbbnjbigl/index.html?addCustomFilter=||abptestpages.org/testfiles/document/*
The following use cases can help you verify that ad filtering works in your browser.
Use Case 1: Verify ads are blocked when ad blocking is on and Acceptable Ads are off.
Given I have ad blocking enabled and AA disabled on eyeo Chromium SDK
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are not displayed.
Scenario 2: Verify ads are blocked when ad blocking is on and Acceptable Ads are on.
Given I have ad blocking enabled and AA disabled on eyeo Chromium SDK
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are displayed.
Scenario 3: Verify ads are blocked when ad blocking is off.
Given I have ad blocking disabled on eyeo Chromium SDK
When I open "https://www.ask.com"
And search for "laptops"
Then I verify that ads are displayed.
Scenario 4: Verify allowlisting feature is working properly.
Given I have ad blocking enabled
When I add www.wikihow.com to allowlisted domains and
And open a subpage on www.wikihow.com
Then I verify that ads are displayed
ABP test pages are designed to test ad-filtering code against various types of HTML elements in a controlled environment.
Enable More Blocking Options to run these tests.
- 1.On the
More blocking options
screen, selectCustom Filter lists
. - 2.Enter the URL
https://abptestpages.org/en/abp-testcase-subscription.txt
in the text field and select the + icon. - 3.
- 4.Verify that you see green boxes, according to the descriptions of the test cases.
You can also try adding custom filters rather than a custom filter list, which avoids unexpected interplay between filters defined for different test cases.
- 1.Navigate to ABP Test Pages and click on the page you wish to test. For example:
https://abptestpages.org/en/filters/blocking
. - 2.Copy the filter mentioned on the test page corresponding to the scenario under test.
- 3.On the
More blocking options
screen, selectCustom Filters
. - 4.Paste the filter to the custom filter field and refresh the page under test.
- 5.Verify the test state matches the test case description, typically by showing a green box.
eyeo Chromium SDK uses filter lists to filter ads. Filter lists define which web resources should be blocked or hidden.
On first run, the browser will attempt to download and install the following default filter lists:
The SDK attempts to select a language-specific filter list of Easylist, for example Easylist+spanish if the device's language is Spanish. Not all languages have corresponding filter lists.
It will take a couple of seconds to download and install these lists. Users can browse the web while this is happening. The SDK falls back to built-in, preloaded variants of the default lists to provide some level of ad-filtering.
The SDK downloads filter lists when:
- The browser starts for the first time and the default lists are installed
- The user selects a new list in the Filter lists menu
- The user adds a new custom filter list in the More Blocking Options menu
- A filter list expires and needs to be updated
Every filter list download is a GET request to the URL of the filter list with a set of extra GET parameters.
The SDK reports some information to eyeo through GET parameters added to the URL of each filter list.
This information preserves the user's anonymity and is used for the following:
- Count how many active users your browser attributes to the Acceptable Ads program
- Collect insights about what platforms eyeo should focus development efforts on
Parameter | Value |
---|---|
addonName | eyeo-chromium-sdk |
addonVersion | 1.0 |
application | The name of for your product. |
applicationVersion | Follows Chromium's versioning by default, but can be overridden to reflect your product's version. |
platform | Windows , MacOSX , Linux or Android , depending on the operating system. |
platformVersion | 1.0 |
lastVersion | Version of the filter list that is being updated, for example 202111101251 . The version is normally parsed from the filter list's "! Version: 202111101251" header comment. 0 if it's a new download or when a filter list doesn't declare a version. |
disabled | true when Acceptable Ads is disabled in settings, false if it's enabled. |
downloadCount | Total number of successful update downloads of the subscription. For anonymity reasons, restricted to a value between 0 and 4+ . |
An example:
https://easylist-downloads.adblockplus.org/exceptionrules.txt?addonName=eyeo-chromium-sdk&addonVersion=1.0&application=Chromium&applicationVersion=110.0.5476.3&platform=Linux&platformVersion=1.0&lastVersion=202301021041&disabled=false&downloadCount=3
The SDK performs periodic pings to monitor how many users have disabled Acceptable Ads.
A ping is a HEAD-type filter list download request similar to ordinary filter list download requests. Because it's a HEAD (and not GET) request, the server will not respond with filter list content and the browser will not download Acceptable Ads. However, the server will be made aware of the user's existence.
While Acceptable Ads is disabled, pings are sent every 24 hours. They are visible as HEAD requests to:
https://easylist-downloads.adblockplus.org/exceptionrules.txt?addonName=eyeo-chromium-sdk&...&disabled=true
The browser updates the filter lists according to their expiration times - typically every 24 hours. To check if filter lists are updated upon expiration, do the following:
- 1.Let all the default filter lists download successfully.
- 2.On Android, force stop the application.
- 3.Navigate to phone settings to advance the time by 25 hours.
- 4.Launch the application.
- 5.Filter lists download requests should be sent to the server with an increased
downloadCount
in request parameter. - 6.If you have enabled VLOGs, you should see relevant logs in the system console, for example:
... [eyeo] Running update check
... [eyeo] Updating expired subscription https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt
... [eyeo] Downloading https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt?addonName=eyeo-chromium-sdk&...&downloadCount=4+
... [eyeo] Finished downloading https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt, starting conversion
... [eyeo] Finished converting https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt successfully
... [eyeo] Updated subscription https://easylist-downloads.adblockplus.org/abp-filters-anti-cv.txt, current version 202301121221
- 1.The browser sends an eyeometry ping every 12 hours. You should see it in browser logs if you have enabled VLOGs.
... [eyeo] Telemetry request for https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1 is due
... [eyeo] Telemetry request for https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1 starting now
... [eyeo] Sending request to: https://eyeo-chromium.telemetry.eyeo.com/topic/eyeochromium_activeping/version/1
... [eyeo] Telemetry ping succeeded
- 2.If you see this line in the logs, your product wasn't built with a valid
client id
[eyeo] Using default Telemetry server since a Telemetry client ID was not provided. Users will not be counted correctly by eyeo. Please set an ID via "eyeo_telemetry_client_id" gn argument.`
- 3.If you see this line in the logs, your product wasn't built with a valid
auth token
[eyeo] No Telemetry authentication token defined. Users will not be counted correctly by eyeo. Please set a token via "eyeo_telemetry_activeping_auth_token" gn argument.
eyeo Chromium SDK uses the following levels of logging:
- 1.
LOG(INFO/WARNING/ERROR)
- These logs appear in all builds. These are emitted relatively rarely, to avoid clutter. - 2.
DLOG(INFO/WARNING/ERROR)
- These logs appear in debug build only. - 3.
VLOG(1/2/3/...)
- These logs appear in all builds ifvmodule
flag is set. - 4.
DVLOG(1/2/3/...)
- This is the same as VLOG, but only in debug builds.
The browser writes these logs to the system console, also known as standard output. Do not confuse this with the Developer Tools console within the Inspector window.
Android
Desktop
- 1.Ensure
Enable command line on non-rooted devices
in chrome://flags is enabled - 2.Run the following command:
adb shell 'echo _ --enable-logging=stderr --vmodule="*subscription*=1,*activeping*=1,*adblock*=1,*converter*=1,*filtering_configuration*=1" > /data/local/tmp/chrome-command-line'
The flag persists until it is cleared.
- 1.Launch the app manually by tapping the icon on a phone.
- 2.Run
adb logcat
to view logs
To check the currently set command line flags, run the command:
adb shell 'cat /data/local/tmp/chrome-command-line'
To clear the currently set flags:
adb shell 'rm /data/local/tmp/chrome-command-line'
Run the browser executable with following arguments:
--enable-logging=stderr --vmodule="*subscription*=1,*activeping*=1,*adblock*=1,*converter*=1,*filtering_configuration*=1
Last modified 13d ago