Release notes

• From version 1.4.0 the plugin is compatible with the Shopware Plugin Store. Unfortunately, the necessary changes are not backwards compatible, so that BEFORE installing version 1.4.0 or higher, all older versions up to 1.3.9 must be uninstalled manually.

• From version 1.4.13, the "Update transaction types" function in the UI should be used so that the manufacturer number can also be transferred.

Introduction

The module synchronise synchronises customer data between Shopware and Maileon. Newsletter subscribers are synchronised from Shopware to Maileon and unsubscribes are transferred from Maileon to Shopware. Furthermore, transaction emails can be triggered via the backend/plugins or the API when orders change. All functions can be set via a configuration panel in Shopware.

The module is used in the XQueue example instance http://dev-shop1000.maileon.com/shopware/ (Figure 1).

...

Installation and preparation

Check requirements

The current module was developed and tested with version 5.5 upwards. For older versions up to version 5.2, the plugin can be used in version 1.1.0 (however, all transactional emails are missing here), unfortunately the module is not suitable for older versions.

Install module

The module can be installed in two ways:

1. From the Shopware Plugin Store (recommended)

https://store.shopware.com/xqueu90114086971f/xqueue-maileon-newslettermanagement-for-shopware-5.html

The advantage of this approach is clear: easy installation and very simple information and update options.

...

2. Install .zip package manually

Upload the zip package to Shopware 5 and install (Figure 3 and Figure 4).

...

Figure 4 shows the Plugin Manager after the module has been successfully uploaded. The module can already be configured via the red marked "Edit" button or first installed and activated via the green + symbol. Figure 5 shows the module after successful activation.

...

Configure module

The module now only needs to be configured by clicking on the "Edit" button.

...

Figure 6 shows the configuration page on which the API key and a permission must first be entered. The API key can be created and viewed in the Maileon account under "Settings" "API Keys". Since version 1.1.0, the plugin is sub/language shop-capable. In the settings, there is then a configuration for each subshop.

Send subscribers to Maileon:

If activated, subscribers to the newsletter are transferred to Maileon.

Maileon API Key:

The Maileon API key that identifies the account and access rights.

Initial permission:

None: No permission. The contact will not receive any emails.

...

Double Opt-in Plus: Double Opt-in including consent to single user tracking. (Please note: Without individual user tracking, no openings, clicks, etc. may be tracked and significant data for evaluating newsletter performance is missing.)

Enable DOI process:

If a DOI mailing is to be sent from Maileon, this option must be set to "Yes".

Enable DOI+ (single user tracking in Maileon):

If, in addition to DOI, consent for single-user tracking is also to be set after the DOI confirmation link, this option must be set to "Yes". DOI+ is the basis for many evaluations on an individual user basis.

DOI key for guests:

Here you can store a DOI mailing key that determines which DOI mailing should be triggered as soon as a guest registers for the newsletter. The key can be configured or read out in Maileon for the corresponding DOI mailing.

DOI key for registered customers:

Here you can store a DOI mailing key that determines which DOI mailing should be triggered as soon as a customer registers for the newsletter. The key can be configured or read out in Maileon for the corresponding DOI mailing.

Send transaction emails from Shopware:

Here you can specify that Shopware sends the transaction emails itself.

Send DOI mails from Shopware:

Here you can specify that Shopware sends the DOI mails itself. Recommended setting: no/nein.

Maileon API Timeout:

With this field, the timeout for unsuccessful calls can be selected between 5 and 30 seconds.

Maileon API key for transactions:

Transactions can be sent via another Maileon account to avoid permission issues. If the transactions are sent via the same account, care should be taken that they are created with SOI in Maileon. Newsletters should not be sent to contacts with SOI in this case.

The following points concern transactional emails. It should be noted that transactions are automatically created the first time they are used. So if a mailing for an order confirmation is to be created, the menu item must first be activated (clear cache afterwards!), then an order can be placed. In Maileon, a transaction type is created as a confirmation on the basis of which the mailing can be created.

Send order information to Maileon:

With this option, order information is sent to Maileon. This means that order confirmation emails can be sent from Maileon or the data can be used for segmentation or marketing automation.

...

shopware_order_confirmation_guest_1.0

Send one additional event per ordered product:

This option only applies if order information is generally transmitted to Maileon. One transaction is triggered per product so that segmentations are possible at the individual product level.

...

shopware_ordered_products_2.0

Additionally use old transaction types:

Since version 1.4.15 new transaction type is used for event per ordered product. If you want to use the old transaction type (shopware_ordered_products_1.0) enable this field.

In version 1.4.15, the old transaction types have been phased out, the following is only true for versions 1.4.14 and older:
Since version 1.3.0, new transaction types are used. To ensure that existing integrations continue to work, the old types can also be transferred in addition to the new transactions until the changeover of the mailings has been completed. This option should be set to "no" for all new customers.

Product properties send in transactions:

For products where variations are available, the variation details will be included in the order per product transaction (shopware_ordered_products_2.0). Since variations can have different properties, a separate configuration interface is needed to set which variation properties should appear in which transaction fields. If this setting is enabled, you will then need to make additional settings in Maileon Manager, see: Product properties config

Automatically add buyers to newsletter:

In some situations, it may be allowed to send interest-based advertising to buyers. With this option, buyers are transferred to Maileon. Buyers who have explicitly unsubscribed from the newsletter will be ignored.

Buyer permission:

When a contact is added through a purchase and the above option is enabled, this permission is set.

Send account confirmation mails from Maileon:

Mails related to account creation and administration.

...

shopware_account_creation

Send password reset mails from Maileon:

This option allows mails with a password change link to be sent via Maileon.

Transaction type:

shopware_password_reset

Send password reset confirmation emails from Maileon:

When enabled, a confirmation email of a password change is triggered via Maileon.

...

shopware_password_reset_confirmation

Send order and payment status emails from Maileon:

This option allows you to send a notification via Maileon when the status of the order, payment status or the status of an individual item changes.

...

shopware_payment_status_third_reminder

Send shopping cart abandonment emails:

Here you define whether forgotten shopping carts should be sent to Maileon for further processing.

shopware_abandoned_carts_1.0

Time after which a shopping cart is considered abandoned (min. 5 minutes):

Number of minutes until a shopping cart is considered abandoned. Recommended setting: 120
The time should be divisible by 5 and the CRON controller that controls the check should not run more frequently.

Send shopping cart abandonment emails to contacts without permission:

Should shopping cart abandonments also be transmitted to Maileon for contacts without newsletter consent? If yes, this option must be activated.

Custom Contact Fields:

For custom forms, the names of the errors to be passed to Maileon can be defined in a semicolon-separated list. The spelling of the names of the fields and the custom fields in Maileon must be identical, including upper and lower case.

If a field is not found in the form data, it will be ignored. If the field does not exist in Maileon, the API will return an error, which will be logged.

Advanced configuration and initial service

If required, the menu item "Marketing" - "Maileon Manager" (Figure 7) can also be used to view current newsletter subscribers and synchronise all subscribers (also from before the module was installed) with Maileon. Furthermore, the manager shows the settings for the webhooks that have to be set up in Maileon and allows the transaction types to be created manually in Maileon. Otherwise, these would only be generated the first time they are used. However, if you want to have all or individual mailings generated before testing, such as an order confirmation mail, then it is advisable to create the transaction type in advance in order to gain access to its variables in the template.

...

Import all newsletter subscriber into Maileon

In the first step, the permission that the contacts are to receive when imported into Maileon must be selected. In contrast to the settings on the configuration page, a mass transfer assumes that a corresponding permission exists for each contact. No DOI mail is sent, but the contacts are entered directly into Maileon with the selected permission.

Clicking the "Send all" button (Figure 8) starts the process. Depending on the number of contacts, the process can take several minutes. Afterwards, the UI notifies about success or errors that have occurred.

...

Configuration information for the Maileon webhooks

The configuration parameters for the Maileon webhooks are displayed here, see Figure 10 and Figure 11.

Create and update transaction types

With this option, transaction types can be created in advance in order to use them in Maileon. If there have been changes to a transaction type in a plug-in update, for example in 1.4.13, new attributes can be added to the affected transaction types via the update button.

...

Product properties config

This section is only visible if “Product properties send in transactions” is enabled in the plugin settings!

...

After configuring the above settings (in this example, the Generic String 3 transaction field is paired with the Color variant config group and the Generic String 4 transaction field is paired with the Size variant config group), the following transaction is created in Maileon for a variant product (Figure 12):

...

Transferred contact data

The plugin transfers a series of contact data to Maileon. These include, if available, e.g. first name, last name, but also the ID of the (sub-)shop from which the registration comes. This chapter contains a list of all transferred contact information.

Customised forms for registration

In addition to the usual login methods provided by Shopware, the plugin also supports customised login and logout pages. For this, it is important that the form is given a corresponding marker:

...

<input type="hidden" name="redirect" value="http://landingpageurl.de">

Settings to be made in Maileon

To synchronise DOI confirmations and unsubscribers with Shopware, a webhook can be entered in Maileon for DOI confirmations and unsubscribers. Maileon webhooks are configured in Maileon under "Settings" "Webhooks". If the menu item is not available, a sales partner or service employee can activate it.

DOI confirmations

A new webhook must now be added for the "DOI login confirmation" event. For this, the URL and the webhook ID from the "Maileon Manager" (Figure 13) must be used.

...

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

2. code (required): For security reasons, the secret code is inserted here. To prevent this code from being read, it is recommended to use an SSL-encrypted connection.

3. reg_date (required if hash param is not set and DOI process is enabled in Shopware basic settings)

4. hash (not required): Since version 1.4.4 it is possible to add a parameter 'hash'. If the parameter is not present, then the plugin works as before, but if the parameter is set, then DOI confirmers are only registered in Shopware if the hash is correct. This function is useful if several physically separated shops are to be controlled from one Maileon account. In this case, a webhook is called on each shop but only the shop to which the contact really belongs will register it.

...

Unsubscribe

A new webhook must now be added for the "Unsubscriber" event. For this, the URL and the webhook ID from the "Maileon Manager" (point 5 in the installation chapter) must be used.

...

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

2. code: For security reasons, the secret code is inserted here. To prevent this code from being read, it is recommended to use an SSL-encrypted connection.

...

Using the plugin from within other plugins

Plugins can use the Maileon plugin to register contacts. This can be the case if a separate login logic has been implemented. For this purpose, the Maileon plugin offers the service "maileon_plugin.maileon_subscribe" as of version 1.4.11. This can be registered in the own plugin and then used as follows. This can be registered in your own plugin and then used as follows:

...

namespace SwagTestPlugin\Subscriber;

use Enlight\Event\SubscriberInterface;
use xqueueMaileonShopware5\Components\MaileonSubscribe;


class RegisterCustomer implements SubscriberInterface
{
    /**
     * @var $taxCalculator TaxCalculator
     */
    private $maileonSubscribe;

    public function __construct(MaileonSubscribe $maileonSubscribe)
    {
        $this->maileonSubscribe = $maileonSubscribe;
    }

    /**
     * {@inheritdoc}
     */
    public static function getSubscribedEvents()
    {
        return [
            'Shopware_Controllers_Frontend_Register::saveRegisterAction::after' => 'afterSaveRegisterAction',
        ];
    }

    public function afterSaveRegisterAction(\Enlight_Event_EventArgs $args)
    {
        $this->maileonSubscribe->subscribeMaileon(
            'test00005@xqueue.com,
            array(
                'firstname' => 'Test',
                'lastname' => 'Contact',
                'salutation' => 'mr.',
                'street' => 'Test str. 5.',
                'zipcode' => '1122',
                'city' => 'TestCity',
                'company' => 'TestCompany',
                'birthday' => '1970-07-04',
                'customergroup_key' => '1',
                'customergroup_name' => 'test'
            )
        );
    }
}

Changelog

• Version 1.4.17, 2023.11.15

  • If the cart is abandoned, the process will not stop if the currency is not set for the cart.

• Version 1.4.16, 2023.08.29

  • Bugfix: If the "Automatically add buyers to newsletter" set to "All customers" or "Only registered" (registered customer) and the contact not exist at Maileon, the contact is not created.

• Version 1.4.15, 2023.08.03

  • Add product variant data to order confirmation and ordered product transactions.

  • Add customer group data when contact created/updated before send a transaction.

...

• Version 1.4.0, 2021.09.21

  • Updated code to be compatible with Shopware plugin store. Installing 1.4.0 requires complete uninstallation of previous versions.

• Version 1.3.9, 2021.09.17

  • Changed to composer version of Maileon PHP API client.

  • Bugfix: Handle if article model not found at order transactions.

  • Bugfix: DOI confirm webhook processes data now correctly, if captcha is enabled.

...

• Version 1.3.0, 2021.02.08

  • Change permission logic (added explicit initial permission and DOI, DOI+ process).

  • Add extended order transaction types (v1.0).
    BE AWARE: This update creates new transaction types. Mails bound to the old type WILL NOT be sent anymore. Make sure to first create the types, e.g. from a staging system, create the mails and then install this update on your live system.

  • Add functionality to create all transaction types at Maileon by clicking one button in the Shopware settings.

...