Manage Rulesets

Provides control over which sets of advertising, tracker and social media blocking rules are active.

Rulesets are a collection of patterns that the blocking engine can use to identify advertisements and tracking requests. The SDK provides methods to specify which rulesets are active, making it easy to customize the user's browsing experience.

List the Available Rulesets

To list all the available rulesets offered by the Ad/Tracker Blocker SDK you can use the listRulesets method to retrieve the metadata of all the rulesets.

TypeScript

const rulesets: Rulesets[] = await client.listRulesets()

Swift

do {
    let rulesets = try await client.listRulesets()
} catch {
    // Handle failure
}

Kotlin

// val client: SudoAdTrackerBlockerClient

launch {
    try {
        val rulesets = withContext(Dispatchers.IO) {
            client.listRulesets()
        }
        // Find the advertising blocking ruleset
        val adBlockRuleset = rulesets.find { ruleset ->
            ruleset.type == Ruleset.Type.AD_BLOCKING 
        }
    } catch (e: SudoAdTrackerBlockerException) {
        // Handle/notify user of exception
    }
}

The metadata of each ruleset provides the following elements.

type	Category of the ruleset. For example: Advertising, Privacy or Social Media
updatedAt	The date/time of when the ruleset was last updated by the Ad/Tracker Blocker service

Update Rulesets

To ensure that your users are protected by the very latest version of the ad and tracker blocking rulesets you can periodically request that the SDK re-fetches the rulesets by calling the updateRulesets method.

On iOS, the latest ruleset data is always returned when your application requests content blocker data from the SDK. See Blocking Ads and Trackers on iOS.

TypeScript

/*
 * The `updateRulesets` method returns a promise that
 * resolves when rulesets have been updated.
 *
 * The rulesets are cached via the StorageProvider 
 * provided to the client.
 */

await client.updateRulesets()

Kotlin

// val client: SudoAdTrackerBlockerClient

launch {
    try {
        withContext(Dispatchers.IO) {
            // For example, if only interested in ads and privacy blocking
            client.updateRulesets(
                Ruleset.Type.AD_BLOCKING,
                Ruleset.Type.PRIVACY
            )
        }
    } catch (e: SudoAdTrackerBlockerException) {
        // Handle/notify user of exception
    }
}

The updateRulesets method performs an HTTP request to update the rulesets. The source of a ruleset is large, typically from 0.5 to over 1 MB. This means that this operation might take some time to complete.

Getting the Active Rulesets

You can allow your users to control which sets of blocking rules are active at any time. To find the current set of active rulesets call the getActiveRulesets method.

On iOS, your application can control which content blockers to add to a custom web view. If your application provides a Content Blocking Extension, your users can enable or disable your content blocker(s) in system settings. See Blocking Ads and Trackers on iOS.

TypeScript

const activeRulesets: RulesetType[] = await client.getActiveRulesets()

Kotlin

// val client: SudoAdTrackerBlockerClient

launch {
    try {
        val activeRulesets = withContext(Dispatchers.IO) {
            client.getActiveRulesets()
        }
        println("Active rulesets: $activeRulesets")
    } catch (e: SudoAdTrackerBlockerException) {
        // Handle/notify user of exception
    }
}

Setting the Active Rulesets

You can allow your users to control which sets of blocking rules are active at any time. The rulesets that are currently active can be controlled by calling the setActiveRulesets method.

On iOS, your application can control which content blockers to add to a custom web view. If your application provides a Content Blocking Extension, your users can enable or disable your content blocker(s) in system settings. See Blocking Ads and Trackers on iOS.

TypeScript

import { RulesetType } from '@sudoplatform/sudo-ad-tracker-blocker'

/* 
 * The `setActiveRulesets` will change the active rulesets
 * in use by the client's filtering engine, and it will
 * save the updated preference via the storage provider.
 */

await client.setActiveRulesets([
  RulesetType.AdBlocking, 
  RulesetType.Privacy
])

Kotlin

// val client: SudoAdTrackerBlockerClient

launch {
    try {
        withContext(Dispatchers.IO) {
            // For example, if only interested in ads and privacy blocking
            client.setActiveRulesets(
                Ruleset.Type.AD_BLOCKING,
                Ruleset.Type.PRIVACY
            )
        }
    } catch (e: SudoAdTrackerBlockerException) {
        // Handle/notify user of exception
    }
}

When you change the active rulesets, the filtering engine will be reinitialized with the new rulesets. This is not instantaneous, it can take a small amount of time. To monitor the status of the filtering engine you can monitor the statusproperty as described in Filtering Status.