# Table of Contents - [FAQ - ClearURLs](#faq-clearurls) - [ClearURLs](#clearurls) - [Permissions - ClearURLs](#permissions-clearurls) - [Excluded Fields - ClearURLs](#excluded-fields-clearurls) - [Rule Catalogs - ClearURLs](#rule-catalogs-clearurls) - [Similar Addons - ClearURLs](#similar-addons-clearurls) --- # FAQ - ClearURLs I have suggestions or complaints. Where can I submit them? If you have any suggestions or complaints, please [create an issue](https://gitlab.com/ClearURLs/ClearUrls/-/issues/new) . Before a clean URL was visible, a dirty URL was briefly in the URL bar. Does ClearURLs work correctly? Sometimes a dirty URL appears initially in the URL bar before a clean URL is displayed. This does not mean that the dirty URL has been called. ClearURLs checks all requests made through the browser, whether initiated by a user or by a background process. Each request passes through ClearURLs' filter, which is incremental, meaning that sometimes a URL that is not yet clean is passed back to the browser. This URL passes through the filter of ClearURLs again before the actual call and is then further cleaned in the next step. This happens until ClearURLs make no more changes to the URL, then the URL leaves the filter of ClearURLs. It is therefore possible that a URL that is not clean may temporarily appear in the URL bar. To make sure that the URL is indeed cleaned correctly, you can use the integrated Cleaning Tool. Here you can clean the resulting URL again and again until no more changes occur, then you have the final clean URL. How can I quickly check if ClearURLs do work correctly? You can visit the [test page](https://test.clearurls.xyz/) of ClearURLs. If only green emojis shines on the page, ClearURLs works correctly. Otherwise, there is an error. Please do not forget to activate JavaScript for this test page. Why does ClearURLs require permission X? An explanation for all required permissions can be found here: [Permissions](../permissions/) For which browsers is ClearURLs available? ClearURLs is currently officially supported by Mozilla Firefox, Google Chrome, and Microsoft Edge. However, it should theoretically be possible to run the addon in all Firefox- or Chrome-based browsers. [![for Firefox](https://blog.mozilla.org/addons/files/2020/04/get-the-addon-fx-apr-2020.svg)](https://addons.mozilla.org/firefox/addon/clearurls/) [![for Edge](https://gitlab.com/KevinRoebert/ClearUrls/-/raw/master/promotion/MEA-button.png)](https://microsoftedge.microsoft.com/addons/detail/mdkdmaickkfdekbjdoojfalpbkgaddei) [![for Chrome](https://storage.googleapis.com/chrome-gcs-uploader.appspot.com/image/WlD8wC6g8khYWPJUsQceQkhXSlv1/HRs9MPufa1J1h5glNhut.png)](https://chrome.google.com/webstore/detail/clearurls/lckanjgmijmafbedllaakclkaicjfmnk) Where do I find the packed version of the addon, e.g. for debugging? Here you can download the packed files for Firefox- or Chrome-based browsers: * [ClearURLs-firefox.zip](https://gitlab.com/KevinRoebert/ClearUrls/-/jobs/artifacts/master/raw/ClearURLs-firefox.zip?job=bundle%20addon%20firefox) * [ClearURLs-chrome.zip](https://gitlab.com/KevinRoebert/ClearUrls/-/jobs/artifacts/master/raw/ClearURLs-chrome.zip?job=bundle%20addon%20chrome) How can I enable the logging feature in ClearURLs? Here you can find a step-by-step tutorial on „How to enable logging in ClearURLs“: [https://www.youtube-nocookie.com/embed/Rm1YkwXQDSM](https://www.youtube-nocookie.com/embed/Rm1YkwXQDSM) * * * Last update: May 19, 2023 [Back to top](#) --- # ClearURLs Overview[¶](#overview "Permanent link") ======================================== **ClearURLs** is an add-on based on the new WebExtensions technology and is optimized for _Firefox_ and _Chrome_ based browsers. This extension will automatically remove tracking elements from URLs to help protect your privacy when browsing through the internet. For this purpose, we use a large catalog of rules, which is actively maintained by us and the community. See also You can find more information about the structure of the rules catalog under [Specifications/Rule Catalogs](specs/rules/) . Hint You can learn more information about the required permissions under [Permissions](permissions/) . Application[¶](#application "Permanent link") ---------------------------------------------- `https://example.com?utm_source=newsletter1&utm_medium=email&utm_campaign=sale` Many websites use tracking elements in the URL to mark your online activity. All that tracking code is not necessary for a website to be displayed or work correctly and can therefore be removed — that is exactly what ClearURLs does. Another common example are Amazon URLs. If you search for a product on Amazon you will see a very long URL, such as: https://www.amazon.com/dp/exampleProduct/ref=sxin_0_pb?__mk_de_DE=ÅMÅŽÕÑ&keywords=tea&pd_rd_i=exampleProduct&pd_rd_r=8d39e4cd-1e4f-43db-b6e7-72e969a84aa5&pd_rd_w=1pcKM&pd_rd_wg=hYrNl&pf_rd_p=50bbfd25-5ef7-41a2-68d6-74d854b30e30&pf_rd_r=0GMWD0YYKA7XFGX55ADP&qid=1517757263&rnid=2914120011 Indeed most of the above URL is tracking code. Once ClearURLs has cleaned the address, it will look like this: `https://www.amazon.com/dp/exampleProduct` Features[¶](#features "Permanent link") ---------------------------------------- * Removes tracking from URLs automatically in the background * Blocks some common ad domains (optional) * Has a built-in tool to clean up multiple URLs at once * Supports redirection to the destination, without tracking services as a middleman * Adds an entry to the context menu so that links can be copied quickly and cleanly * Blocks hyperlink auditing, also known as _ping tracking_ (see also [this article](https://html.spec.whatwg.org/multipage/links.html#hyperlink-auditing) ) * Prevents ETag tracking * Prevents tracking injection over history API (see also: [the replaceState() method](https://developer.mozilla.org/en-US/docs/Web/API/History_API#The_replaceState()_method) ) * Prevents Google from rewriting the search results (prevents the insertion of tracking code) * Prevents Yandex from rewriting the search results (prevents the insertion of tracking code) Download[¶](#download "Permanent link") ---------------------------------------- [![for Firefox](https://blog.mozilla.org/addons/files/2020/04/get-the-addon-fx-apr-2020.svg)](https://addons.mozilla.org/firefox/addon/clearurls/) [![for Edge](https://docs.clearurls.xyz/1.22.0/assets/img/MEA-button.png)](https://microsoftedge.microsoft.com/addons/detail/mdkdmaickkfdekbjdoojfalpbkgaddei) Donation[¶](#donation "Permanent link") ---------------------------------------- [![Buy Me A Coffee](https://raw.githubusercontent.com/KevinRoebert/DonateButtons/master/Paypal.png)](https://www.paypal.me/KevinRoebert) [![Buy Me A Coffee](https://raw.githubusercontent.com/KevinRoebert/DonateButtons/master/BuyMeACoffee.png)](https://www.buymeacoffee.com/KevinRoebert) [Mastodon](https://infosec.exchange/@clearurls) * * * Last update: February 5, 2025 [Back to top](#) --- # Permissions - ClearURLs Permissions =========== This page describes the permissions used by **ClearURLs** and the purpose for which they are used. [``](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns#%3call_urls%3e) [¶](#all_urls "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------------------------- This permission is needed to perform URL or URI cleaning on all pages, regardless of the protocol (HTTPS, HTTP, data, etc.). [`webRequest`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest) and [`webRequestBlocking`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/BlockingResponse) [¶](#webrequest-and-webrequestblocking "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These permissions are needed to be notified of browser requests (i.e., calling a URL/website) and interrupt them to perform any cleaning that may be necessary. The cleaned URL is then passed to the browser. [`storage`](https://developer.mozilla.org/en-US/docs/Web/API/Storage) [¶](#storage "Permanent link") ----------------------------------------------------------------------------------------------------- This permission is needed to save settings, logs, and rules. [`unlimitedStorage`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#unlimited_storage) [¶](#unlimitedstorage "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This permission is needed to exceed any quota imposed by the `storage.local` API. The API otherwise limits us to 5MB, which would quickly be reached with the log turned on, thus rendering the addon unusable. This permission should become optional in the future. [`contextMenus`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus) [¶](#contextmenus "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------- This permission is required for the "Copy Clean Link Location" function on the context menu. [`webNavigation`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webNavigation) and [`tabs`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs) [¶](#webnavigation-and-tabs "Permanent link") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These permissions are needed to prevent websites from manipulating the URL in the location bar after the page load. ClearURLs listen for these events and undo the change. If you don't want this, you can disable this feature in the settings. To disable this feature, you have to switch the "Prevent tracking injection over history API" button, and then the "Save & reload" addon button. [`downloads`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/downloads) [¶](#downloads "Permanent link") ------------------------------------------------------------------------------------------------------------------------------------- This permission is required to export logs and settings. This permission should become optional in the future. * * * Last update: February 11, 2022 [Back to top](#) --- # Excluded Fields - ClearURLs Some fields are absolutely required by a page to function correctly. However, these fields may also contain tracking elements. In such cases, we only have the choice between preventing tracking and a functioning service. Below we list all the fields not included in the official rules because they have caused problems in the past. | **Site / Service** | **Field** | **Description** | | --- | --- | --- | | Google | `hl` | Required for the correct display of Google in different languages | | Google | `gbv` | Required for Google, when visiting without JavaScript | | Google | `client` | Required for asynchronous requests to the API | | Google | `stick` | Required for "People also search for" on Google search | | Google | `zx` | Required for serveral Google services (Hangout, GMail Mailenvelope, etc.) | | Amazon | `s` | Required for sort search results by "Featured", "Price: Low to High", "Price: High to Low", "Avg. Customer Review" and "Newest Arrivals" (is only not filtered on Amazons search page) | | Amazon | `psc` | Required to link to an article, which is available in different versions (e.g., color or size) | | Amazon | `SubscriptionId` | Required for subscriptions | | Amazon Search | `keywords` | Amazon search can loop without this field. See [#55](https://gitlab.com/ClearURLs/rules/-/issues/55) | | Cloudflare | `__cf_chl_jschl_tk__` | Require by Cloudflare to verify, that an user successfully passes a IUAM/JS Challenge or Captcha | | Cloudflare | `__cf_chl_captcha_tk__` | Require by Cloudflare to verify, that an user successfully passes a IUAM/JS Challenge or Captcha | | backcountry.com | `skid` | Required to link to an article, which is available in different versions (e.g., color or size) | | backcountry.com | `fskid` | Required to link to an article, which is available in different versions (e.g., color or size) | | Adobe | `cid` | Used by Adobe for tracking, but also required by many websites for correct functioning. This rule has been temporarily removed until a whitelist feature is available | | TikTok | `language` | Is no tracking and is required for the website, e.g., the profile view | | Facebook | `comment_id` | Required for comments | | Facebook | `fbid` | Required by many different functions. Used mainly as internal ID and not for external tracking | | aliexpress | `pvid` | Required for filtering search results | | taobao.com | `user_number_id` | Required for store frontpage (unique ID for specified store) | | Twitter redirects | `t` | Is required for redirect URLs inside of Twitter mails ([!21](https://gitlab.com/ClearURLs/rules/-/merge_requests/21)
) | | Firefox accounts | `context` | Is required for Firefox Sync ([!135](https://github.com/ClearURLs/Rules/pull/135)
) | | Google Search | `client` | Firefox and other browsers use this as an affiliate code. However, since this information is already accessible to Google via the User-Agent HTTP header, it does not provide any privacy benefits—only a loss of revenue for browser manufacturers. | | Google Search | `sclient` | Used by Google to indicate the search client in use. For example, `sclient=gws-wiz` signifies that the Google Web Search Wizard is being used for the search. | * * * Last update: February 24, 2025 [Back to top](#) --- # Rule Catalogs - ClearURLs Rule Catalogs ============= At the moment ClearURLs knows three types of rule catalogs – each in its respective file. We will only look at two of these three catalogs, as the first version is already outdated. Important If you want to use one of these catalogs in your project and always retrieve the current version, please use the GitLab/GitHub Pages URL to access the catalogs to preserve the GitLab/GitHub infrastructure. The catalog files are available at: GitHub (default) * data.minify.json: [https://rules2.clearurls.xyz/data.minify.json](https://rules2.clearurls.xyz/data.minify.json) * rules.minify.hash: [https://rules2.clearurls.xyz/rules.minify.hash](https://rules2.clearurls.xyz/rules.minify.hash) GitLab * data.minify.json: [https://rules1.clearurls.xyz/data.minify.json](https://rules1.clearurls.xyz/data.minify.json) * rules.minify.hash: [https://rules1.clearurls.xyz/rules.minify.hash](https://rules1.clearurls.xyz/rules.minify.hash) Important Do not use the older **data.json** catalog – it is outdated and will no longer receive any updates. Instead, use the **data.min.json** catalog! data.min.json Catalog[¶](#dataminjson-catalog "Permanent link") ---------------------------------------------------------------- The **data.min.json** catalog is a typical JSON file and saves all rules, exceptions, and redirections, that are maintained by the ClearURLs developers and the community. It is structured in **providers**. Providers are a logical unit under which multiple rules are applied under the same `urlPattern`. Examples of providers are companies or services like Google or Reddit. Every provider has the parent element **providers**, it holds the reference to all providers. Every provider has the following properties: * `urlPattern` (required) * `completeProvider` (required) * `rules` (optional) * `rawRules` (optional) * `referralMarketing` (optional) * `exceptions` (optional) * `redirections` (optional) * `forceRedirection` (optional) Example of a data.min.json file { "providers": { "provider name": { "urlPattern": "^https?://(?:[a-z0-9-]+\\.)*?domainName\\.com", "completeProvider": false, "rules": [\ "trackingField",\ ], "rawRules": [\ "/ref=[^/|?]*"\ ], "referralMarketing": [\ "tag"\ ], "exceptions": [\ "^https?://(?:[a-z0-9-]+\\.)*?domainName\\.com/re.*/redirector.html/"\ ], "redirections": [\ "^https?://(?:[a-z0-9-]+\\.)*?domainName\\.com.*url\\?.*url=([^&]+)"\ ], "forceRedirection": false } } } ### `urlPattern`[¶](#urlpattern "Permanent link") The **urlPattern** is a regular expression, that must match every URL that should be affected by the specified rules, exceptions, or redirections of the provider. The typical structure is `?`. In most cases the following expression covers all the needs, you only have to substitute the remaining `<>` fields: `^https?://(?:[a-z0-9-]+\\.)*?\\.`. If you want to match with every TLD, you can substitute the TLD field with `(?:[a-z]{2,}){1,}`. ### `completeProvider`[¶](#completeprovider "Permanent link") The **completeProvider** is a boolean, that determines if every URL that matches the **urlPattern** will be blocked. If you want to specify rules, exceptions, and/or redirections, the value of **completeProvider** must be `false`. ### `rules`[¶](#rules "Permanent link") The **rules** property is a JSON array. Every element in this array will be automatically rewritten to `(?:&|[/?#&])(?:=[^&]*)` to match the `field name`. The `field name` can still be a regular expression, but don't have to. If ClearURLs found a field that matches a rule in a given URL the field will be deleted. Only URLs that match the **url Pattern** will be checked for matching fields. ### `rawRules`[¶](#rawrules "Permanent link") Because other elements in a URL that should be filtered, besides "well-formed fields" aka normal rules, there is also the **rawRules** property. Regular expressions formulated in this property can refer to the entire URL and not just to individual fields. They are therefore applied directly to the URL. ### `referralMarketing`[¶](#referralmarketing "Permanent link") Since version 1.9.0, you can allow **referral marketing** in ClearURLs. Previously these fields were always removed. Since some people want to support other people through referral marketing, referral marketing can be allowed in the settings. If referral marketing is allowed, the regular expressions in this array are no longer filtered. Attention Referral Marketing is disabled by default. ### `exceptions`[¶](#exceptions "Permanent link") The **exceptions** property is also a JSON array. Every element in this array is a regular expression, that matches a URL. If ClearURLs found a URL, that matches an exception, no further processing on this URL is done. ### `redirections`[¶](#redirections "Permanent link") The **redirections** property is a JSON array. Every element in this array is a regular expression, that matches a URL and must follow a specification. The [first regular expression group](https://www.regular-expressions.info/brackets.html) must be the URL that should be redirected. If ClearURLs find a URL that matches the redirection, the first matching group will be decoded with will `decodeURIComponent()` and replaces the old URL. ### `forceRedirection`[¶](#forceredirection "Permanent link") Some websites, such as Google, have manipulated URLs (`` tags) in such a way that the URL is no longer called normally, rather via a built-in script. The result is that a simple redirect of the URL does no longer work. Thus, to still forward the URL by ClearURLs, there is the property **forceRedirection** which writes the URL into the `main_frame` object of the browser. rules.min.hash[¶](#rulesminhash "Permanent link") -------------------------------------------------- The [**rules.min.hash** file](https://gitlab.com/KevinRoebert/ClearUrls/-/jobs/artifacts/master/raw/rules.min.hash?job=hash%20rules) saves a SHA256 hash of the **data.min.json** file and will be automatically generated by the GitLab CI runner. It is used to ensure, that the rules are not faulty after the download. Important Note that the hash must be in lowercase. data.minify.json Catalog[¶](#dataminifyjson-catalog "Permanent link") ---------------------------------------------------------------------- The [**data.minify.json**](https://gitlab.com/KevinRoebert/ClearUrls/-/jobs/artifacts/master/raw/data.minify.json?job=hash%20rules) file is automatically generated by the GitLab CI runner from the **data.min.json** file and also the corresponding [**rules.minify.hash** file](https://gitlab.com/KevinRoebert/ClearUrls/-/jobs/artifacts/master/raw/rules.minify.hash?job=hash%20rules) . The **data.minify.json** is a minimal version of the **data.min.json** file where all line breaks and spaces, as well as default values and empty lists, are removed to save bandwidth. * * * Last update: May 8, 2021 [Back to top](#) --- # Similar Addons - ClearURLs Note This page is based on the post from [@Cimbali](https://github.com/Cimbali) : [https://github.com/Cimbali/CleanLinks/issues/20#issuecomment-395927561](https://github.com/Cimbali/CleanLinks/issues/20#issuecomment-395927561) | Addon | Removes Tracking Parameters | Removes Redirects | Type of Rules | Notes | | --- | --- | --- | --- | --- | | [ClearURLs](https://github.com/ClearURLs/Addon) | yes | partial | GitLab/GitHub-hosted rules file | | | [Google Search Link Fix](https://addons.mozilla.org/en-US/firefox/addon/google-search-link-fix) | | partial | Site-specific: google, yandex | Use unobfuscated URL present before click | | [Google Redirects Fixer & Tracking Remover](https://addons.mozilla.org/en-US/firefox/addon/google-no-tracking-url/) | yes | partial | Site-specific: google | On request only | | [Link Cleaner](https://addons.mozilla.org/en-US/firefox/addon/link-cleaner) | partial | partial | Site-specific: facebook, steam and reddit for redirects, item pages of aliexpress and amazon, utm\_\* parameters | | | [Don't Track Me Google](https://addons.mozilla.org/en-US/firefox/addon/dont-track-me-google1) | partial | | Site-specific: google | | | [Neat URL](https://addons.mozilla.org/en-US/firefox/addon/neat-url/) | yes | | | | | [LeanURL](https://addons.mozilla.org/en-US/firefox/addon/neat-url/) | partial | | Parameter-specific: utm\_\* | | | [Pure URL](https://addons.mozilla.org/en-US/firefox/addon/pure-url/) | partial | | Parameter-specific: utm\_\* and Site-specific: facebook, yandex | | | [Tracking Token Stripper](https://addons.mozilla.org/en-US/firefox/addon/utm-tracking-token-stripper/) | partial | | Parameter-specific: utm\_\* | | | [Skip Redirect](https://addons.mozilla.org/en-US/firefox/addon/skip-redirect/) | | yes | | Rewriting URLs in page | | [Remove Redirect](https://addons.mozilla.org/en-US/firefox/addon/remove-redirect/) | | yes | | Intercepting requests | | [Open Link Directly (No Redirect)](https://addons.mozilla.org/en-US/firefox/addon/open-link-directly-no-redirect/) | | partial | Site-specific: google, yahoo | | | [Untrack Me](https://addons.mozilla.org/en-US/firefox/addon/untrack-me/) | yes | | | Not open source ? | | [CleanLinks](https://addons.mozilla.org/en-US/firefox/addon/clean-links-webext/) | partial | yes | Parameter-specific: utm\_\* | | | [Referer Control](https://addons.mozilla.org/en-US/firefox/addon/referercontrol/) | | | | Modifies HTTP referer headers | | [Referer Modifier](https://addons.mozilla.org/en-US/firefox/addon/referer-modifier/) | | | | Modifies HTTP referer headers | | [HTTPS Everywhere](https://addons.mozilla.org/en-US/firefox/addon/https-everywhere/) | | | Online rules | Upgrades http requests to https | | [Consistent HTTPS](https://addons.mozilla.org/en-US/firefox/addon/consistent-https/) | | | | Stops downgrading https to http on the same domain | | [Canonical](https://addons.mozilla.org/en-US/firefox/addon/canonical-link/) | | | | Manually redirects to canonical link in page (if exists: link\[rel="canonical"\]) | | [Universal Bypass](https://addons.mozilla.org/en-US/firefox/addon/universal-bypass/) | | | Hardcoded | Automatically redirect from URL shorteners | | [Link Redirect Trace](https://addons.mozilla.org/en-US/firefox/addon/link-redirect-trace-addon/) | | | | List/trace redirects | | [Redirector](https://addons.mozilla.org/en-US/firefox/addon/redirector) | | | | User-defined redirects | * * * Last update: May 8, 2021 [Back to top](#) ---