=== TidyConsent ===
Contributors: heemo521
Tags: consent, cookie banner, cookies, gdpr, consent mode
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Plain-English cookie consent with categories, Google Consent Mode v2, a cookie policy generator, and a consent log stored on your own site.

== Description ==

TidyConsent helps a WordPress site owner ask visitors for permission before optional analytics and marketing tools run. It uses plain English instead of legal or technical jargon, so a non-lawyer can understand what each setting does.

The free plugin is complete on its own. It does not contain locked features, trial timers, or an account requirement.

**What the free plugin does**

* Shows a banner with **Accept all**, **Reject all**, and **Preferences**. Accept and Reject are equally prominent.
* Lets visitors choose the functional, analytics, and marketing categories. Necessary cookies are always allowed because the site and the consent choice itself need them.
* Sets Google Consent Mode v2 defaults to denied for `ad_storage`, `ad_user_data`, `ad_personalization`, and `analytics_storage`, then updates those signals when a visitor makes a choice.
* Holds back eleven common tools until the visitor allows the matching category: Google Analytics, Google Tag Manager, Google Ads, Meta Pixel, Microsoft Clarity, Hotjar, LinkedIn Insight Tag, TikTok Pixel, Pinterest Tag, X (Twitter) Pixel, and Microsoft Advertising. This covers both external script tags and the standard install snippets those tools ask you to paste into a page.
* Works behind page caches and CDNs: every visitor is sent the same page with those tools switched off, and they are switched on in the visitor's own browser only after that visitor allows them.
* Offers visitors only the categories your site actually uses, and names the tools detected in each one.
* Looks like part of your site, with no CSS to write: choose a bar, a corner card, or a centred box; light, dark, automatic (follows each visitor's light or dark mode), your theme's own colours, or your own; your brand colour for the buttons; square, rounded, or pill corners. A live preview shows the result before you save.
* Lets you shape how the pop-up behaves, not just how it looks: slide, fade, or no animation; an optional pause before it appears; category switches open from the start; an optional close (×) that counts as a refusal; an optional "page waits for a choice" mode for the centred layout; how long a choice lasts; and where the small reopen button sits and what it looks like.
* Lets you write it your way: every piece of text is editable, including each category's name and description, with four ready-made tones to start from. Add your logo. Link to your own privacy page.
* One-click looks to start from, and a place for your own CSS (with the class names and variables listed) when you want full control.
* Keeps itself readable: whatever colours you pick, text and button labels are adjusted to stay legible, and Accept and Reject always look identical.
* Remembers a visitor's choice in that visitor's browser and provides a way to reopen the preferences. When a visitor withdraws a category, the known cookies of that category are removed and the page reloads without those tools.
* Records consent choices in the site's own WordPress database. The log stores the time, a consent ID, the category choices, and a salted hash of the IP address rather than the raw IP address.
* Provides a read-only consent log viewer and CSV export for the site administrator.
* Detects known trackers that appear in the page and uses those detections to generate a plain-English cookie policy page.
* Includes an optional Agent Scan panel. If the site owner enters the address of a TidyConsent scan service, an administrator can ask that service to scan the site's public home page, review its plain-English report and proposed settings, and decide whether to apply them. Running a scan changes nothing; applying a proposal always requires a separate click.

**Important limits**

TidyConsent helps you implement consent choices. It is not a law firm, does not provide legal advice, and does not certify that a site complies with GDPR, CCPA, or any other law. The site owner is responsible for checking that the final setup and policy match the site and its legal obligations.

The script blocker recognises the tools listed above. It does not block tools it does not know, and it can miss a known tool that is loaded in an unusual way — for example assembled by another script while the page runs, or merged into a combined file by a performance plugin. Exclude tracker scripts from such combining. The banner is shown to every visitor; this version does not vary by the visitor's country.

The salted IP hash in the consent log is pseudonymous, not anonymous: treat the log as personal data. The log is kept when the plugin is uninstalled unless you tick "Delete the consent log when this plugin is uninstalled" in the settings.

== External service ==

TidyConsent can connect to an external TidyConsent service, but only when the site owner chooses to configure and use it.

**No Service URL means no external calls.** If the **Scan service URL** setting is blank, this plugin makes no external service calls. The banner, category choices, Consent Mode signals, script blocking, policy generator, and local consent log all work without the service.

When a site administrator enters a Service URL and clicks **Run scan**, the plugin sends the site's public home page URL to that service's `/scan` endpoint. The service fetches the public page, looks for known tracker code, and returns tracker names, evidence, categories, a proposed configuration, and a plain-English report. The plugin sends the home page URL for this purpose; it does not send visitor consent records as part of a scan.

A separate TidyConsent Pro add-on is sold outside the WordPress.org directory. Pro is not included in this plugin and is not required for the free features above. If an owner installs Pro and chooses to use it:

* Pro sends the license key and the site URL to the service to activate and periodically validate the license.
* Pro can repeat the scan on a weekly schedule and email the site administrator when it finds a new known tracker.
* If Pro log backup is enabled, Pro sends consent-log entries from the site to the service so they can be stored as a backup. These entries can include the consent time, consent ID, category choices, and the salted IP hash stored by the free plugin.
* The service's terms and privacy policy govern data sent to that service.

PLACEHOLDER LINKS — replace these with the final service URLs before launch or submission:

* TidyConsent service terms: https://tidyconsent.com/terms.html
* TidyConsent service privacy policy: https://tidyconsent.com/privacy.html

== Installation ==

1. Upload the `tidy-consent` folder to `/wp-content/plugins/`, or install the plugin ZIP through **Plugins → Add New → Upload Plugin**.
2. Activate **TidyConsent** in WordPress.
3. Open **Settings → TidyConsent** to review the banner wording and settings.
4. Visit the site in a private browser window to confirm the banner appears and test Accept, Reject, and Preferences.
5. Use the settings page to create a draft Cookie Policy page, review it carefully, and publish it only when it accurately describes your site.

== Frequently Asked Questions ==

= Does TidyConsent work without Pro? =

Yes. The banner, category preferences, Google Consent Mode v2 signals, known-script blocking, policy generator, consent log, log viewer, CSV export, and manual Agent Scan panel are free-plugin features. The separate Pro add-on adds scheduled weekly re-scans, change emails, and hosted log backup. Pro is optional and is not needed to use the free plugin.

= Does TidyConsent make external calls by default? =

No. With no Scan service URL configured, the plugin makes no external service calls. It only contacts a service after the site owner enters a Service URL and an administrator runs a scan or uses the separate Pro features described in the External service section.

= Does TidyConsent slow down my site? =

It is designed to stay small: it loads one stylesheet and one JavaScript file on the front end, stores its settings and log in WordPress, and makes no external request during normal page views. The blocker processes the finished page HTML to find the known tracker scripts, so extremely large or unusual pages should still be tested after activation.

= Does it block every tracker? =

No. This version blocks the eleven tools listed in the description — as external scripts and as their standard pasted snippets — until the matching category is allowed. Tools it does not know, and known tools loaded in unusual ways, may not be blocked. Google Consent Mode signals are still set to denied by default for Google tools that honor them.

= Does it work with a caching plugin or CDN? =

Yes. The page sent to every visitor is the same, with known trackers switched off; nothing about a visitor's choice is baked into the cached page. The choice is applied in the visitor's browser. If a performance plugin combines or rewrites JavaScript, exclude tracker scripts from that feature so TidyConsent can still see them.

= Is this legal advice or a compliance guarantee? =

No. TidyConsent helps site owners implement consent choices. It is not a law firm, does not provide legal advice, and does not certify compliance with GDPR, CCPA, or any other law. Review your site, policy, and settings with a qualified adviser when needed.

= Where are consent choices stored? =

A visitor's current choice is stored in that visitor's browser. The site also stores a consent record in its own WordPress database so the owner has evidence of the choice. The database record uses a salted IP hash instead of the raw IP address.

= Can I export the consent log? =

Yes. An administrator can open **Settings → Consent Log**, filter by date, and download a CSV export.

== Screenshots ==

1. The front-end consent banner with equally prominent Accept and Reject buttons and a Preferences option.
2. The TidyConsent settings page in wp-admin.
3. A generated cookie policy page listing detected tools by category.
4. The read-only consent log viewer with a CSV export control.

== Changelog ==

= 0.4.0 =

* Blocking is now safe behind page caches and CDNs: every visitor receives the same page with known trackers off, and allowed tools are switched on in the browser.
* Blocks the standard pasted install snippets for Google Tag Manager, Meta Pixel, and Google Ads, plus their no-JavaScript fallbacks.
* Adds Google Ads, Microsoft Clarity, Hotjar, LinkedIn Insight Tag, TikTok Pixel, Pinterest Tag, X (Twitter) Pixel, and Microsoft Advertising, each with plain-English cookie descriptions for the generated policy.
* The settings screen now lists the tools found on your site and what visitors must allow for each.
* The banner links to your cookie policy page once it is published.
* Removed the Geo mode setting, which did nothing.
* New Appearance settings with a live preview: position, colours (including automatic light/dark and match-my-theme), brand button colour, corners, and font. Category choices are now switches. The banner has a refreshed, more modern look.
* New Behaviour settings: entrance animation, delay, categories open from the start, optional close button (counts as Reject all), page-waits-for-a-choice for the centred layout, consent duration, and reopen button corner and style.
* New Wording settings: editable category names and descriptions, policy link text and address, logo, and four ready-made tones.
* One-click look presets. A custom CSS box with the styleable class names and variables listed.
* Settings are organised into four tabs beside a live preview that follows text, colours, and CSS as you type.
* For developers: `TidyConsent.hasConsent('analytics')` and a `tidyconsent:change` event.
* The default look is now a card in the bottom-left corner in a clean system font.
* Tracker matching is by web address host, so a site's own files are no longer mistaken for trackers.
* The banner offers only the categories the site uses and names the detected tools. Applying an Agent Scan proposal now changes what the banner asks.
* Withdrawing a category removes that category's known cookies and reloads the page.
* A choice now expires about six months after it was made, wherever it is stored; the visitor is then asked again.
* Accept and Reject are styled identically. The consent cookie is marked Secure on HTTPS sites.
* Consent logging keeps working on cached pages; the public log endpoint validates input and limits requests per address.
* New setting to delete the consent log on uninstall. Uninstall cleans every site of a multisite network.

= 0.3.0 =

* Added the optional Agent Scan panel: an administrator can connect a scan service, review a plain-English report and proposed configuration, and apply the proposal only with a separate click.
* Added tracker evidence and category review before any scan proposal is applied.

= 0.2.0 =

* Added local tracker detection recording.
* Added the plain-English cookie policy generator and the settings action that creates or updates a draft policy page.
* Added the read-only consent log viewer with date filtering and CSV export.

= 0.1.0 =

* Initial internal development release.
* Added the consent banner with Accept, Reject, and category Preferences.
* Added Google Consent Mode v2 defaults and updates.
* Added blocking for known external analytics and marketing scripts before consent.
* Added local consent storage and the WordPress database consent log.

== Upgrade Notice ==

= 0.4.0 =
Blocking now works behind page caches and covers the standard Google Tag Manager, Meta Pixel, and Google Ads snippets. Clear your page cache after updating.

= 0.3.0 =
Adds the optional Agent Scan review-and-apply flow. No scan runs and no settings change unless an administrator connects a service, runs a scan, and separately applies a proposal.
