=== VisualClicks Analytics ===
Contributors: visualclicks
Tags: analytics, woocommerce, heatmap, session recording, cookieless
Requires at least: 6.6
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

Cookieless web analytics, heatmaps and session replays – with WooCommerce complete e-commerce tracking. Set up with just an API token.

== Description ==

VisualClicks Analytics connects your WordPress site to [VisualClicks](https://visualclicks.de), a cookieless web analytics service with heatmaps, session replays and e-commerce analytics.

**On every WordPress site**

* The VisualClicks tracking tag in the page head: page views, clicks, scroll depth, heatmaps and – if enabled in VisualClicks – session replays (input fields are always masked).
* Cookieless by default. With consent, returning visitors are recognised. Consent is taken from the WP Consent API (category "statistics"), Google Consent Mode v2, IAB TCF v2 or `window.vcConsent(true|false)` for any other consent tool.
* The tag is the same for every visitor (works with full page caches) and is excluded from the JavaScript delay/combine features of common optimisation plugins.

**With WooCommerce (9.0 or newer)**

* Product viewed: SKU, name, brand, category path, variant and gross price on every product page.
* Cart from the server: add, quantity changes with the exact difference (1 → 3 = +2), removal, emptying – classic cart, mini cart, AJAX add to cart and the cart/checkout blocks. A login that merges the saved cart is not counted as a change.
* Purchase when the order is placed (classic checkout and checkout block): order number, gross/net value, tax, shipping, coupons, discount, payment and shipping method, items.
* Refunds with their amount (partial refunds included), cancellations with the remaining value – never more than the order value in total.
* Orders created later by a payment provider (webhook) are linked to the shopper's visit as well.
* Cart and order events are sent by the shop itself, after the page was delivered: they are not lost to ad blockers, and the shop keeps working normally when VisualClicks cannot be reached.
* Compatible with High-Performance Order Storage (HPOS) and the cart/checkout blocks.

**Setup:** create an API key with the right "Send events" in VisualClicks (Settings → Website → API keys, any plan), enter it under Settings → VisualClicks, done. The site id is fetched automatically. Check with `wp visualclicks check`.

== External services ==

This plugin connects to the VisualClicks service (https://visualclicks.de, or the address of a self-hosted VisualClicks set under Settings → VisualClicks → Advanced). It does nothing until an API token is entered.

* **Tracking script (visitors' browsers):** on every front-end page the browser loads `/t/fwa.js` from VisualClicks and sends page views (URL, referrer), clicks, scroll depth, technical data of the browser (screen size, language) and – if session replays are enabled in VisualClicks – a masked recording of the page to VisualClicks. Without consent no cookies are used and VisualClicks does not store the IP address. With consent the browser additionally stores a visitor id (local storage) and the visit id (cookie `vc_vid`).
* **Site lookup (your server):** with the API token the plugin requests `/api/s/v1/site` to get the public site id, consent mode and modules of your VisualClicks website – at most once per hour, and on the settings page.
* **Server events (your server, only with WooCommerce, can be switched off):** when the cart changes, an order is placed or refunded, the plugin sends to `/api/s/v1/events`: product data (SKU, name, brand, category, variant, price, quantity), order data (order number, totals, tax, shipping, coupon codes, discount, payment and shipping method names) and refund amounts. To assign the events to the shopper's visit it also sends the shopper's IP address, user agent, the URL of the page and – with consent – the visit id. Names, addresses, e-mail addresses and phone numbers are never sent.

VisualClicks privacy policy: https://visualclicks.de/datenschutz – legal notice: https://visualclicks.de/impressum

== Installation ==

1. Install the plugin (Plugins → Add New → Upload Plugin, or `wp plugin install visualclicks-analytics.zip --activate`) and activate it.
2. In VisualClicks: Settings → Website → API keys → create a key with the right "Send events".
3. In WordPress: Settings → VisualClicks → enter the key as API token and save. The status box shows the connected VisualClicks website.
4. Multisite: every site has its own settings (and its own VisualClicks website).

== Frequently Asked Questions ==

= Do I need a cookie banner? =

Without consent VisualClicks measures cookieless. If you use a consent tool, VisualClicks follows it (WP Consent API, Google Consent Mode v2, IAB TCF v2, or call `window.vcConsent(true)` / `window.vcConsent(false)`).

= What happens when VisualClicks is not reachable? =

The shop works normally. Events that could not be sent are retried once after five minutes (Action Scheduler), warnings are written to the WooCommerce log (source "visualclicks").

= Can I exclude administrators? =

Yes: Settings → VisualClicks → "Do not track logged-in administrators and shop managers".

= Filters for developers =

`visualclicks_tag_data`, `visualclicks_render_tag`, `visualclicks_item`, `visualclicks_purchase`, `visualclicks_brand_taxonomies`, `visualclicks_report_order`, `visualclicks_failed_order_delay`, `visualclicks_client_ip`.

== Changelog ==

= 1.0.0 =
* First release: tracking tag with consent bridges, product views, cart, purchases, refunds and cancellations from the server, WP-CLI check, German translation.
