Skip to content

Commit 527d6d2

Browse files
EdsunsEdsuns
committed
Update README.md and add README.zh-cn.md
1 parent c817abc commit 527d6d2

2 files changed

Lines changed: 162 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
[![](https://jitpack.io/v/Edsuns/AdblockAndroid.svg)](https://jitpack.io/#Edsuns/AdblockAndroid)
44

5+
*Read this in other languages: English | [简体中文](README.zh-cn.md)*
6+
57
A lightweight and efficient adblock engine library for Android, which has strong compatibility for filters like [EasyList](https://easylist.to/) and [AdGuard Filters](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters).
68

79
The native C++ code is based on [brave/ad-block](https://github.com/brave/ad-block). Beyond adapting it to Android platform, I fixed some fatal issues ([d85d341](https://github.com/Edsuns/AdblockAndroid/commit/d85d341692efbde551712f44b79ae590f4df64d5), [583f87a](https://github.com/Edsuns/AdblockAndroid/commit/583f87a2b193257aff797e3f6ba093e619700335)), made 40x better parsing performance ([ab18236](https://github.com/Edsuns/AdblockAndroid/commit/ab182369edcd2c86d6fbc3e9e2d85ca8ec82954e), [a0009c8](https://github.com/Edsuns/AdblockAndroid/commit/a0009c83857f435ea6c055a2b5fff6ec3ee88bdc)) and implemented some new features.
@@ -16,7 +18,7 @@ The native C++ code is based on [brave/ad-block](https://github.com/brave/ad-blo
1618
- Support for [checksum](https://hg.adblockplus.org/adblockplus/file/tip/validateChecksum.py)
1719
- Support for background download and installation
1820
- Custom filter subscriptions
19-
- Custom rules (In development)
21+
- Custom rules
2022

2123
## Tech Stack
2224

@@ -32,29 +34,29 @@ See [releases](https://github.com/Edsuns/AdblockAndroid/releases) and the code i
3234

3335
## Get Started
3436

35-
Note: This development requires you to have fundamental Android WebView experience.
37+
*Note: This development requires you to have fundamental Android WebView experience.*
3638

37-
Note: A full application example can be found in the `:app` module.
39+
*Note: A full application example can be found in `:app` module.*
3840

3941
### 1. Gradle Configuration
4042

4143
Add it in your root build.gradle at the end of repositories:
4244

4345
```groovy
44-
allprojects {
45-
repositories {
46-
...
47-
maven { url 'https://jitpack.io' }
48-
}
49-
}
46+
allprojects {
47+
repositories {
48+
...
49+
maven { url 'https://jitpack.io' }
50+
}
51+
}
5052
```
5153

5254
Add the dependency:
5355

5456
```groovy
55-
dependencies {
56-
implementation 'com.github.Edsuns:AdblockAndroid:Tag'
57-
}
57+
dependencies {
58+
implementation 'com.github.Edsuns.AdblockAndroid:ad-filter:Tag'
59+
}
5860
```
5961

6062
### 2. Coding
@@ -65,7 +67,7 @@ Add the code in your `Application` class
6567
class App : Application() {
6668
override fun onCreate() {
6769
super.onCreate()
68-
// Debug configuration
70+
// Debug configuration.
6971
if (BuildConfig.DEBUG) {
7072
Timber.plant(Timber.DebugTree())
7173
}
@@ -125,15 +127,15 @@ class MainActivity : AppCompatActivity(), WebViewClientListener {
125127
"NoCoin Filter List" to "https://filters.adtidy.org/extension/chromium/filters/242.txt"
126128
)
127129
for ((key, value) in map) {
128-
val filter = filterViewModel.addFilter(key, value)
129-
filterViewModel.download(filter.id)
130+
val subscription = filterViewModel.addFilter(key, value)
131+
filterViewModel.download(subscription.id)
130132
}
131133
}
132134
}
133135
}
134136
```
135137

136-
Congratulations, great success!
138+
**Congratulations, great success!**
137139

138140
## Thanks To
139141

‎README.zh-cn.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# AdblockAndroid
2+
3+
[![](https://jitpack.io/v/Edsuns/AdblockAndroid.svg)](https://jitpack.io/#Edsuns/AdblockAndroid)
4+
5+
*阅读其他语言版本：[English](README.md) | 简体中文*
6+
7+
一个轻量级、高性能、为安卓量身打造的 adblock 过滤引擎依赖库，支持 [EasyList](https://easylist.to/) 和 [AdGuard Filters](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters) 的过滤规则。
8+
9+
底层的算法实现基于 [brave/ad-block](https://github.com/brave/ad-block)，在将其适配到安卓平台之外，我还修复了几个致命的错误（[d85d341](https://github.com/Edsuns/AdblockAndroid/commit/d85d341692efbde551712f44b79ae590f4df64d5)，[583f87a](https://github.com/Edsuns/AdblockAndroid/commit/583f87a2b193257aff797e3f6ba093e619700335)）、使安装规则的性能提升了40倍（[ab18236](https://github.com/Edsuns/AdblockAndroid/commit/ab182369edcd2c86d6fbc3e9e2d85ca8ec82954e)，[a0009c8](https://github.com/Edsuns/AdblockAndroid/commit/a0009c83857f435ea6c055a2b5fff6ec3ee88bdc)），并实现了许多新的特性。
10+
11+
## 特性
12+
13+
- 所有来自 [brave/ad-block](https://github.com/brave/ad-block) 的特性
14+
- 支持 [element hiding](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-elemhide-rules)
15+
- 支持 [Extended CSS selectors](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#extended-css-selectors)
16+
- 支持 [CSS rules](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules)
17+
- 支持 [Scriptlet rules](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#scriptlets)
18+
- 支持 [checksum](https://hg.adblockplus.org/adblockplus/file/tip/validateChecksum.py)
19+
- 支持在后台下载和安装
20+
- 支持订阅过滤列表
21+
- 支持自定义过滤规则
22+
23+
## 技术栈
24+
25+
- Android
26+
- Kotlin
27+
- C++
28+
- JavaScript
29+
- JNI
30+
31+
## 示例
32+
33+
请查看 [releases](https://github.com/Edsuns/AdblockAndroid/releases) 和 `app/src`里的代码。
34+
35+
## 快速上手
36+
37+
*注意：本教程要求阅读者有基本的WebView开发经验*
38+
39+
*注意：完整的示例应用可查看 `:app` 模块*
40+
41+
### 1. Gradle 配置
42+
43+
在项目根目录的 build.gradle 添加仓库地址：
44+
45+
```groovy
46+
allprojects {
47+
repositories {
48+
...
49+
maven { url 'https://jitpack.io' }
50+
}
51+
}
52+
```
53+
54+
在具体模块添加依赖：
55+
56+
```groovy
57+
dependencies {
58+
implementation 'com.github.Edsuns.AdblockAndroid:ad-filter:Tag'
59+
}
60+
```
61+
62+
### 2. 代码
63+
64+
添加以下代码到 `Application` 类
65+
66+
```kotlin
67+
class App : Application() {
68+
override fun onCreate() {
69+
super.onCreate()
70+
// Debug配置
71+
if (BuildConfig.DEBUG) {
72+
Timber.plant(Timber.DebugTree())
73+
}
74+
// 启动过滤器
75+
val filter = AdFilter.create(this)
76+
}
77+
}
78+
```
79+
80+
添加以下代码到 `WebChromeClient` 类
81+
82+
```kotlin
83+
class WebClient(private val webViewClientListener: WebViewClientListener) : WebViewClient() {
84+
85+
private val filter = AdFilter.get()
86+
87+
override fun shouldInterceptRequest(
88+
view: WebView?,
89+
request: WebResourceRequest?
90+
): WebResourceResponse? {
91+
val result = filter.shouldIntercept(view!!, request!!)
92+
return result.resourceResponse
93+
}
94+
95+
override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
96+
filter.performScript(view, url)
97+
}
98+
}
99+
```
100+
101+
添加以下代码到 `Activity` 类
102+
103+
```kotlin
104+
class MainActivity : AppCompatActivity(), WebViewClientListener {
105+
106+
private lateinit var binding: ActivityMainBinding
107+
108+
override fun onCreate(savedInstanceState: Bundle?) {
109+
super.onCreate(savedInstanceState)
110+
binding = ActivityMainBinding.inflate(layoutInflater)
111+
setContentView(binding.root)
112+
113+
val filter = AdFilter.get()
114+
val filterViewModel = filter.viewModel
115+
116+
// 为WebView安装过滤器
117+
filter.setupWebView(binding.webView)
118+
119+
// 在首次安装时添加订阅并下载
120+
if (!filter.hasInstallation) {
121+
val map = mapOf(
122+
"AdGuard Base" to "https://filters.adtidy.org/extension/chromium/filters/2.txt",
123+
"EasyPrivacy Lite" to "https://filters.adtidy.org/extension/chromium/filters/118_optimized.txt",
124+
"AdGuard Tracking Protection" to "https://filters.adtidy.org/extension/chromium/filters/3.txt",
125+
"AdGuard Annoyances" to "https://filters.adtidy.org/extension/chromium/filters/14.txt",
126+
"AdGuard Chinese" to "https://filters.adtidy.org/extension/chromium/filters/224.txt",
127+
"NoCoin Filter List" to "https://filters.adtidy.org/extension/chromium/filters/242.txt"
128+
)
129+
for ((key, value) in map) {
130+
val subscription = filterViewModel.addFilter(key, value)
131+
filterViewModel.download(subscription.id)
132+
}
133+
}
134+
}
135+
}
136+
```
137+
138+
**大功告成！**
139+
140+
## 致谢
141+
142+
- [brave/ad-block](https://github.com/brave/ad-block)
143+
- [github.com/AdguardTeam](https://github.com/AdguardTeam)
144+
- [duckduckgo/Android](https://github.com/duckduckgo/Android)

0 commit comments

Comments
 (0)