iyo 的 Web 扩展辅助过滤解决方案

这是一个图书馆,提供集成 eyo's Ad Blocking Core 用于铬和Firefox扩展(如 附加障碍) (中文(简体) ). 广告 封锁核心在 adblockpluscore 目录。 见该目录的内容 以供参考.

行为守则

这个项目的所有捐助者都必须阅读并跟踪我们 行为守则。 。 。 .

目录结构

core/sdk/
├── adblockpluscore/        # adblockpluscore ad-filtering engine
├── docs/                   # Documentation
├── dist/                   # SDK distribution files
├── scripts/                # Build scripts and tooling
├── src/                    # SDK Source code
│   ├── all/ (or shared/)     # Code for any execution context
│   ├── background/           # Code for background process
│   ├── content/              # Code for isolated world
│   ├── front/                # Code for UI page and isolated world
│   └── main/                 # Code for main world
└── test/                   # Functional tests

SDK源代码由 执行上下文。 。 。 .

开始

图书馆分为四个部分:

• ewe-api.js 包含在扩展的背景页面中
• ewe-content.js 要装入为内容脚本( 孤立世界)
• ewe-content-main.js 要装入为内容脚本( 主世界)
• ewe-content-api.js 将导入扩展名的各种内容脚本
• ewe-ui.js 要装入扩展名的各种UI页面

你可以从 无。 。 。 .

此外,SDK还提供独立的公用事业,在这两个部门都能够工作 浏览器扩展上下文,以及其他Javascript上下文.

有了两个版本的API,《宣言V2》和《宣言V3》 您需要两个不同的列表, 取决于您的 API 目标.

支持的浏览器

网外过滤解决方案(作为短期,我们使用“引擎”) 以下版本:

宣言五2:

• 127和最新铬
• Firefox 128 和最新版本
• 最近的边缘

Chromium 129和较新的不支持MV2网络扩展,因此版本为"128.06613.0" 用于MV2测试.

外观V3:

• 127和最新铬
• 最近的边缘
• Safari 最新- iOS 和 macOS( 有限支持)

由扩展和 Webext 支持的浏览器列表可见于 支持的浏览器。 。 。 .

V2声明

对于"宣言"V2,扩展 manifest.json 要求 包括下列配置:

{
  "manifest_version": 2,
  "background": {
    "scripts": [
      "ewe-api.js"
    ]
  },
  "content_scripts": [
    {
      "all_frames": true,
      "js": [
        "ewe-content.js"
      ],
      "match_about_blank": true,
      "matches": [
        "http://*/*",
        "https://*/*"
      ],
      "run_at": "document_start"
    }
  ],
  "permissions": [
    "webNavigation",
    "webRequest",
    "webRequestBlocking",
    "scripting",
    "storage",
    "unlimitedStorage",
    "tabs",
    "<all_urls>"
  ]
}

V3声明

对于表V3,扩展 manifest.json 要求 包括下列配置:

{
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "all_frames": true,
      "js": [
        "ewe-content.js"
      ],
      "match_about_blank": true,
      "matches": [
        "http://*/*",
        "https://*/*"
      ],
      "run_at": "document_start"
    }
  ],
  "permissions": [
    "declarativeNetRequest",
    "scripting",
    "storage",
    "tabs",
    "webNavigation",
    "webRequest",
    "unlimitedStorage"
  ],
  "host_permissions": [
    "<all_urls>"
  ],
  "declarative_net_request": <output from "subs-generate" script>
}

上面的例子需要几处修改,不能使用 现为.

这个 service_worker 需要将值设置为您构建的文件 背景脚本,包括 ewe-api.js。 。 。 .

请注意,对于上面的样本,你需要确保设置 数值 declarative_net_request 适当的时候, 显示于 解析网 文档。 。 。 . 这意味着您还需要在扩展名中添加包含 本节中声明的规则以及文本过滤列表。 参考 改为 宣言V3文件 更多细节.

许可 declarativeNetRequestWithHostAccess 要求 host_permissions 将会是 <all_urls>。你可以使用 declarativeNetRequest 允许不设置 host_permissions但它将起到防止 过滤内容并限制网络请求的屏蔽 中指明的 host_permissions默认配置 提供的功能最多.

需要的许可和为什么我们需要这些许可

WebExt 自动过滤解决方案需要多个权限才能运行 对 上面的表单文件模板包括所需的权限. 这就是为什么我们需要每个:

• webNavigation: 允许访问 Web 导航 API, 我们使用它 应用文档级别允许过滤并屏蔽弹出.
• webRequest: 给予访问网络请求 API. 用于应用 URL 过滤器 在MV2中,并在MV3中报告URL过滤器. 也用来取回站点密钥 为网站.
• webRequestBlocking (仅MV2):允许基于 URL 过滤器的屏蔽请求 在MV2中进行.
• declarativeNetRequest (仅MV3):允许访问声明网 请求API,我们使用它来应用MV3中的URL过滤器.
• storage: 允许访问存储的 API, 我们用来存储下载的 API 订阅,用户自定义过滤器等.
• unlimitedStorage:默认情况下,只允许扩展存储 5MB, 这还不足以让更多的人订阅 此权限可以删除 限制.
• tabs: 允许访问一些标签元数据, 包括标签的 URL, 即 用于在标签上应用允许过滤的文档级别.
• scripting: (仅限MV3和Firefox MV2). 曾经应用内容过滤器, 包括元素隐藏过滤器和片段过滤器.
• <all_urls>:允许WebExt Ad-Filtering解决方案在所有网站上采取行动. 请注意,在MV2中,这表现在 permissions,但在MV3 说明这是新的 host_permissions 节.

浏览器扩展权限及其效果 谷歌的文档为 MV2 权限 财务报告和审定财务报表 MV3 权限

API 密码

API 将以您自己的背景脚本和UI 页面通过 全球 EWE 对象。 在背景脚本中,请拨打 EWE.start() 开始屏蔽广告.

至少需要将下列信息传递给 EWE.start()数字 :

• bundledSubscriptions (仅限 Express v3)
  可在 bundledSubscriptionsPath
• bundledSubscriptionsPath (仅限 Express v3)
  包含 ABP- syntax 过滤器列表的扩展构建中的目录路径 文件
  例如/数据/规则/附录
• heavyDependenciesPath
  扩展架构中 dist/ewe- heavy-dependency.js 文件的路径
  例如,/vendor/@yeo/webext-ad-filtering-solution/havy-dependenies.js

注意在MV3扩展中, EWE.start() 必须在第一个 服务员事件循环的转弯,以便它能够附加 事件听众.

模块捆绑器( 可选)

ewe-api.js 财务报告和审定财务报表 ewe-ui.js 作为UMD模块构建(Universal模块) 定义),并因此也可以与模块捆绑器一起使用.

如果对背景脚本使用模块捆绑器, 别 添加 ewe-api.js 给您的 manifest.json。类似地,如果对脚本使用模块捆绑器 UI页面, 别 添加 ewe-ui.js 到你的UI页面. 因此,不会有一个全球 EWE 对象.

常见JS

const EWE = require("@eyeo/webext-ad-filtering-solution");
EWE.start(addonInfo);

无害环境管理

import * as EWE from "@eyeo/webext-ad-filtering-solution";
EWE.start(addonInfo);

也可以导入内容脚本. 这只应包括一次 扩展名,因为它开始运行内容脚本而无需调用 任何一种"启动"功能.

import "@eyeo/webext-ad-filtering-solution/content";

任何情况下都可以使用的个别公用事业也可以进口.

import {Scheduler} from "@eyeo/webext-ad-filtering-solution/all/scheduler.js";

用于在UI背景下运行的功能性(流行、选项等) 将使用 ewe-ui.js 文档。 可通过下列方式导入到这些页面: 使用ui页中的以下机制:

import * as EWE from "@eyeo/webext-ad-filtering-solution/ui";

或直接处理捆绑和导入生成的文件:

<script src="ewe-ui.js"></script>

在内容脚本上下文运行的功能性 将使用 ewe-content-api.js 文档。 此选项可通过 使用下列机制:

import * as EWE from "@eyeo/webext-ad-filtering-solution/content-api";

片段过滤支持

这个 片段库 默认可用 EWE。 。 。 . 查阅文件 片段过滤器 学会如何学习 使用它们.

共有资源

有一些共享资源被两个Webext-ad-filtering-Solution使用 生产代码( p) :

• browser
  • 全局由网络扩展-多填充版本0.8.0.
• browser.runtime.connect()编号 :browser.runtime.onConnect
  • 频道名前缀为"ewe:".
• browser.runtime.sendMessage()编号 :browser.runtime.onMessage
  • 我们的信息是带有“类型”属性的对象,其值前缀为 "我们:".
• indexedDB.open()
  • 数据库名称以"EWE"为前缀.
• 网页链接
  • 模块使用的链接被前缀为"abp:"或"https://subcritic.adblockplus.org/".
• browser.storage.local 财务报告和审定财务报表 browser.storage.session
  • 存储密钥前缀有"ewe:"或"abp:pref:".

在初始化期间,引擎将遗留数据从 本地存储为索引DB。 迁移的文件必须前缀 : file:。 。 。 . 前缀的文件 file:/// 将被忽略.

通知支持

使用 通知模块 是可选的。 开始 用它,需要初始化:

EWE.notifications.start();

一个点击允许列表支持

要启用一次点击允许列表, 您需要设置列表 授权用于认证允许列名的公共密钥 请求.

EWE.allowlisting.setAuthorizedKeys(keys);

见 允许列表模块 更多文件 细节.

通过正确的算法和设置可以创建新的密钥页 使用我们的键盘页创建脚本.

npm run -w @eyeo/webext-ad-filtering-solution create-allowlisting-keypair

关于我们剧本的运行详情,见下文开发部分 以及其他EWE开发任务. 键也可以使用 其他程序如OpenSSL. 密钥使用 RSASSA- PKCS1- v1 5 算法,SHA512散列和4096位长模. 此外,何时 转至 setAuthorizedKeys,键应当为 base64 编码 字符串,使用 SPKI 格式.

npm install

npm run build -- --scope @eyeo/webext-ad-filtering-solution

cd core/sdk/
npx webpack --watch

npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --help

# Build only engine, no test extensions
npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --config-name engine

# Don't generate any sourcemaps
npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --no-devtool

npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --force-subscription-update

npm run -w @eyeo/test-utils start-sdk-server &
npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --use-external-server

npm run build:release -- --scope @eyeo/webext-ad-filtering-solution

npm run -w @eyeo/webext-ad-filtering-solution docs

npm run lint

测试

关于测试的全部文件,请参见我们 测试文档。 。 。 .

出版

SDK按照 SDK 发布进程。 。 。 .

活动

图书馆提供听众观察事件:

• EWE.allowlisting.onUnauthorized: 拒绝允许列名请求时予以批准
• EWE.filters数字 :
  • onAdded: 添加新过滤器时发送
  • onChanged: 当过滤器被启用或被禁用时,或当过滤器被禁用时,即被放出 元数据已更改
  • onRemoved: 过滤器被取出
• EWE.subscriptions数字 :
  • onAdded: 添加新订阅时发出
  • onChanged: 认购财产发生变化时被放行
  • onRemoved: 订阅被删除时被接收
• EWE.debugging.onLogEvent: 调试输出时发出
• EWE.reporting.onBlockableItem: 当任何可阻塞项目匹配时被放出

使用 addListener(...) 订阅和订阅 removeListener(...) 以取消订阅.

示意图V3

见 宣言V3文件 为进一步 解释.