1# 使用Web组件的广告过滤功能
2
3ArkWeb为应用提供广告过滤功能，支持通过云端推送默认的easylist规则，或允许应用通过接口设定自定义规则文件。它在网络层拦截广告资源的下载，或在网页中注入CSS规则以隐藏特定的广告元素。
4
5当前配置文件格式为easylist语法规则。
6
7## 常用easylist语法规则
8
9| 规则类别     | 说明   | 示例 |
10| ---------- | ------ | ---- |
11| URL拦截规则 | 拦截所有网站中url能匹配"example.com/js/*_tv.js"的子资源请求。用于定义域名过滤规则，用于匹配特定的域名及其所有子域名。 | \|\|example.com/js/*_tv.js   |
12| URL拦截规则 | 拦截非alimama.com、非taobao.com域名网站中的url匹配"alimama.cn"的第三方资源。\$third\_party是一种options语法，表示匹配第三方资源；域名前使用'~'表示不包括该域名。 | \|\|alimama.cn^$third-party,domain\=~alimama.com\|\~taobao.com   |
13| 例外规则 | 关闭example.com网页内的广告过滤。@@是例外规则的语法关键字，表示不过滤。 | \@\@\|\|example.com^$document   |
14| 例外规则 | 在域名为litv.tv的网页中，不过滤能匹配上".adserver."的子资源。 | \@\@.adserver.$domain=litv.tv   |
15| 元素隐藏规则 | 隐藏myabandonware.com和myware.com域名中所有class="i528"的元素。##用于表示元素隐藏。 | myabandonware.com, myware.com##.i528   |
16| 元素隐藏例外规则 | 不隐藏sdf-event.sakura.ne.jp网站中id="ad_1"的元素。 | sdf-event.sakura.ne.jp#@##ad_1   |
17
18例外规则，通常是配合普通规则一起使用的，使普通规则在某些场景下不起作用，单独应用例外规则没有意义。
19例如先配置了一条过滤所有网站的拦截规则，||abc.com/js/123.js，但是某些网站中出现了误拦截或者不能拦截的场景，就可以针对这些网站配置新的例外规则。
20
21## 约束与限制
22
23- 在[WebviewController](../reference/apis-arkweb/js-apis-webview.md#webviewcontroller)类中，增加开启/关闭广告过滤特性的接口[enableAdsBlock()](../reference/apis-arkweb/js-apis-webview.md#enableadsblock12)，支持Web实例级的特性开关。
24
25- 新增[AdsBlockManager](../reference/apis-arkweb/js-apis-webview.md#adsblockmanager12)全局单例类，提供自定义广告过滤配置、控制网站级特性开关的能力。
26
27- Web实例上提供了[onAdsBlocked()](../reference/apis-arkweb/ts-basic-components-web.md#onadsblocked12)回调通知方法，支持将拦截信息通知到上层应用。
28
29- [AdsBlockManager](../reference/apis-arkweb/js-apis-webview.md#adsblockmanager12)接口[setAdsBlockRules()](../reference/apis-arkweb/js-apis-webview.md#setadsblockrules12)接口仅能设置一份自定义配置，此配置会持久化，应用冷启动无需重新配置，可避免每次冷启动配置规则都触发广告过滤配置的编译解析。
30
31- [AdsBlockManager](../reference/apis-arkweb/js-apis-webview.md#adsblockmanager12)接口[addAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockdisallowedlist12)、[removeAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#removeadsblockdisallowedlist12)、[clearAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#clearadsblockdisallowedlist12)、[addAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockallowedlist12)、[removeAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#removeadsblockallowedlist12)、[clearAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#clearadsblockallowedlist12)操作的数据不会持久化，应用冷启动需要重新设置。
32
33- 如果1个Web实例启用了广告过滤特性，但未调用[AdsBlockManager](../reference/apis-arkweb/js-apis-webview.md#adsblockmanager12)接口[addAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockdisallowedlist12)、[removeAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#removeadsblockdisallowedlist12)、[clearAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#clearadsblockdisallowedlist12)、[addAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockallowedlist12)、[removeAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#removeadsblockallowedlist12)、[clearAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#clearadsblockallowedlist12)配置disallowlist和allowlist数据，则默认所有网站均启用广告过滤。
34
35- allowlist和disallowlist数据共同使用时，allowlist的优先级高于disallowlist，即先使用allowlist匹配，如果匹配成功就不再使用disallowlist匹配，该网站会启用广告过滤特性。
36
37- 如果应用没有使能广告过滤特性，那么确保Web组件不会向服务器请求默认的内置easylist配置文件。
38
39- disallowlist和allowlist数据采用后缀匹配，例如应用的设置的域名"xxyy.com"，可以匹配上url为"wwsstt.xxyy.com"的网站。
40
41## 使用场景
42
43### 开启广告过滤
44应用可以通过AdsBlockManager提供的[setAdsBlockRules()](../reference/apis-arkweb/js-apis-webview.md#setadsblockrules12)接口设置自定义的easylist过滤规则，并通过Web组件的[enableAdsBlock()](../reference/apis-arkweb/js-apis-webview.md#enableadsblock12)接口使能广告过滤特性。
45
46在下面的示例中，演示了一个应用通过文件选择器选择easylist规则文件，并开启广告过滤功能。
47
48```ts
49// xxx.ets
50import { webview } from '@kit.ArkWeb';
51import { picker, fileUri } from '@kit.CoreFileKit';
52
53// 演示点击按钮，通过filepicker打开一个easylist规则文件并设置到Web组件中
54@Entry
55@Component
56struct WebComponent {
57  main_url: string = 'https://www.example.com';
58  controller: webview.WebviewController = new webview.WebviewController();
59
60  @State input_text: string = 'https://www.example.com';
61
62  build() {
63    Column() {
64      Row() {
65        Flex() {
66          Button({type: ButtonType.Capsule}) {
67            Text("setAdsBlockRules")
68          }
69          .onClick(() => {
70            try {
71              let documentSelectionOptions: ESObject = new picker.DocumentSelectOptions();
72              let documentPicker: ESObject = new picker.DocumentViewPicker();
73              documentPicker.select(documentSelectionOptions).then((documentSelectResult: ESObject) => {
74                if (documentSelectResult && documentSelectResult.length > 0) {
75                  let fileRealPath = new fileUri.FileUri(documentSelectResult[0]);
76                  console.info('DocumentViewPicker.select successfully, uri: ' + fileRealPath);
77                  webview.AdsBlockManager.setAdsBlockRules(fileRealPath.path, true);
78                }
79              })
80            } catch (err) {
81              console.error('DocumentViewPicker.select failed with err:' + err);
82            }
83          })
84        }
85      }
86      Web({ src: this.main_url, controller: this.controller })
87        .onControllerAttached(()=>{
88          this.controller.enableAdsBlock(true);
89        })
90    }
91  }
92}
93```
94
95如果存在内置的easylist规则文件，[setAdsBlockRules()](../reference/apis-arkweb/js-apis-webview.md#setadsblockrules12)接口的replace参数可用于设置规则文件的使用策略，replace为true表示不使用内置的easylist规则文件，replace为false表示自定义规则和内置的规则将会同时工作，如果发现内置规则与自定义规则冲突，可使用replace=true禁用内置规则效果。
96
97设置的自定义规则文件将在应用进程内对所有的Web组件生效，是一个应用级全局配置文件，并将持久化，应用重启后可继续工作。
98
99### 关闭特定域名页面的广告过滤
100在Web组件的广告过滤开关开启后，应用有时候会期望关闭一些特定页面的广告过滤功能，除了可以使用自定义的easylist规则，AdsBlockManager还提供了[addAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockdisallowedlist12)接口完成此功能。
101
102```ts
103// xxx.ets
104import { webview } from '@kit.ArkWeb';
105
106// 演示通过一个按钮的点击向Web组件设置广告过滤的域名策略
107@Entry
108@Component
109struct WebComponent {
110  main_url: string = 'https://www.example.com';
111  text_input_controller: TextInputController = new TextInputController();
112  controller: webview.WebviewController = new webview.WebviewController();
113
114  @State input_text: string = 'https://www.example.com';
115
116  build() {
117    Column() {
118      Row() {
119        Flex() {
120          TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
121            .id("input_url")
122            .height(40)
123            .margin(5)
124            .borderColor(Color.Blue)
125            .onChange((value: string) => {
126              this.input_text = value;
127            })
128
129          Button({type: ButtonType.Capsule}) { Text("Go") }
130          .onClick(() => {
131            this.controller.loadUrl(this.input_text);
132          })
133
134          Button({type: ButtonType.Capsule}) { Text("addAdsBlockDisallowedList") }
135          .onClick(() => {
136            let arrDomainSuffixes = new Array<string>();
137            arrDomainSuffixes.push('example.com');
138            arrDomainSuffixes.push('abcdefg.cn');
139            webview.AdsBlockManager.addAdsBlockDisallowedList(arrDomainSuffixes);
140          })
141        }
142      }
143      Web({ src: this.main_url, controller: this.controller })
144        .onControllerAttached(()=>{
145          this.controller.enableAdsBlock(true);
146        })
147    }
148  }
149}
150```
151
152[addAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockdisallowedlist12)接口将域名设置到AdsBlockManager的DisallowedList中，下次页面加载时会使用网页url和DisallowedList中的域名进行后缀匹配，匹配成功则不会对此页面进行广告过滤。此外，还提供了[addAdsBlockAllowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockallowedlist12)接口配合DisallowedList进行域名设置，控制是否开启广告过滤。
153
154AdsBlockManager中缓存有2组域名列表，分别为DisallowedList和AllowList，其中DisallowedList用于禁用网页的广告过滤，而AllowList用于重新开启被DisallowedList关闭的广告过滤开关，其中AllowList优先级更高。页面加载时会先使用网页url和AllowList进行匹配，匹配成功的网页广告过滤将保持开启，否则将会继续使用DisallowedList进行匹配，匹配成功将关闭网页的广告过滤。如果访问的网页不在AllowList和DisallowedList中，那么默认网页的广告过滤会保持开启状态。
155
156例如，应用想要开启域名为'news.example.com'和'sport.example.com'的广告过滤，但需要关闭'example.com'的其他域名下网页的广告过滤，就可以先使用addAdsBlockDisallowedList()接口添加'example.com'域名到DisallowedList，再使用[addAdsBlockDisallowedList()](../reference/apis-arkweb/js-apis-webview.md#addadsblockdisallowedlist12)接口添加'news.example.com'和'sport.example.com'域名。
157
158```ts
159// xxx.ets
160import { webview } from '@kit.ArkWeb';
161
162// 演示addAdsBlockAllowedList和addAdsBlockAllowedList配套使用，设置网页级的广告过滤开关。
163@Entry
164@Component
165struct WebComponent {
166  main_url: string = 'https://www.example.com';
167  text_input_controller: TextInputController = new TextInputController();
168  controller: webview.WebviewController = new webview.WebviewController();
169
170  @State input_text: string = 'https://www.example.com';
171
172  build() {
173    Column() {
174      Row() {
175        Flex() {
176          TextInput({ text: this.input_text, placeholder: this.main_url, controller: this.text_input_controller})
177            .id("input_url")
178            .height(40)
179            .margin(5)
180            .borderColor(Color.Blue)
181            .onChange((value: string) => {
182              this.input_text = value;
183            })
184
185          Button({type: ButtonType.Capsule}) { Text("Go") }
186          .onClick(() => {
187            this.controller.loadUrl(this.input_text);
188          })
189
190          Button({type: ButtonType.Capsule}) { Text("addAdsBlockAllowedList") }
191          .onClick(() => {
192            let arrDisallowDomainSuffixes = new Array<string>();
193            arrDisallowDomainSuffixes.push('example.com');
194            webview.AdsBlockManager.addAdsBlockDisallowedList(arrDisallowDomainSuffixes);
195
196            let arrAllowedDomainSuffixes = new Array<string>();
197            arrAllowedDomainSuffixes.push('news.example.com');
198            arrAllowedDomainSuffixes.push('sport.example.com');
199            webview.AdsBlockManager.addAdsBlockAllowedList(arrAllowedDomainSuffixes);
200          })
201        }
202      }
203      Web({ src: this.main_url, controller: this.controller })
204        .onControllerAttached(()=>{
205          this.controller.enableAdsBlock(true);
206        })
207    }
208  }
209}
210```
211
212需要注意的是，AdsBlockManager的DisallowedList和AllowedList列表不会持久化，因此重启应用后会重置为空。
213如果Web组件未通过[enableAdsBlock()](../reference/apis-arkweb/js-apis-webview.md#enableadsblock12)接口开启广告过滤功能，上述接口设置在此Web组件中将不起作用。
214
215### 收集广告过滤的信息
216在Web组件的广告过滤开关开启后，访问的网页如果发生了广告过滤，会通过Web组件的[onAdsBlocked()](../reference/apis-arkweb/ts-basic-components-web.md#onadsblocked12)回调接口通知到应用，应用可根据需要进行过滤信息的收集和统计。
217
218```ts
219// xxx.ets
220import { webview } from '@kit.ArkWeb';
221
222
223@Entry
224@Component
225struct WebComponent {
226  @State totalAdsBlockCounts: number = 0;
227  controller: webview.WebviewController = new webview.WebviewController();
228
229  build() {
230    Column() {
231      Web({ src: 'https://www.example.com', controller: this.controller })
232        .onAdsBlocked((details: AdsBlockedDetails) => {
233          if (details) {
234            console.log(' Blocked ' + details.adsBlocked.length + ' in ' + details.url);
235            let adList: Array<string> = Array.from(new Set(details.adsBlocked));
236            this.totalAdsBlockCounts += adList.length;
237            console.log('Total blocked counts :' + this.totalAdsBlockCounts);
238          }
239        })
240    }
241  }
242}
243```
244
245由于页面可能随时发生变化并不断产生网络请求，为了减少通知频次、降低对页面加载过程的影响，仅在页面加载完成时进行首次通知，此后发生的过滤将间隔1秒钟上报，无广告过滤则无通知。
246