Skip to content

Commit c648220

Browse files
didarul-codesdidarul-codes
committed
Update readme
1 parent c1e29bc commit c648220

12 files changed

Lines changed: 321 additions & 320 deletions

File tree

‎.github/workflows/tests.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,3 @@ jobs:
2626
run: |
2727
flutter test
2828
cd packages/adblocker_core && flutter test
29-
cd ../adblocker_manager && flutter test

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
BSD 3-Clause License
22

3-
Copyright (c) 2023, Md Didarul Islam
3+
Copyright (c) 2025, Md Didarul Islam
44

55
Redistribution and use in source and binary forms, with or without
66
modification, are permitted provided that the following conditions are met:

‎README.md‎

Lines changed: 240 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,255 @@
11
[![style: very good analysis](https://img.shields.io/badge/style-very_good_analysis-B22C89.svg)](https://pub.dev/packages/very_good_analysis)
22

3-
- A webview implementation of in Flutter that blocks most of the ads that appear inside of the webpages
4-
- Current implementation is based on official `flutter_inappwebview` packages. So, the features and limitation of that package
5-
is included
3+
# AdBlocker WebView Flutter
64

7-
>On iOS the WebView widget is backed by a [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview).
8-
On Android the WebView widget is backed by a [WebView](https://developer.android.com/reference/android/webkit/WebView).
5+
A Flutter WebView implementation that blocks ads and trackers using EasyList and AdGuard filter lists.
96

10-
| | Android | iOS |
11-
|-------------|----------------|-------|
12-
| **Support** | SDK 19+ or 20+ | 11.0+ |
7+
## Features
138

14-
## Getting started
15-
Add `adblocker_webview` as a [dependency](https://pub.dev/packages/adblocker_webview/install) in your pubspec.yaml file.
9+
- 🚫 Basic ad and tracker blocking using EasyList and AdGuard filters
10+
- 🌐 Supports both URL and HTML content loading
11+
- 🔄 Navigation control (back, forward, refresh)
12+
- 📱 User agent strings for Android and iOS
13+
- ⚡ Early resource blocking for better performance
14+
- 🎯 Domain-based filtering and element hiding
15+
- 🔍 Detailed logging of blocked resources
16+
- 💉 Custom JavaScript injection support
1617

17-
## Usage
18-
1. Acquire an instance of [AdBlockerWebviewController](https://pub.dev/documentation/adblocker_webview/latest/adblocker_webview/AdBlockerWebviewController-class.html)
19-
```dart
20-
final _adBlockerWebviewController = AdBlockerWebviewController.instance;
18+
## Getting Started
19+
20+
### Installation
21+
22+
Add this to your `pubspec.yaml`:
23+
24+
```yaml
25+
dependencies:
26+
adblocker_webview: ^1.0.0
2127
```
22-
It's better to warm up the controller before displaying the webview. It's possible to do that by
28+
29+
### Basic Usage
30+
2331
```dart
32+
import 'package:adblocker_webview/adblocker_webview.dart';
33+
34+
// Initialize the controller (preferably in main())
35+
void main() async {
36+
await AdBlockerWebviewController.instance.initialize();
37+
runApp(MyApp());
38+
}
39+
40+
// Use in your widget
41+
class MyWebView extends StatelessWidget {
2442
@override
25-
void initState() {
26-
super.initState();
27-
_adBlockerWebviewController.initialize();
28-
/// ... Other code here.
43+
Widget build(BuildContext context) {
44+
return AdBlockerWebview(
45+
url: Uri.parse('https://example.com'),
46+
shouldBlockAds: true,
47+
adBlockerWebviewController: AdBlockerWebviewController.instance,
48+
onLoadStart: (url) => print('Started loading: $url'),
49+
onLoadFinished: (url) => print('Finished loading: $url'),
50+
onLoadError: (url, code) => print('Error: $code'),
51+
onProgress: (progress) => print('Progress: $progress%'),
52+
);
2953
}
54+
}
55+
```
56+
57+
### Loading HTML Content
58+
59+
```dart
60+
AdBlockerWebview(
61+
initialHtmlData: '<html><body>Hello World!</body></html>',
62+
shouldBlockAds: true,
63+
adBlockerWebviewController: AdBlockerWebviewController.instance,
64+
)
3065
```
3166

32-
2. Add the [AdBlockerWebview](https://pub.dev/documentation/adblocker_webview/latest/adblocker_webview/AdBlockerWebview-class.html) in widget tree
67+
### Navigation Control
68+
3369
```dart
34-
AdBlockerWebview(
35-
url: "Valid url Here",
36-
adBlockerWebviewController: widget.controller,
37-
onProgress: (progress) {
38-
setState(() {
39-
_progress = progress;
40-
});
41-
},
42-
shouldBlockAds: true,
43-
/// Other params if required
44-
);
70+
final controller = AdBlockerWebviewController.instance;
71+
72+
// Check if can go back
73+
if (await controller.canGoBack()) {
74+
controller.goBack();
75+
}
76+
77+
// Reload page
78+
controller.reload();
79+
80+
// Execute JavaScript
81+
controller.runJavaScript('console.log("Hello from Flutter!")');
4582
```
46-
Supported params of [AdBlockerWebview](https://pub.dev/documentation/adblocker_webview/latest/adblocker_webview/AdBlockerWebview-class.html]) are:
47-
```dart
48-
const AdBlockerWebview({
49-
required this.adBlockerWebviewController,
50-
required this.shouldBlockAds,
51-
this.url,
52-
this.initialHtmlData,
53-
this.onLoadStart,
54-
this.onLoadFinished,
55-
this.onProgress,
56-
this.onLoadError,
57-
this.onTitleChanged,
58-
this.options,
59-
this.additionalHostsToBlock = const [],
60-
super.key,
61-
}) : assert(
62-
(url == null && initialHtmlData != null) ||
63-
(url != null && initialHtmlData == null),
64-
'Both url and initialHtmlData can not be non null');
83+
84+
## Configuration
85+
86+
The WebView can be configured with various options:
87+
88+
```dart
89+
AdBlockerWebview(
90+
url: Uri.parse('https://example.com'),
91+
shouldBlockAds: true, // Enable/disable ad blocking
92+
adBlockerWebviewController: AdBlockerWebviewController.instance,
93+
onLoadStart: (url) {
94+
// Page started loading
95+
},
96+
onLoadFinished: (url) {
97+
// Page finished loading
98+
},
99+
onProgress: (progress) {
100+
// Loading progress (0-100)
101+
},
102+
onLoadError: (url, code) {
103+
// Handle loading errors
104+
},
105+
onUrlChanged: (url) {
106+
// URL changed
107+
},
108+
);
65109
```
66-
#### Caching
67-
- API response for Ad hosts is cached automatically and no config is required!
68-
69-
### Contribution
70-
Contributions are welcome 😄. Please file an issue [here](https://github.com/islamdidarmd/flutter_adblocker_webview/issues) if you want to include additional feature or found a bug!
71-
#### Guide
72-
1. Create an issue first to make sure your request is not a duplicate one
73-
2. Create a fork of the repository (If it's your first contribution)
74-
3. Make a branch from `develop`
75-
4. Branch name should indicate the contribution type
76-
- `feature/**` for new feature
77-
- `bugfix/**` for a bug fix
78-
5. Raise a PR against the `develop` branch
110+
111+
## Features in Detail
112+
113+
### Ad Blocking
114+
- Basic support for EasyList and AdGuard filter lists
115+
- Blocks common ad resources before they load
116+
- Hides ad elements using CSS rules
117+
- Supports exception rules for whitelisting
118+
119+
### Resource Blocking
120+
- Blocks common trackers and unwanted resources
121+
- Early blocking for better performance
122+
- Basic domain-based filtering
123+
- Exception handling for whitelisted domains
124+
125+
### Element Hiding
126+
- Hides common ad containers and placeholders
127+
- CSS-based element hiding
128+
- Basic domain-specific rules support
129+
- Batch processing for better performance
130+
131+
## Migration Guide
132+
133+
### Migrating from 1.2.0 to 2.0.0-beta
134+
135+
#### Breaking Changes
136+
137+
1. **Controller Initialization**
138+
```dart
139+
// Old (1.2.0)
140+
final controller = AdBlockerWebviewController();
141+
await controller.initialize();
142+
143+
// New (2.0.0-beta)
144+
await AdBlockerWebviewController.instance.initialize(
145+
FilterConfig(
146+
filterTypes: [FilterType.easyList, FilterType.adGuard],
147+
),
148+
);
149+
```
150+
151+
2. **URL Parameter Type**
152+
```dart
153+
// Old (1.2.0)
154+
AdBlockerWebview(
155+
url: "https://example.com",
156+
// ...
157+
)
158+
159+
// New (2.0.0-beta)
160+
AdBlockerWebview(
161+
url: Uri.parse("https://example.com"),
162+
// ...
163+
)
164+
```
165+
166+
3. **Filter Configuration**
167+
```dart
168+
// Old (1.2.0)
169+
AdBlockerWebview(
170+
//.. other params
171+
additionalHostsToBlock: ['ads.example.com'],
172+
);
173+
174+
// New (2.0.0-beta)
175+
// Use FilterConfig for configuration
176+
await AdBlockerWebviewController.instance.initialize(
177+
FilterConfig(
178+
filterTypes: [FilterType.easyList, FilterType.adGuard],
179+
),
180+
);
181+
```
182+
183+
4. **Event Handlers**
184+
```dart
185+
// Old (1.2.0)
186+
onTitleChanged: (title) { ... }
187+
188+
// New (2.0.0-beta)
189+
// Use onUrlChanged instead
190+
onUrlChanged: (url) { ... }
191+
```
192+
193+
#### Deprecated Features
194+
- `additionalHostsToBlock` parameter is removed
195+
- Individual controller instances are replaced with singleton
196+
- `onTitleChanged` callback is replaced with `onUrlChanged`
197+
198+
#### New Features
199+
- Singleton controller pattern for better resource management
200+
- Structured filter configuration using `FilterConfig`
201+
- Improved type safety with `Uri` for URLs
202+
- Enhanced filter list parsing and management
203+
- Better performance through early resource blocking
204+
205+
#### Steps to Migrate
206+
1. Update the package version in `pubspec.yaml`:
207+
```yaml
208+
dependencies:
209+
adblocker_webview: ^2.0.0-beta
210+
```
211+
212+
2. Replace controller initialization with singleton pattern
213+
3. Update URL parameters to use `Uri` instead of `String`
214+
4. Replace deprecated callbacks with new ones
215+
5. Update filter configuration to use `FilterConfig`
216+
6. Test the application thoroughly after migration
217+
218+
## Contributing
219+
220+
We welcome contributions to improve the ad-blocking capabilities! Here's how you can help:
221+
222+
### Getting Started
223+
1. Fork the repository
224+
2. Create a new branch from `main` for your feature/fix
225+
- Use `feature/` prefix for new features
226+
- Use `fix/` prefix for bug fixes
227+
- Use `docs/` prefix for documentation changes
228+
3. Make your changes
229+
4. Write/update tests if needed
230+
5. Update documentation if needed
231+
6. Run tests and ensure they pass
232+
7. Submit a pull request
233+
234+
### Before Submitting
235+
- Check that your code follows our style guide (see analysis badge)
236+
- Write clear commit messages
237+
- Include tests for new features
238+
- Update documentation if needed
239+
- Verify all tests pass
240+
241+
### Pull Request Process
242+
1. Create an issue first to discuss major changes
243+
2. Update the README.md if needed
244+
3. Update the CHANGELOG.md following semantic versioning
245+
4. The PR will be reviewed by maintainers
246+
5. Once approved, it will be merged
247+
248+
### Code Style
249+
- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart) guidelines
250+
- Use the provided analysis options
251+
- Run `dart format` before committing
252+
253+
## License
254+
255+
This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

0 commit comments

Comments
 (0)