Table of Contents

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 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/ (Illustration 1).

...

Commissioning name of the module

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:

Recommended: About the Shopware Plugin Store

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 (Illustration 2).

...

Via "Settings" "Plugin Manager" "Installed" "Upload Plugin" can be added to Shopware (Illustration 3 and Illustration 4).

...

Image Added

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

...

Configure module

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

...

Illustration 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, as can be seen in Illustration 6.

Transfer newsletter 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 advertising permission:

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

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 emails, 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 email has been clicked and thus the interest in the entry has been confirmed, can the contact be sent.

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.

Activate DOI process:

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

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

Transaction types:

shopware_order_confirmation_cash_in_advanced_1.0

shopware_order_confirmation_customer_1.0

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.

Transaction types:

shopware_ordered_products_1.0

Additionally use old transaction types:

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.

Automatically add buyers to newsletter recipients:

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.

Advertising permission for buyers:

When a contact is added through a purchase, this permission is set.

Send account confirmation mails from Maileon:

Mails related to account creation and administration.

Note: depending on whether DOI is activated for account creation in Shopware, an email with a confirmation link is sent first (shopware account confirmation), otherwise the confirmation is sent immediately and the account is activated.

Transaction types:

shopware_account_change_email

shopware_account_confirmation

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.

Transaction type:

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

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 consent:

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" (Illustration 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 applicants 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 (Illustration 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 Illustration 10 and Illustration 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.

...

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.

Contact field

FIRSTNAME

LASTNAME

SALUTATION

ADDRESS

ZIP

CITY

ORGANIZATION

BIRTHDAY

Shopware_NL	Custom field with boolean value true (=registration came from Shopware)
Customergroup_key	The ID of the Shopware group to which the contact belongs.
Customergroup_name	The name of the Shopware group to which the contact belongs
shopware_store_id	The ID of the (sub-)shop from which a contact originates.
Shopware_url	The URL from which a contact was created
Shopware_hash	The hash value used for identification in the DOI process.

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:

If the value 1 is set here as "value", it is a registration form. If the value is -1, it is a deregistration form (the entered e-mail address would be deregistered).

Currently, only the following form values are transmitted (name of the inputs):

email
firstname
lastname
salutation

Furthermore, custom fields can be inserted into the form and transmitted to Maileon. However, this requires an entry in the configuration (last point, Illustration 6).

Finally, a forwarding in case of success can be set up by inserting a hidden form field with the name "redirect":

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" (Illustration 10) must be used.

The webhook expects four parameters:

email (required): The email address of the contact must be entered here.
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.
reg_date (required if hash param is not set and DOI process is enabled in Shopware basic settings)
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.

The webhook expects two parameters:

email: The email address of the contact must be entered here.
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:

services.xml:

Code Block

language	xml

<services>

	<service id="swag_test_plugin.subscriber.register_customer" class="SwagTestPlugin\Subscriber\RegisterCustomer">

		<argument type="service" id="maileon_plugin.maileon_subscribe"/>

		<tag name="shopware.event_subscriber"/>

	</service>

</services>

Implementing class (registered above as "SwagTest\Subscriber\RegisterCustomer")

Code Block

language	php

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.13, 19.05.2023
- Contact event update functionality added
- Manufacturer number added to order contact events
  - If the new attribute is to be used, the contact event must be updated manually

Version 1.4.12
- Bugfix: If Captcha is activated when registering for a newsletter and is entered incorrectly, the contact is no longer registered with Maileon.

Version 1.4.11, 31.05.2022
- Added a service that allows other plugins to use the login and logout functions of the plugin.

Version 1.4.10, 17.05.2022
- Added transfer of customer data when a logged in customer registers for the newsletter in the order process.

Version 1.4.9, 29.04.2022
- Use of MediaServiceInterface instead of the class MediaService for better extensibility when analysing cancelled shopping carts and status changes of orders

Version 1.4.8, 11.04.2022
- Customers can register for the newsletter when ordering
- Automatic registration of buyers is now only related to the corresponding option and no longer to whether order confirmation transmission has been activated or not

Version 1.4.7, 25.02.2022
- Product SKUs added as comma separated list to order confirmation transactions
- The previous extended order information (information about products, there was one transaction type per customer) was reduced to one transaction type
- Product URL was added to the shopping cart abandonment transactions

Version 1.4.6, 03.02.2022
- Bugfix: Processing of permissions "NONE" and "OTHER" when importing all contacts from Shopware to Maileon
- Option to overwrite permissions when importing all contacts from Shopware to Maileon

Version 1.4.5, 06.12.2021
- Contacts can be added directly to the distribution list during order confirmation. It is possible to add a separate permission for all customers or only for registered customers.

Version 1.4.4, 17.11.2021
- Added optional parameter 'hash' to DOI confirmation webhook to identify if a reported contact belongs to this very Shopware instance.
- Added customfields Shopware_url and Shopware_hash

Version 1.4.3, 28.10.2021
- Bugfix: As of Shopware 5.7.0 administrators were logged out, who called the Maileon Manager in the Marketing menu in the backend.

Version 1.4.2, 19.10.2021
- When subscribing to the newsletter, if the subscriber already exists at Maileon and has a valid authorisation, the OptIn is entered directly in Shopware.

Version 1.4.1, 28.09.2021
- Updating and translating of configuration
- Added API test button

Version 1.4.0, 21.09.2021
- Updated code to be compatible with Shopware plugin store. Installing 1.4.0 requires complete uninstallation of previous versions

Version 1.3.9, 17.09.2021
- 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.8, 03.09.2021
- Updated Maileon PHP API client library
- Add functionality to add separate Maileon permission for buyers

Version 1.3.7, 02.08.2021
- Fix redirect when newsletter subscribe form uses captcha

Version 1.3.6, 23.06.2021
- Updated deprecated log methods

Version 1.3.5, 21.06.2021
- Added Birthday to standard contact field sync
- Added order confirmation transaction data: order.brands and order.categories will now be filled
- Fixed problem when contacts were not registered with Maileon when an invalid custom field mapping was configured

Version 1.3.4, 17.03.2021
- Add DOI confirmation date to DOI confirmation webhook

Version 1.3.3, 17.03.2021
- Fixed bug with abandoned carts and multiple subshops
- Newsletter subscribe validation update

Version 1.3.2, 24.02.2021
- Order transaction type attributes updates
- Split DOI and transaction mails switch at config
- Add enable/disable functionality to send subscribers to Maileon

Version 1.3.1, 12.02.2021
- Old transaction types are available in addition (backwards compatibility)
- Fixed “Get Shopware version” bug that prevented e.g. password reminder mails from being sent in some Shopware versions
- Fixed bug with subshop configs bug

Version 1.3.0, 08.02.2021
- 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

Version 1.2.8, 27.01.2021
- Fixed problem with abandoned carts not being sent to contacts without permission

Version 1.2.7, 12.01.2021
- Fixed popup not showing up when changing order states from open to “in process”

Version 1.2.6, 21.12.2020
- Fixed problem with invalid password reset links in versions below Shopware 5.4.5

Version 1.2.5, 03.11.2020
- Custom fields submit at Newsletter subscribe form and redirect after submit

Version 1.2.4, 11.08.2020
- Added custom field shopware_store_id for subscribers
- Added abandoned carts transactions
- Updated plugin backend structure

Version 1.2.3, 13.05.2019
- Subscriber sync add customergroup key and name

Version 1.2.2, 13.05.2019
- Transactions float format change

Version 1.2.1, 05.03.2019
- Order and payment status transactions extended

Version 1.2.0, 01.03.2019
- Added order and payment status transactions to Maileon

Version 1.1.0, 30.05.2018
- Plugin handle for subshops and language shops

Version 1.0.10, 08.03.2018
- Bugfix “empty unsubscribe”

Version 1.0.9
- Config extend set Maileon API timeout value

Version 1.0.8, 07.02.2018
- Config extend disable Shopware mails;Doi confirmation bugfix

Version 1.0.7
- Plugin view js loader disable

Version 1.0.6, 27.11.2017
- Bugfix at Maileon api client (trim doikey)

Version 1.0.5, 09.08.2017
- Required min version change

Version 1.0.4
- Bugfix Shopware mails

Version 1.0.0
- Subscribers sync; Alle Subscriber sync

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

Release notes

Introduction

Commissioning name of the module

Check requirements

Install module

Recommended: About the Shopware Plugin Store

Via "Settings" "Plugin Manager" "Installed" "Upload Plugin" can be added to Shopware (Illustration 3 and Illustration 4).

Configure module

Transfer newsletter subscribers to Maileon:

Maileon API Key:

Initial advertising permission:

Activate DOI process:

Activate DOI+ (single user tracking in Maileon):

DOI key for guests:

DOI key for registered customers:

Send transaction emails from Shopware:

Send DOI mails from Shopware:

Maileon API Timeout:

Maileon API key for transactions:

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.

Send one additional event per ordered product:

Additionally use old transaction types:

Automatically add buyers to newsletter recipients:

Advertising permission for buyers:

Send account confirmation mails from Maileon:

Send password reset mails from Maileon:

Send password reset confirmation emails from Maileon:

Send order and payment status emails from Maileon:

Send shopping cart abandonment emails:

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

Send shopping cart abandonment emails to contacts without consent:

Custom Contact Fields:

Advanced configuration and initial service

Import all applicants into Maileon

Configuration information for the Maileon webhooks

Create and update transaction types

Transferred contact data

Customised forms for registration

Settings to be made in Maileon

DOI confirmations

Unsubscribe

Using the plugin from within other plugins

Changelog