Current version: v1.9.0
The module synchronizes customer data, order data and shopping cart information between Magento and Maileon. Magento is the primary system, which means that the customer information in Magento is considered the main information and changes to that data are synchronized with Magento. Conversely, only certain information is synchronized: the DOI confirmation and unsubscription. For order details and cart abandonments, this information is sent to Maileon as transactions (events) and can be used either to analyze data using contact filters or to activate a trigger mailing. All functions can be set via a configuration panel in Magento.
The first step is to copy the Maileon directory into the /app/code directory of the Magento installation. If the app directory doesn't already contain a code subdirectory please create it. After this the module must be enabled using the following steps:
Copy the Maileon plugin to the Magento root folder (/sources/magento-2/Xqueue/Maileon/). Add the following line to the Magento composer.json:
"require": {
"xqueue/module-maileon": "^1.8"
},
"repositories": [
{
"type": "composer",
"url": "https://repo.magento.com/"
},
{
"name": "xqueue/module-maileon",
"type": "path",
"url": "sources/magento-2/Xqueue/Maileon"
}
], |
Run composer update at command line
Before enable the module, we must check to make sure Magento has recognize our module or not by enter the following at the command line:
php bin/magento module:status
If you follow above step, you will see this in the result:
List of disabled modules: Xqueue_Maileon |
This means the module has recognized by the system but it is still disabled. Run this command to enable it:php bin/magento module:enable Xqueue_Maileon
If the above succeeded the following message is displayed:
The following modules has been enabled: Xqueue_Maileon |
This’s the first time you enable this module so Magento require to check and upgrade module database. We need to run this command:php bin/magento setup:upgrade
If everything went well you can switch to Magento’s admin interface. The plugin settings are available in the following menu:
Stores -> Configuration -> Maileon
Copy the contents of the new version package to /sources/magento-2/Xqueue/Maileon/
Run composer update at command line
To update database schema and dependencies, run this command:
php bin/magento setup:upgrade
The configuration can be found under “Stores” “Configuration” and, since version 1.8, can be set on Storeview level. This means, that for each Storeview, you can select an own API key, to use different Maileon accounts or you can select different DOI mail keys to send out DOIs in e.g. different languages.
Maileon Api Key: The API key associated with the Maileon account you wish to use.
Print CURL Debug Data: Enabling this will show Maileon API responses. Useful for debugging. Not to be used in a live environment!
Active: This enables the newsletter subscriber module. This module synchronizes new subscriptions to Maileon.
Initial Permission: The initial permission level to set for new Maileon subscribers.
None: No permission. This is most likely what is required, e.g. in Germany.
Single Opt-in: Consent only given once, e.g. by entering the email address on the registration form. This does not guarantee that the subscriber is indeed identical with the email account owner.
Confirmed Opt-in: A confirmation mail about the registration is sent to the provided email address, but it does not contain a confirmation link. This method is frequently abused by spammers. The recipient will have to actively revoke consent in order not to receive any advertising emails. This method is not really legal in Germany and should not be used.
Double Opt-in: Set double-opt-in in Maileon, e.g. if such a permission has already been gathered externally.
Double Opt-in Plus: Double-opt-in including consent to single user tracking.
DOI Process: A confirmation email including a “confirmation link” is sent to the provided email address. The subscription will not be valid until the recipient clicks this link. Thus it is ensured that the recipient is identical to the mailbox owner and really wishes to receive your emailings (the recipient cannot click the confirmation link without having signed in to her or his mailbox). Double Opt-in is the only subscription method we can recommend. Please note that XQ can only provide general information but no official legal counselling. Please contact your lawyer in the case of legal questions on this topic.
DOI+ Process: Requires option “DOI Process”. A DOI+ permission will be registered after the user clicks the DOI confirmation link in the DOI mail.
Please note: You can only obtain significant response analyses and react appropriately when your contacts have given consent to single user tracking. Taking into account that only the double-opt-in procedure is legally safe (for German-based providers), the only permission method we can recommend is “Double Opt-in including consent to single user tracking”.
Doi Mailing ID: If the permission above is set to DOI or DOI-Plus the newsletter subscriber will be sent a confirmation mailing using Maileon. This field can be used to customize which DOI mailing will be sent from Maileon. Leaving it empty means that the default DOI confirmation will be sent. (A default DOI confirmation mailing must be set in Maileon in order for this to work.)
Unsubscribe Hook Token: This token is used to synchronize Maileon unsubscribers back to Magento. This field must be a unique string. (Think of it as a password.) The hook setup will be detailed later.
Doi Hook Token: This token is used to synchronize Maileon DOI confirmations back to Magento. If set the Magento subscriber state will match the Maileon subscription state of each customer. This field must be a unique string. (Think of it as a password.) The hook setup will be detailed later.
Unsubscribe All Emails: Since Magento 2.4, an email can be registered multiple times with Magento (one time for each storeview). When Maileon reports back unsubscribers to Magento it passes along the storeview ID but if that data gets deleted or is not added in the webhook configuration, Magento does not know from which storeview to unsubscribe the contact of. This option allows to unsubscribe all contacts with a given email address (from all storeviews) if ambiguous or if required (e.g. by law).
Disable confirmation request email: Used to disable the built-in Magento DOI confirmation email.
Disable success email: Used to disable the built-in Magento DOI success email.
Disable unsubscription email: Used to disable the built-in Magento unsubscriber email.
Active: This enables the order confirmation module. This module synchronizes order events to Maileon. Each order creates two types of transactions: magento_orders and magento_orders_extended. The transaction magento_orders contains one event for each order. The transaction magento_orders_extended contains one event per line item in the order.
Enable separate permsission for buyers: todo
Buyers permission: todo
Abandoned Cart Settings
Figure 7: Shopping Cart Abandonnment Mail Settings
Active: This enables the cart abandonment module. This module synchronizes abandoned cart events to Maileon.
Fallback permission: the permission a contact will get when added to Maileon. This should be set to none in most cases.
# Of Hours Before Sending Reminder: This is the number of hours after an open cart is considered abandoned.
Shadow Email: This email address also receives a copy of the cart abandonment email.
Email Override: If this field is set customers won’t receive cart abandonment emails. This address will receive them instead.
Figure 8: Transactiontype for Cart Abandonnments
Configuring Custom Forms
In order to submit other standard or custom data to Maileon, the following scheme must be used:
Standard fields: The standard fields must use the prefix standard_, followed by the exact name and providing the correct format, documented on http://dev.maileon.com/api/rest-api-1-0/contacts/standard-contact-fields/
Example: standard_FIRSTNAME
Custom fields: I custom fields should be submitted, they need to have the prefix custom_. Capizalization needs to be respected exactly as specified in Maileon.
Example: custom_MySpecialField
Enhancing Transactional Data
In some cases, it is required to add custom data transactions. E.g. if you use a plugin, which allows customizing products with names, custom images, etc., and the image shall be displayed in the order confirmation mail, you need to pass this URL to Maileon. Or this case, the plugin provides a simple way to add data to the transactions by overriding class “Maileon\SyncPlugin\Helper\External\Data” from an external plugin.
To ease development, we provide a test plugin that shows a minimalistic setup. In di.xml, the class is overwritten with an own implementation:
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<preference for="Maileon\SyncPlugin\Helper\External\Data" type="Maileon\TestPlugin\Helper\External\Data" />
</config>
Investigating class “Maileon\TestPlugin\Helper\External\Data”, which is provided by the test package and can be also named freely, there are different methods that can be used.
This method adds attributes to a single product within an order. Based on the product, e.g. a URL of a custom image could be retrieved and returned in the array:
getCustomProductAttributes($product)
This method adds attributes to an order, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition1:
getCustomOrderTransactionAttributes($transaction_content)
This method adds attributes to single item transactions, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition2:
getCustomOrderExtendedTransactionAttributes($transaction_ext_content)
This method adds attributes to a single product within an card abandonment transaction. Based on the product, e.g. a URL of a custom image could be retrieved and returned in the array:
getCustomAbandonedCartProductAttributes($product)
This method adds attributes to a cart abandonment transaction, directly. As we are working with a transaction directly, make sure to use as a key one of the valid keys provided in the transaction type definition3:
getCustomAbandonedCartTransactionAttributes($transaction_content)
The data can be added e.g. by writing it to one of the free generic string fields:
$result['generic.string_1'] = "this is an additional information";
This value can then be used in a mailing to print it, use it as a link or an image URL.
The installation of the plugin is as expected done by using Composer. The first step is to copy the ‘Maileon’ directory of the test plugin into the /app/code directory of the Magento installation. If the app directory doesn’t already contain a code subdirectory please create it. After this the module must be enabled using the following steps:
Using the command line check if the module is recognized by Magento.
Type the following command:
php bin/magento module:status
This should result in the following response:
List of disabled modules:
Maileon_TestPlugin
This means that the system has recognized the synchronization module but it isn’t enabled yet.
Issue the following command to enable the module:
php bin/magento module:enable Maileon_TestPlugin
If the above succeeded the following message is displayed:
The following modules has been enabled:
- Malieon_TestPlugin
After this Magento must check and update its database. Issue the following command:
php bin/magento setup:upgrade
If everything was installed as expected, the next time e.g. an order is triggered, some additional data should be attached to it.
Figure 9: Additional information attached to a transaction
Webhook Settings in Maileon
Changed parameters in version 1.8:
Since Magento 2.4, an email can be added as newsletter subscriber for each storeview, thus, the email can exist multiple times in the Magento newsletter module. As of version 1.8 of the plugin, configuration is based on storeview level, thus, an email can be added to different Maileon newsletter accounts based on its origin. Thus, when Maileon reports back a DOI confirmation or unsubscription, it needs to identify the correct storeview for a given contact. This is done by adding a new parameter “storeview_id”.
Unsubscription Webhook Setup
The unsubscription webhook is used to synchronize Maileon unsubscribers back to Magento. To set this up in Maileon you must navigate to Settings/Webhooks. In this panel click Create new webhook. Select Unsubscription from the event dropdown. Enter the following for HTTP post URL (substituting your own domain):
http://<my domain>/rest/V1/maileon/webhook-unsubscribe
e.g.: http://maileonmagento.com/rest/V1/maileon/webhook-unsubscribe
Add the following URL parameters:
email -> contact field value -> E-mail address
token -> user-defined value -> <token>
storeview_id -> contact field value -> magento_storeview_id
The token must match the value given for the Unsubscribe Hook Token given in Magento settings.
Figure 10: Webhook Settings for Unsubscriptions
Please note: To now anonymize the contact field “magento_storeview_id” in case of an unsubscription, it is required to configure Maileon accordingly.
DOI Confirmation Webhook Setup
The DOI confirmation webhook is used to synchronize Maileon DOI confirmations back to Magento. To set this up in Maileon you must navigate to Settings/Webhooks. In this panel click Create new webhook. Select DOI Confirmation from the event dropdown. Enter the following for HTTP post URL (substituting your own domain):
http://<my domain>/rest/V1/maileon/webhook-doi_confirm
eg.: http://maileonmagento.com/rest/V1/maileon/webhook-doi_confirm
Add the following URL parameters:
email -> contact field value -> E-mail address
token -> user-defined value -> <token>
storeview_id -> contact field value -> magento_storeview_id
The token must match the value given for the DOI Hook Token given in Magento settings.
Figure 11: Webhook Settings for DOI-Confirmations
Changelog
30.08.2022 – v 1.8.9
Added payment method ID and name to order transactions
13.05.2022 – v 1.8.8
Enhancing of loading images in abandoned carts when model is not initialized in cron job, yet
11.05.2022 – v 1.8.7
Change in URLs for images inside abandoned cart transactions
Compatibility fix for 2.4.4
25.01.2022 – v 1.8.6
Changing DB table creation to declarative model
18.01.2022 – v 1.8.5
Added thumbnail to abandoned carts transaction
19.11.2021 – v 1.8.4.1
Added description about how to enable Maileon to send contactfield storeview_id to the Magento webhook when unsubscribing
17.11.2021 – v 1.8.4
Fixed users getting redirected to blank page after subscribing in some Magento versions
Fixed error message when specifying wrong storeview ID in webhooks
Added configuration for testing abandoned carts
13.09.2021 – v 1.8.3
Add functionality to add separate Maileon permission for buyers
10.09.2021 – v 1.8.2
Resubscribe with same email address fix
13.07.2021 – v 1.8.1
Recreate the package to work with composer
07.07.2021 – v 1.8
Plugin configuration extended to storeview level
Add extra parameter to DOI confirmation and unsubscribe webhook to identify the correct storeview
Add a custom field to contact: magento_storeview_id
Add a custom field to contact: magento_source
Renamed plugin from Maileon_SyncPlugin to Xqueue_Maileon in order to match marketplace requirements. Manual deinstallation and reinstallation needed for updating. Configuration will be kept.
04.02.2021 – v 1.7
Updated subscriber logic to support “initial” and “target” permission separately
27.01.2021 – v 1.6
Added new settings for fallback permissions for orders and cart abandonments
15.01.2021 – v 1.5
Added new Maileon webhooks API URLs, to process DOI confirm and unsubscribe webhooks
Bugfix at abandoned carts methods in case of exceptions
Add new fields to order transactions and round the float values to two digits
24.11.2020 – v 1.4
Added overwritable class for enriching transactions with custom data
Switching to default transaction type definitions defined at https://dev.maileon.com/api/implementation-guideline/implementation-guidelines-transactions/
Fixing warning about deprecated syntax in Maileon API client