Markdown (Eisvogel)

itkwebgains-anwenderdokumentation.md

---
title: "ItkWebGains"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ItkWebGains"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Was macht dieses Plugin?

**WebGains** ist ein Affiliate-Netzwerk: Partner verlinken auf den Shop und erhalten Provision, wenn über diese Zuordnung ein Kauf zustande kommt. Das Plugin **ItkWebGains** ist die technische Anbindung in Shopware `6.6` und erledigt für dich im Wesentlichen drei Dinge:

1. **Tracking im Storefront** – Es können Skripte (Container / Landing) eingebunden und – sofern aktiviert – **Clickthrough-Daten** über Parameter wie **siteid** und `utm_source` in einem Cookie gemerkt werden. Bei der Bestellung werden diese Infos an der **Bestellung** hinterlegt (Custom Fields), damit spätere Auswertungen und Exporte stimmen.

2. **Transaktions-Tracking** – Auf der **Bestellabschlussseite** wird – wenn du es einschaltest und die DSGVO-Logik greift – ein **Transaktions-Pixel** bzw. die dafür vorgesehene Ausspielung genutzt, damit WebGains den Umsatz der zugeordneten Partneraktion sehen kann.

3. **Produktfeed** – Unter einer festen Storefront-URL wird eine **CSV-Datei** mit Produktdaten bereitgestellt, die du bei WebGains als Katalog hinterlegen kannst. Optional wird der Feed **gecached**, damit große Kataloge den Server nicht bei jedem Abruf neu berechnen.

Zusätzlich gibt es im **Admin** (API-Routen) **CSV-Exporte** für Transaktionen (neu, Approve, Reject, Adjust) und den Produktfeed – typischerweise angebunden über ein Admin-Modul oder externe Tools, die die Shopware-Admin-API nutzen.

**Voraussetzungen:** Aktives **WebGains-Programm** mit **Program ID** und **Event ID** (und ggf. weiteren IDs aus deinem WebGains-Account). **Kein** separates Composer-Paket nötig – nur dieses Plugin und ein funktionierender Shop.

---

::: {.pdf-landscape}

## Diagramm: Partner bis Auswertung

```mermaid
flowchart LR
  P[Partner Link] --> C[Cookie und Clickthrough]
  C --> B[Bestellung]
  B --> F[Custom Fields und Export]
  F --> WG[WebGains Auswertung]
```

:::

# Wo du die Einstellungen findest

**Erweiterungen → Meine Erweiterungen** → **ITK WebGains Affiliate Marketing** → **Konfiguration**.

Oben kannst du den **Sales Channel** wählen. WebGains-Konfiguration ist **kanalspezifisch**: Jeder Kanal kann eigene IDs, eigenes Tracking und einen eigenen Feed haben.

---

# Typischer Ablauf nach der Installation

1. In der Konfig **Plugin aktivieren** (**active** = an) für den gewünschten Kanal.  
2. **Program ID**, **Event ID**, **Container ID** (laut WebGains-Dokumentation) eintragen.  
3. Entscheiden: **Container Tag** und **Transaction Tracking** an oder aus.  
4. **DSGVO:** Wenn du Consent brauchst, **„GDPR berücksichtigen“** anlassen und den **Standard-Wert** setzen (siehe technischer Abschnitt unten).  
5. **Produktfeed:** aktivieren, URL bei WebGains eintragen (`https://deine-domain/webgains/feed/products.csv`).  
6. **Testbestellung** mit Partnerlink (Cookie gesetzt) durchspielen und in WebGains prüfen, ob die Zuordnung ankommt.  
7. Logs bei Problemen: `var/log/webgains.log`.

---

# Plugin-Konfiguration (technisch, alle Felder)

Alle Keys hängen am Präfix `ItkWebGains.config.` (im Admin siehst du nur die Felder).

## Karte „WebGains Grundeinstellungen“

| Feldname (intern) | Typ | Bedeutung |
|-------------------|-----|-----------|
| **active** | bool | Hauptschalter. Wenn aus, liefert der Feed 404 und Tracking-Skripte werden nicht eingebunden. |
| **programId** | Text | WebGains Program ID. |
| **eventId** | Text | WebGains Event ID (für Transaktions-Tracking). |
| **containerId** | Text | Container ID für den WebGains Tag Manager / Skript-Container. |
| **campaignId** | Text | Optionale Campaign ID. |

## Tracking Einstellungen

| Feldname | Typ | Bedeutung |
|----------|-----|-----------|
| **enableContainerTag** | bool | Steuert, ob Container-Skripte auf den Storefront-Seiten erzeugt werden (Default laut XML: an). |
| **enableTransactionTracking** | bool | Transaktions-Tracking auf der Bestellbestätigungsseite (Default: an). |
| **respectGdpr** | bool | Wenn an, wird Tracking nur ausgeführt, wenn laut Implementierung Consent gegeben ist (Default: an). |
| **gdprDefault** | Auswahl | Wert **-1** = unbekannt, **0** = DSGVO gilt nicht, **1** = DSGVO gilt – wird in der Tracking-Logik ausgewertet, wenn kein expliziter Consent-Zustand ermittelt werden kann. |

## Export Einstellungen

| Feldname | Typ | Bedeutung |
|----------|-----|-----------|
| **enableProductFeed** | bool | Öffentlichen CSV-Feed unter `/webgains/feed/products.csv` freischalten. |
| **enableProductFeedCache** | bool | Feed über Symfony Cache (`cache.app`) zwischenspeichern. |
| **productFeedCacheLifetime** | int | Cache-Laufzeit in **Minuten** (Default 60). |
| **enableTransactionExport** | bool | Schaltet die Nutzbarkeit der Transaktions-Export-Logik frei (für Admin-API; fachlich mit internen Prozessen abstimmen). |
| **transactionValidationDays** | int | Zeitraum in Tagen für Validierungs-Kontexte im Export (Default 30). |

## Clickthrough Parameter

| Feldname | Typ | Bedeutung |
|----------|-----|-----------|
| **trackClickthrough** | bool | Ob `utm_source` / **siteid** (und verwandte Daten) im Cookie `wg_clickthrough` gespeichert werden. |
| **clickthroughCookieLifetime** | int | Cookie-Lebensdauer in **Tagen** (Default 30). |

---

# Produktfeed-URL für WebGains

Öffentlicher Endpunkt (Storefront):

```
GET https://<deine-shop-domain>/webgains/feed/products.csv
```

Voraussetzungen: Plugin **aktiv**, **Product Feed aktiv**, Aufruf im Kontext des richtigen **Sales Channels** (Domain muss zum Kanal passen). Sonst antwortet der Server mit **404 Not Found**.

Der Feed wird mit **Content-Disposition: attachment** ausgeliefert – für WebGains meist unkritisch, Hauptsache die URL ist erreichbar. Die **Cache-Dauer** steuert sowohl den internen Cache (falls an) als auch den HTTP-Header **Cache-Control: max-age=…** (in Sekunden, aus den Minuten der Config umgerechnet, mindestens sinnvoller Default).

---

# Admin-Exporte (CSV)

Über die **Admin-API** (nicht im klassischen Storefront-Menü) stellt das Plugin u. a. bereit:

| Methode | Pfad | Zweck (kurz) |
|---------|------|----------------|
| POST | `/api/_action/webgains/export/transactions/new` | Neue Transaktionen im Zeitraum (**from**, **to**, optional **salesChannelId**). |
| POST | `/api/_action/webgains/export/transactions/approve` | Approve-CSV anhand Bestellnummern. |
| POST | `/api/_action/webgains/export/transactions/reject` | Reject-CSV. |
| POST | `/api/_action/webgains/export/transactions/adjust` | Adjust-CSV. |
| POST | `/api/_action/webgains/export/products` | Produktfeed wie Storefront, aber als Download aus dem Admin-Kontext. |

Du brauchst ein **authentifiziertes** Admin-Request (OAuth / Integrations-Account), genaue Request-Bodies stehen in der Entwicklerdoku bzw. im PHP-Controller.

---

# Daten an der Bestellung (Clickthrough)

Wenn ein Cookie `wg_clickthrough` vorhanden ist und eine Bestellung geschrieben wird, versucht das Plugin, folgende **Order Custom Fields** zu setzen (sofern die Werte nicht leer sind):

- `webgains_clickthrough_siteid`
- `webgains_clickthrough_clickref`
- `webgains_clickthrough_utm_source`
- `webgains_clickthrough_timestamp`

Diese Felder müssen in Shopware als **Custom Fields** an der **Order** existieren und für den Editor sichtbar sein – sonst schlagen Updates fehl oder Werte erscheinen nicht. Wenn ihr das Set noch nicht angelegt habt, muss das einmalig im Projekt erfolgt werden (Migration oder Admin).

---

# Grenzen und was das Plugin nicht ist

- **Kein** Ersatz für eure **Rechts- oder Cookie-Beratung** – **respectGdpr** und Consent hängen mit Cookie-Tool und Theme zusammen.  
- **Keine** Garantie, dass jeder Browser oder jede Adblock-Erweiterung Skripte oder Pixel durchlässt.    
- **Provision und Attribution** werden letztlich von **WebGains** berechnet; das Plugin liefert nur Daten und Schnittstellen.

---

# Troubleshooting

| Problem | Prüfpunkt |
|---------|-----------|
| Kein Tracking / kein Pixel | **active**, **enableTransactionTracking**, DSGVO-Consent, Adblocker, `webgains.log` |
| Feed 404 | **active**, **enableProductFeed**, richtige Domain = richtiger Sales Channel |
| Keine Attribution | Cookie `wg_clickthrough` gesetzt? **trackClickthrough** an? Laufzeit nicht abgelaufen? |
| Custom Fields fehlen an der Order | Felddefinitionen in Shopware für **order** angelegt? |
| Alte Feed-Daten | Cache: **enableProductFeedCache** + Lifetime; Shopware-Cache leeren |

---

# Kurz für die Übergabe an Marketing

- IDs kommen aus dem **WebGains-Account**.  
- **Feed-URL** exakt kopieren, in WebGains als Produktquelle eintragen.  
- **Testkauf** mit echtem Partnerlink und danach Daten in WebGains prüfen.  
- **DSGVO:** Nur testen, wenn Consent wie im Live-Shop erteilt wird.