Table of contents
Installing Cookie Cutter GDPR Auto-Deny
This project is hosted on sourceforge at https://sourceforge.net/projects/cookie-cutter/. Packaged versions are available for both Firefox and Chrome (click the link to download the version for your browser). These are listed publically on the mozilla addons site and chrome web store, respectively. Download the addon, follow the prompts in your browser to allow installation and grant permissions, and then the addon is installed.
Installing Development and Pre-Release versions of Cookie Cutter GDPR Auto-Deny
For developers and people who want cutting-edge versions that aren't publically released yet, you can clone the repository and install the unpackaged addon. For this to work you will need to have a local copy of the sourceforge code repository downloaded to your computer.
When installing the addon in developer mode, you need to make sure that it is compiled for your specific browser program.
To do this, run ./build.sh firefox false (firefox) or ./build.sh chrome false (chrome) from the source code directory BEFORE attempting to load the addon in your browser.
This build script is written for linux, but it should work on mac os or windows (if cygwin is installed).
Once that's done, we can install the addon.
In firefox (version 90+) this can be done using the Hamburger Menu (3 bars on the right) -> Settings -> Extensions and Themes -> Cog Icon -> Debug Add-Ons -> Load Temporary Add-on -> Open the manifest-ff.json file in the code repository.
In chrome (version 92+) this can be done using the Hamburger Menu (3 vertical dots on the right) -> Settings -> Extensions -> Developer Mode -> Load Unpacked -> Open code repository directory.
To select the addon, choose the location where you cloned the repository and select either the folder itself or the manifest.json file (depending on your browser).
This will install the development version of the addon.
Configuring Website Settings for the Current Site
These settings are only available for configured websites. If the website you have open has not yet been configured for this addon, see the section on Adding Support for Additional Websites below.
Here is what the per-website settings popup looks like for a configured website.
Website Settings
Cookie Cutter GDPR Auto-Deny currently has two settings which are configured on a per-website basis. These settings apply only for websites which have an associated rule (i.e. websites which have been configured for Cookie Cutter, either by Cookie Cutter developers or by the user).
The first setting is enable/disable, otherwise known as the whitelist.
Cookie Cutter rules are enabled by default for all supported sites but can be disabled for a particular site by unchecking this checkbox.
When a website is whitelisted Cookie Cutter rules will not be applied and you will need to configure cookie settings through the website as if Cookie Cutter were not installed.
Rules for other sites remain active; this is a per-website setting, not a global setting.
If you want to re-enable the Cookie Cutter rule once a site is whitelisted, simply change the setting again and Cookie Cutter will once again be active on the site.
When a site is whitelisted, the cookies it used to store your preferences will be cleared, so you will be greeted with the site-specific cookie consent prompt.
In rare cases this might also log you out of the website.
The second setting available is visibility. By default Cookie Cutter hides all cookie prompt containers so you don't even notice that they are there. However if you want to peek under the hood and see what Cookie Cutter is actually doing you can change this setting so that the cookie prompts are visible (though still grayed out). This will let you see what Cookie Cutter is clicking, and can provide insight if a website isn't working as expected. As with the whitelist this is a per-website setting and is not globally applied.
Website Actions
In addition to per-website settings, there are also some per-website actions available in recent versions of Cookie Cutter. The first two listed actions are present to allow rules to be updated in case website code changes, since websites can change their code any time. Although each rule is thoroughly tested before being included, just because it worked once doesn't mean it will continue to work forever.
The first action ("Reconfigure this site manually") allows you to manually reconfigure this site in case it's not working because website code changed. This lets you create a locally-updated rule to fix Cookie Cutter and make it work for the current site. This is something you can do yourself, and works exactly the same as Adding Support for Additional Websites. Once support for this website is updated, we encourage you to submit your updated rule via the All Website Settings configuration page so we can get it fixed for everyone in future versions.
The second action ("Report this site as broken") lets you inform the developers that a supported site isn't working as expected (likely because website code changed). This is useful in cases where manually reconfiguring the site is not easy due to changes the website made. When you report a broken site, the developers will attempt to update support for the site and fix it in future versions of the addon.
The third and final action ("Display currently-loaded site rule json") is a debugging tool used by developers and technical users. It shows the internal json representation of the Cookie Cutter rule currently in use by this website. Most users can ignore this action, and in future versions we might hide it by default to avoid confusion.
Configuring All Website Settings
Recent versions of Cookie Cutter GDPR Auto-Deny (1.1.0 and later) include a global settings page for configuring many website preferences at once as well as adding customizations. This can be accessed in one of two ways: either by the browser addon preferences button, or by clicking "View All Settings for All Domains" in the addon popup.
Here is what the settings page looks like. The settings shown for the askubuntu.com domain are the default settings for all domains.
The checkboxes here work the same way as the popup checkboxes; this display just puts them all in one place.
For manually configured domains the display looks a little different. Here's what that looks like when there is no default rule.
If you want your custom rules to be available by default in future versions of Cookie Cutter, you can submit those rules to the addon developers. We will verify that the rule works as expected and if so support will be included in future releases. This is good for the addon's functionality in general, and also helps you save some time if you install this addon on other computers.
Finally for domains which have been manually configured but also have a default rule, there's an option to reset to the default rule.
Because websites are subject to change at any time, we now accept site support requests for updated rules as well, even if a default rule is already present.
Rules are defined by JSON objects, and this view gives you the option to edit these objects. This is considered advanced functionality and should only be used by programmers or people with technical knowledge. This can be useful in cases where the manual configuration tool didn't quite configure the site correctly by default. As an example this could occur if the page refreshed before Cookie Cutter saved the relevant cookie information, which can cause the disable/whitelist functionality to not work for that domain. In order to allow customization at this level, we include a very simple text edit view that allows this data to be changed. You can put anything in this field as long as it's valid JSON, but it won't work correctly unless you follow the expected data format which is present in the default ruleset.
Once saved this rule will be applied. For domains which have a default rule this can later be reset. For domains which have no default rule there is no reset/undo functionality so be careful!
Adding Support for Additional Websites
Cookie Cutter by default comes with support for over 200 websites (at time of writing), including some of the most popular websites on the internet. On those websites you shouldn't need to do anything; it should already be configured and work as expected.
However as there are millions of websites on the internet, you might find that Cookie Cutter isn't configured for some sites you use. Not to worry; Cookie Cutter provides the option to add support for any new site you come across in just a few clicks!
To add support for a site, first open the Cookie Cutter menu while you are navigated to that site. The add support option will only be visible if the site is not already configured, or if the site is currently whitelisted. If the site already has a rule and is not whitelisted this option will not be shown.
Once you click the "Configure this site manually" button, you will be put into element selection mode. You can cancel this any time by clicking the cancel element selection button.
When in element selection mode you will be shown an outline of any element you hover over, and when you click an element it will become highlighted. Once an element has been selected you will be shown a prompt which asks what type of element you just selected.
Available options are: Container (the entire cookie prompt container or dialog), Block All (the button or link that denies all cookies), Additional Dialog (i.e. this button/element opens another dialog from which deny/block can then be selected), or Checkbox (a checkbox or radio button that sets options prior to final confirmation). You can select as many containers, additional dialogs, and checkboxes as are required for the site you're adding support for. In the case that there is a form, the Block All action will be the final submit button for that form once all options have been configured.
Once a Block All action has been selected, the rule will be saved and cookies will be automatically denied by Cookie Cutter on every subsequent visit to this site.
Once a rule is created it will be stored locally and function as you configured it. However it will not be immediately available to other users of this addon. This rule will only be present in your installation and not for anyone else. If you want this rule to be available by default for all future users of this addon, follow the instructions in Submitting Custom Website Support Rules to get your rule added to the default ruleset.
If you are unable to successfully configure support for a website yourself and you think the site should be supported by default, please file a ticket on sourceforge asking that support be added for the site in question. We will attempt to add support if possible in future versions of Cookie Cutter.
Submitting Custom Website Support Rules
Manually configured domains/rules means sites whose configuration you created via the Adding Support for Additional Websites process.
Beginning with release 1.2.0, if you have manually configured Cookie Cutter support for a website, you will then have the option to share your configuration with the addon developers. There are several reasons why you may want to submit support for additional websites, but in short it makes the addon more useful for everyone. Once a domain rule has been submitted and the developers have verified that it works as expected, it will be included by default in future Cookie Cutter releases. This means that (once the next release is made) when you or anyone else installs this addon in the future manual configuration will no longer be needed and it will just work as expected.
In order to submit a custom rule, first you need to open the All Website Settings view. This can be accessed in one of two ways: either by the browser addon preferences button, or by clicking "View All Settings for All Domains" in the addon popup. For detailed documentation about everything you see on this view, see the Configuring All Website Settings section. In this section we will focus soley on the rule submission process.
The option to submit a new rule will appear for domains which were not already configured in the default ruleset.
Rules in the default ruleset do not need to be submitted, and if you have made no customizations there will not be an option to submit those rules.
If you have made customizations for default-configured domains, you will see an option to submit the customized rule as an update. This can be useful since websites can change their consent popup code over time and Cookie Cutter needs to continuously update to reflect these changes. Please use this ONLY when the site is currently broken in the default ruleset and your new configuration fixes it. If our current default rule already works, we will ignore your submission.
Here is what the option to submit a new or updated rule looks like (note that the example domain here, stackexchange.com, is already included in the default ruleset; this is just an illustration):
Once you click the Submit Custom Rule button a pre-filled submission form will open in a new tab. You should see your manually-configured domain listed under the rules to be submitted section. This submission form is on the documentation site at cookie-cutter.sourceforge.io, which is probably also where you're reading this now. All you need to do is to provide your email address and demonstrate that you're a human; everything else is done for you. If you want your name to appear in the credit section, toggle the checkbox for that option. We will need to know your name in order to give you credit.
After you enter your email address and hit submit, if all went well you will see a success message. If this is what you see, that's it. You can close the submission tab and go on with your day. Thanks for your help in adding additional site support!
If anything goes wrong during submission you should see an error. Some example of errors are "Email Address Invalid" (if your email address isn't correct) or "CAPTCHA challenge failed" (if you didn't correctly fill out the hCAPTCHA CAPTCHA field to show that you're human). If this occurs, please correct the noted error and try your submission again. If there is an error that you don't understand or can't fix, please open a ticket on sourceforge and we will look into it. If we can reproduce your problem, we will attempt to fix it.
Heuristic (DOM Element) rules
Per a feature request filed on sourceforge, Cookie Cutter supports Consent-O-Matic style rules based on the presence of certain elements in the DOM, as a fallback for websites which have no explicit rules defined. This feature was added in version 1.2.0 and is present in all later versions. Cookie Cutter behaviour on sites with explicit rules defined (either manually or from the default rule set) is not affected by this setting. Support for this is DISABLED BY DEFAULT because of a number of limitations of this approach which can lead to a suboptimal user experience on sites that are supported only by this approach.
From a user perspective, the biggest limitation is that whitelisting will not work for sites that have DOM-based rules applied. The ruleset imported from Consent-O-Matic does not have the necessary information to apply whitelist settings without manually clearing cookies, and the popup where the setting is shown doesn't currently have sufficient information to know whether or not a DOM rule was applied. As a result, when DOM rules are enabled you will not be able to set whitelist settings for any sites that make use of these rules. Websites which are in the default-enabled domain-based ruleset are unaffected by this and will continue to have whitelist support as expected.
One other notable limitation is that DOM-based rules are based on imperfect heuristics which can be wrong. If a DOM rule is incorrectly applied (applied when it shouldn't be because other elements with the same id happen to be on the page, for example), incorrect and unexpected behaviour may result.
Those notes aside, turning on DOM based rules can be a quick way to add support for hundreds of websites which would otherwise be unsupported by this addon. So if you understand the tradeoffs and want to enable this setting anyway, just turn it on in the all settings (options-ui) page.
Here is what the DOM rules section of the settings page looks like (the section which contains the same text as above is snipped out for brevity).
Reporting Issues or Bugs
If a supported website isn't working correctly, we now (as of version 1.4.0) offer actions to manually reconfigure the site or report the site as broken. An error that only occurs for one particular website is usually not a bug in Cookie Cutter but we still want to know about it so we can fix support for that website in the default ruleset. See Configuring Website Settings for the Current Site for information about how to do this.
Bugs are tracked via sourceforge tickets. Please use https://sourceforge.net/p/cookie-cutter/tickets/ to report any bugs that you find. We try our best to address all bugs in a timely manner but this is an open-source project with limited manpower so please be aware of that.
How to contribute to this project
Please note that contributions are on a VOLUNTEER basis. If you contribute to Cookie Cutter, your work will be credited but will not be paid.
Additional Site Support
If you visit a website that has a cookie consent dialog but is not currently supported by this addon, add support for it and then submit your rule for that site. This is the easiest way for most users to contribute, and is why this addon has support for so many websites.
Translations
If you speak multiple languages you can help us by translating this addon into more languages. Please fill out the translation offer form to let us know what languages you speak and what translation experience you have. In order to fully support a new language we need to have the addon itself as well as the documentation and forms translated. At this time we will consider accepting translations for all languages which use left-to-right-top-to-bottom writing systems (such as the latin alphabet). We are most interested in languages which are spoken in EU member states.
The original version of this addon is written in English and the English text is considered the reference which should be used as a basis for translation into other languages.
Development
Cookie Cutter is Free and Open Source software, under the terms of the GNU LGPL v3. As such its code is available for anyone to view, modify, and edit. Cookie Cutter is currently hosted on sourceforge and is versioned in git. As with all web extensions, Cookie Cutter is written primarily in javascript and in order to contribute you will need to be somewhat familiar with javascript, html, and css. If you have meaningful contributions that can help the project, we encourage you to put them in and open a Merge Request (aka a Pull Request) so we can put your changes in future releases. If you are a developer and want to help but don't know where to start, check open tickets on sourceforge and TODOs in the code.
Credit
The following people have worked on this project.
Development
- Lead Developer - Dan M
Translation
- English - Dan M
- French - TBD
Site Support
There are many site support contributions which aren't included here, either because they were made anonymously or because they were added prior to this credits section. If you previously added support for sites and would like to be credited here, please contact us. We will verify some details (what site rules were added, when, submitter email address) and add your name and chosen link here.