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
        },
        …
    ],
    …
}

⚠️Warning: Be careful when adding new surrogate scripts to the mapping.json file. The block lists are regenerated using the version of mapping.json pushed to main (not the version most recently released). From there, redirection rules are automatically added, sometimes even for requests that have specific exceptions. If the surrogate script in question is not yet available on a given platform, the corresponding requests might start being blocked!⚠️

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