Competing approaches for content-blocking PR

[tifroz]

I’m working on a PR to bring content blocking to SkipWeb. The main challenge is that iOS and Android expose very different capabilities here, so we need to make an early design decision with real long-term consequences.

For scale: a typical blocker may ship with around 50,000 rules, combining network request blocking and CSS-based hiding.

On iOS, WKWebView provides a mature and fairly prescriptive model through WKContentRuleListStore and related APIs:

• The app provides rule files in Apple’s prescribed format.
• WebKit compiles those rules into an optimized internal representation.
• WebKit is then responsible for applying the rules efficiently at runtime.

On Android, WebView is much more low-level. It provides enough hooks to implement content blocking in an ad hoc way, but it does not provide a built-in content-blocking system comparable to WebKit’s:

• shouldInterceptRequest can be used to block network requests.
• Injection APIs can be used to insert CSS that hides known page elements.
• The app developer is responsible for deciding which rules apply for a given page, frame, or request, and for handling indexing, lookup, and runtime evaluation.
• Some rule shapes from the WKWebView world do not map neatly onto Android. For example, rules that depend on both the top-level page URL and a subframe URL are difficult to reproduce, because CSS often needs to be injected before the full frame structure is known.

Because iOS already has a mature optimized pipeline, it seems natural to use it there. The main design question is what SkipWeb should do on Android.

Option 1: SkipWeb provides a WKContentRuleListStore-like abstraction
SkipWeb would consume iOS-style rule files, index them on first launch, cache the derived data, and apply them on Android as closely as possible.

✅ Pros:

• Easier migration for teams already using iOS/WebKit rule lists.
• Gives developers a more unified cross-platform surface.
• Reduces the amount of blocker-specific infrastructure each app has to build.

❌ Cons:

• Substantially more complexity and long-term maintenance burden in SkipWeb.
• Unclear upfront performance cost for indexing large rule sets.
• Likely additional disk usage if large rule files need to be transformed or duplicated for indexing.
• Android support would still be best-effort, because some iOS rule semantics do not map cleanly to Android APIs.
• Developers may lose flexibility, since this effectively forces an iOS-shaped model onto Android.

Option 2: SkipWeb exposes Android-oriented primitives
SkipWeb would provide content-blocking-friendly wrappers around shouldInterceptRequest plus hooks for CSS injection, while leaving rule format, indexing, and matching strategy to the app developer.

✅ Pros:

• Much simpler and lower-risk design for SkipWeb.
• More transparent and less “magical.”
• Gives app developers full control over rule format, indexing strategy, and tradeoffs.
• Lets Android implementations be designed around Android’s actual constraints instead of imitating WebKit.

❌ Cons:

• Shifts substantial complexity onto app developers.
• Increases adoption friction, since each app may need to build its own rule pipeline.
• Makes cross-platform reuse of existing iOS rule sets harder.

@marcprux I am happy to work on either one of the 2 options - but considering the substantial tradeoffs either way, it would be helpful to know which side makes more sense from the perspective of the Skip platform

[marcprux]

This will be a great addition! I'm honestly not sure which option is best, or to go a third way (just creating our own abstraction and having platform-specific implementations). Maybe experiment with prototypes with all three?

You might be interested in Net Skip's implementation of loadContentBlockerRules() (using Brave's content blocker specifications), which currently only works on iOS. But I'd love to expend this support to Android!

[tifroz]

I looked up loadContentBlockerRules()...as you mentioned it only provides the iOS implementation as a think wrapper around the native (and very prescriptive) WKWebView content blocking infrastructure. The complexity is 100% on the Android implementation that only provides basic hooks so I am not sure what I can learn/reuse from that implementation - but maybe I missed the point?

I think will go with a 2-step approach

• 1st PR implements option 2: bare bone APIs for implementing content-blocking (thin wrapper for iOS, exposes hooks for Android)
• The 2nd PR implements option 1:
  • will be based off of the 1st PR
  • less control, latency hit on first application load, storage space hit - but much easier adoption.

The 2nd PR may come with new Android-specific dependencies added to the SkipWeb package. Let me know if you have any guidelines you can share upfront (in particular, what type of os licenses are you ok with)?

[marcprux]

I definitely agree that the complexity is all on the Android side. I just wanted to point at that project as a reference example, and also provide an example of some existing content blocking rules that might be useful for testing.

The 2nd PR may come with new Android-specific dependencies added to the SkipWeb package. Let me know if you have any guidelines you can share upfront (in particular, what type of os licenses are you ok with)?

That sounds good. Do you have particular dependencies in mind? I think we're OK with pretty much any OSI-approved license, but we also want to be careful to not add too many required dependencies to skip-web, since this won't necessarily be a common use case.