Magento

 

Einleitung

Das Modul synchronisiert Kundendaten, Bestelldaten und Warenkorbabbruchsinformationen zwischen Magento und Maileon. Magento ist hierbei das Primärsystem, das bedeutet, dass die Kundeninformationen in Magento als die Hauptinformationen angesehen werden und Änderungen an diesen Daten mit Magento synchronisiert werden. Anders herum werden nur bestimmte Informationen synchronisiert: die DOI-Bestätigung und Abmelder. Bei Bestelldaten und Warenkorbabbrüchen werden diese Informationen als Transaktionen (Events) an Maileon gesendet und können hier entweder zur Analyse oder zum Auslösen eines Triggermailings verwendet werden. Alle Funktionen sind über ein Konfigurationspanel in Magento einstellbar.
 

Inbetriebname des Moduls

Installation

Das Modul besteht aus zwei Hauptverzeichnissen: app und lib. Unter app befinden sich alle Konfigurationen und der Quellcode der für das Modul geschrieben wurde. Unter lib befindet sich eine Kopie des Maileon-PHP-API-Clients der auf der Entwicklerwebsite1 heruntergeladen werden kann. Diese Dateien werden einfach in das Hauptverzeichnis von Maileon eingefügt. Hinweis: es werden keine Dateien überschrieben aber da sich das Modul in das Newslettersystem von Magento integriert, wird die Klasse Mage_Newsletter_Model_Subscriber im lokalen Modul erweitert. Sollten Sie ein anderes Modul verwenden welches das Newslettersystem ändert, so deaktivieren Sie dieses bitte. Hinweis: im Maileon-Account müssen ein Custom-Field mit der Bezeichnung createdByTransaction vom Typ boolean, sowie storeViewCode vom Typ string angelegt werden. Seit Version 0.11.2 werden diese Kontaktfelder bei Bedarf automatisch angelegt und der Vorgang wird in der Log-Datei ‚ xqueue.plugin.log ‘ protokolliert.

Konfiguration

Wenn die Installation abgeschlossen ist finden Sie im Magento-Administrationsbereich unter System → Konfiguration die neue Einstellung Xqueue → Maileon-Settings, Abbildung 1 zeigt diese Option. Wenn eine Fehlermeldung 404 angezeigt wird loggen Sie sich bitte aus und melden Sie sich erneut am Backend an.

Abbildung 1: Einstellungen für Maileon

Abbildung 2: Allgemeine Einstellungen

Abbildung 2 zeigt die allgemeinen Einstellungen:
– Maileon API URL
Die URL zur Maileon REST-API.
– Maileon API Key
Der kundenspezifische API-Key2.
– Maileon API Timeout
Der Timeout für die verbindung, standard (keine Eingabe) ist 30 Sekunden
– Enable Extended Logging:
Logging-Informationen aktivieren oder deaktivieren. Bei Aktivierung werden alle Vorgänge mit Maileon geloggt, bei Deaktivierung nur Fehler.
– Print CURL Debug Data
Wenn diese Option aktiviert ist werden alle CURL-Anfragen auf der Website ausgegeben. So können Fehler bei der Kommunikation analysiert werden.

Abbildung 3: Spezielle Einstellungen zu Transaktionen

Abbildung 3 zeigt Einstellungen, welche für die Versendung von allgemeinen Transaktionen notwendig ist:

– Maileon API Key for Transactional Mails
Ein kundenspezifischer API key, welcher für die Versendung von Transaktionen verwendet wird. Hierdurch kann ein gesondertes Konto verwendet werden. Wenn das Feld leer gelassen wird, so wird der allgemeine API Key verwendet.
– Permission for Contacts Created by Transaction
Wenn eine Transaktionsnachricht an einen Kontakt geschickt wird, so muss dieser in Maileon angelegt werden, sofern er nicht existiert. Durch das Update am 06.12.2019 wird für den versand bestimmter E-Mails, etwa Bestellbestätigungen, keine Newsletterpermission mehr benötigt. Daher sollte NONE als Permission für diese Kontakte belassen werden. Es ist jedoch auch möglich eine andere permission zu setzen. Vorsicht ist jedoch geboten: Kontakte mit einer anderen Permission als NONE dürfen mit regulären Newslettern von Maileon beschickt werden.

Abbildung 4: Allgemeine Einstellungen für Newsletter-Anmelder

Abbildung 4 zeigt die Einstellungen für reguläre Newsletter-Anmeldungen.

– Enabled
Aktiviert die Synchronisierung von Newsletter-Abonnenten
– Use Maileon DOI-Process
Wenn diese Option aktiviert ist wird ein DOI-Mailing über Maileon versendet, ansonsten wird das DOI-System von Magento verwendet.
– DOI Mailing ID
Falls im Maileon-Newsletter-Account mehr als ein DOI-Mailing existiert kann hier der Schlüssel des gewünschten Mailings angegeben werden.
– Initial Permission
Wenn ein Kontakt in Maileon angelegt wird bekommt er einen initialen Permission-Status. In den meisten Fällen „Keine Permission“
– Final Permission
Mit Anstoßen des DOI-Prozesses kann gewählt werden ob eine reguläre DOI-Permission oder eine DOI+ (DOI + Berechtigung zum Einzelnutzertracking) als Ergebnis des Klicks auf den Bestätigungslink in der DOI-Mail eingeholt wird.
– Unsubscriber Check Range
In der Modulkonfiguration (config.xml) wird ein Cron-Job definiert der die Abmelder von Maileon abfragt. Diese Option legt fest für welchen Zeitraum dies geschieht und sie sollte etwas höher als die Cron-Job-Taktung sein, damit es Überschneidungen gibt. Läuft der Cron-Job z.B. alle 20 oder 25 Minuten sollten die Abmelder der letzten 30 Minuten abgefragt werden. Doppelte Abfragen werden korrekt verarbeitet.
– DOI Hook Token
Für Rückmeldungen aus Maileon (DOI-Subscriber) muss ein geheimer Schlüssel in Maileon und Magento bekannt gemacht werden. Der Schlüssel kann hier eingesehen und geändert werden.

Abbildung 5: Erweiterte Einstellungen für Newsletter-Anmelder

Abbildung 5 zeigt Einstellungen für Spezialfälle bezüglich der Anmeldungen.

– Behavior for Customer Changing Email
Wenn ein Kunde seine E-Mail im Shop ändert ist es dem Shopbetreiber überlassen ob die Änderung der E-Mail validiert oder ungeprüft übernommen wird. Es ist jedoch zu beachten, dass beim Änder der E-Mail-Adresse die DOI-Permission normalerweise nicht auf den neuen Kontakt übergeht. Je nach Datenschutzbeauftragtem wird dies jedoch anders bewertet, so bietet das Plugin drei Einstellungen:
a. Do not change subscriber
Der Kunde wird unabhängig vom Newsletter-Kontakt gesehen und der Kontakt bleibt in Maileon unberührt von der Änderung in Magento.
b. Update email in Maileon, keep permission
Die E-mail-Adresse des Kontaktes in Maileon wird aktualisiert, die Permission bleibt erhalten.
c. Update email in Maileon, remove and request new permission
Die E-Mail-Adresse in Maileon wird aktualisiert, die permission des Kontaktes wird entzogen und ein neuer DOI-Prozess für die neue E-Mail-Adresse wird ausgelöst.
– Send DOI for logged in Users
Wenn sich ein Benutzer eingeloggt hat und in seinem Profil die Newsletterverwaltung öffnet und sich zum newsletter anmeldet, so kann ein DOI-Prozess angestoßen werden oder der Benutzer wird direkt als Kontakt mit Permission angelegt. Die Permission wird mit der nachfolgenden Einstellung definiert.
– Permission for subscribing Customers without DOI
Soll ein eingeloggter Kontakt ohne DOI direkt in Maileon eingetragen werden, so kann hier die Permission definiert werden.
– Subscribe Contacts when Completing an Order
Durch das „berechtigte Interesse“ ist es möglich Kontakte direkt an den Newsletter anzumelden, sofern diese eine Bestellung aufgeben. Dies kann hier aktiviert werden. Kontakte werden nur angelegt, sofern sie sich nicht zuvor schon einmal aktiv abgemeldet haben.
– Permission for Subscribing Customers when Completing an Order
Wenn Kontakte beim Bestellen automatisch zum Newsletter angemeldet werden, so kann hier definiert werden mit welcher Permission dies geschehen soll. Empfehlenswert wäre etwa „Single-Opt-In“ oder „Other“.

Abbildung 6: Einstellungen für Bestellbestätigungen

Abbildung 6 zeigt die Einstellungen für Bestellbestätigungen

– Enabled
Aktiviert die Weiterleitung von Bestellevents an Maileon.
– Maileon Transaction Type ID
Die ID des Transaction-Typs für Bestellungen in Maileon.
– Generate TX Type
Mit dieser Schaltfläche kann das Ereignis in Maileon angelegt oder abgefragt und in Magento eingetragen werden.
Vorsicht: Die Konigurationsseite wird nach Drücken des Buttons neu geladen.
– Custom-Field Map
Ein assoziatives JSON-Array als Schlüssel Magento Custom Attributes von Produkten enthält und als Werte die Bezeichnung im Produkt/Item der Maileon-Transaktion. Beispiel: {„size“: „size_readable“, „size_id“:“size_id“} Diese Anweisung würde das Magento-Produkt-Attribut size den Produkten/Items unter der Bezeichnung size_readable und das Attribut size_id als size_id der Transaktion hinzufügen.
– Custom-Options-Field Map
Ein assoziatives JSON-Array als Schlüssel Magento Custom Option von Produkten enthält (Wahloptionen des users) und als Werte die Bezeichnung im Produkt/Item der Maileon-Transaktion. Beispiel: {„myCustomOption“: „maileonFieldName“}
– Shadow Email
Wird hier eine Emailadresse gesetzt, so wird bei jeder Bestellung eine zweite Transaktion in Maileon angelegt welche ein Triggermailing an diese Emailadresse auslöst. Hinweis: die Option dient zu Testzwecken und wenn in der Bestellbestätigung Kontaktinformationen aus Maileon verwendet werden, dann werden diese aus dem Kontaktprofil übernommen welches zu dieser Email gehört.
– Email Override
Wird hier eine Emailadresse gesetzt, so werden die Events mit dieser Emailadresse in Maileon eingetragen. Triggermailings die dann versendet werden, werden ebenfalls (nur) an diese Emailadresse gesendet. Die Option dient zu Testzwecken.

Abbildung 7: Spezielle Einstellungen für Bestellungen

Abbildung 7 zeigt erweiterte Einstellungen für Bestellungen

– Send Flat Transactions
Während reguläre Bestellbestätigungstransaktionen die Produkte als JSON-Array enthalten wird bei Verwendung dieser Option zusätzlich pro Produkt eine transaktion ausgelöst. Hintergrund: Es ist leider nicht möglich Kontaktfilter auf Listen vom Typ JSON anzuwenden. Über diese einzelnen Transaktionen kann etwa gefiltert werden, welche Kontakte Produkte bestimmter Kategorien gekauft haben.
– Maileon Transaction Type ID
Die ID des Transaction-Typs für Bestellungen in Maileon.
– Generate TX Type
Mit dieser Schaltfläche kann das Ereignis in Maileon angelegt oder abgefragt und in Magento eingetragen werden.
Vorsicht: Die Konigurationsseite wird nach Drücken des Buttons neu geladen.

Abbildung 8: Allgemeine Einstellungen zu Warenkorbabbrüchen

Abbildung 8 zeigt die Einstellungen für Warenkorbabbrüche

– Enabled
Aktiviert die Weiterleitung von Warenkorbabbrechern an Maileon.
– Maileon Transaction Type ID
Die ID des Transaction-Typs für Warenkorbabbrecher in Maileon.
– Generate TX Type
Mit dieser Schaltfläche kann das Ereignis in Maileon angelegt oder abgefragt und in Magento eingetragen werden.
Vorsicht: Die Konigurationsseite wird nach Drücken des Buttons neu geladen.
– # Of Hours Before Sending Reminder
Diese Option gibt an nach wie vielen Stunden ein nicht bestellter Warenkorb als verwaist gilt und ein Warenkorbabbrecher-Event gesendet wird.
– Custom-Field Map
Ein assoziatives JSON-Array als Schlüssel Magento Custom Attributes von Produkten enthält und als Werte die Bezeichnung im Produkt/Item der Maileon-Transaktion.
Beispiel: {„size“: „size_readable“, „size_id“:“size_id“} Diese Anweisung würde das Magento-Produkt-Attribut size den Produkten/Items unter der Bezeichnung size_readable und das Attribut size_id als size_id der Transaktion hinzufügen.
– Custom-Options-Field Map
Ein assoziatives JSON-Array als Schlüssel Magento Custom Option von Produkten enthält (Wahloptionen des users) und als Werte die Bezeichnung im Produkt/Item der Maileon-Transaktion. Beispiel: {„myCustomOption“: „maileonFieldName“}.
– Shadow Email
Wird hier eine Emailadresse gesetzt, so wird bei jeder Warenkorbabbruchs-Transaktion zweite Transaktion in Maileon angelegt welche ein Triggermailing an diese Emailadresse auslöst. Hinweis: die Option dient zu Testzwecken und wenn in der Bestellbestätigung Kontaktinformationen aus Maileon verwendet werden, dann werden diese aus dem Kontaktprofil übernommen welches zu dieser Email gehört.
– Email Override
Wird hier eine Emailadresse gesetzt, so werden die Events mit dieser Emailadresse in Maileon eingetragen. Triggermailings die dann versendet werden, werden ebenfalls (nur) an diese Emailadresse gesendet. Die Option dient zu Testzwecken.
Wichtig: Das Modul beruht auf den Mechaniken des von Magento selbst bereit gestellten Newslettersystems. Daher greifen auch die Einstellungen des Standardsystemes und es ist notwendig Magento mitzuteilen, dass bei neuen Newsletter-Anmeldern eine Bestätigung (DOI) benötigt wird. Dazu in der Konfiguration den Menüpunkt „Newsletter“ auswählen und die Bestätigung auf „Ja“ setzen, Abbildung 9 zeigt die Konfiguration.

Abbildung 9: Aktivierung der DOI Bestätigung

Verschiedene Stores an Maileon anbinden

Es ist möglich verschiedene Storeviews an verschiedene Newsletter-Accounts anzubinden. Abbildung 10 zeigt, dass z.B. der API-Key und somit der entsprechende Maileonaccount auf Storeview-Ebene überschrieben werden kann. Weitere Einstellungen sind auf dem Screenshot ebenfalls markiert, so kann man z.B. auch die Newsletterabbonentenverwaltung über Maileon in bestimmten Stores komplett deaktivieren.

Abbildung 10: Konfigurationseinträge die auf Store-Ebene angepasst werden können

Zur Anpassung der Storeview-Konfiguration muss oben links unter „Current Configuration Scope“ die entsprechende Storeview ausgewählt werden. In Abbildung 11 wurde als Beispiel ein englischer Store als 2. Store mit einer eigenen Storeview eingefügt, die Konfiguration hierfür ausgewählt und der Haken für „Defaultwert“ entfernt. Somit kann für diese Storeview ein anderer API-Key hinterlegt werden und es würden alle Newsletteranmelder in einem eigenen Newsletteraccount verwaltet.

Abbildung 11: Konfiguration einer Storeview

 

Funktion der Komponenten

Kundendaten

Generelle Kundendaten
Kunden können über verschiedene Wege in Magento registriert werden: über den Registrierungsprozess im Allgemeinen, über den Registrierungsprozess während einer Bestellung oder von einem Shopadministrator. Im Standardmodus (Option 9 steht auf „Nein“) werden die Kunden nur angelegt, wenn auf die Option für den Newsletter angeklickt wurde. Steht Option 9 auf „Ja“, wird der Kontakt mit der Erlaubnis „SOI“ in Maileon angelegt. Ausnahme: hat sich ein Kunde einmal absichtlich in Maileon vom Newsletter abgemeldet wird er nicht wieder automatisch angemeldet. Für Neuregistrierungen werden in Magento die Hooks customer_save_before und customer_address_save_before verwendet. Diese werden auch bei Kontaktdatenänderungen aufgerufen. Änderungen vom Kunden oder einem Administrator werden dabei sofort an Maileon weitergeleitet. Bei der Newsletteran-/abmeldung gibt es jedoch eine Besonderheit: entfernt ein Kunde in den Einstellungen den Haken beim Newsletter wird er abgemeldet , fügt er ihn wieder hinzu wird er ohne DOI-Bestätigungsmail mit DOI+ Erlaubnis zu Maileon hinzugefügt, da er sich ja im Magento-Administrationsbereich befindet und somit authentifiziert ist.

Abmeldungen
Abmeldungen aus Magento heraus werden wie beschrieben direkt mit Maileon synchronisiert, Abmelder die sich bei Maileon abgemeldet haben werden durch einen Cron-Job (TT_checkMaileonForUnsubscribers) in der Standardeinstellung alle 20 Minuten von Maileon abgefragt. Da sich Kunden zum Beispiel mehrmals innerhalb kurzer Zeit an-/abmelden können wird hierbei die Änderungszeit des Status eines Kunden in die Zeitzone des Maileon-REST-API Servers übersetzt und verglichen welcher Status der aktuellste ist. Ist der aktuellste Status eine Abmeldung, wird der Kontakt auch in Magento als Abmelder registriert. Die Zeitzone des Maileon-Servers ist „Europe/Berlin“.

DOI-Bestätigungen
Wird das Magento-DOI-Verfahren verwendet, so wird die Bestätigung direkt über die Maileon-Rest-API an Maileon weitergeleitet. Wird das Maileon-DOI-Verfahren verwendet wird ein Webhook aufgerufen der diese Daten an Magento weiterleitet. In Maileon wird der Webhook unter Einstellungen → Konto → Webhooks erstellt, siehe Abbildung 12. Dazu wird als Kontaktereignis DOI gewählt. Die POST-URL ist die URL die aufgerufen werden muss. Hier ist das Schema: http://myshop.com/de/xqueue/contact/acknowledgeDOI. Das „/de/“ muss in der URL angegeben werden, wenn die Ländererweiterung aktiviert ist, sonst muss es weggelassen werden. Als Parameter muss „email“ mit dem Kontaktfeldwert „Emailadresse“ und „token“ mit dem Wert, welcher unter Option 10 angegeben wurde, angegeben werden.

Abbildung 12: Webhook-Einstellungen in Maileon

Gespeicherte Daten:
1. ‚SALUTATION‘
2. ‚GENDER‘
3. ‚LOCALE‘
4. ‚GENDER‘
5. ‚FIRSTNAME‘
6. ‚LASTNAME‘
7. ‚FULLNAME‘
8. ‚CITY‘
9. ‚COUNTRY‘
10. ‚ADDRESS‘
11. ‚ZIP‘

Custom-Werte an Maileon übergeben
Aktuell unterstützt das Modul Customwerte für Kontakte nur durch eine Änderung des entsprechenden Codes in der Datei app/code/local/TT/XQueue/Helper/Data.php. Zum Zeitpunkt der Dokumentation betrifft dies die beiden Zeilen 197 und 244
Zeile 197: $newContact->custom_fields = array(‚createdByTransaction‘ => $createdByTransaction); Zeile 244: $newContact->custom_fields = array(‚createdByTransaction‘ => false);
In diesen Zeilen wird ein Wert an das Maileon-Customfeld „createdByTransaction“ übergeben. Hier könnte nun zum Beispiel die StoreView-ID oder das StoreView-Kürzel übergeben werden.
Die Zeilen würden sich dann wie folgt ändern: Zeile 197: $newContact->custom_fields = array(‚createdByTransaction‘ => $createdByTransaction, ‚magentoStoreViewCode‘ => Mage::app()->getStore()->getCode()); Zeile 244: $newContact->custom_fields = array(‚createdByTransaction‘ => false, ‚magentoStoreViewCode‘ => Mage::app()->getStore()->getCode());

Hier wird das Modul angewiesen dem Maileon-Customfeld „magentoStoreViewCode“ den Code der aktuellen StoreView zuzuweisen. Dieser Wert kann dann verwendet werden um etwa alle Kontakte einer Storeview herauszufiltern. Es muss sichergestellt sein, dass es die hier verwendeten Felder in Maileon gibt und den notwendigen Datentyp (in der Regel einfach „Text“) repräsentieren. Bitte auch die Groß- und Kleinschreibung beachten!
Dazu kann eine Funktion des Moduls in der zuvor genannten Klasse aufgerufen werden. Folgender Aufruf erstellt die Felder, falls sie noch nicht existieren:
$this->createMissingContactfields(array(‚createdByTransaction‘ => ‚boolean‘, ‚magentoStoreViewCode‘ => ’string‘));

Transaktionsnachrichten

die Schaltflächen in den Einstellungen können die Standardereignisse ‚magento_order‘, ‚magento_order_product‘ und ‚magento_abandonned_cart‘ erstellt werden. Jedes dieser Ereignisse hat eigenständige Standard-Attribute aber auch einen gemeinsamen Attributstamm, welcher frei mit zusätzlichen Informationen belegt werden kann. Die Liste der generischen Attribute ist wie folgt definiert:
1. ‚generic.string.1‘
2. ‚generic.string.2‘
3. ‚generic.string.3‘
4. ‚generic.string.4‘
5. ‚generic.string.5‘
6. ‚generic.double.1‘
7. ‚generic.double.2‘
8. ‚generic.double.3‘
9. ‚generic.double.4‘
10. ‚generic.double.5‘
11. ‚generic.integer.1‘
12. ‚generic.integer.2‘
13. ‚generic.integer.3‘
14. ‚generic.integer.4‘
15. ‚generic.integer.5‘
16. ‚generic.boolean.1‘
17. ‚generic.boolean.2‘
18. ‚generic.boolean.3‘
19. ‚generic.boolean.4‘
20. ‚generic.boolean.5‘
21. ‚generic.date.1‘
22. ‚generic.date.2‘
23. ‚generic.date.3‘
24. ‚generic.date.4‘
25. ‚generic.date.5‘
26. ‚generic.json.1‘
27. ‚generic.json.2‘
28. ‚generic.json.3‘

Diese Attribute werden standardmäßig nicht befüllt und können mittels Hooks aus einem externen Modul befüllt werden. Hinweis: auch die Standardattribute können bei Bedarf überschrieben werden.

Verfügbare Hooks:
– xqueue_order_submitting_before
Wird ausgelöst bevor eine Bestellbestätigungsttransaktion versendet wird und erlaubt es den Inhalt der Transaktion zu verändern.
– xqueue_order_product_submitting_before
Wird ausgelöst bevor ein einzelnes Produkt einer Bestellung als transaktion versendet wird und erlaubt es den Inhalt der Transaktion zu verändern.
– xqueue_abandoned_cart_submitting_before
Wird ausgelöst bevor eine Warenkorb-Abbruch-Transaktion versendet wird und erlaubt es den Inhalt der Transaktion zu verändern.

Ein Listener kann sich für die Ereignisse standardkonform registrieren. Ein Beispiel:

<xqueue_order_submitting_before> 
  <observers> 
     <my_model_observer>
         <type>model</type> 
         <class>My_Model_Observer</class> 
         <method>addDataToOrderTransaction</method> 
     </my_model_observer> 
   </observers> 
</xqueue_order_submitting_before>

Beispiel für die Implementierung der Listener-Methode:

public function addDataToOrderTransaction($observer) { 
    $event = $observer->getEvent(); 
    $varien_object = $event->getVarienObj(); 
    $content = $varien_object->getContent();

    // Adding data here 
    $content['generic.string.1'] = "this information has been added using event 'xqueue_order_submitting_before'";
    $varien_object->setContent($content);
}

 

Bestellungen

Abgeschlossene Bestellungen werden über den Magento-Hook sales_order_place_after abgefangen und als Transaktion an Maileon über die REST-API übertragen. Es werden pluginseitig die Hooks xqueue_order_submitting_before und xqueue_order_product_submitting_before angeboten.

Dabei werden folgende Standard-Werte übergeben:
29. ‚order.date‘
30. ‚order.total‘
31. ‚order.currency‘ (derzeit nur €)
32. ‚order.productIds‘ (Kommaseparierte Liste aller IDs der bestellten Produkte)
33. ‚order.categories‘ (Kommaseparierte Liste aller Kategorien der bestellten Produkten)
34. ‚order.shipping_fee‘
35. ‚order.tax_amount‘
36. ‚order.payment_type‘ (not working yet)
37. ‚order.discount.code‘
38. ‚order.discount.code‘
39. ‚order.discount.rules‘ (Regeln als JSON-Array)
40. ‚order.discount.rules_string‘ (Kommaseparierte Liste aller Regel-Namen)
41. ‚order.items‘
42. ‚customer.salutation‘
43. ‚customer.full_name‘
44. ‚customer.first_name‘
45. ‚customer.last_name‘
46. ‚customer.id‘
47. ‚billing.address.fullname‘
48. ‚billing.address.street‘ (Straße, Hausnummer)
49. ‚billing.address.zip‘ (PLZ)
50. ‚billing.address.city‘ (Stadt)
51. ‚billing.address.region‘ (Bundesland)
52. ’shipping.address.fullname‘
53. ’shipping. address.street‘ (Straße, Hausnummer)
54. ’shipping. address.zip‘ (PLZ)
55. ’shipping. address.city‘ (Stadt)
56. ’shipping. address.region‘ (Bundesland)
57. <Custom-Implementation-Attribute, siehe Ende dieses Kapitels>

Weiterhin werden für jedes Produkt im Warenkorb folgende Informationen übergeben:
1. ‚id‘
2. ’sku‘
3. ’name‘
4. ’single_price‘
5. ‚thumbnail‘
6. ‚image‘
7. ‚quantity‘
8. ‚combined_price‘
9. ’short_description‘
10. ‚description‘
11.
12. <Custom-Implementation-Attribute, siehe Ende dieses Kapitels>

Maileon bedingt es derzeit, dass zu jeder Transaktion ein Kontakt mit der Emailadresse existiert damit die Transaktion einem „Kontakt“ zugeordnet werden kann. Sollte eine Transaktion für eine Emailadresse ausgelöst werden die in Maileon nicht existiert, dann wird diese von Maileon abgelehnt. Dieses Verhalten soll in naher Zukunft geändert werden aber aus diesem Grund wird in diesem Fall derzeit ein SOI-Kontakt angelegt. Dieser bleibt auch nach Absenden der Transaktion bestehen, damit die History der gesendeten Transaktionen nicht beeinflusst wird. Hinweis: Die Kontakte werden markiert indem das Custom-Field createdByTransaction auf „true“ gesetzt wird. Sollen diese Kontakte nicht beschickt werden sollte ein Kontaktfilter verwendet werden, welcher diese Kontakte ausschließt. Der Wert wird bei einer etwaigen Registrierung für einen Newsletter überschrieben.

Custom Attributes
Spezielle Attribute (in Magento auch Custom Options oder Custom Attributes genannt) die in das Datenmodell von Magento eingefügt wurden können den Produkten/Items der Transaktion hinzugefügt werden, indem ein Mapping, wie in Abbildung 2 [13] dargestellt, übergeben wird. Wenn diese Funktionalität jedoch nicht ausreicht können eigene Implementierungen vorgenommen werden, welche z.B. Daten aus einer externen Datenbank sammeln und der Transaktion hinzufügen. Die Daten können über den Hook xqueue_order_submitting_before hinzugefügt werden.

 

Warenkorbabbrecher

Warenkorbabbrecher sind Kunden die Produkte in ihren Warenkorb legen und diesen dann nicht bestellen. Wenn der Kunde eine Emailadresse hinterlegt hat kann diese genutzt werden um ihn an den Warenkorb zu erinnern. Dazu werden zwei Cron-Jobs eingesetzt: der erste (TT_markAbandonedCarts) analysiert den Datenbestand und legt verwaiste Warenkörbe in einer Tabelle ab (xqueue_queue). Ein zweiter Cron-Job (TT_sendAbandonedCartsEmails) liest aus dieser Tabelle die Warenkorbabbrecher und erstellt daraus eine Transaktion in Maileon. Dabei wird der Hook xqueue_abandoned_cart_submitting_before angeboten um die Daten der Transaktion anzureichern. Erneutes Senden einer Warenkorbabbrecher-Transaktion an den gleichen Kontakt: es wird nur eine einzelne Transaktion für den Kontakt an Maileon gesendet. Eine erneute Transaktion kann nur ausgelöst werden, wenn der Kontakt entweder einen weiteren Warenkorb nicht bestellt oder den Inhalt des Warenkorbs seit Absenden der Transaktion geändert hat.

Dabei werden derzeit folgende Werte übergeben:
1. ‚cart.date‘
2. ‚cart.currency‘ (derzeit nur €)
3. ‚cart.productIds‘ (Kommaseparierte Liste aller IDs der bestellten Produkte)
4. ‚cart.categories‘ (Kommaseparierte Liste aller Kategorien der
5. ‚cart.total‘
6. ‚cart.items‘
7. ‚cart.discount.code‘
8. ‚cart.discount.total‘
9. ‚cart.discount.rules‘ (Regeln als JSON-Array)
10. ‚cart.discount.rules_string‘ (Kommaseparierte Liste aller Regel-Namen)
11. ‚customer.salutation‘
12. ‚customer.full_name‘
13. ‚customer.id‘
14. <Custom-Implementation-Attribute, siehe Ende dieses Kapitels>

Weiterhin werden für jedes Produkt im Warenkorb folgende Informationen übergeben:
1. ‚id‘
2. ’sku‘
3. ’name‘
4. ’single_price‘
5. ‚thumbnail‘
6. ‚image‘
7. ‚quantity‘
8. ‚combined_price‘
9. ’short_description‘
10. ‚description‘
11. <Custom-Attribute, siehe Abbildung 2 [18]>
12. <Custom-Implementation-Attribute, siehe Ende dieses Kapitels>

Custom Attributes
Für Warenkorbabbrüche gelten die gleichen Möglichkeiten wie für Bestellungen. Es wird jedoch eine gtrennter Hook angeboten: xqueue_abandoned_cart_submitting_before.

 

Funktionsweise der Warenkorb-Analyse

Die Analyse der abgebrochenen Warenkörbe basiert auf 3 Basistabellen
1. sales_flat_quote
Diese Tabelle stammt von Magento und wird lesend verwendet um zu analysieren welche Warenkörbe ein gewisses Alter haben.
2. xqueue_queue
Der Job der Warenkörbe aus Tabelle 1 analysiert schreibt Aufträge für Erinnerungsmails in diese Tabelle.
3. xqueue_log
Ein zweiter Job arbeitet die Einträge aus Tabelle 2 ab. Dazu nimmt er die Einträge, generiert und sendet eine Anfrage an Maileon, schreibt die Anfrage in die xqueue_log Tabelle und löscht dann den Eintrag aus Tabelle 2. Der Job der die Warenkörbe analysiert vergleicht die Warenkorb-ID mit dieser Tabelle und findet so heraus ob bereits für diesen Warenkorb eine Erinnerung vorliegt.

 

Übersicht über versendete Warenkorb-Erinnerungen

Ab Version 0.13.2 bietet das Plugin in Magento unter „Reports“ → „XQ Abandoned Carts Log“ die Möglichkeit die Einträge aus dem Datenbanklog der versendeten Warenkörbe anzusehen und bei Bedarf abzuspeichern.

 

Versenden kundenspezifischer Transaktionen

Die Kernfunktionalität des Plugins zum Versenden von transaktionen kann auch von externen Plugins verwendet werden. Anwendungsbeispiele: Erinnerungen an bestellte Produkte deren Nutzungsdauer bald ausläuf und die nachbestellt werden könnten (z.B. Kontaktlinsen) oder Änderungen an Preisen beobachteter Produkte.
Die Transaktionskomponente des Maileon Magento Plugins besteht ab Version 0.12.0 aus zwei, von extern verwendbaren, Bereichen:

1. Das Ermitteln und Anlegen von Transaktionstypen auf dem Namen basierend
Bis vor Version 0.12.0 war es notwendig die Transaktionstypen in Maileon manuell anzulegen. Mit dem Update wurden in den Optionen Buttons hinzugefügt, damit die Standardtypen (etwa Bestellbestätigungen) auf Knopfdruck in Maileon erstellt und in die Magento-Konfiguration eingetragen werden können. Die Funktionen können auch von anderen Komponenten verwendet werden. Die Klasse TT_XQueue_Helper_TransactionTypeHelper enthält dazu zwei Methoden:
1. public function getTransactionTypeId($name, $storeId = null)
Diese Methode ermittelt anhand eines Namens, ob der Transaktionstyp im entsprechenden Konto existiert und liefert entsprechend die ID zurück. Existiert der Typ nicht, so wird im Falle der Standardtransaktion deren Erstellung eingeleitet. Dieser Teil muss bei der externen Anwendung selbst realisiert werden, indem die nachfolgende Methode aufgerufen wird, wenn der Rückgabewert „null“ ist.
2. public function createTransactionType($tt, $storeId = null)
Diese Methode legt einen transaktionstypen in Maileon an. Beispiele für die Definition eines Transaktionstypen finden sich am Ende der Datei, etwa ind er Methode „getOrderTransactionType“ .

Mit Hilfe dieser Methoden kann eine Erweiterung das Anlegen von Transaktionstypen steuern. In Magento wird der Transaktionstyp in der Konfiguration gespeichert, dies ist aber nicht unbedingt notwendig. Das Shopware-Plugin fragt bei jedem Request nach dem Namen und ermittelt so die ID. Die Abwägung der Performance ist allerdings dem Entwickler überlassen, ein Aufruf dauert im Normalfall jedoch nur etwa 15ms.

2. Der Versand von Transaktionen
Ist der Transaktionstyp in Maileon angelegt, egal ob über die unter Option 1 beschriebene Methode, einen eigenen API Aufruf oder manuell über das Maileon UI, so kann er mit Daten beschickt werden. Wichtig dabei ist die Änderung des Maileon-Updates vom 06.12.2019 zu beachten: – Vorher musste jeder Kontakt der mit einer Transaktion beschickt werden sollte, eine valide Permission haben. Dies führt zu Konflikten, wenn man im gleichen Konto transaktionen und Newsletter versendet. – Nach dem Update ist es möglich Triggermails als „Werbefrei“ zu markieren, etwa Bestellbestätigungen. Diese Transaktionsmails können dann ohne Permission versendet werden.
Durch dieses Update entfallen gewisse Designentscheidungen die bisher implementiert wurden.

Die allgemeine Helper-Klasse TT_XQueue_Helper_Data enthält für den Versand eine Methode „sendTransaction“, welche den versand einer Transaktionsnachricht regelt.
Die verwendung kann am besten am Beispiel der Bestellbestätigungen gezeigt werden. Zunächst wird im entsprechenden Observer „TT_XQueue_Model_Observer“ in Methode „placeOrder“ auf das Event reagiert, indem ein Transaktionsereignis-Objet erstellt wird. Exemplarischer Codeauszug:

$email = $order->getCustomerEmail();

$content = array(); 
$content['order.date'] = $order['updated_at']; 

$ordered_items = $order->getAllVisibleItems(); 

// Get information about the order 

$items = array(); 
$categories = array(); 
$productIds = array(); 
foreach ($ordered_items as $i) { 
… 
   $item['id'] = $i->getProductId(); 
   $item['sku'] = $i->getSku(); 
   $item['name'] = $i->getName(); 
   $item['single_price'] = number_format(doubleval($i-
>getPriceInclTax()), 2, '.', ''); 
… 
  } 
… 
// Send event to Maileon 
$response = Mage::helper('xqueue')->sendOrderTransaction($email, 
$content, $customer, $billing_address);

 

Die Methode “sendOrderTransaction” ist ein Wrapper, welcher die Daten an „sendtransaction“ weiterleitet und ein paar Conveniencemethoden hinzufügt, etwa das Senden einer Kopie an einen zweiten Kontakt. Diese Funktionen sind optional.

 

FAQ

Q: Wenn ich mich nicht als Kunde eingeloggt habe aber mich mit einer E-Mail-Adresse eines Kunden einloggen möchte kommt eine Fehlermeldung „Signup for the newsletter is not working, another user is using the same email address“. Wieso ist das so und wie kann man dies abschalten?
A: Dieses Verhalten kommt von Magento selbst. Der zugehörige Code befindet sich in der Klasse app\code\core\Mage\Newsletter\controllers\SubscriberController.php, ca. um Zeile 60 herum. Zum Ändern des Verhaltens muss die Klasse überschrieben werden, wobei der Fall einfach auskommentiert werden kann.

Q: Ich verwende OneStepCheckout und wnen ich mich im Bestellprozess für den Newsletter anmelde bekommt ein Kunde 2 DOI Mails, wieso?
A: OneStepCheckout hat einen Aufruf für eine DOI während der Abarbeitung der Bestelldaten und einen welcher Kunden nach Abarbeitung registriert. Durch einen Bug in manchen Versionen schließen sich die beiden Fälle jedoch nicht aus, sodass ein Kunde beide DOIs bekommt. Das Problem wurde bisher behoben indem die Klasse app/code/local/Idev/OneStepCheckout/Block/Checkout überschrieben wurde. In dem Code-Abschnitt der für Anmelde-Registrierungen zuständig ist wurde dann der Flag auf false gesetzt, welcher die zweite Registrierung auslöst.