# Autoconsent
This is a library of rules for navigating through common consent popups on the web. These rules
can be run in a Chrome extension, or in a Playwright-orchestrated headless browser. Using
these rules, opt-in and opt-out options can be selected automatically, without requiring
user-input.
## Using the library
Autoconsent is meant to be used in browser apps and extensions. [DuckDuckGo browser apps](https://duckduckgo.com/app) use this library to automatically handle cookie consent popups.
To integrate Autoconsent, you'll need to instantiate the main `AutoConsent` class in a content script (running in isolated page context), and implement some configuration hooks in a background script. See [this document](docs/api.md) for more details on internal APIs and data flows.
```javascript
import AutoConsent from '@duckduckgo/autoconsent';
import { autoconsent } from '@duckduckgo/autoconsent/rules/rules.json';
const autoconsent = new AutoConsent(
chrome.runtime.sendMessage, // provide a callback to send messages to the background script
null, // optionally provide a config object here if you don't want to implement a background script
{ autoconsent },
);
// connect the message receiver callback to handle messages from the background script
chrome.runtime.onMessage.addListener((message) => {
return Promise.resolve(consent.receiveMessageCallback(message));
});
```
In some environments (e.g. browser extensions), it's useful to access [eval snippet functions](./lib/eval-snippets.ts) directly in the background script. This can be done by importing the `evalSnippets` object from the library:
```javascript
import { evalSnippets } from '@duckduckgo/autoconsent';
```
### Heuristics
The heuristic popup and button classification is available on its own, without DOM dependencies, so it can run in Node (e.g. to post-process crawl data):
```javascript
import { checkHeuristicPatterns, classifyButtonTextRegex, classifyButtons, classifyPopup } from '@duckduckgo/autoconsent/heuristics';
classifyButtonTextRegex('Reject all'); // 'reject'
```
`dist/autoconsent.playwright.js` also exposes `window.autoconsentHeuristics.getPotentialPopups(timeout)` and `getButtonData(element)`, so other scripts injected into the same world can reuse autoconsent's popup and button discovery.
## Browser extension
Autoconsent comes with a reference extension implementation. It is not published in stores since the feature is available in all [DuckDuckGo apps](https://duckduckgo.com/app), but you can build it yourself and use for testing.
To build the extension:
```bash
# Download dependencies
npm install
# Build the extension
npm run prepublish
```
The extension-specific code can be found in the `addon` directory. There are two versions of the
addon (found under `dist/addon` after building), one for `mv3` version for Chromium-based browsers, and a `firefox` version for Firefox.
You can load these in [Chrome](https://developer.chrome.com/docs/extensions/mv3/getstarted/#unpacked)
in developer mode, and in [Firefox](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/)
as a temporary addon.
### Watch mode
For development, you can run in watch mode
```bash
npm run watch
```
This will rebuild the extension on every source file change. You still need to refresh the extension in the browser to see the changes.
## Using with Puppeteer
See [puppeteer.md](./docs/puppeteer.md) for a full integration guide.
## Rules
The library's functionality is implemented as a set of rules that define how to manage consent on
a subset of sites. These generally correspond to specific Consent Management Providers (CMPs)
that are installed on multiple sites. Each CMP ruleset defines:
* If the site is using that CMP
* If a popup is displayed
* Steps to specify an 'opt-in' or 'opt-out' consent for the CMP.
* Optionally, a test if the consent was correctly applied.
There are currently two ways of implementing a CMP:
1. As a [JSON ruleset](./rules/autoconsent/), intepreted by the `AutoConsent` class.
1. As a class implementing the `AutoCMP` interface. This enables more complex logic than the linear AutoConsent
rulesets allow.
For more details on rule types, see [Rule Syntax Reference](docs/rule-syntax.md).
## AI agent setup
The agent skills in `.agents/skills/` need a few environment variables.
1. Copy the contents from [`.claude/user-settings.json.TEMPLATE`](.claude/user-settings.json.TEMPLATE) to your user settings (e.g. `~/.claude/settings.json`), in addition to your existing config. If your settings already have an `env` block, merge the entries into it: a second `env` key would silently override the first.
2. Replace the values in the template. Proxy values must be complete URLs with an `http://`, `https://`, or `socks5://` scheme, and without embedded credentials. `REGIONAL_PROXY_USERNAME` and `REGIONAL_PROXY_PASSWORD` are optional: they are only used for `https://` proxies, so remove them if your proxies don't need authentication. `OXYLABS_USER` and `OXYLABS_PASSWORD` are optional too: they enable the `oxylabs-testing` skill for sites that show our proxies a bot wall, so remove them if you don't have an Oxylabs account.
3. Start a new Claude Code session: settings are only read at startup.
For other agents or plain shell use, `export` the same variables in your shell profile instead.
## License
MPLv2.
## Manual Testing
To test the extension / addon with Firefox, open the `about:debugging`, navigate to "This Firefox" on the menu and under "Temporary Extensions" click on "Load Temporary Addon". Select the `manifest.json` file from the `dist/firefox` directory. You will need to build the extension before as described above. The extension should then be active and you can test it manually by simply visiting websites.
README-Quelldatei lesen