# VisualClicks Analytics für PrestaShop 8.1 – 9.x

Cookielose Web-Analyse, Heatmaps, Session-Replays und vollständiges E-Commerce-Tracking für PrestaShop – eingerichtet mit nur einem API-Token.

## Was das Modul 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 (Referenz der Kombination bzw. des Produkts), Name, Marke, Kategoriepfad der Standardkategorie, Variante (Attribute), Bruttopreis |
| Warenkorb | Server (PrestaShop) | hinzufügen, Menge ändern (1 → 3 = +2), entfernen, leeren |
| Kauf | Server, bei der Bestellung | Bestellreferenz, Wert brutto/netto, Steuer, Versand, Gutscheincodes und Rabatt, Zahlungs- und Versandart, Artikel |
| Erstattung / Stornierung | Server | Gutschrift (auch Teilerstattung) mit ihrem Betrag; Status „Erstattet“, „Storniert“ oder „Zahlungsfehler“ mit dem noch nicht erstatteten Rest – insgesamt nie mehr als der Bestellwert, jeder Betrag nur einmal |

Warenkorb und Bestellungen werden direkt von PrestaShop 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`).

Wird eine Bestellung erst später von einem Zahlungsanbieter bestätigt (Webhook/IPN, Cron, Backoffice), nutzt das Modul die beim Warenkorb gespeicherte Kundensitzung – der Kauf landet trotzdem im richtigen Besuch.

Eine Bestellung, die sowohl im Browser als auch vom Server gemeldet wird, zählt nur einmal (Abgleich über die Bestellreferenz). Wird ein Warenkorb auf mehrere Bestellungen aufgeteilt (mehrere Lieferadressen), meldet das Modul einen Kauf mit der gemeinsamen Referenz und der Summe.

## Installation

1. In PrestaShop: **Module → Modulverwaltung → Modul hochladen** und die ZIP-Datei auswählen. Das Modul wird installiert.
2. In VisualClicks: **Einstellungen → Website → API-Keys** einen Schlüssel mit dem Recht **„Events senden“** anlegen (funktioniert in jedem Tarif).
3. In PrestaShop: **Module → VisualClicks Analytics → Konfigurieren** den Schlüssel als **API-Token** eintragen und speichern. Unter „Verbindung“ erscheinen Name und ID der VisualClicks-Website. Fertig – die Website-ID holt sich das Modul selbst.

**Multistore:** Die Einstellungen gelten für den oben im Backoffice gewählten Kontext (alle Shops, Shop-Gruppe oder ein Shop). Shops erben von ihrer Gruppe und von „Alle Shops“ – für mehrere Shops mit eigenen VisualClicks-Websites den Token je Shop setzen.

Prüfen per Konsole:

```bash
php bin/console visualclicks:check
```

## Einwilligung (Cookie-Banner)

PrestaShop hat keinen eingebauten Cookie-Manager. Das Modul erkennt die üblichen Signale automatisch:

- **Google Consent Mode v2** (`gtag('consent', 'update', {analytics_storage: 'granted'})`, auch über den Google Tag Manager),
- **IAB TCF v2** (`__tcfapi`, Zwecke 1 und 8 – z. B. Usercentrics, Cookiebot, OneTrust im TCF-Modus),
- jedes andere Banner per JavaScript: `window.vcConsent(true)` bei Zustimmung, `window.vcConsent(false)` beim Widerruf.

Ohne Zustimmung misst VisualClicks cookielos. Mit Zustimmung erkennt es wiederkehrende Besucher und darf Sitzungen aufzeichnen (Eingabefelder sind immer maskiert).

## Gut zu wissen

- **Versand nach der Antwort:** Mit PHP-FPM werden die Events erst nach dem Ausliefern der Seite gesendet – der Kunde wartet nicht darauf. Ohne PHP-FPM (z. B. mod_php) wird kurz blockierend gesendet (max. 2 s Verbindungsaufbau, 4 s gesamt); ist VisualClicks nicht erreichbar, pausiert das Modul eine Minute lang. Der Shop läuft in jedem Fall normal weiter; Warnungen stehen unter **Erweiterte Parameter → Logs**.
- **Caches und Optimierer:** Das Tag ist je Shop statisch (Full-Page-Cache möglich) und so markiert, dass „CCC“, Cloudflare Rocket Loader und JavaScript-Verzögerer es nicht verschieben (`data-keepinline`, `data-cfasync="false"`, `data-no-optimize` …).
- **Login:** Wird beim Anmelden der gespeicherte Warenkorb wiederhergestellt („Warenkorb nach Anmeldung erneut anzeigen“) oder der Gast-Warenkorb übernommen, zählt das weder als hinzugefügt noch als entfernt.
- **Gutschriften als Gutschein** (statt Gutschrift-Beleg) haben keinen Erstattungsbetrag und werden nicht gemeldet.
- **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.
- **Selbst gehostetes VisualClicks:** unter „Erweitert“ die Adresse ändern.
- **Server-Events abschalten:** unter „Erweitert“; dann erfasst nur der Browser.
- **Deinstallation** entfernt die Einstellungen und die drei Tabellen des Moduls (`visualclicks_cart`, `visualclicks_order`, `visualclicks_site`).

## Voraussetzungen

PrestaShop 8.1, 8.2 oder 9.x (PHP 7.2 – 8.4), ausgehende HTTPS-Verbindungen zu visualclicks.de.

---

# VisualClicks Analytics for PrestaShop 8.1 – 9.x (English)

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

1. Upload the ZIP under **Modules → Module Manager → Upload a module**.
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 **Modules → VisualClicks Analytics → Configure** (per shop in multistore if needed). The connection status shows the VisualClicks website.

Product views are tracked in the browser; cart changes (incl. quantity changes), orders (one purchase per order reference) and refunds (credit slips incl. partial refunds, cancellation/refund/payment error states with the remaining amount) are sent by PrestaShop itself and linked to the shopper's browser session (cookieless via IP + user agent, with consent via the visit id) – also when a payment webhook validates the order later. Consent: Google Consent Mode v2, IAB TCF v2 or `window.vcConsent(true|false)`. Check with `php bin/console visualclicks:check`.