Einleitung
Hinweis: Durch die Änderungen der Shopware-API ist dieses Plugin nur mit Shopware 6 kompatibel. Für Shopware 5 gibt es ein eigenständiges Plugin.
Das Modul synchronisiert Kundendaten zwischen Shopware und Maileon. Newsletter-Anmelder werden von Shopware nach Maileon synchronisiert und Abmeldungen werden aus Maileon an Shopware übergeben. Weiterhin können Transaktionsmails bei Änderungen der Bestellungen über das Backend/Plugins oder die API ausgelöst werden. Alle Funktionen sind über ein Konfigurationspanel in Shopware einstellbar.
Das Modul wird in der XQueue-Beispielinstanz http://dev-shop1000.maileon.com/shopware6 verwendet (Abbildung 1).
Abbildung 1: Beispielinstanz von Shopware
Inbetriebname des Moduls
Updates
Wichtiger Hinweis: Ab Shopware 6.4 wird zum Bestätigen von Newsletter-Abonnenten ein Parameter „hash“ benötigt, welcher daher ab Plugin-Version 1.0.6 beim Versenden einer DOI in das Kontaktfeld‚ Shopware_hash‘ geschrieben wird und beim Webhook-Aufruf an Shopware mit zurück gegeben werden muss. Details, siehe Abbildung 17.
Wenn dieser Wert nicht übergeben wird, werden Anmeldebestätiger in Shopware NICHT als aktiv markiert.
Wichtiger Hinweis: Wir haben Berichte erhalten, dass nach einem Update auf 1.0.4 oder 1.0.5 Funktionen wie der Test-Button und der Import-All-Button nicht funktionieren bis man das Plugin deaktiviert und neu aktiviert. Daher empfehlen wir das Plugin standardmäßig nach einem Update zu deaktivieren und neu zu aktivieren.
Installation
Voraussetzungen prüfen
Das aktuelle Modul wird stetig weiterentwickelt und mit aktuellen Shopware-Versionen getestet.
Wichtiger Hinweis: Mit dem Update von Shopware 6.2 auf 6.3 wurden grundlegende Mechanismen in Shopware umgestellt, sodass es Einschränkungen vom Plugin bezüglich der Shopware-Version gibt:
Plugin 1.0.3 ist kompatibel mit Shopware 6.0-6.2
Plugin 1.0.4 ist kompatibel mit Shopware 6.3 -6.3.4
Plugin 1.0.5 ist kompatibel ab Shopware 6.3.5+
Modul installieren
Das Modul kann direkt über den Shopware Store installiert werden:
https://store.shopware.com/xqueu37905376689f/xqueue-maileon-newslettermanagement.html
Alternativ kann der Shopware Store auch über „Einstellungen“ „Plugin Manager“ „Shopware Store“ aufgerufen und nach „Maileon“ gesucht werden (Abbildung 2 und Abbildung 3). Anschließend muss das Modul über die drei Punkte installiert und dann über die entsprechende Schaltfläche aktiviert werden (Abbildung 4).
Abbildung 2: Installation des Moduls
Abbildung 3: Installation des Moduls 2
Abbildung 4: Installation und Aktivierung
Konfiguration
Das Modul kann nun über einen Klick auf die drei Punkte und dann die „Konfiguration“-Schaltfläche konfiguriert werden.
Abbildung 5: Allgemeine Einstellungen des Maileon Moduls
Generelle Konfiguration
Abbildung 5 zeigt die allgemeinen Einstellungen der Konfigurationsseite auf der für alle Verkaufskanäle oder jeden Verkaufskanal einzeln zunächst der API-Key und eine Ziel-Permission angegeben werden muss. Der API-Key kann im Maileon-Konto unter „Einstellungen“ „API-Keys“ erstellen und einsehen. Die Permission steuert, ob der Kontakt direkt mit Permission (etwa SOI) eingetragen wird oder ob eine DOI/DOI+-Mail zugestellt werden soll.
API Key:
Der API-Key kann im Maileon-Konto unter „Einstellungen“ „API-Keys“ erstellt und eingesehen werden und stellt die Verbindung zum Konto sicher.
Über die Schaltfläche „Test“ kann die Verbindung getestet werden. Bei einer erfolgreichen Überprüfung des API-Keys wird die Meldung „Verbindung wurde erfolgreich getestet“ eingeblendet. Ist der Test nicht erfolgreich sollte der API-Key überprüft werden. Häufige Fehler:
Gültigkeitszeitraum überschritten
Key wurde in Maileon deaktiviert
Es wurden Zeichen am Anfang oder Ende abgeschnitten
Permissions:
Die Ziel-Permission.
None: Keine Erlaubnis. Der Kontakt wird keine Newsletter erhalten.
Single Opt-in: Erlaubnis wurde einfach gewährt, z.B. durch Eintrag einer Emailadresse in einem Formular. Diese Methode erlaubt es technisch den Kontakt zu beschicken, stellt jedoch nicht sicher, dass die Emailadresse der Person gehört, welche sie eingetragen hat.
Double Opt-in: Bei dieser Erlaubnis wird eine Bestätigungsmail mit einem Bestätigungslink an die Emailadresse geschickt. Erst wenn der Link in der Mail angeklickt wurde und somit das Interesse an der Eintragung bestätigt wurde, kann der Kontakt beschickt werden.
Double Opt-in Plus: Double Opt-in inclusive Einwilligung zum Einzelnutzertracking.
Bitte beachten: Ohne Einzelnutzertracking dürfen keine Öffnungen, Klicks, usw. auf Einzelnutzer zurückgeführt werden werden und signifikante Daten zur Auswertung der Newsletterperformance fehlen.
DOI Schlüssel:
Hier kann ein DOI-Mailing-Schlüssel hinterlegt werden der bestimmt welches DOI-Mailing ausgelöst werden soll, sobald sich ein Gast oder Kunde zum Newsletter anmeldet. Der Schlüssel kann in Maileon beim entsprechenden DOI-Mailing in den Basiseinstellungen konfiguriert oder ausgelesen werden.
Webhook Token:
Ein zufällig zu generierender geheimer String der zur Identifikation der Aufrufe der Webhooks von Maileon aus verwendet wird. Es gibt einen Webhook für DOI-Bestätigungen und einen für Abmeldungen, damit diese Änderungen sofort in Shopware übernommen werden können. Die weitere Einrichtung der Webhooks wird in Kapitel „Einstellungen die in Maileon vorzunehmen sind“ dargestellt.
Sende DOI-Mails aus Maileon:
Hier kann festgelegt werden, ob die DOI-Mails aus Maileon heraus versendet werden oder nicht. Empfohlene Einstellung: ja.
WICHTIG: Der Punkt unterdrückt NICHT die DOI Mails aus Shopware. Der DOI-Mail-Versand von Shopware selbst kann unter "Einstellungen Business-Events" über den Eintrag newsletter.register deaktiviert werden.
Bei Registrierung eines angemeldeten Kunden:
Wenn sich ein Shop-Kunde in seinem Kundenprofil über das Häkchen anmeldet kann ausgewählt werden, ob er direkt mit der Ziel-Permission angelegt wird oder ob ein DOI-Prozess gestartet werden soll.
Verhalten bei einer Änderung der E-Mail-Adresse in Shopware:
Wenn ein am Newsletter angemeldeter Kontakt im Shop seine E-Mail-Adresse ändert, dann sind drei Szenarien möglich:
Die E-Mail-Adresse des Shop-Kunden ist logisch losgelöst von der Newsletter-Anmeldung. Es passiert nichts weiter und die Newsletter werden weiterhin an die (verifizierte) alte E-Mail-Adresse geschickt.
Die E-Mail-Adresse des Kontaktes in Maileon wird aktualisiert und die Permission beibehalten. Hier muss der Kunde mit seinem Datenschützer abklären, ob die erteilte Permission auch für eine neue E-Mail-Adresse gilt. Dies könnte z.B. der Fall sein, wenn der Shop die E-Mail-Adresse erst ändert, wenn verifiziert ist, dass der angemeldete Kunde auch dazu berechtigt ist.
Die E-Mail-Adresse des Kontaktes in Maileon wird aktualisiert und die Permission zurückgesetzt. Dabei wird ein neuer DOI-Prozess angestoßen.
Maileon API Timeout:
Mit diesem Feld kann Timeout für erfolglose Aufrufe zwischen 5 und 30 Sekunden gewählt werde.
Transaktionsmail-Einstellungen (Allgemein und Bestellbestätigungen)
Abbildung 6: Einstellungen für Transaktionsmails
Die nachfolgenden Punkte betreffen die Einstellungen für Transaktionsmails (Abbildung 6). Es ist zu beachten, dass die Transaktionen automatisch bei der ersten Verwendung angelegt werden. Wenn ein Mailing für eine Bestellbestätigung erstellt werden soll muss also zunächst der Menüpunkt aktiviert werden (Cache danach leeren!), dann kann eine Bestellung aufgegeben werden. In Maileon wird als Bestätigung ein Transaktionstyp angelegt auf Basis dessen dann das Mailing erstellt werden kann.
Maileon API-Key für Transaktionen:
Transaktionen können über ein anderes Maileon-Konto versendet werden, um Permission-Probleme zu vermeiden. Wenn das Feld leer ist, wird der reguläre API-Key verwendet.
Sende Bestellbestätigungs-Mails über Maileon:
Hier werden Bestellinformationen an Maileon übermittelt. Dies verhindert nicht das Versenden von Bestellbestätigungsmails durch Shopware, es werden lediglich die Daten an Maileon übertragen, welche z.B. zur Filterung von Kontakten verwendet werden können. Sollen Bestellbestätigungsmails aus Maileon ausgelöst werden, so müssen entsprechende Triggermails entworfen und aktiviert werden. Anschließend kann man die Bestellbestätigungsmails von Shopware, wie in Kapitel „Shopware Systemmails konfigurieren“ beschrieben, deaktivieren
Transaktionstypen:
shopware_order_confirmation_customer_1.0
shopware_order_confirmation_guest_1.0
shopware_ordered_products_1.0
Sende Kontobestätigungs-Mails über Maileon:
Mails die mit der Accounterstellung und Verwaltung zusammenhängen.
Hinweis: je nachdem ob DOI für die Account-Erstellung in Shopware aktiviert ist wird zunächst eine E-Mail mit Bestätigungslink versendet (shopware account confirmation) ansonsten wird sofort die Bestätigung geschickt und der Account aktiviert.
Transaktionstypen:
shopware_account_change_email
shopware_account_confirmation
shopware_account_creation
Sende Passwort-Reset-Mails über Maileon:
Diese Option erlaubt es Mails mit einem Passwort-Änderungs-Link über Maileon zu versenden.
Transaktionstyp:
shopware_password_reset
shopware_password_reset_confirmation
Sende Bestell- und Zahlungstatusänderungen über Maileon:
Diese Option erlaubt es bei Statusänderungen der Bestellung, des Zahlungsstatus oder des Status eines einzelnen Items eine entsprechende Benachrichtigung über Maileon zu versenden.
shopware_order_confirmation_cash_in_advanced
shopware_order_confirmation_customer
shopware_order_confirmation_guest
shopware_order_status_acknowledgement_returns
shopware_order_status_cancelled
shopware_order_status_clarification_required
shopware_order_status_completed
shopware_order_status_completed_delivery_customer
shopware_order_status_completed_delivery_guest
shopware_order_status_in_process
shopware_order_status_partial_cancellation
shopware_order_status_partially_completed
shopware_order_status_partially_delivery_customer
shopware_order_status_partially_delivery_guest
shopware_order_status_ready_delivery
shopware_payment_status_completed_invoiced
shopware_payment_status_completed_paid
shopware_payment_status_delayed
shopware_payment_status_encashment
shopware_payment_status_first_reminder
shopware_payment_status_no_credit_appr
shopware_payment_status_partially_invoiced
shopware_payment_status_partially_paid
shopware_payment_status_recrediting
shopware_payment_status_review_required
shopware_payment_status_second_reminder
shopware_payment_status_third_reminder
Separate Erlaubnis für Käufer einrichten:
Sollen Kunden nach einem Kauf automatisch zum Newsletter hinzugefügt werden, so kann dies hier aktiviert werden. Käufer werden dann, sofern sie sich nicht zuvor explizit abgemeldet haben oder bereits eine Permission besitzen, zu Maileon hinzugefügt. Die Art der Permission kann im nächsten Punkt konfiguriert werden. Vor der Aktivierung sollte der Datenschutzbeauftragte des Unternehmens konsultiert werden, da es hier unterschiedliche Auffassungen der Rechtslage geben kann.
Käufer Permission:
Hier kann die Permission angegeben werden, welche Käufer automatisch zugewiesen wird.
Product properties to custom fields
Ab Version 1.0.13 gibt es eine Option zum Übertragen von Produkteigenschaften als Customfelder in Maileon (Abbildung 7).
Abbildung 7: Hinzufügen von Produkteigenschaften zu Customfeldern
Hier können die Attribute ausgewählt werden, welche bei einer Bestellung an Maileon übertragen werden sollen. Sollte ein Produkt mehrere Werte für ein Attribut aufweisen, so werden alle Werte übertragen. Die Werte werden durch das Trennzeichen „|“ getrennt. Für die Werte wird dabei ein „rollender Ansatz“ verwendet, das bedeutet, es werden immer die neuen Attribute an den Anfang des Kontaktfeldes gesetzt, wobei Duplikate entfernt werden. Sollte der Eintrag länger als 255 Zeichen werden, so würden die ältesten Werte am Ende der Liste entfernt (Abbildung 8).
Die Felder in Maileon werden mit dem Prefix „shopware_“ angelegt.
Abbildung 8: Produkteigenschaften als Customfelder in Maileon
Product properties to order confirm product transactions
Ab Version 1.0.13 gibt es eine Option zum Übertragen von Produkteigenschaften als Transaktionsvariablen bei Bestelltransaktionen (Abbildung 9).
Abbildung 9: Hinzufügen von Produkteigenschaften zu Transaktionsdaten
Analog zu den Attributswerten in Kontaktfeldern, werden auch diese Werte durch das Trennzeichen „|“ getrennt.
Für reguläre Bestellbestätigungstransaktionen werden die Werte einfach als neue Attribute zu den Produktinformationen hinzugefügt.
Bei den Einzeltransaktionen für Produkte hingegen muss ein Mapping durch einen zusätzlichen Schritt durchgeführt werden, da hier die Informationen auf der obersten Informationsebene stehen und Maileon hier eine feste Struktur der Daten erfordert. Hier muss unter „Marketing“ „Maileon Plugin“ ein Mapping eingestellt werden. Dabei können bis zu 10 Werte an Maileon übergeben werden (Abbildung 10 und Ergebnis in Abbildung 11).
Abbildung 10: Einstellungen für die Attributzuweisung
Abbildung 11: Ergebnis der Daten in Maileon
Warenkorb-Abbrecher
Abbildung 12: Einstellungen für Warenkorbabbrecher
Wenn ein Kunde einen Warenkorb befüllt und nicht bestellt ist es möglich, einen Reminder zu versenden. Hierzu muss regelmäßig auf nicht bestellte Warenkörbe geprüft werden.
Im Vergleich zu vielen anderen Shop-Systemen gibt es hier eine Besonderheit zu beachten: Bei Shopware wird in der Datenbank leider nur die Erstellung eines Warenkorbes direkt vermerkt, nicht aber die letzte Änderung. Daher bezieht sich die Erinnerung auf den Erstellungszeitpunkt. Der Wartezeitraum sollte also groß genug sein, damit der Kunde genug Zeit hat einzukaufen, also zum Beispiel 2-4h. Eine weitere Besonderheit ist, dass es auf Grund des fehlenden Änderungsdatums bisher nicht möglich ist nach einer Erinnerung und darauffolgenden Änderung, erneut zu erinnern. Das ist erst möglich, wenn der Kunde den Warenkorb komplett geleert oder bestellt hat oder der Warenkorb durch Shopware irgendwann bereinigt wurde.
Warenkorbabbrüche an Maileon senden:
Transaktionen für Warenkorbabbrecher werden an Maileon übermittelt, sofern diese Option aktiv ist.
Nach wie vielen Minuten soll an einen Warenkorb erinnert werden:
Diese Einstellung legt den Zeitraum in Minuten nach Erstellung des Warenkorbs fest, nach dem an diesen erinnert werden soll, sofern er nicht bestellt wurde.
Kontakte ohne Permission erstellen:
Je nach Ansicht des jeweiligen Datenschutzbeauftragten besteht nach einem Kauf eine Geschäftsbeziehung und ein Kontakt darf auch mit einem Newsletter beschickt werden. Sollte dies gewünscht sein, soll diese Option deaktiviert werden, da ansonsten der Kontakt ohne Permission erstellt wird.
Testen der Warenkorbabbrecher
Um Warenkorbabbrecher zu testen, muss sichergestellt sein, dass der Task-Scheduler und der Message-Consumer von Shopware laufen. Zum Testen kann man dies auch manuell durchführen, indem folgende zwei Anwendungen gestartet werden:
./bin/console scheduled-task:run
./bin/console -vv messenger:consume
Die Option -vv gibt alle konsumierten Tasks aus und dient lediglich der Übersicht beim Testen. Sie ist für den Live-Betrieb nicht notwendig.
Wird nun ein Warenkorb bestellt und die Zeit für die Erinnerung ist abgelaufen, so sollten folgende Einträge im Consumer zu sehen sein (Abbildung 13):
Abbildung 13: Nachricht bei aktivierter Anzeige im Message-Consumer
In Maileon wird dann der Transaktionstyp „shopware_abandoned_carts_1.0“ angelegt. Die Versionsnummer bezieht sich auf die Standarddefinition 1.01.
Shopware Systemmails konfigurieren
Ab Shopware 6.3 wurde das E-Mail-Modul von Shopware derart umgestellt, dass es nicht möglich ist Systemmails (etwa Bestellbestätigungen) durch das Plugin zu deaktivieren. Sollen Bestellbestätigungen nur noch von Maileon versendet werden, so ist es (nur ab Shopware 6.3, also ab Plugin 1.0.4) notwendig die Funktion in den Maileon-Einstellungen zu aktivieren und zusätzlich in Shopware unter „Einstellungen“ „E-Mail-Templates“ (Abbildung 14) das entsprechende Template zu entfernen. Somit wird aus Shopware keine E-Mail mehr versendet.
Abbildung 14: Mail-Template-Einstellungen in Shopware 6.3
Es empfiehlt sich das Template abzuspeichern, falls man es später noch einmal benötigt.
Beispiel für Typ „Bestellbestätigung“
Betreff: Bestellbestätigung
Absender: {{ salesChannel.name }}
Text: …
HTML: …
Initiale Synchronisierung von Kontakten
Bei Bedarf können über den Menüpunkt „Marketing“ „Maileon Manager“ (Abbildung 15) auch aktuelle Newsletter-Anmelder eingesehen und alle Anmelder mit Maileon synchronisiert werden (Abbildung 16).
Abbildung 15: Maileon Manager im Menü "Marketing"
Abbildung 16: Übertragung historischer Anmelder an Maileon
Import aller Anmelder in Maileon
Im ersten Schritt muss die Erlaubnis (Permission) gewählt werden, welche die Kontakte beim Import in Maileon bekommen sollen. Im Unterschied zu den Einstellungen auf er Konfigurationsseite geht eine Massenübertragung jedoch davon aus, dass für jeden Kontakt eine entsprechende Erlaubnis vorliegt. Es wird keine DOI-Mail versendet, sondern die Kontakte werden mit der gewählten Erlaubnis direkt in Maileon eingetragen.
Durch Anklicken der “Import to Maileon”-Schaltfläche (Abbildung 16) wird der Prozess gestartet. Je nach Anzahl der Kontakte kann der Vorgang mehrere Minuten in Anspruch nehmen. Das UI benachrichtigt im Anschluss über Erfolg oder aufgetretene Fehler.
Einstellungen die in Maileon vorzunehmen sind
Um DOI-Bestätigungen und Abmelder mit Shopware zu synchronisieren kann in Maileon je ein Webhook für DOI-Bestätigungen und Abmelder eingetragen werden. Maileon Webhooks werden in Maileon unter “Einstellungen” “Webhooks” konfiguriert. Wenn der Menüpunkt nicht vorhanden sein sollte kann ein Vertriebspartner oder Servicemitarbeiter diesen freischalten.
DOI-Bestätigungen
Es muss nun ein neuer Webhook für das Ereignis „DOI-Anmeldebestätigung“ hinzugefügt werden. Dazu muss die URL „https://{your-shop}/maileon/doiconfirm“ und das Webhook-Token aus den Einstellungen (Punkt 3 im Installationskapitel und Abbildung 5) verwendet werden.
Der Webhook erwartet zwei Parameter:
email: Hier muss die Emailadresse des Kontaktes hinterlegt werden
token: Zur Absicherung wird der geheime Code an dieser Stelle eingefügt. Damit dieser nicht ausgelesen werden kann wird empfohlen eine SSL-verschlüsselte Verbindung zu wählen.
Hash: Seit Shopware-Version 6.4.0 benötigt Shopware zwingend einen eigens erstellten Hash um einen Kontakt zu aktivieren. Dieser wird ab Plugin Version 1.0.6 beim Versand einer DOI über Maileon in das Kontaktfeld „Shopware_hash“ geschrieben und muss auch im Webhook an Shopware übergeben werden.
Abbildung 17: Einstellungen für den DOI-Bestätigungs-Webhook in Maileon
Abmelder
Es muss nun ein neuer Webhook für das Ereignis „Abmelder“ hinzugefügt werden. Dazu muss die URL „https://{your-shop}/maileon/unsubscribe“ und das Webhook-Token aus den Einstellungen (Punkt 3 im Installationskapitel und Abbildung 5) verwendet werden.
Der Webhook erwartet zwei Parameter:
email: Hier muss die Emailadresse des Kontaktes hinterlegt werden
token: Zur Absicherung wird der geheime Code an dieser Stelle eingefügt. Damit dieser nicht ausgelesen werden kann wird empfohlen eine SSL-verschlüsselte Verbindung zu wählen.
Abbildung 18: Einstellungen für den Abmelde-Webhook in Maileon
Changelog
Version 1.0.13, 11.09.2022
When submitting an order contact event, submit multiple customer details in contact fields.
Submit product properties in contact fields when submitting an order contact event.
When submitting an order contact event, submit product properties in the contact event fields.
Added customfields „shopware_count_orders”, „shopware_count_total”, „shopware_last_order” and „shopware_last_order_datetime” that are updated when a order is complete (and reflect only values of completed orders)
Version 1.0.12, 05.05.2022
Bugfix: Abandoned cart job threw Exception when customer_id was empty
Version 1.0.11, 25.02.2022
Change Maileon API PHP library to composer version
Add product url to order confirmation and abandoned carts transactions
Add one transaction per purchased item to order confirm
Version 1.0.10, 21.12.20221
Fixed administration JS to work with Shopware 6.4.7
Version 1.0.9, 10.06.2021
Add order.categories and order.brands to order confirmation transaction
Add functionality to add separate Maileon permission for buyers
Plugin config works with different Sales Channels
Fixed not being able to send transactions using PHP 8+
Version 1.0.4, 12.08.2020
Updated plugin to work with Shopware 6.3
Version 1.0.3, 04.06.2020
Added abandoned carts functionality
Improve order transaction types to standard 1.0, see https://maileon.com/support/transactions/
Version 1.0.2
Customers that subscribe e.g. using the checkbox in their profile, will not be subscribe with permission directly, there is an option, to send DOI to customer instead.
Added setting to decide what happens when a customer changes the email address in Shopware (change it in Maileon, change it but revoke DOI and re-request it, or just do nothing in Maileon).
Remove customer title field from Maileon sync. as mandatory field.
Version 1.0.1
If transaction API key is empty, the general API key will be used.
Transaction contacts, if not existing in Maileon, will be created with permission NONE.
Version 1.0.0, 29.04.2018
Initial update from Shopware 5