This document describes the setup and functions of the XQueue extension for Shopware 6 manual.

Version: 1.3.0

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).

Open

Figure 1: Example instance of Shopware

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).

Open

Figure 2: Installation of the module

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:

1. Validity period exceeded

2. Key was deactivated in Maileon

3. 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: https://maileon.atlassian.net/wiki/spaces/MSI/pages/2385674241/User+documentation#Set-different-API-keys-depending-on-language.1

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:

1. 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.

2. 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.

3. 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: https://maileon.atlassian.net/wiki/spaces/MSI/pages/2389442561

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_2.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_confirmation_1.0

• shopware_account_doi_registration_1.0

• shopware_guest_doi_order_1.0

Send password reset mails via Maileon

This option allows sending mails with a password change link via Maileon.

Transaction type:

• 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.0

• shopware_order_delivery_status_changed_1.0

• shopware_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).

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.

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:

1. ./bin/console scheduled-task:run

2. ./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/)

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:

Mark abandoned carts

./bin/console xqueue-maileon:abandoned-cart:mark

Use this command to search for abandoned carts in the carts table. If the command finds an abandoned basket it will save it in a separate table.

Send abandoned carts

./bin/console xqueue-maileon:abandoned-cart:send

Sends the details of the abandoned basket to Maileon.

Delete abandoned carts

./bin/console xqueue-maileon:abandoned-cart:delete

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.

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 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.

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.

Create transaction types before using

In case you are using a Maileon account and you want to pre-configure your transaction letters, you can create transaction types in Maileon. From the drop-down list, select the transaction type you want and click on the button to create the transaction type in Maileon.

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:

1. email: The email address of the contact must be entered here.

2. 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.

3. 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:

1. email: The email address of the contact must be entered here.

2. 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.

Double opt-in for registered customers

From version 6.5 of Shopware onwards, it is possible to configure in the Shopware settings whether registered customers should go through a DOI (double opt-in) process or become subscribers immediately. In older versions of Shopware, registered customers were instantly subscribed, so the plugin was developed to enable the setup of a double opt-in process for them.

It is important that these settings are synchronized with the plugin configurations. Therefore, if the DOI (double opt-in) process is globally disabled here, it should also be disabled in the plugin settings.

At Shopware admin go to Settings → Newsletter

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.

As a first step, we need to enable the 'Set different API keys depending on language' setting in the plugin configuration. After that, a form becomes available where we can enter the API keys; to access this, navigate to Marketing -> Maileon Plugin menu (Figure 21). Here, you will see a section titled 'Set different API keys depending on language.' In this form, the languages that are assigned to at least one Saleschannel will be displayed. In the text field next to each language, you can enter the API keys. It is not mandatory to fill in every field. If there is no API key assigned to a particular language, the plugin will use the default API key specified in the first field of the plugin settings. Clicking the save button, the plugin checks the validity of the provided API keys, and if everything is in order, it saves them.

In the case of an abandoned cart, Shopware does not store the language in the cart entity, so the plugin will consider the language stored with the customer.

Changelog

Version 1.3.0, 2024.01.26

• Add functionality to set different Maileon API keys depending on languages

• Newsletter form can handle Maileon standard fields at subscribe

Version 1.2.5, 2023.11.20

• Fix: If order line item is not a product, skip get the product url

Version 1.2.4, 2023.07.19

• Improve abandoned cart functionality

Version 1.2.3, 2023.07.11

• Change order state name to order state technical name

Version 1.2.2, 2023.06.29

• Added new functionality: Send language code with DOI key

• Added a button to Maileon Plugin page, to create transaction types at Maileon

Version 1.2.1, 2023.05.22

• Bugfix, also filters for language when generating product url

Version 1.2.0, 2023.05.16

• Make the plugin compatible with Shopware 6.5.x

• Improve API key test

Version 1.1.9, 2023.07.19

• Improve abandoned cart functionality

Version 1.1.8, 2023.07.11

• Bugfix, also filters for language when generating product url

• Change order state name to order state technical name

Version 1.1.7, 2023.06.29

• Added new functionality: Send language code with DOI key

• Added a button to Maileon Plugin page, to create transaction types at Maileon

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
  

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