Search…
Blocking Ads and Trackers
Block advertising and user tracking URLs to create a safe browsing experience.

Blocking Ads and Trackers on Android and JavaScript

Before checking if a URL is allowed, you should activate at least one ruleset and allow the Ad/Tracker Blocker to compile the rules.

Filtering Status

The Ad/Tracker Blocker client can take some time to compile the rules after changing the active rulesets. Use the status property to determine the state of this process.
TypeScript
Kotlin
1
import { Status } from '@sudoplatform/sudo-ad-tracker-blocker'
2
​
3
/*
4
* Status values:
5
*
6
* Status.Preparing:
7
* Calls to checkUrl() will be resolved when status
8
* becomes `Ready`.
9
*
10
* Status.Ready:
11
* Filter engine is ready and calls to checkUrl()
12
* will be answered immediately.
13
*
14
* Status.Error:
15
* An error occured while (re) initializing the
16
* filter engine.
17
*/
18
​
19
const status: Status = client.status
Copied!
1
// val client: SudoAdTrackerBlockerClient
2
​
3
enum class FilterEngineStatus {
4
/** The filter engine is (re)initializing */
5
PREPARING,
6
/** The filter engine is ready to be used */
7
READY,
8
/** The filter engine failed to update or initialize correctly */
9
ERROR,
10
UNKNOWN
11
}
12
​
13
/** The status of the filter engine. */
14
val status = client.status
Copied!

Check URL Against Active Rulesets

To check if a URL should be blocked or allowed, call the checkUrl method and supply the URL in question. The input to the checkUrl function consists of two URLs. The first is the URL of a resource that is being requested, and the second is the URL of the main page, if any. If the main page URL is provided and is present in the list of exceptions, content will not be blocked.
If the MIME type of the requested URL is known, it can optionally be provided to aid blocking decisions.
TypeScript
Kotlin
1
const url = "http://somehost.com/somewhere/ad?type=banner"
2
const sourceUrl = "http://somehost.com/about-us"
3
​
4
const result: CheckUrlResult = await client.checkUrl(url, sourceUrl)
Copied!
1
// val client: SudoAdTrackerBlockerClient
2
​
3
launch {
4
try {
5
if (client.status != SudoAdTrackerBlockerClient.FilterEngineStatus.READY) {
6
return@launch
7
}
8
withContext(Dispatchers.IO) {
9
val urlStatus = client.checkUrl(
10
url = "http://somehost.com/somewhere/ad?type=banner",
11
sourceUrl = "http://somehost.com/about-us"
12
)
13
if (urlStatus == SudoAdTrackerBlockerClient.CheckUrlResult.BLOCKED) {
14
// URL should not be loaded
15
}
16
}
17
} catch (e: SudoAdTrackerBlockerException) {
18
// Handle/notify user of exception
19
}
20
}
Copied!

Blocking Ads and Trackers on iOS

The iOS SDK differs from other platforms due to the requirements of Apple's Content Blocker implementation. Whereas the Android and JavaScript SDKs provide a custom blocking engine, the iOS SDK provides ruleset data in the Apple Content Blocking format. The lists provided by the iOS SDK can then be used to block content in WKWebView or the system Safari app.

Fetching Content Blocker Data

Use the getContentBlocker function to retrieve ruleset data in the Apple Content Blocking format. The rulesetData property of the returned ContentBlocker can then be used with a WKWebView or the system Safari app. The ruleset data is a combination of the base ruleset data plus any exceptions added via the client. See Manage Exceptions for documentation on adding/removing exceptions.
Ruleset data is cached for performance, and the most recent ruleset is always fetched if the cache is out of date.
Swift
1
//let client: SudoAdTrackerBlockerClient
2
//let ruleset: Ruleset
3
​
4
client.getContentBlocker(ruleset: ruleset) { (result) in
5
switch result {
6
case .success(let contentBlocker):
7
break
8
case .failure(let error):
9
break
10
}
11
}
12
​
13
/// Represents a base ruleset combined with a list of exceptions.
14
public struct ContentBlocker {
15
​
16
/// Generated ID of this content blocker. Based on the base ruleset and an exceptions added.
17
public let id: String
18
​
19
/// The base ruleset used to generate the content blocking json
20
public let baseRuleset: Ruleset
21
​
22
/// The content blocking json in Apples content blocking format. This can be passed to either a content blocking extension or Webkit for blocking.
23
public let rulesetData: String
24
​
25
/// Exceptions applied to the content blocker.
26
public let exceptions: [BlockingException]
27
}
Copied!
The getRuleset function can be used to retrieve the base ruleset data without any exceptions applied.

Using Ruleset Data with a WKWebView

The rulesetData from the iOS SDK can be used to block content in a WebKit View. Refer to Apple's documentation on WKContentRuleList and WKUserContentController for more details.
Compiling a ruleset can be an expensive operation. The id property of a ContentBlocker can be used as a cache key to avoid unnecessary compilation.
Swift
1
let contentBlocker: ContentBlocker // ... see above ...
2
​
3
let store = WKContentRuleListStore.default()
4
store.compileContentRuleList(
5
forIdentifier: contentBlocker.id,
6
encodedContentRuleList: contentBlocker.rulesetData
7
) { (ruleList, error) in
8
guard let ruleList = ruleList else {
9
// Display or log the error.
10
return
11
}
12
​
13
let userContentController = WKUserContentController()
14
userContentController.add(ruleList)
15
​
16
let configuration = WKWebViewConfiguration()
17
configuration.userContentController = userContentController
18
let webView = WKWebView(frame: .zero, configuration: configuration)
19
// Present the web view.
20
}
Copied!
Last modified 1mo ago