# VisualClicks Analytics für WordPress und WooCommerce

Cookielose Web-Analyse, Heatmaps, Session-Replays und – mit WooCommerce – vollständiges E-Commerce-Tracking, eingerichtet mit nur einem API-Token. WordPress 6.6–7.1, WooCommerce 9.0–11.2 (optional), PHP 7.4–8.4.

## Was das Plugin erfasst

| Bereich | Wie | Daten |
|---|---|---|
| Seitenaufrufe, Klicks, Scrolltiefe, Heatmaps, Replays | Tracking-Tag im Browser (wird automatisch im `<head>` eingebunden) | wie auf jeder Website mit VisualClicks |
| Produkt angesehen | Browser, auf jeder Produktseite | Artikelnummer (SKU), Name, Marke, Kategoriepfad, Variante, Bruttopreis |
| Warenkorb | Server (WooCommerce) | hinzufügen, Menge ändern (1 → 3 = +2), entfernen, leeren – klassischer Warenkorb, Mini-Warenkorb, AJAX und Warenkorb-/Kassen-Blöcke |
| Kauf | Server, beim Abschluss der Bestellung (klassische Kasse und Kassen-Block) | Bestellnummer, Wert brutto/netto, Steuer, Versand, Gutscheine, Rabatt, Zahlungs- und Versandart, Artikel |
| Erstattung / Stornierung | Server, bei jeder Erstattung (auch Teilerstattungen) und bei „Storniert“ | Erstattungsbetrag bzw. der noch nicht erstattete Rest – insgesamt nie mehr als der Bestellwert |

Ohne WooCommerce ist das Plugin ein reines Analyse-Plugin für jede WordPress-Website (nur das Tracking-Tag).

Warenkorb und Bestellungen werden direkt vom Shop gemeldet – sie gehen also auch bei Werbeblockern nicht verloren und landen in derselben Sitzung wie der Browserbesuch:
- **ohne Einwilligung (cookielos):** über IP-Adresse und Browserkennung des Kunden (die IP wird von VisualClicks nicht gespeichert),
- **mit Einwilligung:** zusätzlich über die Sitzungs-ID (Cookie `vc_vid`).

Eine Bestellung, die sowohl im Browser als auch vom Server gemeldet wird, zählt nur einmal (Abgleich über die Bestellnummer).

## Installation

1. In WordPress: **Plugins → Installieren → Plugin hochladen** und die ZIP-Datei auswählen, installieren und aktivieren (oder `wp plugin install visualclicks-analytics-1.0.0.zip --activate`).
2. In VisualClicks: **Einstellungen → Website → API-Keys** einen Schlüssel mit dem Recht **„Events senden“** anlegen (funktioniert in jedem Tarif).
3. In WordPress: **Einstellungen → VisualClicks** den Schlüssel als **API-Token** eintragen und speichern. Der Status zeigt die verbundene VisualClicks-Website. Fertig – die Website-ID holt sich das Plugin selbst.
4. Multisite: Jede Website des Netzwerks hat eigene Einstellungen (und eine eigene VisualClicks-Website).

Prüfen per Konsole:

```bash
wp visualclicks check            # aktuelle Website
wp visualclicks check --network  # alle Websites eines Multisite-Netzwerks
```

## Einwilligung (Cookie-Banner)

Ohne Einwilligung misst VisualClicks cookielos. Mit Einwilligung erkennt es wiederkehrende Besucher und darf Sitzungen aufzeichnen (Eingabefelder sind immer maskiert). Das Plugin übernimmt die Einwilligung automatisch aus
- der **WP Consent API** (Kategorie „Statistiken“; z. B. Complianz oder CookieYes) – das Plugin ist dort als kompatibel registriert und meldet seine Cookies/Speichereinträge,
- dem **Google Consent Mode v2** (`analytics_storage`),
- dem **IAB TCF v2** (Zwecke 1 und 8),
- oder jedem anderen Tool per JavaScript: `window.vcConsent(true)` bzw. `window.vcConsent(false)`.

Unter **Einstellungen → Datenschutz** steht ein Textvorschlag für die Datenschutzerklärung bereit.

## Gut zu wissen

- **Versand nach der Antwort:** Die Events werden am Ende der Anfrage gesendet, mit PHP-FPM/LiteSpeed nach dem Ausliefern der Seite (`fastcgi_finish_request`) – der Kunde wartet nicht darauf. Fällt VisualClicks aus, läuft der Shop normal weiter; nicht zugestellte Events werden nach fünf Minuten einmal erneut gesendet (Action Scheduler). Warnungen stehen unter **WooCommerce → Status → Protokolle** (Quelle „visualclicks“).
- **Seiten-Cache und Optimierer:** Das Tag ist für alle Besucher gleich (Full-Page-Cache ist kein Problem) und von WP Rocket, LiteSpeed Cache, Autoptimize, Cloudflare Rocket Loader u. ä. ausgenommen.
- **Zahlungsanbieter mit Webhook:** Wird eine Bestellung erst später vom Zahlungsanbieter angelegt oder bezahlt, ordnet das Plugin sie über die beim letzten Warenkorb-Kontakt gespeicherte Kundensitzung dem Besuch zu. Bestellungen aus dem Backend und aus Schnittstellen ohne Bezug zu einem Shop-Besuch (z. B. Marktplätze) zählen nicht als Web-Kauf (Filter `visualclicks_report_order`).
- **Fehlgeschlagene Zahlungen** („Fehlgeschlagen“) zählen erst nach 6 Stunden als storniert – bezahlt der Kunde in der Zwischenzeit doch noch, bleibt der Umsatz erhalten.
- **Login:** Führt WooCommerce beim Login den Gast-Warenkorb mit dem gespeicherten Kundenwarenkorb zusammen, zählt das weder als hinzugefügt noch als entfernt; das Abmelden ebenso wenig.
- **HPOS:** Bestellungen werden nur über die WooCommerce-API gelesen und markiert – kompatibel mit High-Performance Order Storage und dem klassischen Speicher.
- **IPv6:** Erreicht ein Kunde den Shop per IPv6, VisualClicks aber per IPv4 (oder umgekehrt), können Warenkorb/Kauf ohne Einwilligung in einer eigenen Sitzung landen. Umsatz und Artikel werden trotzdem vollständig gezählt, nur die Herkunft (Kanal) fehlt dann.
- **Hinter einem Proxy/CDN:** Die Kunden-IP wird wie von WooCommerce ermittelt; für Sonderfälle gibt es den Filter `visualclicks_client_ip`.
- **Administratoren ausschließen:** Option „Angemeldete Administratoren und Shop-Manager nicht erfassen“.
- **Selbst gehostetes VisualClicks:** unter „Erweitert“ die Adresse ändern.
- **Server-Events abschalten:** unter „Erweitert“; dann erfasst nur der Browser.
- **Deinstallation** entfernt die Einstellungen; die kleinen Markierungen an Bestellungen bleiben, damit eine Neuinstallation alte Bestellungen nicht erneut meldet.

## Voraussetzungen

WordPress 6.6 oder neuer, PHP 7.4 oder neuer, für das E-Commerce-Tracking WooCommerce 9.0 oder neuer; ausgehende HTTPS-Verbindungen zu visualclicks.de.

---

# VisualClicks Analytics for WordPress and WooCommerce (English)

Cookieless web analytics, heatmaps, session replays and – with WooCommerce – complete e-commerce tracking, set up with just an API token. WordPress 6.6–7.1, WooCommerce 9.0–11.2 (optional), PHP 7.4–8.4.

1. Upload the ZIP under **Plugins → Add New → Upload Plugin** (or `wp plugin install visualclicks-analytics-1.0.0.zip --activate`) and activate it.
2. In VisualClicks create an API key with the right **"Send events"** (Settings → Website → API keys; any plan).
3. Enter it as **API token** under **Settings → VisualClicks** (per site in a multisite network).

The tag is printed in the page head on every front-end page (cache friendly, excluded from JS optimisers); product views are tracked in the browser. With WooCommerce, cart changes (incl. quantity changes, cart/checkout blocks), orders (classic checkout and checkout block, also orders created later by payment webhooks) and refunds/cancellations (partial refunds included) are sent by the shop itself and linked to the shopper's browser session – cookieless via IP + user agent, with consent via the visit id. Consent is taken from the WP Consent API, Google Consent Mode v2, IAB TCF v2 or `window.vcConsent(true|false)`. HPOS compatible. Check with `wp visualclicks check`.