# VisualClicks Analytics für Magento 2

Cookielose Web-Analyse, Heatmaps, Session-Replays und vollständiges E-Commerce-Tracking für Magento Open Source, Adobe Commerce und Mage-OS – eingerichtet mit nur einem API-Token.

## Was das Modul erfasst

| Bereich | Wie | Daten |
|---|---|---|
| Seitenaufrufe, Klicks, Scrolltiefe, Heatmaps, Replays | Tracking-Tag im Browser (wird automatisch eingebunden) | wie auf jeder Website mit VisualClicks |
| Produkt angesehen | Browser, auf jeder Produktseite | SKU, Name, Hersteller, Kategoriepfad, Preis inkl. MwSt. |
| Warenkorb | Server (Magento) | hinzufügen, Menge ändern (1 → 3 = +2), entfernen, leeren – im Shop, per REST und GraphQL (PWA, Headless, Hyvä Checkout) |
| Kauf | Server, beim Aufgeben der Bestellung | Bestellnummer, Wert brutto/netto, Steuer, Versand, Gutschein, Rabatt, Zahlungs- und Versandart, Artikel |
| Erstattung / Stornierung | Server, bei jeder Gutschrift (auch Teilgutschriften) und bei Stornierung | Betrag der Gutschrift bzw. der stornierte Rest, nie mehr als der Bestellwert, jeweils einmal |

Warenkorb und Bestellungen meldet Magento selbst – 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

Magento 2.4.7, 2.4.8, 2.4.9 oder Mage-OS, PHP 8.2–8.4. Zwei gleichwertige Wege:

**A) Composer (empfohlen)** – die ZIP-Datei `visualclicks-magento2-analytics-1.0.0.zip` in einen Ordner legen, z. B. `packages/` im Magento-Verzeichnis:

```bash
composer config repositories.visualclicks artifact ./packages
composer require visualclicks/magento2-analytics:^1.0
bin/magento module:enable VisualClicks_Analytics
bin/magento setup:upgrade
# nur im Produktionsmodus:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy de_DE en_US
bin/magento cache:flush
```

**B) Manuell nach app/code** – `VisualClicks_Analytics-1.0.0.zip` im Magento-Verzeichnis entpacken (legt `app/code/VisualClicks/Analytics` an), dann dieselben `bin/magento`-Befehle wie oben (ohne `composer`).

## Einrichtung

1. In VisualClicks: **Einstellungen → Website → API-Keys** einen Schlüssel mit dem Recht **„Events senden“** anlegen (funktioniert in jedem Tarif).
2. In Magento: **Stores → Konfiguration → Dienste → VisualClicks Analytics** den Schlüssel als **API-Token** eintragen (er wird verschlüsselt gespeichert) und speichern. Unter **Verbindung** erscheint sofort der Name und die ID der VisualClicks-Website. Für mehrere Websites/Store-Views mit eigenen VisualClicks-Websites den Token je Website bzw. Store-View setzen.
3. Den Seiten-Cache aktualisieren (System → Cache-Verwaltung; Magento weist nach dem Speichern darauf hin). Fertig – die Website-ID holt sich das Modul selbst.

Prüfen per Konsole (alle Store-Views):

```bash
bin/magento visualclicks:check
```

Auch per Konsole einrichtbar: `bin/magento config:set visualclicks/general/api_token vcsk_…` (wird verschlüsselt gespeichert).

## Einwilligung

Ohne Einwilligung misst VisualClicks cookielos. Mit Einwilligung erkennt es wiederkehrende Besucher und darf Sitzungen aufzeichnen (Eingabefelder sind immer maskiert). Das Modul übernimmt die Einwilligung automatisch aus:

- **Magentos Cookie-Hinweis** (Stores → Konfiguration → Allgemein → Web → Standard-Cookie-Einstellungen → **Cookie-Beschränkungsmodus**): Klick auf „Cookies zulassen“ gilt als Einwilligung.
- **Google Consent Mode v2** (`analytics_storage` = `granted` / `denied`), z. B. aus Cookiebot, Usercentrics, CookieYes, Consentmanager über den dataLayer.
- **IAB TCF v2** (Zwecke 1 und 8).
- Für jedes andere Cookie-Tool: `window.vcConsent(true)` bzw. `window.vcConsent(false)` aufrufen.

## Caching, Performance, Sicherheit

- **Full-Page-Cache und Varnish** bleiben voll wirksam: Der Tag enthält nur Daten der Store-View und des Produkts, nichts Kundenbezogenes; Produktansichten aus dem Cache werden normal gezählt.
- **JS-Bündelung, Minifizierung, „JavaScript ans Seitenende“, HTML-Minifizierung**: kompatibel. Der Tag ist reines JavaScript ohne RequireJS/jQuery (Luma, Hyvä, eigene Themes) und als Datei des Moduls eingebunden – ohne Inline-Code.
- **Content Security Policy** (Magento 2.4.7+): `visualclicks.de` ist freigegeben (`csp_whitelist.xml`); eine eigene VisualClicks-Adresse wird beim Speichern automatisch für `script-src` und `connect-src` freigegeben. Funktioniert auch im strikten Modus und auf gecachten Seiten.
- Script-Optimierer (z. B. Cloudflare Rocket Loader) lassen den Tag in Ruhe (`data-cfasync="false"` u. a.).
- **Versand nach der Antwort:** Die Events werden nach dem Ausliefern der Seite gesendet (PHP-FPM, `fastcgi_finish_request`) – der Kunde wartet nicht darauf. Fällt VisualClicks aus, läuft der Shop normal weiter (kurze Zeitlimits: 2 s Verbindung, 4 s gesamt); Hinweise stehen in `var/log/system.log` („VisualClicks: …“).

## Gut zu wissen

- **Varianten:** Konfigurierbare Produkte zählen mit der SKU des Hauptprodukts, die gewählte Ausprägung steht als Variante (SKU des einfachen Produkts). Bundles zählen als ein Artikel.
- **Hersteller:** Attribut `manufacturer`, ersatzweise `brand`. **Kategorie:** tiefste aktive Kategorie des Produkts unter der Hauptkategorie der Store-View.
- **Login:** Meldet sich ein Kunde mit gefülltem Gast-Warenkorb an, führt Magento ihn mit dem gespeicherten Kundenwarenkorb zusammen – das zählt weder als hinzugefügt noch als entfernt.
- **Bestellungen ohne Kunde** (Zahlungs-Webhooks/IPN, Bestellungen per API, Cron): Das Modul merkt sich am Warenkorb, wer zuletzt daran gearbeitet hat, und ordnet den Kauf dieser Sitzung zu. Im Admin angelegte Bestellungen werden ohne Sitzung gezählt.
- **Mehrere Lieferadressen (Multishipping):** jede Bestellung zählt einzeln mit ihrer Bestellnummer.
- **Erstattungen:** jede Gutschrift (online/offline, auch teilweise) mit ihrem Betrag; eine Stornierung mit dem nicht berechneten Rest. Bestellungen von vor der Installation werden nicht nachträglich gemeldet.
- **Proxy/Varnish:** Steht der Shop hinter einem lokalen Proxy, nimmt das Modul die Kunden-IP aus `X-Forwarded-For`/`X-Real-IP`.
- **Headless/PWA:** Ruft der Browser REST/GraphQL direkt auf, wird alles zugeordnet. Läuft der Aufruf über einen eigenen Server (BFF/SSR), sollte dieser `User-Agent` und `X-Forwarded-For` des Kunden weitergeben – Warenkorb-Änderungen ganz ohne Kundenkontext (Bots, Skripte) meldet das Modul nicht.
- **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:** ebenfalls unter „Erweitert“; dann erfasst nur der Browser.
- **Daten im Shop:** zwei kleine Tabellen – `visualclicks_quote` (letzter gemeldeter Warenkorb-Stand und Kundenkontext je Warenkorb, wird mit dem Warenkorb gelöscht) und `visualclicks_order` (was je Bestellung gemeldet wurde).

## Deinstallation

```bash
bin/magento module:disable VisualClicks_Analytics
composer remove visualclicks/magento2-analytics   # bzw. app/code/VisualClicks/Analytics löschen
bin/magento setup:upgrade
```

---

# VisualClicks Analytics for Magento 2 (English)

Cookieless web analytics, heatmaps, session replays and complete e-commerce tracking for Magento Open Source, Adobe Commerce and Mage-OS 2.4.7–2.4.9 (PHP 8.2–8.4) – set up with just an API token.

1. Install either via Composer (`composer config repositories.visualclicks artifact ./packages`, put `visualclicks-magento2-analytics-1.0.0.zip` into `packages/`, `composer require visualclicks/magento2-analytics:^1.0`) or by unzipping `VisualClicks_Analytics-1.0.0.zip` in the Magento root (creates `app/code/VisualClicks/Analytics`). Then `bin/magento module:enable VisualClicks_Analytics && bin/magento setup:upgrade` (production mode: `setup:di:compile`, `setup:static-content:deploy`).
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 **Stores → Configuration → Services → VisualClicks Analytics** (per website/store view if needed; stored encrypted), check the connection status shown below it and refresh the page cache.

Product views are tracked in the browser; cart changes (storefront, REST and GraphQL – incl. quantity changes), orders (also multishipping and orders created by payment webhooks, linked via the shopper context stored on the cart) and refunds (every credit memo incl. partial ones, cancellations with the remaining amount, never more than the order value) are sent by Magento itself and linked to the shopper's browser session (cookieless via IP + user agent, with consent via the visit id). Consent is taken from Magento's Cookie Restriction Mode, Google Consent Mode v2, IAB TCF v2 or `window.vcConsent(true|false)`. Full page cache/Varnish, JS bundling/minification, "move JS to bottom" and strict CSP keep working. Check with `bin/magento visualclicks:check`.