An Android library project, tests and demo application for AdblockWebView widget.

Adblock Plus for Android has dependencies that aren't in this repository. To update those, call:

./ensure_dependencies.py

An Android library that provides the core functionality of Adblock Plus. You can find it in the 'libadblockplus-android' directory.

• The Android SDK
• Android SDK Build tools 24.0.1
• The Android NDK, 12b

Edit 'buildToolsVersion' in 'build.gradle' files if necessary.

In the project root directory create the file local.properties and set sdk.dir and ndk.dir to where you installed it, e.g.:

sdk.dir = /some/where/sdk
ndk.dir = /some/where/ndk

In the project root directory run:

./gradlew assembleDebug

This will generate *.aar library artifact in the 'libadblockplus-android/build/outputs/aar/' directory.

Android permissions note

An app that uses the library have to add the following permissions to AndroidManifest.xml:

• <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
• <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

(added automatically if building with Gradle or should be added manually otherwise).

By default Gradle uses build directory to build modules, however it can be undesired for some use cases like CI or building as Chromium submodule. Set GRADLE_BUILD_DIR environment variable to configure build directory:

GRADLE_BUILD_DIR=/tmp ./gradlew clean assemble

Note

[Configuration] Building project in /tmp

output while building

This can be desired to use product's V8 (let's say Chromium) instead of built-in V8. Put prebuilt shared V8 library file(s) in ARCH directories and set SHARED_V8_LIB_FILENAMES environment variable before building. You can pass multiple filenames, separated with space. Libadblockplus is required to be linked with that library file(s).

For example:

SHARED_V8_LIB_FILENAMES=libv8.cr.so ./gradlew clean assemble

or

SHARED_V8_LIB_FILENAMES="libv8.cr.so libfoo.so" ./gradlew clean assemble

for multiple library files.

Note

[Configuration] Excluding shared v8 library libv8.cr.so from AAR
...
[Configuration] Linking dynamically with shared v8 library ./libadblockplus-binaries/android_armeabi-v7a/libv8.cr.so
...

output while building.

Set SHARED_V8_LIB_DIR environment variable as full absolute path to pass specific directory instead of default one (libadblockplus-android/jni/libadblockplus-binaries).

By default libadblockplus-android is built for both ARM and x86 and it can be filtered when building end-user android application. However sometimes it can be desired to build "libadblockplus-android.aar" for single ARCH.

Pass abi_arm or abi_x86 to build it for single arch or abi_all for all ARCHs:

`./gradlew clean assembleAbi_arm`

Note

[Configuration] Using libadblockplus-android ABI flavor: abi_arm

output while building.

Android tests for the library. You can find them in the 'libadblockplus-android-tests' directory.

Make sure Library requirements are present.

Make sure you've created the local.properties file to build the library (see above). In the project root directory run:

./gradlew assembleDebugAndroidTest

This will generate *.apk in the 'libadblockplus-android-tests/build/outputs/apk/' directory.

You can select test class/method and click 'Run ..Test'. The library and test app will be compiled, installed to emulator/device and launched automatically.

An Android library that provides a configuration interface for Adblock Plus. You can find it in the 'libadblockplus-android-settings' directory:

• GeneralSettingsFragment - main fragment
• WhitelistedDomainsSettingsFragment - whitelisted domains fragment

Create AdblockEngineProvider instance and AdblockSettingsStorage instance. You can use SharedPrefsStorage implementation to store settings in SharedPreferences. Or you can use AdblockHelper:

AdblockHelper
  .get()
  .init(this, getFilesDir().getAbsolutePath(), true, AdblockHelper.PREFERENCE_NAME);

  // optional - provide preloaded subscription files in app resoruces
  .preloadSubscriptions(AdblockHelper.PRELOAD_PREFERENCE_NAME, map);

Make sure you initialize it once during app launch, call isInit() to check it:

if (!AdblockHelper.get().isInit())
{
  // requires initialization
  ...
}

Sometimes it's desired to initialize or deinitialize FilterEngine instance when created:

AdblockHelper
  .get()
  .init(...)
  .addEngineCreatedListener(engineCreatedListener)

or disposed:

AdblockHelper
  .get()
  .init(...)
  .addEngineDisposedListener(engineDisposedListener)

Implement the following interfaces in your settings activity:

• BaseSettingsFragment.Provider
• GeneralSettingsFragment.Listener
• WhitelistedDomainsSettingsFragment.Listener

and return created instance or AdblockHelper instances:

AdblockHelper.get().getProvider().getEngine();  // engine
AdblockHelper.get().getStorage(); // storage

Retain Adblock instance in activity onCreate in synchronous mode (it may take few seconds):

AdblockHelper.get().getProvider().retain(false);

or in asynchronous mode (without current thread lock):

AdblockHelper.get().getProvider().retain(true);

Invoke waitforReady every time you need AdblockEngine instance if retained in asynchronous mode:

AdblockHelper.get().getProvider().waitForReady();

Release Adblock instance in activity onDestroy:

AdblockHelper.get().getProvider().release();

Insert GeneralSettingsFragment fragment instance in runtime to start showing settings UI.

In the project root directory run:

./gradlew assemble

This will generate *.aar in the 'libadblockplus-android-settings/build/outputs/aar' directory.

An Android library that provides a WebView component with Adblock Plus integrated. You can find it in the 'libadblockplus-android-webview' directory.

AdblockWebView class provides built-in ad blocking (both resource loading filtering and element hiding) and inherits from Android 'WebView'.

In layout XML:

<org.adblockplus.libadblockplus.android.webview.AdblockWebView
    android:id="@+id/main_webview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

In java source code:

AdblockWebView webView = (AdblockWebView) findViewById(R.id.main_webview);

Use setAdblockEnabled(boolean adblockEnabled) to enable/disable adblocking.

Use setDebugMode(boolean debugMode) to turn debug log output (Android log and JS console) on/off.

Use setAllowDrawDelay(int allowDrawDelay) to set custom delay to start render webpage after 'DOMContentLoaded' event is fired.

Use setProvider(AdblockEngineProvider provider) to use external adblock engine provider. The simplest solution is to use AdblockHelper from -settings as external adblock engine provider:

webView.setProvider(AdblockHelper.get().getProvider());

If adblock engine provider is not set, it's created by AdblockWebView instance automatically.

Use dispose(Runnable disposeFinished) to release resources (required). Note it can be invoked from background thread.

In the project root directory run:

./gradlew assemble

This will generate *.aar in the 'libadblockplus-android-webview/build/outputs/aar' directory.

An Android application that demonstrates how to use AdblockWebView. You can find it in the 'libadblockplus-android-webviewapp' directory.

Make sure Library requirements are present.

In the project root directory run:

./gradlew assemble

This will generate *.apk in the 'libadblockplus-android-webviewapp/build/outputs/apk/' directory.