This document describes the setup and functions of the XQueue extension for Shopware 6 manual.
...
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: Major Shopware updates usually include changes that are not compatible with older versions. Therefore, the following list summarises which plugin versions are compatible with which Shopware versions:
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 - 6.4.7
Plugin 1.1.x is compatible with Shopware 6.4.x
Plugin 1.2.x is compatible with Shopware 6.5.x
Plugin 1.3.x is compatible with Shopware 6.5.x
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.
The plugin settings can be configured for all Sales channels or separately for each Sales channel. From the Sales channel drop-down menu, you can choose which Sales channel settings are displayed.
...
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
...
Permission
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.
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.
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.
Send language code with DOI key
...
If this option is enabled, the language code used by the subscriber will be appended to the end of the DOI key specified above, so that a language-dependent DOI mail can be sent from Maileon. Pattern: somedoikey_en-GB or somedoikey_de-DE
IMPORTANT: In Maileon, all DOI mailing completed with the code of the language used in Shopware must be created and activated. If the DOI mailing does not exist with the DOI key added to the language code, it will be resent by the plugin but without the DOI key, so the default DOI mail will be sent.
...
Set different API keys depending on language
...
For those webshops that use a Saleschannel with multiple languages and would like the data to be sent to different Maileon accounts for each language. More info:
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".
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.
Important note: This configuration setting is not available from plugin version 1.3.0, because this functionality is available from Shopware 6.5.x in the Shopware Newsletter settings. More info: https://maileon.atlassian.net/wiki/spaces/MSI/pages/2385674241/User+documentation#Settings-to-be-made-in-Maileon
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:
...
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".
...
shopware_order_confirmation_customer_1.0shopware_order_confirmation_guest_1.0shopware_ordered_products_2.0
Send account confirmation mails via Maileon
...
Mails related to account creation and management.
...
shopware_account_confirmation_1.0shopware_account_doi_registration_1.0shopware_guest_doi_order_1.0
Send password reset mails via Maileon
...
This option allows sending mails with a password change link via Maileon.
...
shopware_password_reset_1.0
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_status_changed_1.0shopware_order_delivery_status_changed_1.0shopware_order_transaction_status_changed_1.0
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).
...
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).
...
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.
Transaction:shopware_abandoned_carts_1.0
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:
...
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/)
As of version 1.2.4, you can also run the abandoned cart from the command line for testing. You can using the following commands:
...
Delete abandoned carts without references.
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.
...
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
...
subscriber 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.
...
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.
...
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.
...
At Shopware admin go to Settings → Newsletter
...
Changelog
Version 1.2.5, 2023.11.20
...