=== OneLence Consent ===
Contributors: onelence
Tags: consent, cookies, analytics, wordpress
Requires at least: 6.0
Tested up to: 6.6
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

OneLence Consent is a focused WordPress consent plugin that helps sites show a cookie banner, store visitor consent choices, and load supported services only after the relevant consent has been granted.

It is especially designed to help WordPress sites load OneLence Mark only after analytics consent is granted, while also supporting a small set of additional consent-aware services.

This plugin is intentionally narrow. It is not a full compliance suite, not a generic tag manager, and not a legal guarantee.

== Description ==

OneLence Consent helps WordPress site owners manage a consent banner without turning consent management into a complex technical setup.

With this plugin you can:

- show a cookie banner or consent pop-up
- choose between a simple global banner and a region-specific banner setup
- customize the banner layout, wording, and theme
- generate a practical cookie policy draft page
- manage a curated set of services inside the plugin dashboard
- load OneLence Mark only after analytics consent

The plugin keeps its scope intentionally narrow:

- it helps with consent-driven loading for supported services
- it stores visitor choices in the browser
- it can optionally show aggregate consent activity in the admin dashboard

It does not claim to replace legal review, a lawyer, or a full enterprise CMP.

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` or install it through the WordPress admin.
2. Activate **OneLence Consent**.
3. Open **Settings > OneLence Consent**.
4. Turn on the plugin in **OneLence Setup > Plugin Setup**.
5. Configure your cookie banner under **Cookie Banner**.
6. If you use OneLence Mark, enter your OneLence site key and site ID under **OneLence Setup > OneLence Mark**.
7. If you want a cookie policy draft page, fill in the fields under **Cookie Page** and create the draft.

You do **not** need a OneLence account or Mark credentials just to use the cookie banner itself.

== OneLence Mark ==

OneLence Consent is designed to help WordPress sites load OneLence Mark only after analytics consent is granted.

If you use OneLence Mark through this plugin:

- keep OneLence Consent as the only WordPress loader for Mark on the site
- disable any separate plugin or manual snippet that also loads Mark
- enter your OneLence site key and site ID in the OneLence Mark section

If Mark is also loaded somewhere else, tracking may start before consent is granted.

== Supported Services ==

This plugin supports a curated service model rather than open-ended script management.

Current managed or partially managed services include:

- OneLence Mark
- Google Analytics
- Meta Pixel
- TikTok Pixel
- Microsoft Clarity
- Hotjar

Some services may still require their own provider ID or other setup details in the Services tab.

Google Ads is currently not a full no-code managed integration in this plugin.

== Region Detection ==

For region-specific behavior, the plugin can use country information provided by trusted server or CDN headers when those headers are available.

If your project needs a custom region detector, switch the detection source to **Developer-provided detector hook** and provide a result through the `onelence_consent_detect_mode` filter.

Example:

`add_filter( 'onelence_consent_detect_mode', function () { return array( 'matched' => true, 'reliable' => true ); } );`

Supported return values:

- `strict`
- `standard`
- `true` to indicate a matched stricter region and use the configured regional mode
- an array such as `array( 'mode' => 'standard', 'reliable' => true )`

If detection is unavailable or untrusted, the plugin falls back to Strict mode.

== Frontend Consent Events ==

For custom integrations and manually managed SDKs, the frontend dispatches consent events that developers can listen to.

Available events:

- `onelence-consent-granted`
- `onelence-consent-denied`
- `onelence-consent-changed`

The category-specific events are emitted for optional categories on initial page load and whenever consent changes.

Event detail includes:

- `category` such as `analytics` or `marketing`
- `granted` as `true` or `false`
- `source` as `initial` or `update`
- `decisionMade`
- `state` with the full normalized consent state

Example:

`document.addEventListener( 'onelence-consent-granted', function ( event ) { if ( event.detail.category === 'marketing' ) { /* enable marketing SDK */ } } );`

For backward compatibility, the legacy `onelenceConsentChanged` event is still emitted for now, but new integrations should use `onelence-consent-changed`.

== FAQ ==

= Do I need a OneLence account to use the cookie banner? =

No. You can use the banner, consent storage, and cookie page draft features without connecting OneLence Mark.

= Do I need the OneLence site key and site ID to use this plugin? =

No. Those fields are only required if you want OneLence Consent to load OneLence Mark on your site.

= Does this plugin guarantee GDPR or cookie-law compliance? =

No. The plugin helps with consent-aware loading and visitor choice management, but it does not provide legal advice or guarantee compliance for every jurisdiction or site setup.

= Can this plugin block every script already pasted into my theme header? =

No. This plugin focuses on services that are configured through its own dashboard and supported loading paths. Manually added theme or header snippets are outside its direct control unless you wire them to the consent events yourself.

= Can I generate a cookie policy page? =

Yes. The plugin can create a practical WordPress draft page that you can review and edit before publishing.

= Can I add custom services? =

Yes. You can add custom services with structured metadata and an external script URL. Advanced custom initialization code is intended for gated or paid-style integrations and should be treated as an advanced feature.

== Limitations ==

This plugin is intentionally narrow. Current limitations include:

- it is not a full compliance suite or enterprise CMP
- it does not provide legal advice or legal guarantees
- it does not automatically classify or block every third-party snippet already added in a theme or plugin
- it does not aim to be a general-purpose tag manager
- some services still require provider-specific IDs or additional setup
- Google Ads is not yet a full no-code managed service in the current version
- visitor consent cookies already stored in browsers cannot be retroactively removed from every device during uninstall

== Screenshots ==

1. Overview dashboard placeholder
2. OneLence Setup placeholder
3. Cookie Banner customization placeholder
4. Cookie Page draft generator placeholder
5. Services management placeholder

== Cleanup Notes ==

Uninstalling the plugin removes the plugin settings stored in WordPress.

Consent choices are stored in visitor browsers as cookies. Those browser-side cookies cannot be retroactively deleted from every visitor device during uninstall. They expire naturally, can be overwritten by the plugin while active, or can be cleared by the visitor.

If analytics consent is withdrawn after OneLence Mark or another supported analytics service has already initialized on a page, the change may fully apply on the next page load depending on that service's runtime consent support.

