Surrogates are small scripts that our apps and extensions serve in place of trackers that cause site breakage when blocked. Surrogates mock the API structure of the original scripts they replace, allowing pages that depend on the existence of certain methods, or properties, to function as if the original script was loaded.

All surrogates are bundled together and deployed to a CDN from which they are picked by client apps and extensions. For platforms that don't allow remote code execution this repository is imported as a git submodule and surrogates are embedded at build time.

DuckDuckGo clients using surrogates:

• Chrome and Firefox extensions
• Safari extension
• iOS app
• Android app

• scripts/ - testing and deployment scripts
• surrogates/ - surrogate files
• mapping.json - list of regular expressions that map urls to surrogates that should be served as request responses. Data from this file is incorporated into the web blocklist.

Format of the mapping.json file:

{
    "example.com": [
        {
            "regexRule": "example.com\\/rule\\/matching\\/[a-z_A-Z]+\\/file.js", // regular expression for matching urls
            "surrogate": "surrogate_name.js", // name of the file from the `surrogates/` folder
            "action": "block-ctl-example" // optional action name, used by the blocklist, indicating that this surrogate is meant for the Click To Load feature
        },
        …
    ],
    …
}

We don't take external contributions at this time, but please feel free to open issues.