Klaviyo – Deliver Smarter Marketing

Anleitung SW6 - Plugin

1. Installation & API-Keys einrichten

Shopware Admin → Erweiterungen → Meine Erweiterungen → Klaviyo – Deliver Smarter Marketing installieren & aktivieren.

Anschließend: Erweiterungen → Meine Erweiterungen → Klaviyo → Konfiguration.

PUBLIC API-Key
Den öffentlichen API-Key aus Klaviyo eintragen. Bei mehreren Verkaufskanälen oben den Kanal wechseln und jeden einzeln konfigurieren.

PRIVATE API-Key
Nur nötig, wenn die Newsletter-Funktion verwendet wird.

Methode zum Tracking der Events
Klaviyo empfiehlt JavaScript Events. Hinweis: Einige Events (z.B. Fulfilled Order, Purchased Items) werden immer über die Server-Side API übertragen.

Klaviyo Cookie erforderlich (DSGVO)
Events werden nur übertragen, wenn der Kunde das Cookie „shopsyKlaviyo“ akzeptiert hat. Wird nicht der Shopware Consent Manager verwendet, muss diese Option deaktiviert oder das Cookie im eigenen Manager eingetragen werden.

Track Ordered Product / Placed Order / Placed Order Extra Daten
Rechnungs- und Versandadresse zusätzlich im „Placed Order“ Event übertragen.

Track Purchased Items
Event bei Zahlstatus „Komplett bezahlt“.

Track Fulfilled Order
Event bei Bestellstatus „Komplett ausgeliefert“.

Track Cancelled Order / Refunded Order
Events bei Stornierung oder Rückgabe.

Track Placed Review
Wenn ein Shopkunde ein Produkt Review erstellt hat.

Track Viewed Product
Wenn ein Kunde eine Produktdetailseite aufruft. Gilt für Javascript- und Serverside-Methode.

Track Added to Cart
Wenn ein Produkt in den Warenkorb gelegt wird. Gilt für Javascript- und Serverside-Methode.

Track Started Checkout
Wenn ein Kunde die Checkout-Bestätigungsseite erreicht. Gilt für Javascript- und Serverside-Methode.

Track Checkout Completed
Event nach Klaviyo senden auf der Checkout-Abschluss-Seite. Gilt für Javascript- und Serverside-Methode.

Track Recently Viewed Items
Fügt dem Klaviyo-Profil die Eigenschaft „RecentlyViewedItems“ (zuletzt 10 angesehene Produkte) hinzu, wenn ein Produkt angesehen wird. Nützlich für personalisierte E-Mail-Kampagnen. Gilt für Javascript- und Serverside-Methode.

Back in Stock
Kunden können benachrichtigt werden, wenn Artikel wieder verfügbar sind. Voraussetzung: Produkte müssen über den Produktexport in Klaviyo vorhanden sein.
Optionen: Double-Opt-in, Datenschutz-Checkbox, CAPTCHA konfigurierbar.

Produktkatalog Sync
Zusätzlich zum bestehenden XML-Produktexport können Produkte direkt über die API in den Klaviyo-Katalog übertragen werden. Läuft automatisch im Hintergrund (Intervall unten) und kann zusätzlich manuell über den Button gestartet werden.

Umfang der Synchronisation
„Nur Hauptprodukte“ überträgt je Produkt ein Katalog-Item (Preis/Bestand des Hauptprodukts). „Hauptprodukte + Varianten“ legt zusätzlich für jede Produktvariante eine Klaviyo Catalog-Variante mit eigenem Preis/SKU/Bestand an.

Intervall der automatischen Synchronisation
Wie oft die Hintergrundaufgabe den Klaviyo-Katalog mit dem Shop abgleichen soll. Es werden nur geänderte Produkte übertragen, kürzere Intervalle sind daher unbedenklich. Diese Einstellung gilt global (für alle Verkaufskanäle).

Deaktivierte/gelöschte Produkte aus dem Klaviyo-Katalog entfernen
Wenn aktiviert, werden in Shopware deaktivierte oder gelöschte Produkte bei der nächsten Synchronisation automatisch aus dem Klaviyo-Katalog entfernt.

Katalog jetzt synchronisieren
Startet sofort eine vollständige Katalog-Synchronisation für den aktuell ausgewählten Bereich (Global = alle aktiven Verkaufskanäle, oder nur den ausgewählten Sales Channel). Verwendet die Einstellungen oben (Sync-Umfang, Löschen inaktiver Produkte). Für die importierten Produktdaten wird die Standardsprache des Verkaufskanals verwendet.

Newsletter Abonnenten syncen
Newsletter Listen aus Klaviyo werden mit Shopware synchronisiert und Kunden entsprechend in der Shopware Datenbank aktualisiert.
Hinweis: Bei sehr vielen Abonnenten kann dieser Vorgang sehr lange dauern. Dann wird empfohlen dies nur einmal in der Nacht durchzuführen.

Klaviyo Newsletter-Listen-Zuordnung
„Automatisch“ entspricht dem bisherigen Verhalten (je Verkaufskanal/Sprache wird automatisch eine Liste in Klaviyo angelegt). „Manuell“ verwendet die unter „Klaviyo Listen-Zuordnung“ im Hauptmenü konfigurierte Zuordnung.

Bestellpositionen ausschließen
Semikolon getrennt alle Typen eintragen, die nicht nach Klaviyo übertragen werden sollen.
Wichtig: Drittanbieter Plugins fügen mitunter auch „productTypes“ hinzu, die keine „wirklichen“ Produkte sind. Diese müssen auch zwingend in dieser Tabelle hinzugefügt werden.

Verwendung vom Plugin „Produkt Konfigurator für Sets und Stücklisten“ von skweb
Bei Verwendung der Javascript Methode muss diese Option auf aktiviert gesetzt werden, damit das Event „added to cart“ funktioniert, sofern das Plugin von skweb verwendet wird.

Cover-URL-Prefix (Started Checkout Event)
Wenn ein externes CDN für die Bildtransformation verwendet wird, kann an dieser Stelle ein Präfix hinterlegt werden. Dieses Präfix wird vor die eigentliche Cover-URL des Produktbildes gestellt.

Klaviyo API Timeout (Sekunden)
Maximale Wartezeit in Sekunden für Klaviyo API-Antworten. Standard: 5 Sekunden. Erhöhen Sie den Wert bei langsameren Verbindungen.

Klaviyo API Verbindungs-Timeout (Sekunden)
Maximale Wartezeit in Sekunden für Klaviyo API-Antworten. Standard: 5 Sekunden. Erhöhen Sie den Wert bei langsameren Verbindungen.

Klaviyo API Verbindung testen
Testet den PRIVATE API-Key für den aktuell ausgewählten Bereich (Global oder den ausgewählten Sales Channel). Der Check ist read-only und legt KEINE Test-Events oder -Profile in Klaviyo an.
Sales-Channel-spezifische Keys werden direkt geprüft; leere Felder werden vom globalen Bereich geerbt.

2. Produktkatalog-Export einrichten

Bei Installation wird automatisch ein Produktexport-Verkaufskanal erstellt. Dieser muss noch minimal nachkonfiguriert werden.
Hinweis: Ab Pluginversion 2.2.9 kann der Produktkatalog auch via Klaviyo-API gefüllt/aktualisiert werden. Optionen dazu befinden sich in der Pluginkonfiguration.

Schritte:

1. Unter Kataloge → Dynamische Produktgruppen: Den Eintrag „Klaviyo“ editieren und Bedingungen definieren (Standard: alle aktiven Produkte).
2. Verkaufskanal „Klaviyo Catalog Feed“ öffnen und konfigurieren: Storefront Verkaufskanal, Domain und Währung auswählen. Dateiname: klaviyo.xml, Zeichenkodierung: UTF-8, Format: XML. „Varianten als eigene Produkte exportieren“ empfohlen. API-Zugangsschlüssel generieren → Export-URL kopieren.

Template einrichten: Im Verkaufskanal auf den Tab „Template“ klicken und den Code aus der beiliegenden Datei einfügen. Dann „Template testen“ und „Vorschau generieren“.

Klaviyo Product Feed Template herunterladen

In Klaviyo einrichten: Content → Products → Add new Source. Export-URL aus Shopware eintragen → „Define Source“. Unter „Configure Field Mapping“ sind keine Änderungen nötig, wenn das mitgelieferte Template verwendet wird. → „Complete Feed setup“.

3. Historische Bestellungen übertragen

Ab Plugin Version 1.8.9 auch via Scheduled Task oder Konsole möglich:
php console scheduled-task:run-single shopsy.klaviyo.historical_orders_sync

Bitte beachten: Bei sehr vielen Bestellungen kann die Verarbeitung mehrere Stunden dauern.

4. Gutscheine (Coupons) nach Klaviyo syncen

Aktive Promotions aus der Shop-Administration können nach Klaviyo übertragen werden – für die Verwendung in Flows und Kampagnen. Nur individuelle Coupons werden in Klaviyo angelegt. Bereits vorhandene Coupons werden nicht erneut erstellt.

Promotions nach Klaviyo übertragen:
Im Promotion-Listing auf den Button „Promotions nach Klaviyo übertragen“ klicken.

Einzelne Promotion übertragen:
In der Detailansicht einer Promotion möglich.

Status aktualisieren:
Mit „Promotions in Klaviyo aktualisieren“ werden eingelöste Coupons automatisch aus Klaviyo entfernt. Ein Scheduled Task („shopsy.klaviyo_update_promotions“) übernimmt dies auch automatisch.

5. Klaviyo Custom Field Mapping

Ab Version 2.2.6 können beliebige Shopware Custom Fields automatisch als Properties an Klaviyo Events und Profile übergeben werden. So lassen sich z. B. Treuepunkte, Kundensegmente oder bestellbezogene Zusatzinfos direkt in Klaviyo für Segmentierung und Flows nutzen.

Die Konfiguration erfolgt unter Marketing → Klaviyo Custom Field Mapping

Im Listing werden alle konfigurierten Mappings gelistet. Hier ist es möglich, jeden Eintrag individuell zu bearbeiten, bzw. neue Mappings zu erstellen:

Übersicht der Spalten:

• Quelle – Die Shopware-Entität, von der das Custom Field gelesen wird (Kunde, Bestellung oder Produkt).

• Custom Field – Technischer Name des Shopware Custom Fields.

• Klaviyo-Property – Name, unter dem der Wert in Klaviyo gespeichert wird.

• Sales Channel – „Global“ gilt für alle Verkaufskanäle. Kanalspezifische Mappings überschreiben globale.

• Aktiv – Nur aktive Mappings werden beim Event-Versand berücksichtigt.

• Position – Reihenfolge bei mehreren Mappings (niedrigere Werte zuerst).

 

In der Detailansicht können die einzelnen Optionen konfiguriert werden. Werden zu den einzelnen Optionsfelder weitere Informationen benötigt, sind diese über das Fragezeichen jeweils einzusehen.

Tipp: Wird ein Custom Field nicht im Dropdown angezeigt (z. B. weil es dynamisch von einem anderen Plugin erzeugt wird), kann über den Schalter „Manuell eingeben“ der technische Feldname direkt eingegeben werden.

Beispiel: Ein Custom Field custom_customer_loyalty_level am Kunden soll als LoyaltyLevel in Klaviyo erscheinen.

1. Neues Mapping anlegen

2. Quelle: Kunde

3. Custom Field: custom_customer_loyalty_level auswählen

4. Klaviyo-Property: LoyaltyLevel eintragen

5. Speichern → Ab sofort wird der Wert bei jedem Event-Versand automatisch mitgeschickt.

6. Klaviyo Newsletter-Listen-Zuordnung

Ab Version 2.2.8 können Newsletter-Abonnenten manuell bestimmten Klaviyo-Listen zugewiesen werden.

Die Konfiguration erfolgt unter Marketing → Klaviyo Listen-Zuordnung:

Es können beliebig viele Einträge erstellt und konfiguriert werden. In der Detailansicht kann für jeden Verkaufskanal individuell die konfiguration vorgenommen werden:

Bei Fragen stehe ich per Kontaktformular zur Verfügung.