Shopware-Plugin
Plugin für Shopware 6.6 und 6.7: Installation per ZIP, Cookie-Hinweis, Worker für Wiederholungen. In Shopware Cloud nutzt du den universellen Webhook.
Das Plugin colly Tracking speichert die Click-ID aus der Landing-Adresse, hängt sie an die Bestellung und meldet bezahlte Bestellungen und Erstattungen signiert an colly. Es läuft auf Shopware 6.6 und 6.7 und braucht PHP 8.2 oder neuer.
Diese Seite ist für Advertiser. Download und Kurzanleitung findest du unter Integration, Reiter Shops, Abschnitt Shopware.
- Markierung 1: Plugin herunterladen lädt die Datei
colly-shopware.zip. In colly ändert sich dadurch nichts.
Installation Schritt für Schritt
Schritt 1: Plugin per ZIP installieren
Klicke in colly auf Plugin herunterladen. Öffne in Shopware Erweiterungen → Meine Erweiterungen → Erweiterung hochladen, wähle die ZIP-Datei, installiere und aktiviere das Plugin.
Schritt 2: API-Schlüssel in colly erstellen
Wechsle zum Reiter Postback & API und klicke unter API-Schlüssel auf Schlüssel erstellen. Kopiere Key-ID und Secret sofort: Sie werden nur einmal angezeigt. Siehe API-Schlüssel.
Schritt 3: Zugangsdaten in Shopware eintragen
Öffne Einstellungen → Erweiterungen → colly Tracking und trage API-Adresse, Key-ID und Secret ein. Fehlt einer dieser Werte, sendet das Plugin nichts.
Schritt 4: Ziel-URL deines Angebots anpassen
Setze beim Angebot die Ziel-URL auf deinen Shop mit
?click_id={click_id}.Schritt 5: Gutscheine angleichen (optional)
Lege in Shopware dieselben Aktionscodes an wie bei den Gutscheincodes deiner Angebote.
Schritt 6: Mit einer Bestellung testen
Besuche den Shop über einen echten Trackinglink, stimme im Cookie-Hinweis dem Eintrag colly Tracking zu und bestelle. Setze dann die Zahlung der Bestellung auf Bezahlt. Öffne in colly den Reiter Protokoll: Die
event_iddes Eintrags beginnt mitsw-.
Alle Einstellungen des Plugins
Alle Werte lassen sich je Verkaufskanal unterschiedlich setzen.
| Feld | Standard | Was es bewirkt |
|---|---|---|
| API-Adresse | https://joincolly.com | Wohin das Plugin meldet. |
| Key-ID (pk_…) | leer | Aus colly: Integration, Reiter Postback & API. |
| Secret (sk_…) | leer | Geheimer Teil deines Schlüssels. |
| Parameter der Click-ID | click_id | Name des Adressparameters mit der Click-ID. |
| Cookie-Laufzeit (Tage) | 30 | 1 bis 90 Tage. |
| Einwilligung beachten | an | Speichert die Click-ID erst nach Zustimmung. Siehe Cookie-Hinweis. |
| Ziel-Schlüssel (optional) | leer | Leer nimmt das Standardziel des Angebots. |
| Umsatzbasis | Zwischensumme | Zwischensumme nach Rabatten oder Gesamtbetrag. |
| Gutscheincodes senden | an | Sendet eingelöste Aktionscodes mit. |
| Testmodus | aus | colly prüft und protokolliert Bestellungen nur und bucht nichts. |
Cookie-Hinweis und Einwilligung
Das Plugin fügt dem Cookie-Hinweis von Shopware den Eintrag colly Tracking hinzu. Mit Einwilligung beachten (Standard) passiert Folgendes:
- Vor der Zustimmung speichert das Plugin nichts.
- Stimmt der Besucher zu, setzt Shopware das Cookie
colly-tracking=1. Das Plugin speichert die Click-ID dann im Cookiecolly_click_id(First-Party, HttpOnly, SameSite=Lax). - Stimmt der Besucher erst auf der Landing-Seite zu, ist die Adresse beim nächsten Aufruf schon eine andere. Das Plugin übernimmt die Click-ID dann aus der Adresse der vorherigen Seite desselben Shops. Der Klick bleibt so erhalten, ohne dass vorher etwas gespeichert wird.
- Ohne Zustimmung gibt es keine Click-ID an der Bestellung. Sie lässt sich dann nur über einen Aktionscode zuordnen.
Was das Plugin wann tut
| Wann | Was passiert |
|---|---|
| Bestellung wird abgeschlossen | Die Click-ID aus dem Cookie wird im Zusatzfeld colly_click_id der Bestellung gespeichert. |
| Zahlung wechselt auf Bezahlt | Das Plugin meldet die Conversion mit den eingelösten Aktionscodes. Ohne Click-ID und ohne Code sendet es nichts. |
| Zahlung wechselt auf Erstattet oder Bestellung auf Storniert | War die Conversion gemeldet, sendet das Plugin eine Statusmeldung: Ausstehend wird Abgelehnt, Freigegeben wird Storniert. Teilerstattungen lösen nichts aus. |
Die transaction_id besteht aus der Bestellnummer und den ersten 8 Zeichen der Bestell-ID. So bleiben mehrere Shops eines Advertisers auseinander, auch wenn die Nummern gleich sind.
Worker und Wiederholungen
Das Plugin versucht jede Meldung zuerst direkt, mit einer Wartezeit von höchstens 5 Sekunden. Bei einem Netzwerkfehler, 429 oder Serverfehler (5xx) legt es eine Nachricht in die Warteschlange von Shopware. Shopware wiederholt die Meldung dann nach seiner eigenen Strategie. Eine Störung bei colly hält den Bezahlvorgang im Shop nicht auf.
Das Ergebnis an der Bestellung
Das Plugin schreibt das Ergebnis in die Zusatzfelder der Bestellung. Fachliche Ablehnungen stehen außerdem im Log von Shopware und werden nicht wiederholt.
| Zusatzfeld | Inhalt |
|---|---|
colly_click_id | Die gespeicherte Click-ID. |
colly_transaction_id | Die gemeldete Transaktion. Sie wird für spätere Stornos gebraucht. |
colly_conversion_id | Die ID der Conversion bei colly. |
colly_last_error | Der letzte Fehlercode, zum Beispiel click_not_found. Die Bedeutung steht im Protokoll. |
Häufige Probleme
| Was du siehst | Ursache | Lösung |
|---|---|---|
| Kein Eintrag im Protokoll | Die Zahlung steht nicht auf Bezahlt, oder die Bestellung hat keine Click-ID und keinen Code, oder Zugangsdaten fehlen. | Zusatzfeld colly_click_id an der Bestellung prüfen und Zustimmung im Cookie-Hinweis geben. |
colly_last_error enthält invalid_signature oder unknown_key | Secret oder Key-ID sind falsch, oder der Schlüssel ist widerrufen. | Daten neu eintragen, notfalls neuen Schlüssel erstellen. |
| Meldungen kommen stark verspätet | Der Worker läuft nicht oder selten. | Worker von Shopware prüfen. |
| Bestellungen eines Verkaufskanals fehlen | Für diesen Kanal fehlen Einstellungen. | Einstellungen je Verkaufskanal prüfen. |