This document describes the setup and functions of the XQueue extension for Shopware 6 manual.
Version: 1.1.6.
Introduction
Note: Due to the changes in the Shopware API, this plugin is only compatible with Shopware 6. There is a standalone plugin for Shopware 5.
The module synchronizes customer data between Shopware and Maileon. Newsletter subscribers are synchronized from Shopware to Maileon and unsubscribes are transferred from Maileon to Shopware.
Furthermore, transactional emails can be triggered when orders change via the backend/plugin or API. All functions are configurable via a configuration panel in Shopware.
The module is used in the XQueue sample instance: http://dev-shop1000.maileon.com/shopware6
(Figure 1).
Commissioning name of the module
Updates
Important note: As of Shopware 6.4, a "hash" parameter is required to confirm newsletter subscribers, so as of plugin version 1.0.6, this parameter is written to the contact field 'Shopware_hash' when sending a DOI, and must be returned to Shopware with the webhook call. Details, see Figure 17.
If this value is not passed, login confirmers will NOT be marked as active in Shopware. marked.
Important note: We have received reports that after updating to 1.0.4 or 1.0.5, features like the test button and the import-all button does not work until you deactivate and reactivate the plugin. Therefore, we recommend disabling and re-enabling the plugin by default after an update.
Installation
Check requirements
The current module is constantly being developed and tested with current Shopware versions.
Important note: With the update from Shopware 6.2 to 6.3 basic mechanisms in Shopware have been changed, so there are restrictions from the plugin concerning the Shopware version:Plugin 1.0.3 is compatible with Shopware 6.0 - 6.2
Plugin 1.0.4 is compatible with Shopware 6.3 - 6.3.4
Plugin 1.0.5 is compatible with Shopware 6.3.5+ and higher
Install module
The module can be installed directly from the Shopware Store:
https://store.shopware.com/xqueu37905376689f/xqueue-maileon-newslettermanagement.html
Alternatively, the Shopware Store can also be accessed via "Extensions"→"My Extensions"→ "Shopware Account" and searched for "Maileon" (Figure 2 and Figure 3). The module must then be installed via the three dots and then activated via the corresponding button (Figure 4).
Configuration
The module can now be configured by clicking on the three dots and then the "Configuration" button - button can be configured.
General configuration
Figure 5 shows the general settings of the configuration page where the API key and a target permission must first be specified for all sales channels or each sales channel individually. The API key can be created and viewed in the Maileon account under "Settings"→"API Keys". The permission controls whether the contact is entered directly with permission (e.g. SOI) or whether a DOI/DOI+ mail should be delivered.
API Key:
The API Key can be created and viewed in the Maileon account under "Settings" → "API Keys" and ensures the connection to the account. The connection can be tested via the "Test" button. If the API key is checked successfully, the message "Connection was tested successfully" is displayed. If the test is not successful the API key should be checked. Common errors:
Validity period exceeded
Key was deactivated in Maileon
Characters were truncated at the beginning or end
Permissions:
None: No permission. The contact will not receive newsletters.
Single Opt-in: Permission was simply granted, e.g. by entering an email address in a form. This method technically allows the contact to receive newsletters, but does not ensure that the email address belongs to the person who entered it.
Double Opt-in: With this permission, a confirmation email with a confirmation link is sent to the email address. Only when the link in the mail has been clicked and thus the interest in the entry has been confirmed, the contact can be sent.
Double Opt-in Plus: Double opt-in including consent for single user tracking. Please note: Without individual user tracking, no openings, clicks, etc. may be traced back to individual users and significant data for evaluating newsletter performance is missing. newsletter performance is missing.
DOI Key:
Here you can define a DOI mailing key that determines which DOI mailing should be triggered as soon as a guest or customer registers for the newsletter. The key can be configured or read out in Maileon for the corresponding DOI mailing in the basic settings.
Webhook Token:
A randomly generated secret string used to identify the calls to the webhooks from Maileon. There is one webhook for DOI confirmations and one for unsubscribes so that these changes can be applied to Shopware immediately. Further setup of the webhooks is shown in chapter "Settings to be made in Maileon".
Send DOI mails from Maileon:
Here you can specify whether the DOI mails are sent from Maileon or not. Recommended setting: yes.
IMPORTANT: The item does NOT suppress the DOI mails from Shopware. The DOI mail dispatch from Shopware itself can be disabled under "Settings → Business Events" via the newsletter.register entry.
When registering a registered customer:
When a store customer registers in his customer profile via the check mark it can be selected whether he is created directly with the target permission or whether a DOI process should be started.
Behavior in case of a change of the email address in Shopware:
If a contact registered to the newsletter changes his email address in the store, then three scenarios are possible:
The email address of the store customer is logically detached from the newsletter registration. Nothing else happens and the newsletters are still sent to the (verified) old email address.
The email address of the contact in Maileon is updated and the permission is kept. Here the customer must clarify with his data protection officer whether the granted permission also applies to a new e-mail address. This could be the case, for example, if the store does not change the e-mail address until it has been verified that the registered customer is also authorized to do so.
The contact's email address in Maileon is updated and the permission is reset. This triggers a new DOI process.
Resend DOI mail if the subscriber has already subscribed:
If you enable this option, the DOI mail will send again for subscribers who have already subscribed(confirmed) and want to subscribe again on the subscription form. The option "Send DOI from Maileon" must be enabled, otherwise this option does nothing.
Maileon API Timeout:
With this field timeout for unsuccessful calls can be selected between 5 and 30 seconds.
Custom Contact fields:
If custom fields are submitted for the subscription form, they will be included in Maileon. If multiple fields, separate them with semicolons. For example:
customField1;customField2;customField3
If a field is not found in the form data, it will be ignored. If the field does not exist in Maileon, the plugin will create it.
More info about add custom fields to Shopware NL form: Custom fields to NL Form Plugin
Transaction mail settings (general and order confirmations)
The following points concern the settings for transaction mails (Figure 6). It should be noted that transactions are created automatically the first time they are used. If a mailing for an order confirmation is to be created, the menu item must therefore first be activated (clear cache afterwards!), then an order can be placed. In Maileon a transaction type is created as confirmation on the basis of which the mailing can be created.
Maileon API key for transactions:
Transactions can be sent via another Maileon account to avoid permission issues. If the field is empty, the regular API key will be used.
Send order confirmation emails via Maileon:
This is where order information is sent to Maileon. This does not prevent Shopware from sending order confirmation mails, it only transfers the data to Maileon which can be used for filtering contacts for example. If order confirmation emails are to be triggered from Maileon, appropriate trigger emails must be designed and activated. Then you can deactivate the order confirmation mails from Shopware, as described in chapter "Configure Shopware system mails".
Transaction types:
shopware_order_confirmation_customer_1.0
shopware_order_confirmation_guest_1.0
shopware_ordered_products_1.0
Send account confirmation mails via Maileon:
Mails related to account creation and management.
Note: depending on whether DOI is enabled for account creation in Shopware, an email with confirmation link will be sent first (shopware account confirmation) otherwise the confirmation will be sent immediately and the account will be activated.
Transaction types:
shopware_account_change_email
shopware_account_confirmation
shopware_account_creation
Send password reset mails via Maileon:
This option allows sending mails with a password change link via Maileon.
Transaction type:
shopware_password_reset
shopware_password_reset_confirmation
Send order and payment status changes via Maileon:
This option allows sending appropriate notification via Maileon in case of order status, payment status or single item status changes.
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
Set up separate permission for buyers:
If customers should be automatically added to the newsletter after a purchase, this can be activated here. Buyers will then be added to Maileon, unless they have explicitly unsubscribed before or already have a permission. The type of permission can be configured in the next point. Before activating, the company's data protection officer should be consulted, as there may be different views of the legal situation here.
Buyer Permission:
Here you can specify the permission that will be automatically assigned to buyers.
Product properties to custom fields
As of version 1.1.2, there is an option to transfer product properties as custom fields in Maileon (Figure 7).
Here you can select the attributes that are to be transferred to Maileon when an order is placed. If a product has several values for an attribute, all values will be transferred. The values are separated by the separator "|". A "rolling approach" is used for the values, which means that the new attributes are always placed at the beginning of the contact field, and duplicates are removed. If the entry becomes longer than 255 characters, the oldest values at the end of the list would be removed (Figure 8).
The fields in Maileon are created with the prefix "shopware_".
Product properties to order confirm product transactions
As of version 1.1.2, there is an option to transfer product properties as transaction variables for order transactions (Figure 9).
Similar to the attribute values in contact fields, these values are also separated by the "|" separator.
For regular order confirmation transactions, the values are simply added as new attributes to the product information.
For single transactions for products, on the other hand, mapping must be performed by an additional step, since here the information is at the top information level and Maileon requires a fixed structure of the data here. Here, a mapping must be set under "Marketing"→ "Maileon Plugin". Up to 10 values can be transferred to Maileon (Figure 10 and result in Figure 11).
Shopping Cart Abandonment
If a customer fills a shopping cart and does not order it is possible to send a reminder. This requires regular checks for unordered shopping carts.
Compared to many other store systems, there is a special feature to note here: In Shopware, unfortunately, only the creation of a shopping cart is directly noted in the database, but not the last change. Therefore, the reminder refers to the creation time. So the waiting period should be long enough so that the customer has enough time to shop, for example 2-4h. Another peculiarity is that due to the missing date of change, it is not possible to remind again after a reminder and subsequent change. This is only possible when the customer has completely emptied the shopping cart or ordered or the shopping cart has been cleaned by Shopware at some point.
Send shopping cart abandonments to Maileon:
Transactions for shopping cart abandoners are sent to Maileon if this option is active.
After how many minutes a shopping cart should be reminded:
This setting specifies the time period in minutes after the shopping cart has been created after which it should be reminded if it has not been ordered.
Create contacts without permission:
Depending on the view of the respective data protection officer, a business relationship exists after a purchase and a contact may also be sent a newsletter. If this is desired, this option should be disabled, otherwise the contact will be created without permission.
Testing shopping cart abandoners
To test shopping cart abandoners, make sure that Shopware's task scheduler and message consumer are running. For testing, you can also do this manually by starting the following two applications:
./bin/console scheduled-task:run
./bin/console -vv messenger:consume
The -vv option outputs all consumed tasks and is only used for an overview during testing. It is not necessary for live operation.
If a shopping cart is now ordered and the time for the reminder has expired, the following entries should be visible in the consumer (Figure 13):
The transaction type "shopware_abandoned_carts_1.0" is then created in Maileon. The version number refers to the default definition 1.01. (https://maileon.com/support/shopping-cart-abandonment/)
Configure Shopware System Mails
As of Shopware 6.3, the email module of Shopware has been changed in such a way that it is not possible to deactivate system emails (such as order confirmations) through the plugin. If order confirmations are to be sent only from Maileon, it is necessary (only from Shopware 6.3, i.e. from plugin 1.0.4) to activate the function in the Maileon settings and also to remove the corresponding template in Shopware under "Settings" → "Email templates" (Figure 14). Thus, no more e-mail will be sent from Shopware.
It is recommended to save the template in case you need it again later. Example for type "Order confirmation
Subject: Order confirmation
Sender: {{ salesChannel.name }}
Text: ...
HTML: ...
As of Shopware 6.4, automatic system emails are located in Flow Builder. Find the event and then edit it. When editing, delete the action that sent the email and save it.
Initial synchronization of contacts
If required, current newsletter subscribers can also be viewed via the menu item "Marketing"→"Maileon Manager" (Figure 15) and all subscribers can be synchronized with Maileon (Figure 16).
Importing all registrants into Maileon
The first step is to select the permission that the contacts should receive when imported into Maileon. In contrast to the settings on the configuration page, a mass transfer assumes that each contact has a corresponding permission. No DOI mail is sent, but the contacts are entered directly into Maileon with the selected permission.
Clicking the "Import to Maileon" button (Figure 16) starts the process. Depending on the number of contacts, the process can take several minutes. The UI subsequently notifies about success or errors that have occurred.
Settings to be made in Maileon
To synchronize DOI confirmations and unsubscribers with Shopware, a webhook for DOI confirmations and unsubscribers can be entered in Maileon. Maileon webhooks are configured in Maileon under "Settings"→"Webhooks". If the menu item is not available, a sales partner or service representative can enable it.
DOI confirmations
A new webhook must now be added for the "DOI login confirmation" event.
To do this, the URL "https://{your-shop}/maileon/doiconfirm" and the webhook token from the settings (item 3 in the installation chapter and Figure 5) must be used.
The webhook expects three parameters:
email: The email address of the contact must be entered here.
token: For security reasons the secret code is inserted here. So that this can not be read, it is recommended to choose an SSL-encrypted connection.
hash: Since Shopware version 6.4.0, Shopware requires a specially created hash to activate a contact. This is written from plugin version 1.0.6 when sending a DOI via Maileon in the contact field "Shopware_hash" and must also be passed in the webhook to Shopware.
Unsubscriber
A new webhook must now be added for the "unsubscriber" event.
For this, the URL "https://{your-shop}/maileon/unsubscribe" and the webhook token from the settings (point 3 in the installation chapter and Figure 5) must be used.
The webhook expects two parameters:
email: The email address of the contact must be entered here.
token: For security reasons the secret code is inserted here. So that this cannot be read, it is recommended to choose a SSL-encrypted connection. choose.
Changelog
Version 1.1.6, 2023.04.27
Added functionality: Resend DOI mail if the subscriber has already subscribed and subscribe again
Version 1.1.5, 2023.03.31
Bugfix, orderconfirm categories first is empty
Version 1.1.4, 2023.03.07
Custom fields can be submitted to Maileon on the NL subscription form
Version 1.1.3, 2022.11.17
Bugifx: in some settings the DOI process restarted when DOI was confirmed
Version 1.1.2, 2022.11.09
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.1.1, 2022.05.05
Bugfix: Abandoned cart job threw Exception when customer_id was empty
Version 1.1.0, 2022.02.25
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, 2021.12.21
Fixed administration JS to work with Shopware 6.4.7
Version 1.0.9, 2021.06.10
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, 2020.08.12
Updated plugin to work with Shopware 6.3
Version 1.0.3, 2020.06.04
Added abandoned carts functionality
Improve order transaction types to standard 1.0, see
https://maileon.com/support/transactions/
Version 1.0.2 2019.05.09
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 2018.11.20
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, 2018.04.29
Initial update from Shopware 5