=== WorkMore Cookie Crumb ===
Contributors: connextsystem
Tags: cookie consent, cookie banner, gdpr, pdpa, consent log
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A cookie banner that holds tracking scripts back until visitors answer, with a cookie scan and a consent log, all on your own site.

== Description ==

WorkMore Cookie Crumb asks your visitors which cookies they allow, and holds everything else back until they answer. It lives inside your WordPress site: no account to open, no outside service, no page view quota.

**It really holds scripts back.** Scripts, embedded videos and maps, and tracking pixels of the services you list do not run and do not load before a visitor allows their category — those written in the page, and those other scripts add later. A held-back video or map shows a placeholder with a button that allows it. When a visitor withdraws consent, the listed cookies your site set are deleted from their browser.

**It leaves your site fast.** Every visitor gets the same page; what runs is decided in the browser, so page caches and CDNs work without any configuration. The visitor side is one small inline script and one deferred file of about 7 KB, with no library, no font and no request to another server. The banner does not push your content around as it appears.

**It keeps a record.** Each answer is one row in a consent log on your own site, found by the consent ID the visitor sees in the cookie settings window, and exported as CSV. A record holds as little as it takes: no full IP address, no cookie values, nothing tied to a user account. The log keeps the last 90 days.

= What you get =

* A banner and a cookie settings window, in any number of languages, with words ready in English and Thai. Two ways of asking: consent first, or notice only.
* A setup wizard: scan the site, sort what was found, look at the banner on your own pages, publish.
* A cookie scan that opens your pages in your own browser the way a visitor gets them, and lists the cookies they set and what they load from other sites, with a category suggested where the service is known. Once the banner is published, it also shows whatever still loads before a visitor answers.
* Known services to start from: Google Analytics, Google Tag Manager, Google Ads, YouTube, Google Maps, Meta Pixel and Facebook embeds, and the cookies of WordPress and WooCommerce themselves. Anything else is added by hand: a cookie by its name, a script by a piece of its address.
* Google Consent Mode v2 signals, and the WP Consent API for plugins that ask it.
* Draft and publish: you edit a draft with a live preview on your real site at desktop, tablet and phone widths. Visitors see nothing new until you publish, and each record names the version of the banner the visitor answered.
* A dashboard: how many accepted, rejected or chose, which categories were allowed, how that changed over time — and page views by month.
* A button on every page, a link to `#cookie-settings` or the `[wmcc_settings]` shortcode, so visitors can change their answer whenever they like.
* Light or dark, your own main color with text that stays readable on it, top or bottom of the page, and the banner only on the pages you choose.
* For theme developers: the banner keeps to itself (your theme's styles do not reach it by accident), and can be restyled on purpose through a documented set of CSS custom properties and named parts.
* Made to be used by everyone: keyboard use, the names and roles a screen reader announces, contrast, small screens and reduced motion are part of the plugin's test suite.

= A tool, not legal advice =

The plugin is a tool. It does not by itself make a site comply with any law, and nothing in it is legal advice: which cookies need consent, how to ask and how long to keep a record depend on the law that applies to your site.

= Pro add-on =

Everything above is free and complete. A separate plugin, WorkMore Cookie Crumb Pro, sold on [workmore.connextsystem.com](https://workmore.connextsystem.com/cookie-crumb), sends consent records on to a database of your own and adds a design screen for the banner — more positions, a logo, colors and sizes of single parts, button styles, rounded corners — a health check of your settings and a registry of services common in Thailand. Inside this plugin the add-on is only mentioned on the "Upgrade to Pro" tab; nothing here is locked or limited.

= Source code =

The plugin's JavaScript ships minified for performance (`assets/admin.js`, `assets/guard.js`, `assets/banner.js`, `assets/probe.js`); the human-readable source is included in the plugin's `src/` directory together with the build configuration (`vite.config.js`).

== Installation ==

1. Install the plugin under Plugins → Add New, or upload the zip under Plugins → Add New → Upload Plugin.
2. Activate it.
3. Open Settings → Cookie Crumb. The setup leads from a scan of your site to a published banner in four steps; it can be skipped, and everything in it can be changed afterwards.

Nothing changes for your visitors until you press "Publish banner".

== Frequently Asked Questions ==

= Does it work with a page cache or a CDN? =

Yes. The server sends the same page to every visitor and never reads the visitor's answer; what runs is decided in the browser. Publishing the banner asks the cache plugins and hosts the plugin knows to clear their page cache (WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, WP Fastest Cache, Cache Enabler, WP-Optimize, Autoptimize, Breeze, Hummingbird, Comet Cache, SiteGround Optimizer, Nginx Helper, WP Engine, Pantheon); for any other cache, clear it after publishing. Plugins that combine, defer or delay scripts are asked — by marks on its tag that Autoptimize, LiteSpeed Cache, WP Rocket and Cloudflare's Rocket Loader read — to leave the plugin's first script where it is: it has to run before every other script of the page.

= Does it work with Google Tag Manager and Google Consent Mode? =

Yes. Before a visitor answers, the plugin sets the Consent Mode v2 signals to "denied" — the advertising signals follow your marketing category, the analytics signal your analytics category — and updates them with each answer; an event named `wmcc_consent` is pushed to the data layer as well. You choose how Tag Manager itself is treated: listed under a category, the container waits for that category like any other script; left out of the list, it loads and its tags follow the Consent Mode signals.

= Which services does it recognise? =

Google Analytics, Google Tag Manager, Google Ads, YouTube, Google Maps, Meta Pixel and Facebook embeds, and the cookies WordPress and WooCommerce set themselves. A recognised service gets its category suggested, and its cookies listed with what they are for. Anything else the scan finds is shown as not known: you choose its category. A script is held back by a rule that looks for a piece of its address, so any script can be listed.

= How does the cookie scan work? =

When you press "Scan the site", the screen opens a sample of your pages — the front page, the newest entry of each kind of content, a shop's own pages, and addresses you add — in your own browser, served the way a visitor who is not logged in gets them. The server notes the cookies it sets and what stands in each page's markup; a small script in the page notes the cookies scripts set and everything the page loads. Nothing is sent to an outside service, and nothing is added to your cookie list until you choose it. A scan cannot see what loads only after a click or a purchase, what an ad blocker in your browser stops, or the cookies another site keeps on its own domain; those are listed where the service is known. While it runs, your pages' own trackers run once in your browser, as they would for a visitor who allowed everything — in a browser that is logged in to your site, and including trackers your site leaves out for administrators.

= Can everything be held back? =

Scripts and embedded frames always can, and images and loading hints when they stand in the page's markup. What a script that is already running sends by itself or writes into the page as markup, and style sheets and fonts loaded from another site, cannot be held back by a rule: hold back the script that does it, or serve the file from your own site. After you publish, the scan lists whatever still reaches another site before a visitor answers, and says for each whether a rule can hold it.

= How can visitors change their answer? =

By default a small round button stays in a corner of every page and opens the cookie settings window. Instead of it, or as well, any link to `#cookie-settings` opens the window — in a menu, a footer or a page — and so does the `[wmcc_settings]` shortcode. Withdrawing consent deletes the listed cookies your site set and loads the page again without the scripts. Cookies another site keeps on its own domain, and cookies no script can read, cannot be deleted from a page.

= What does a consent record hold about a visitor? =

As little as it takes to be a record: a random consent ID (kept in the visitor's own consent cookie, and shown to them in the cookie settings window), the time, the answer and the categories it allowed, the version and language of the banner, the address of the page without its query string, the browser's name and major version with the name of the operating system, and the network part of the IP address — the last part of the address is never stored. A record is not linked to a user account, and is deleted after 90 days. Settings → Privacy → Policy guide has a paragraph you can use in your privacy policy.

= How are page views counted? =

A page reports that it was shown, with one small request to your own site that carries no cookie and nothing about the visitor; the site adds one to that day's number. A busy site (more than 2,500 page views a day) counts a sample instead — one page view in so many, each counted for that many — so the counting stays light however much traffic there is. A developer can switch page view counting off with the `wmcc_count_pageviews` filter.

= Can I restyle the banner with my theme's CSS? =

Yes, on purpose only. The banner lives in a shadow root under `<div id="wmcc-root">`, so your theme's styles do not change it by accident. What your style sheet can set are these custom properties on `#wmcc-root` — `--wmcc-bg`, `--wmcc-text`, `--wmcc-muted`, `--wmcc-line`, `--wmcc-font-size`, `--wmcc-radius`, `--wmcc-button-radius` — and rules for its named parts, written `#wmcc-root::part(name)`: `banner`, `text`, `title`, `body`, `policy`, `actions`, `button` (with `accept`, `reject`, `settings`, `save`, and `in-banner` or `in-window`), `close`, `overlay`, `window`, `window-head`, `window-title`, `window-body`, `window-foot`, `intro`, `category`, `category-name`, `switch`, `consent-id`, `reopen`, `reopen-icon`. For example: `#wmcc-root::part(accept) { background: #0a7d3c; color: #fff; }`. Keeping the text readable on your colors is then yours to check, and a font or picture such a rule loads from another site reaches that site before the visitor answers.

= In which languages is the banner? =

In any you add: each language has its own words, and the banner follows the language of the page. Words are ready in English and Thai; for another language you start from the English ones and write your own. The plugin's own screen is in English, with translations served by WordPress.org as they are completed.

= Does it work on a multisite network? =

Yes. Each site of a network has its own banner, cookie list and consent log, managed by that site's administrators.

= Does the plugin connect to an outside service or collect data? =

No. The banner, its script and the cookie list are served by your own site, answers and page views are recorded in your own database, and the plugin makes no request to any other server and adds no credit or link to your pages. On its screen, the only link to our website is on the "Upgrade to Pro" tab, and it opens only when you click it.

= What happens when I deactivate or uninstall the plugin? =

Deactivating takes the banner off and stops holding scripts back at once: nothing in your content was changed, so there is nothing to undo. It deletes nothing. Uninstalling removes the consent log, the statistics and the settings only if you asked for it under Settings → Cookie Crumb → Settings, where the switch is off by default — a consent log is a record you may be asked for.

== Screenshots ==

1. The banner on a site: accept, reject or choose — and a video that waits shows a placeholder with a button of its own.
2. The cookie settings window: a switch for each category, the cookies in it, and the visitor's consent ID.
3. The first-time setup: scan the site, sort what was found, look at the banner, publish.
4. Cookie scan: the cookies your pages set and what they load from other sites, each with a category suggested where the service is known.
5. Cookies: categories, the cookies visitors read about, and the rules that hold scripts back.
6. Banner design: words, languages, colors and position beside a live preview on your own site.
7. Consent log: how visitors answered, by kind, by category and over time, and page views by month.
8. Consent log: one record for each answer, found by the visitor's consent ID and exported as CSV.

== Changelog ==

= 1.0.0 =
* First release: consent banner and cookie settings window in any number of languages; scripts, frames and pixels held back until the visitor allows their category; Google Consent Mode v2 and WP Consent API; cookie scan and setup wizard; consent log with search by consent ID and CSV export; dashboard with page views by month.

== Upgrade Notice ==

= 1.0.0 =
First release.
