Must-Have Cookie Documentation

Current Version: 0.3.7
Text Domain: mhcookie

Must-Have Cookie is a privacy-first Consent Management Platform for WordPress. It governs cookies and third‑party resources based on consent, without external trackers.

Resources are blocked at the source until allowed: Set-Cookie headers, scripts, iframes, images, fonts, and even imported CSS are controlled. The UI supports banner and dialog modes, multilingual content, geolocation-based opt-in, and Google Consent Mode v2.

How it works

Getting Started

Choose the right plan

Must-Have Cookie is an unlimited Consent Management Plugin. There are 2 available plans:

Single plan

You can use Must-Have Cookie with Single plan for 1 WordPress site. It can be the right choice if you have only 1 site, or if you would like to test what can Must-Have Cookie do (you can upgrade your subscription later).

Unlimited plan

We created Unlimited plan for freelancers and agencies. Unlimited plan can be used on unlimited sites.

Live Editor

The Live Editor lets you configure banner, dialog, and the preferences widget with instant visual feedback. You can edit texts inline, adjust styles, and switch languages while previewing exactly how users will see it.

Install Must-Have Cookie

1. Login to My account on musthaveplugins.com
2. On the next screen you will see all available plugins. You can download Must-Have Cookie installer here in the Must-Have Cookie box
3. Login to WordPress admin where you would like to install Must-Have Cookie
4. Go to Plugins > Add new and click to upload plugin
5. Select the previously downloaded ZIP file (must-have-cookie.zip) and click to install

General Settings

Here you can configure the basic functionality of the plugin.

Preview mode

When this is turned on, the plugin won't affect the frontend of your site. You can test your settings first, then turn off preview mode to activate the plugin on your site.

Mode

This setting determines which content the plugin should block.

In Notice-only mode, the plugin does not block cookies or embedded third-party content; it only displays a notification.

In Cookie-consent mode, the plugin blocks non-essential cookies until the user consents to the use of a specific cookie or its category. In this mode, embedded third-party content is not blocked.

In Full-consent mode, the plugin blocks both non-essential cookies and domains until the user explicitly consents to the use of the cookie, domain, or their category.

Display Mode

You can choose between two display modes: Full Screen and Banner.

Full Screen: This mode displays an overlay with a popup dialog, requiring the user to either give consent or close the dialog before proceeding. If the user closes the popup without taking any action, only essential resources will be enabled.

Banner: The banner is fixed to either the top or bottom of the screen, based on your preference. The detailed full-screen dialog opens only when the visitor clicks on "Details."

Consent by Geolocation

This setting ensures compliance with regional regulations by applying opt-in consent only for visitors from the European Economic Area (EEA) and the UK. For visitors from other regions, opt-out rules will apply.

The plugin uses intelligent detection to determine the visitor's citizenship, even if they are abroad or using a VPN, ensuring that the appropriate consent logic (opt-in or opt-out) is applied accurately.

Logging

When enabled, this feature logs all user consent actions, including any changes made by users. The log records the date, IP address, device information, and detailed consent data, providing a comprehensive record for compliance and transparency.

Google Consent Mode

When enabled, the plugin manages Google’s Consent Mode version 2, streamlining compliance with consent regulations.

Must-Have Cookie automatically sends consent states to Google, ensuring seamless integration with Tag Manager. This allows you to manage consent requirements for your tags directly in Tag Manager, while the plugin handles the rest effortlessly.

In addition, Must-Have Cookie offers advanced resource management. If a user does not give consent, the plugin prevents the resource from loading—regardless of how it is initiated. This includes blocking resources loaded via Tag Manager, scripts, iframes, image tags, fonts, or imported CSS files, even when referenced within other CSS files.

Multi Language Mode

Enable this option to support multiple languages on your site, ensuring a seamless user experience for visitors in their preferred language.

Dialog language

If Multi-Language Mode is enabled, you can choose to display the cookie consent dialog in the current site language or adapt it to the visitor’s browser language for a more personalized experience.

Enabled languages

Specify the languages you want to support in this section. If a visitor's language is not included in the list, the site will default to the fallback language. All textual content can be fully customized for each enabled language.

Consent expiry

If the visitor accepts all cookies and services, their consent will be stored until they withdraw it. However, if the visitor does not accept everything, the dialog will reappear after the set expiration period, prompting them to review their choices.

Custom CSS

While you can configure colors for the banner, dialog, or widget, you can also write your own CSS rules here to customize the consent dialog and widget down to the smallest details.

Banner

If you choose the banner display mode, you can customize the banner's text, colors, and position here. If Multi-Language Mode is enabled, a language selector will appear, allowing you to modify the text separately for each language.

You can edit textual content, including message and buttons, directly in the live editor. Simply click on the content you want to modify.

Color scheme

Select the main colors for the dialog to match your site's design. You can instantly see the changes in the live preview. For more advanced customization, use the Custom CSS option in General Settings.

Banner position

Decide where the banner will be displayed on your site for optimal visibility and user experience. You can choose between positioning it at the top or bottom of the screen to best suit your design and layout.

Dialog

If Multi-Language Mode is enabled, a language selector will appear, allowing you to modify the text separately for each language.

You can edit textual content, including description, labels and buttons, directly in the live editor. Simply click on the content you want to modify. In dialog live editor, you can also format the text and add links.

Color scheme

Select the main colors for the dialog to match your site's design. You can instantly see the changes in the live preview. For more advanced customization, use the Custom CSS option in General Settings.

Widget

Enable the preferences widget on your site to allow users to open the consent popup and review or modify their consent settings.

Widget Type

Choose between two widget types: a text widget or an icon widget. If you select the text widget, you can customize the text using the live editor. When Multi-Language Mode is enabled, you can also edit the text for each language separately.

Icon

If you choose the icon widget, you can select an image or icon that represents the widget. Customize it to align with your site’s design and functionality.

Color Scheme

Select the widget's color scheme to match your site's design. Changes can be previewed instantly in the live editor. For advanced customization, use the Custom CSS option in General Settings.

Widget Position

Choose where the widget will appear on the site. It can be placed in one of the following positions: bottom-left, bottom-right, bottom-center, middle-left, or middle-right areas of the screen.

Cookies

In the Cookies tab, you can manage the cookies used on your site. You can add or remove cookies, edit cookie names, and update their purposes.

• Edit Purposes: Change the purpose of a cookie by clicking on the current purpose and selecting a new one from the dropdown list.
• Edit Cookie Names: Cookie names are editable, and you can use * as a wildcard for patterns.
• Remove Cookies: Any cookie can be removed by clicking the Remove link next to it.

This tab allows for complete flexibility in managing your site's cookies to ensure compliance and proper categorization.

Cookie Purposes

Each cookie must be categorized according to its purpose to comply with GDPR. Below are the available categories:

• Essential: These cookies are used without user consent. Only cookies essential for the core functionality of the site should be classified as essential. They should not store personal data or be used for profiling. Examples include session cookies required for maintaining login states.
• Required: These cookies are necessary for using the site but require user consent under GDPR. Examples include cookies related to captchas or payment gateways that are essential for completing transactions.
• Analytics: These cookies collect information about how users interact with the site, such as pages visited, time spent on pages, and bounce rates. The data collected is used to improve the site's functionality and user experience. Analytics cookies should not collect identifiable personal data unless the user explicitly consents.
• Marketing: Cookies used for marketing purposes, such as displaying personalized ads or tracking users across websites for targeted advertising. These cookies require explicit user consent under GDPR.
• Media: These cookies are used for displaying embedded media, such as videos or audio players. They ensure proper functionality and playback of third-party media content and often require user consent.
• Other Services: Any cookies that do not fit into the above categories. These might include cookies from third-party services that provide additional functionality unrelated to analytics, media, or marketing.

Proper categorization ensures transparency and compliance with GDPR, allowing users to make informed decisions about their cookie preferences.

Domains

In the Domains tab, you can manage third-party domains associated with your site. You can add or remove domains, edit their names, and assign them to specific purposes.

• Edit Purposes: Assign a purpose to each domain by clicking on its current purpose and selecting a new one from the dropdown list.
• Edit Domain Names: You can modify domain names to match your setup. Use * as a wildcard for subdomains or patterns.
• Inline Descriptions: Provide human-readable descriptions for each domain or resource. These notes appear in the dialog and shortcodes so end-users know why a host/resource is used before granting consent.
• Remove Domains: Remove any domain by clicking the Remove link next to it.

This tab allows you to control the behavior of third-party domains, ensuring compliance with GDPR and proper categorization.

Domain Purposes

Each domain must be categorized according to its purpose to comply with GDPR. Below are the available categories:

• Essential: Domains essential for the core functionality of the site, such as content delivery networks (CDNs) or domains serving critical assets (e.g., scripts, stylesheets). These domains are necessary for the site to function properly.
• Required: Domains necessary for specific functionalities, such as captchas or payment gateways, that are required to provide essential services. These require user consent under GDPR.
• Analytics: Domains used for analytics purposes, such as collecting data about site traffic, user behavior, and interactions. These domains facilitate performance improvements and user experience optimization but require user consent for activation.
• Marketing: Domains used for marketing purposes, such as displaying targeted ads or tracking user activity for advertising strategies. These require explicit user consent under GDPR.
• Media: Domains used for embedding or displaying media, such as videos, images, or audio content. These domains ensure proper functionality of third-party media content and may require user consent.
• Other Services: Any domains that do not fit into the above categories. These may include third-party services providing additional functionalities unrelated to analytics, media, or marketing.

Proper categorization ensures transparency and compliance with GDPR, allowing users to make informed decisions about their interactions with third-party domains.

Logs

The Logs tab displays detailed consent data, including:

• Device ID: The unique identifier of the user's device, showing all consents associated with it over time.
• Consent: A detailed record of what the user consented to, including specific cookie categories or services.
• IP Address: The user's IP address at the time of the consent action.
• Device: Information about the user's device type.
• Timestamp: The exact date and time of the consent action.

System

The System tab provides essential tools for managing your license and performing maintenance operations.

• License: Displays whether your license is active. If the license is already connected, you can disconnect it here to replace it with a different one.
• Scan: Must-Have Cookie includes an automated real-time scanning feature that detects new cookies and domains on your site. You can also initiate a manual site scan from this tab.

Dialog Triggers

The consent UI can be controlled via hash links, CSS triggers, programmatic events, custom DOM events, and a postMessage API. Use these to integrate buttons/links without writing custom JS.

document.dispatchEvent(new Event('mhcookie/do/show_dialog'));
document.dispatchEvent(new Event('mhcookie/do/hide_dialog'));
document.dispatchEvent(new Event('mhcookie/do/store_consent'));

parent.postMessage({type:'mhcookie/allowHost', host:'www.youtube.com'}, '*');
parent.postMessage({type:'mhcookie/allowMedia'}, '*');
parent.postMessage({type:'mhcookie/allowAll'}, '*');
parent.postMessage({type:'mhcookie/forceReload'}, '*');

Shortcodes

With shortcodes, you can integrate the plugin's functions anywhere on your site.

Consent History

Using the [mhcookie_consent_history] shortcode, you can display the user's consent history on your page. If the user has not provided any consent yet, the section will remain blank.

Usage:

[mhcookie_consent_history]

Cookies

Using the [mhcookie_cookies] shortcode, you can list all the cookies used on your site, grouped by their purpose, along with a description of each purpose.

Usage:

[mhcookie_cookies]

Details

Using the [mhcookie_details] shortcode, you can display a link or button that opens the consent dialog.

Attributes:

• style possible values: btn or empty. If you set it to btn, it will use Must-Have Cookie primary button style, otherwise it will be an unformatted <a> tag.
• text any text for the link/button. If it is not set it will use the default text of Details button.

[mhcookie_details style="btn" text="Show details"]

Domains

Using the [mhcookie_domains] shortcode, you can list all the domains used on your site, grouped by their purpose, along with a description of each purpose.

Usage:

[mhcookie_domains]

Entities

Using the [mhcookie_entities] shortcode, you can list all the cookies & domains used on your site, grouped by their purpose, along with a description of each purpose.

Usage:

[mhcookie_entities]

Group Description

Using the [mhcookie_group_description] shortcode, you can display a purpose group description.

Attributes:

• group possible values: essential, functional, analytics, marketing, media, other.

[mhcookie_group_description group="analytics"]

Opt-in

Using the [mhcookie_optin] shortcode, you can display a link or button that, when clicked by the user, accepts the categories you have configured.

Attributes:

• type possible values: accept-all, accept-required
• style possible values: btn or empty. If you set it to btn, it will use Must-Have Cookie primary button style, otherwise it will be an unformatted <a> tag.
• text any text for the link/button. If it is not set it will use the default text of Accept All / Accept Required button.

[mhcookie_optin type="accept-all" style="btn" text="Accept all cookies & services"]

Opt-out

Using the [mhcookie_optout] shortcode, you can display a link or button that revokes all previous consents when clicked by the user.

Attributes:

• style: Possible values are btn or empty. If set to btn, it will use the Must-Have Cookie primary button style. Otherwise, it will render as an unformatted <a> tag.
• text: Any text to be displayed on the link or button. If not set, the default text "Withdraw Consent" will be used.

[mhcookie_optout style="btn" text="Revoke consent"]

Placeholder

If you have an embedded script on your site that creates an iframe or some content, nothing will be displayed while it’s blocked. In such cases, you can either add a data-mhcookie-placeholder attribute to the <script> tag or insert the [mhcookie_placeholder] shortcode in the area where the script generates the content. Attributes:

• src: The url of the script

[mhcookie_placeholder src="https://example.com/embed.js"]

Available Filters

add_filter('mhcookie_option_consent-expiry', function($value){
    return max(30, min(395, (int)$value));
});

Available Actions

Compatibility Features

JavaScript API

if (!window.mhCookieIsBlocked('https://www.youtube.com/embed/xyz')) {
  // safe to load
}

REST API

Changelog