Cookie Consent

A cookie banner and preferences window with Google Consent Mode v2, third-party scripts that wait for consent and an optional consent log. This guide covers installation, every setting and day-to-day use.

• Demo (Luma): https://demo.softawarecommerce.com/
• Demo (Hyvä): https://demo.softawarecommerce.com/hyva/
• Admin demo: https://demo.softawarecommerce.com/try-admin/cookie-consent
• Changelog: Release notes · Questions: FAQ

A note before you start: the module does what this guide describes and nothing more. Which tags you run, how you categorise them and what your cookie policy says are your decisions; take legal advice if you are unsure what applies to your shop.

1. Requirements

2. Installation

Cookie Consent is free. Install it with Composer from repo.softawarecommerce.com, using the Composer keys from your account on softawarecommerce.com (see https://softawarecommerce.com/shop/composer-access/):

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-cookie-consent
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

On Hyvä the module's templates are picked automatically, and the module registers itself for Tailwind source scanning. If you build your theme's CSS yourself, run your usual Hyvä build after installing.

To update later: composer update softaware/module-cookie-consent, then the same bin/magento commands.

3. Quick start

1. Open Stores > Configuration > Softaware > Cookie Consent (also under Softaware > Cookie Consent > Settings).
2. General > Enabled = Yes. The module is off after installation, so nothing changes until you switch it on.
3. Set Cookie / Privacy Policy URL to your cookie policy page.
4. Check the texts under Banner, Preferences Window and Cookie Categories for each store view.
5. Move your tracking snippets to Softaware > Cookie Consent > Third-party Scripts (section 5), or set General > Scripts in Design Configuration to a category (section 6).
6. Save Config and flush the cache. Open the shop in a private window: the banner appears.

4. Settings

Texts and most options can be set per store view. Consent version, expiry and the consent log switches are set per website, the log retention globally. Most fields show their default under the input.

General

Banner

Preferences Window

Title, introduction, the "Save Choices" button, the "Always On" text shown for necessary cookies, and the label of the close button read out by screen readers.

Cookie Categories

Google Consent Mode v2

Categories map to Google consent types as follows: Necessary to security_storage; Preferences to functionality_storage and personalization_storage; Analytics to analytics_storage; Marketing to ad_storage, ad_user_data and ad_personalization.

Appearance

By default the banner uses your theme's fonts and buttons (Luma .action.primary, Hyvä btn btn-primary). Set Use Custom Colours = Yes to choose background, text, button background, button text and link/switch colours (hex values), and optionally a Font Family.

Consent Log

5. Third-party Scripts

Softaware > Cookie Consent > Third-party Scripts holds the vendor snippets that must wait for consent, such as a Meta Pixel, Hotjar or a chat widget.

Click Add Script and fill in:

• Active, Name
• Cookie Category: the category the visitor must accept
• Position: Page head or End of page body, as the vendor's instructions say
• Store Views and Sort Order
• Snippet (HTML): paste the vendor's code as it is

On the storefront, <script> tags are output as type="text/plain" data-sw-consent="<category>"; sources of img, iframe, source, video, audio and embed tags become data-sw-src / data-sw-srcset, and external stylesheets data-sw-href. Once the category is accepted they are activated in their original order. Remote hosts are added to the Content Security Policy, and inline scripts get a CSP nonce on pages with a strict policy (checkout). A snippet with an unclosed <script> tag is refused when you save it.

Inside a snippet, data-sw-consent="necessary" on a single tag keeps that tag running without consent, and data-sw-consent="marketing" (or any other category code) uses that category for that tag instead of the snippet's.

The grid has keyword search on the name, filters, an Active / Inactive badge and mass delete.

6. Scripts in Design Configuration

Chat widgets and pixels are often pasted into Content > Design > Configuration, under HTML Head > Scripts and Style Sheets or Footer > Miscellaneous HTML. By default they run as before. Set General > Scripts in Design Configuration to a category (for example Wait for consent: Preferences) and these scripts, iframes and third-party images and stylesheets wait for that category too. Images and stylesheets from your own domain keep loading.

The settings page and the Third-party Scripts grid list every such script that still loads without consent, per store view, so you can see what is left to sort out.

7. What your visitors see

First visit. The banner with "Accept all", "Reject all" (if shown) and "Manage preferences", plus the policy link.

Preferences window. One switch per category, with the necessary category marked "Always on". "Save choices" keeps the switches as they are. The window is a modal dialog: focus moves into it, Tab stays inside, Escape closes it and focus returns to the button that opened it.

The stored choice. The first-party cookie sw_consent holds the version, a random ID, the time and the accepted categories. Visitors are asked again when the consent version changes or the choice expires.

Changing their mind. The footer link, the floating button, the CMS widget Softaware Cookie Settings Link, or any link to #cookie-settings (or element with data-sw-cc-open) opens the preferences again. Withdrawing a category deletes its listed cookies and reloads the page, so scripts that already ran stop.

Hyvä and mobile. Hyvä templates are included; on phones the buttons stack and the window scrolls inside the screen.

Hyvä	Mobile

8. Consent log

With Record Consent Choices on, every choice is stored and shown under Softaware > Cookie Consent > Consent Log: date, consent ID, choice (Accepted all, Rejected all, Custom choice), accepted categories, consent version, store view and IP hash. The consent ID is the random ID stored in the visitor's sw_consent cookie.

The IP address is stored only as a keyed hash (HMAC-SHA256 with your installation's key), optionally truncated first. No names, email addresses or raw IP addresses are stored. The grid has filters (including store view), CSV and XML export and mass delete. The public logging endpoint stores at most 60 entries per (truncated) IP address and hour.

9. Google Tag Manager and developers

dataLayer. On every page with a stored choice and on every new choice, this event is pushed:

{event: 'softaware_consent_update', sw_consent_trigger: 'stored' | 'user',
 sw_consent: {necessary: 'granted', analytics: 'denied', ...},
 sw_consent_categories: 'necessary,analytics', sw_consent_version: 1}

JavaScript (window.SwConsent, available from the head):

SwConsent.has('analytics');
SwConsent.whenGranted('marketing', function () { /* load pixel */ });
SwConsent.onChange(function (detail) { /* detail.categories, detail.trigger */ });
SwConsent.open(); SwConsent.acceptAll(); SwConsent.rejectAll(); SwConsent.save(['necessary', 'analytics']);

Markup that waits for consent:

<script type="text/plain" data-sw-consent="analytics">/* runs after consent */</script>
<iframe data-sw-consent="marketing" data-sw-src="https://www.youtube-nocookie.com/embed/..."></iframe>

PHP: inject Softaware\CookieConsent\Model\ScriptBlocker (or use the view model Softaware\CookieConsent\ViewModel\ScriptBlocker in templates) and call block($html, 'marketing') or attributes('analytics'). When the module is disabled both return the markup unchanged.

10. Command line

bin/magento softaware:cookie-consent:bump-version
bin/magento softaware:cookie-consent:log:clean [--days=N]

bump-version increases the consent version in every scope where it is set and cleans the config and full-page caches, so every visitor is asked again. log:clean deletes log entries older than the retention period (or --days); the cron job does the same every night at 03:17.

11. Permissions (ACL)

Under Softaware > Cookie Consent in System > Permissions > User Roles:

12. Troubleshooting

13. Uninstall

bin/magento module:disable Softaware_CookieConsent
composer remove softaware/module-cookie-consent
bin/magento setup:upgrade
bin/magento cache:flush

The visitors' sw_consent cookies expire on their own. Scripts you moved to Third-party Scripts are no longer output, so move them back to your theme or tag manager first if you still need them. The module's database tables (scripts and consent log) are kept.