Magento 2:: Magento 2 Integration Manual (v2) – Emarsys

Magento 2 can be integrated with Emarsys using our plug-in, which does the hard work for you. It connects your store and automatically syncs customers, events and orders to Emarsys. Then you will be able to use your Magento data in Emarsys for creating smart contact segments, personalizing your messages, building event-based programs and automating retention marketing.

The plug-in also automatically installs our Web Extend data collection scripts on your Magento 2 store, which will allow you to deliver personalized product recommendations both on your website and in emails or to track revenue from your campaigns.

Here you will find all the information you need to set up and work with the Emarsys Magento 2 plug-in.

As a quick reminder, here is the onboarding video about the Magento plug-in:

Important

This plug-in is designed to work with the default Magento 2 installation settings. If your platform instance has had a lot of custom development, we cannot guarantee that it will work as intended, nor will we be able to support you should any issues arise.

Please consider the following about product recommendations:

Predict can calculate the recommendations by using the data coming from the Emarsys plug-in.
The Emarsys plug-in does not have an editor with which you can modify the recommendation widgets.
The Email Recommender is part of the Visual Content Editor. You can easily create your Email Recommender by following the instructions in Adding recommendation to your emails.
If you would like to use the Web Recommender, then you need to add the Web Recommender template to your webshop manually.

If you are using Smart Insight, then don't forget to assign the BI Administrator user role to users who need to access the Smart Insight screens.

Supported functionality, prerequisites and synchronization

Supported functionality

Currently, only the email address identifier is supported by the Emarsys Magento 2 plug-in for:
- Creating, updating and deleting contacts
- Triggering events
- Synchronizing orders

This does not apply to Web behavior tracking, which uses the email identifier that can be switched to Magento ID.

Initial import of all customer data from Magento 2 to Emarsys.
Regular update of all default and individually mapped customer data from Magento 2 to Emarsys in near real time.

Please note that the Emarsys plug-in for Magento relies on the Magento database as its primary data source, so if you change any data in Emarsys, then it will be overwritten the next time the given contact is synchronized (i.e. by adjusting the mapping) based on your Magento store's current status, except for opt-in data.

This is how opt-in data is synced between Magento 2 (opt-in field) and Emarsys (opt-in field):

- Magento: 1 (subscribed) -> Emarsys: true

- Magento: 2 (status not active) -> Emarsys: empty/NULL

- Magento: 3 (unsubscribed) -> Emarsys = empty/NULL (if the opt-in is already false in Emarsys, it will remain false and it will not change to NULL)

- Emarsys: true -> Magento: 1 (subscribed)

- Emarsys: empty -> Magento: 3 (unsubscribed)

- Emarsys: false -> Magento: 3 (unsubscribed)

Sync of contact opt-in data from Emarsys to Magento 2 in near real time.

Important: The Emarsys Magento plug-in is specifically designed for synchronizing email opt-in changes to Magento to keep this data up-to-date. This mechanism is not designed to sync a large volume of opt-in data changes from Emarsys to Magento and most probably your store will not be able to accept these changes. If this mechanism is used to update opt-in data in general from Emarsys to Magento, then it might block services provided by the plug-in and affect your Magento store's functionality. If you need to update a large volume of contact opt-in status data, please always import them in your Magento store. The Emarsys plug-in will fetch the changes in near real time and ensure your Emarsys database is up-to-date.

Data is synced from Magento to Emarsys in near real time similar to contact changes and updates.
Only the opt-in data is synced from Emarsys to Magento. This sync process only applies to contacts who exist in Magento (i.e. contacts whose Magento ID is available in Emarsys). Opt-in data is synced in near real time unless there are connection-related issues. After an opt-in change, Emarsys triggers a Magento webshop update instantly. In most cases, it takes 1-2 minutes. In case of a webshop outage or if your connection speed appears to be slow, the sync might take longer. If Emarsys cannot update the opt-in data on your end, then the following happens:

1. After a couple of retries (after a few minutes), the change request is put into the queue.

2. The change request stays in the queue for 60 minutes.

3. After 60 minutes, Emarsys initiates the update again.

4. This cycle is repeated for 24 hours (it starts when the opt-in change is received in Emarsys).

5. If Emarsys cannot update your webshop within 24 hours, then the opt-in change will be discarded.

Automated triggering of Magento e-commerce events as external events in Emarsys.
Automated upload of all product data from Magento 2 to Emarsys.
Initial upload of all existing orders from Magento 2 to Emarsys.
Regular update of order data from Magento 2 to Emarsys.
Automated installation of the Web Extend data collection scripts on your Magento 2 stores.

Prerequisites

A Magento 2 store (version 2.2.x, 2.3.x or 2.4.x) with admin access.
A fully set up and working Emarsys Marketing Platform account.
An Emarsys merchant ID.

Please consider the following:

As the plugin requires HTTPS, you must encrypt your website with a trusted SSL certificate. Connecting to unsecured sites will be rejected.
Multi-choice fields are not supported by the plug-in at this stage.
The Emarsys plug-in relies on the Magento API to establish a connection to your store. Make sure the following URL is publicly accessible on your server:

<yourdomain>/rest/V1/*

Example for an accessible site:

https://domainname.com/rest/V1/

If your initial connection attempt fails with an Invalid API Token error, check your firewall settings.

Notes

All of the above should already have been set up as part of your standard Emarsys onboarding. If you are missing any of them, please contact your Success Manager (or Implementation Consultant if your onboarding project is still ongoing).
We recommend installing the latest version of the Magento 2 plug-in when it is available on the Magento UI.
Only one Magento website can be connected to an Emarsys account. You can only connect multiple stores or store views to a single Emarsys account if there is a single Magento website with the same unique code (you can check it in the Web Site column on the Stores page). If your Magento installation consists of multiple websites (i.e. there are two or more unique codes in the Web Site column), you will need a separate Emarsys account for each.
- Please also note that you cannot select multiple Stores or Store Views through a common website when using multiple Emarsys accounts. Only one website connection is supported.
  Emarsys does not support Store or Store View-level sync.

How often is data synchronized from Magento to Emarsys?

Data is synchronized from Magento to Emarsys as follows:

The following data types are synced in real time:
- Customer data
- Order data
- Web behavior tracking
The following data type is synced every two hours:
- Product data

Emarsys may process different data types with a varying frequency (e.g. Smart Insight synchronizes the updates on a daily basis).

Installation and connecting your store to Emarsys

Installing the module

Magento 2.4.4. compatibility: Emarsys Magento 2 (v2) plug-in versions 1.16.1 and later are compatible with Magento 2.4.4. If you receive the "Invalid API token" error message when trying to connect, then navigate to Stores > Configuration > Services > OAuth > Consumer Settings > and set the Allow OAuth Access Tokens to be used as standalone Bearer tokens option to Yes.

Our Magento 2 extension is available on Packagist and can be installed with Composer. Proceed as follows:

1. On your Magento server, run the following Composer command to install the package:

$ composer require emartech/emarsys-magento2-extension

Click to copy

2. Then install the module:

$ bin/magento setup:upgrade

Click to copy

Connecting to Emarsys

Log in to the Magento admin.
Go to Stores > Configuration.
Expand the Emarsys panel on the left-hand side.
Click Connect.
Copy the connect token shown in the text area to your clipboard.
Log in to your Emarsys account.
Go to Add-ons > Magento.
Paste the connect token into the appropriate field.
Click Fetch Sites.
Select the website of your Magento 2 store.
Click Connect.

This will open the Manage your stores dialog, in which you can select the stores you would like to associate with the given Emarsys account. Here you can also add a display name for each of your stores: these will be used throughout your account to reference them.

Customers and subscribers

Are there contacts already in Emarsys?

Our Magento 2 plug-in will import your Magento customer data to Emarsys and overwrite any existing values. If you already have contacts in your Emarsys account and would like to make sure that the details of these contacts will not be lost, before using our plug-in, we recommend that you exportyour initial Emarsys contact database and import it to Magento.

Please consult Emarsys Support or the Implementation Team before performing an initial contact import, so that we can help you to protect any critical data that has been collected in Emarsys, such as opt-in status or contact details.

Important

When you enable customer sync for the first time, the plug-in will pull all your Magento customers and newsletter subscribers and push them to your Emarsys account. The UI clearly indicates the size of each category. Please note that contacts can belong to both groups in Magento and these are merged in Emarsys, therefore the total number of contacts may be smaller than the sum of these two.

We always use the email field as the external key to match your Magento customers with your Emarsys contacts.

In the Field mapping section, you can select the Magento customer attributes you want to upload to Emarsys and map each one with a field in your Emarsys contact database. To do so, click Edit Field Mapping.

If you map Magento choice fields to Emarsys fields, then these will be synchronized as text values instead of numeric IDs in Emarsys Magento 2 (v2) plug-in version 1.13.0 and later. Previously (in version 1.12.1 and earlier), such fields were synchronized as numeric IDs in Emarsys. For example:

- In version 1.12.1 and earlier: State/Province: 1 or Color: 13

- In version 1.13.0 and later: State/Province: Alabama or Color: blue

In the Field Mapping dialog, you can see a series of attributes and the mapping our plug-in recommends. You can modify these at any time, except for the predefined ID, Store ID and Accepts Marketing attributes, which are not editable.

You can also add customer attributes to the list by clicking Add Field at the bottom, and remove them by clicking .

Do not select multiple-choice or single-choice Emarsys custom fields for mapping.

If you use custom fields (i. e. customer-specific extension attribute values) in your Magento shop, then these will be displayed under Magento customer attributes in the Field Matching dialog along with your standard fields. It is important that these custom extension attribute value fields should only be matched to text fields in Emarsys.

Once you are done with the field mapping, click the switch Enable to turn on the regular upload of your Magento customers to the Emarsys contact database. This will enable you to make use of your Magento data in your marketing campaigns.

The progress of the initial upload is tracked in the Upload status pane.

Once the process has finished, all your Magento customer data will be available in your Emarsys contact database, which will be automatically updated whenever changes happen in Magento.

Notes

You have to wait until all your customers are uploaded to Emarsys before you can start uploading your Magento events, products and orders, or install our web behavior tracking scripts. This may take up to a few hours, depending on the size of your customer database. But you do not have to keep the page open until the process completes.
After the initial upload of your customer data, you will be able to modify the field mapping at any time. Note that whenever you modify the mapping, we will upload all your customer data to Emarsys again. Please take into consideration that this action will override any existing contact data in Emarsys, including opt-in data, with the values fetched from your store.

Events, personalized messages and Interactions

Events

You can make your Magento events (i.e. user interactions in your store such as customer registration, etc.) available in the Emarsys Marketing Platform and use them for:

sending transactional marketing messages
personalizing them and
building Interactions programs

Event handling in Magento 2 (v2) plug-in version 1.10.0 and later

By default, events are triggered only on the Magento side.

Here you can choose from the following options:

To make your Magento events available only on the Emarsys side, switch the Trigger external events on Emarsys side toggle.

If you activate only the Trigger external events on Emarsys side toggle, then sending transactional emails from Magento will be disabled to prevent duplicate messaging. If you would like to trigger external events only on the Emarsys side, then we recommend migrating your relevant communications from Magento to Emarsys, such as order confirmation emails, before enabling this option.

To make your Magento events available on both sides (i.e. Emarsys and Magento), then switch the Trigger events also on Magento side toggle.

If you activate this toggle, then events will be triggered on both sides (i.e. Emarsys and Magento).

Typical use cases for enabling events on both sides

You can break down testing message sending into smaller steps during migration:

1. Create and send test messages on the Emarsys side only to a test segment.

2. Manually deactivate transactional messages in Magento.

3. Activate your program in Emarsys.

You can send transactional messages from Magento and leverage events to send marketing messages from Emarsys. For example, by using such settings, an order event will trigger an order confirmation message from Magento and the same event will trigger a post-purchase marketing message from Emarsys.

Event handling in Magento 2 (v2) plug-in version 1.9.2 and earlier

In the Events section, click Enable to make your Magento events available in Emarsys.

If event triggering is enabled, sending transactional emails from Magento is automatically disabled to prevent duplicate messaging. We recommend migrating your relevant communications from Magento to Emarsys, such as order confirmation emails, before enabling this option.

Click View Event Mapping to review how individual events are mapped to Emarsys external events.

Click View Event Data to see the list of Magento attributes that are attached to each marketing event. These are available in Emarsys as well for personalization, and you can add these to your messages by using the personalization placeholders shown in the dialog.

Custom events in Emarsys

Prerequisites

You need to have Magento 2 (v2) plug-in version 1.14.0 or later and
You need to create an external event in Emarsys as described in Creating an external event.

Creating a custom event for Emarsys

You can use the built-in Magento event dispatcher to trigger a custom external event.

use Magento\Framework\Event\ManagerInterface;
use Magento\Framework\Exception\LocalizedException;


class MyClass 
{
    /**
     * @var ManagerInterface
     */
    private $eventManager;

    public function __construct(ManagerInterface $eventManager) {
        $this->eventManager = $eventManager;
    }

    public function myTrigger() {
        $id = 123456;
        $data = [
            'customerEmail' => 'customer@email.com',
            'someField'     => 'someValue',
            // ...
        ];
        $storeId = 2;

        try {
            $this->eventManager->dispatch(
                'emarsys_create_custom_event',
                [
                    'event_id'   => $id,
                    'event_data' => $data,
                    'store_id'   => $storeId,
                ]
            );
        } catch(LocalizedException $e) {
            // handle the error
        }
    }
}

Click to copy

Parameters

event_id: The ID of the External Event created in Emarsys. This is a required parameter.
event_data: The payload of the triggered event in Emarsys. It must contain the customerEmail field to identify the contact for event triggering. The event_data parameter can be either an associative array or a JSON encoded string. This is a required parameter.
store_id: It defines which Magento store view should trigger the event (you may have multiple stores or websites connected to Emarsys). The store_id parameter is optional; however, it is strongly recommended to explicitly define it if your Magento website has more than one store. If it is not defined, the observer will determine which store will trigger the event based on the context of your Magento store.

Error messages

The observer displays the error message LocalizedException if the event was not dispatched correctly.
Marketing events are not enabled for store (ID: 2): This error message indicates that event triggering is not enabled for the given store view.
customerEmail is required in event_data: This error message indicates that the required customerEmail field is missing from the event data object.
Need to specify data: [event_id, event_data]: This error message indicates that either the event_id or the event_data parameter is missing.

Personalizing your message content

As a Magento 2 user, you not only have all the data stored in Emarsys available for personalizing your messages, but you can also use content coming directly from Magento. Specifically, each Magento event that triggers an Emarsys external event has a set of information attached to it, which you can add to your emails or other messages.

For a list of variables individual Magento events pass to Emarsys, go to Add-ons > Magento 2, in the Events section click View Event Data, and select an event in the dropdown list.

To add such Magento content to your emails, copy and paste the appropriate Emarsys Scripting Language (ESL) placeholders into the body of your message. When the message is sent, the placeholder will be replaced with the respective value passed by Magento.

For example, to add the discount amount and the grand total values to your email triggered by the Magento Customer new order event you have to add the following placeholders to the HTML of your email:

{{ event.order.discount_amount }}

{{ event.order.grand_total }}

Magento events in Interactions

You can use all Magento events that are available as External events in Emarsys in Interactions. All Magento events are automatically linked to Interactions.

Besides sending Triggered Emails (with the Send email node), you can also leverage all your events and use all the available channels supported by Interactions (currently, email, SMS, Push notification and In-app) with the Magento event node.

You can set any Magento event to trigger your program and all events will be available in the Decision, Decision splitter and Wait for event nodes.

Typical use cases

Double Opt-In (DOI) confirmation and password reset.
Order confirmation: You can send various order status updates (depending on your available events) to your contacts.
Marketing:
- You can combine any event and use them in your messages.
- Events (especially the order-related ones) contain valuable pieces of information that are also available for personalization.
Password reset events indicate momentary engagement: It is also a good opportunity to send marketing messages to your contacts.
Order events: Besides sending transactional notifications, you can also use these events to trigger post-purchase messages in real time, so you do not need to wait until the predict last purchase field is updated.

Creating an Interactions program using the Magento event node

To create an Interactions program that is triggered by a Magento event, proceed as follows:

Navigate to Automation > Automation Programs, click Create Program and select Behavior-focused journeys (Interactions).
Select the trigger Magento event.

Double-click the Magento event node and select the event that will trigger your program.

Add the required nodes to your program, test and activate it when you are ready.

Products, Multi Stock Inventory and Product bundles

Products

In the Products section, click Enable to turn on regular product data upload to Emarsys.

Before enabling product data upload to Emarsys, Predict needs to be implemented on your account.

With this information at your disposal, you will be able to target specific customer segments on the basis of which products they bought, viewed or left in their shopping carts, or send them tailor-made product recommendations.

If you have a single Magento instance with different websites and these are connected to different Emarsys accounts, please note the Emarsys Magento 2 (v2) plug-in Product sync feature will include all products from all your websites with the corresponding availability status.

If you would like to use this feature, you need to use Magento 2 (v2) plug-in version 1.14.5 or later.

The availability of parent products depends on the related child products:

If at least one child product is available, then the parent product is considered available.
If all child products are unavailable, then the parent product is considered unavailable.

Notes:

Please note that Emarsys does not take into account the availability of parent products separately.
If you use custom product fields, then these will be displayed under Magento product attributes on the Field Mapping dialog. To use custom product fields, you need to have Magento 2 plug-in version 1.9.0 or later. You can check whether your newly mapped attribute is synchronized by searching for a sample product in the Management > Predict Data Sources > Product data > Product search widget. Note that it might take a few hours until the Product search widget will return an attribute that has been mapped recently.

Make sure to only match your custom product fields. The standard Emarsys product fields listed in Preparing your product data file do not need manual matching. Changing the automatic matching for the standard fields might cause issues with the product catalog synchronization.

Multi Stock Inventory

The Multi Stock Inventory collects product quantity information from different sources and updates the availability status in the Emarsys product catalog. If, for example, the quantity of a specific item is greater than 0 in at least one inventory, then the product’s status will change to available in the Emarsys product catalog.

Setting up the Multi Stock Inventory

To set up the Multi Stock Inventory in your Magento store, proceed as follows:

Log into your Magento store, then navigate to Stores > Sources.

To create different inventory sources, click the Add New Source button on the Manage Sources page.

To assign your inventory sources to a single or multiple stocks, click the Add New Stock button. In the following example, we have used a custom stock because a custom source cannot be added to the default stock.

To assign sources to a stock and modify the product quantity values, click Edit on the Products page.

The quantity of available products is displayed on the Catalog > Products page in the Salable Quantity column.

Product bundles

Product bundles are displayed in the final purchase as individual items in the specific bundle (in Web Extend and also in Smart Insight sales data). If there is a discount on the bundled products, then the price of the individual items will be reduced evenly by the webshop (not by the plug-in).

Some Web Extend events (e.g. view) do not support product bundles. For example, page views for bundled products will be shown as view for unknown product.

Orders

Notes:

If you have already uploaded sales data to your Emarsys account, do not enable this option. In this case, please contact your Success Manager first so that we can make sure that your orders will not be duplicated.
If you have recently activated the Emarsys Magento 2 (v2) plug-in, then you need to wait circa 1-3 days until you can enable order sync. Currently, Emarsys is working on an automated solution.

In the Orders section, click Enable to turn on regular order upload to Emarsys.

To enable the Order upload functionality, you must have Smart Insight implemented on your account. If Smart Insight is not yet implemented, you can technically still enable the switch and the plug-in will fetch the orders from your Magento instance. However, the sales data will get stuck and you will not be able to access it.

This information is essential for Emarsys features such as revenue reporting or product affinity models, and helps to make our smart features even smarter.

Important

When you enable order sync for the first time, the plug-in will pull the full history of your orders and push it to Emarsys.
By default, the email field will be used as the external key during contact matching in Emarsys.
The plug-in uses our sales data API to upload your orders to Emarsys. If you want to upload additional order data from a different source (such as returns, cancellations or offline data from your physical stores), you will also have to use the API. Please consult your Success Manager if you do not know how to do this.
Orders are only synced from Magento to Emarsys and Smart Insight if their state is complete in Magento, any other state will be ignored.
If you map Magento choice fields to Emarsys fields, then these will be synchronized as text values instead of numeric IDs in Emarsys Magento 2 (v2) plug-in version 1.13.0 and later. Previously (in version 1.12.1 and earlier), such fields were synchronized as numeric IDs in Emarsys. For example:
- In version 1.12.1 and earlier: State/Province: 1 or Color: 13
- In version 1.13.0 and later: State/Province: Alabama or Color: blue

Please take the following into consideration if you are using Smart Insight:

If your Magento plug-in was implemented after March 2021:
- If you upload sales data into Smart Insight via the Emarsys Magento plug-in, select the Upload via Plugin option when you configure your sales data. For more information, see Configuring your sales data.
- If you started to use the Emarsys Magento plug-in after March 10, 2021, then the Upload via Plugin option is selected in Smart Insight during the initial implementation and you don't need to upload sales sample data.
- Order data does not contain taxes when it is synchronized to Smart Insight. Emarsys changed the way sales data is processed on 10 March 2021, as a result, Emarsys synchronizes order data including all details (i.e. the price with and without tax and the delivery cost) and Smart Insight calculations use gross values. If it is required, you can set further purchase filters on the Smart Insight settings page.
- The Emarsys Magento plug-in uses exclusively the email identifier, even though the Smart Insight Self-Service tool shows that ems_user_id (i.e. internal Emarsys ID) is used for identification. The plug-in transforms email into ems_user_id during synchronization to avoid storing personal data on the data platform.
- Emarsys retrieves all available sales data attributes from your Magento store. The mandatory fields are pre-mapped and cannot be changed. You can decide which of these attributes you would like to use for further segmentation and filtering.
If your Magento plug-in was implemented before March 2021:
- This implementation does not support custom fields, only standard fields are synced via the plug-in to Emarsys. Therefore, field mapping is not available on the UI. If you would like to configure Smart Insight, then you can check the preview of your Magento sales data structure by adding sample sales data for Magento on the Product data page. If you would like to upgrade your plug-in to the new implementation described above, please contact your Client Success Manager. The following example shows you how sample sales data for Magento looks like:

item,price,order,timestamp,email,quantity,s_storename
24-MB05,45,9,2018-10-09T08:22:04Z,first@customer.com,1,english_store
24-MB99,4500,10,2018-10-09T08:22:04Z,second@customer.com,1,english_store

Click to copy

Web behavior tracking

Our Web Extend scripts track visitor interactions on your website and process this information to serve validated data to various Emarsys applications, such as Smart Insight, Predict, Interactions or the Automation Center (as Web behavior segments). The plug-in will install them automatically for you.

Click Enable to install the Web Extend data collection scripts on your Magento 2 stores.

The Health check tab

You can check the status of data synchronization between your Magento shop and Emarsys on the Add-ons menu > Magento > Health check tab.

For more information on how to test Magento and Shopify plug-ins, see Quality check of the Emarsys Magento plug-in.

Here you can check the overall synchronization status related to your contact, order and product data, and external events along with the dates of their last successful update.

The data sync status can be one of the following:

OK - It means that data is properly synchronized between your Magento shop and Emarsys.
Data sync error - It means that no data has been synchronized since the date displayed in the status message. Emarsys has not been able to retrieve contact or order updates or external events from your web shop. For more information, please check the warning or error messages listed in the History widget.
X is disabled - It means that synchronization of the specific data type between your Magento shop and Emarsys is disabled.

Here you can see warning and error messages related to data synchronization. Each row can contain multiple messages that belong to the same type and severity level (i.e. warning or error). By default, the last 10 rows are displayed.

Warning and error messages are listed along with their:

Timestamp - The date when the message was received.
Type - The data type to which the warning or error message refers. The following types are available:
- api
- Contact sync
- disconnect
- Order sync
- Product sync
Details - Detailed description of the warning or error message.
You can also search for specific words by typing them into the Search field.

Warning and error messages

The following sections describe the most common warning and error messages.

Request failed with status code {code number}

Type: api
Description: The request failed due to the issue mentioned in the error message. The status code displayed in the error message refers to HTTP error codes.

Events not iterable

Type: api
Description: Events could not be successfully processed because either an incorrect reply or no events have been received.

Shop was down

Type: api
Description: Your shop was unavailable due to maintenance or other issues. If your shop is still unavailable, then a red exclamation mark is displayed next to the Health check tab.

Shop was disconnected

Type: disconnect
Description: Your shop was disconnected due to a connect token or other related issue.

Failed to synchronize subscriber because {cause of the error}

Type: Contact sync
Description: Subscriber contact data could not be synchronized due to the issue described in the error message. Check the field name and the cause mentioned in the error message and correct your contact data accordingly.

Failed to synchronize order with ID: {cause of the error}

Type: Order sync
Description: The order with the ID mentioned in the error message could not be synchronized due to the issue described in the message. Check the order in your order data and correct it accordingly.

Product synchronization warning because “{object name}” must be a string (entity_id: , SKU: )

Type: Product sync
Description: The object with the specific entity_id and SKU mentioned in the error message is not a string. Check the entry in your product data and correct it accordingly.

Product synchronization warning because “{object name}” must be a valid uri (entity_id: , SKU: )

Type: Product sync
Description: The object with the specific entity_id and SKU mentioned in the error message does not have a valid uri value. Check the entry in your product data and correct it accordingly.

Quality check of the Emarsys Magento plug-in

You can check if your Magento plug-in works properly with the following test procedure:

Testing synchronization
Testing contact Opt-in subscription
Testing customer creation during checkout
Testing the purchase process for registered customers
Testing the Abandoned Cart automation (Tactic)

If the rest result does not meet your expectations, then proceed as follows:

1. Raise a support request including the following details:

- Your Emarsys account login name,

- The plug-in you are using (i.e. Magento 1, Magento 2),

- The name of your test segment (e.g. Magento 2 - Contact Creation Test),

- The email address or name of the product you have used during testing and

- The time when you performed the test.

2. Attach the whole test procedure (including all the steps, for example, Testing contact opt-in subscription) to the ticket.

3. Make sure you also describe if the result of a step was OK and include your additional comments related to the steps (e.g. if something did not work according to your expectations) so that we can investigate the issue you encountered carefully.

Testing synchronization

To check that synchronization is working properly without any issues and alerts, proceed as follows:

1. Go to the Management > Predict Data Sources page and check the following widgets:

a. Sales data - To check your sales Upload history, click Manage sales data in the Sales Data widget. Here you can see additional information related to your data uploads, order counts, order amounts and the source of the upload.

On this page, you should see regular uploads that correspond to the behavior of your customers and to the proportion of revenue within a specific period.

b. Product data - For more details about the product Update history, click Manage product data in the Product data widget. Ideally, here you should see that products are uploaded every hour.

If you can see that products were not uploaded for a few hours, then it could indicate an issue.

c. Web Behaviour - Here you should check the following:

Test the steps described below for both unidentified and identified site visitors.

- All warning and error messages,

You can ignore the error messages if they are only related to multiple go commands.

- The view, purchase, category, cart, setEmail or setCustomerId and go (and recommendations if applicable) are present and called on the appropriate pages in accordance with the Emarsys Data collection JavaScript API reference documentation.

- The actions you have performed on your site are displayed properly on the Live events page. You can filter your own events by selecting the fields All events and my visit on this page,

- If you have used Web Extend without the plug-in, then the original scripts should be removed. In this case, only the plug-in Web Extend scripts should be active on your website and

- The Web Extend recommend command is manually pushed on your website before the Web Behaviour tracker is called.

d. Contact Matching - Here you can see contact consistency issues when the contact data collected by the JavaScript API in your online store is inconsistent with those found in the Emarsys contact database.

Only contacts present in the Emarsys contact database can be matched and tracked by Web Extend scripts. This means that the setEmail or setCustomerID events had been received by Emarsys before the contact was created in the Emarsys contact database. There are two possible reasons for this:

- Contact creation was delayed (e.g. if there is a delay of 1-3 minutes when the customer is using Emarsys).

- The contact was not created at all.

You can solve this issue by using the API to create contacts before calling the setEmail or setCustomerID events.

2. Navigate to Add-ons > Magento, click the Health check tab and check the following:

a. In the Status widget, OK is displayed in the Contacts, Orders, Events and Products columns.

b. The timestamp under Last successful update in Contacts, Orders, Events and Products columns in the Status widget.

c. All warning or error messages in the History widget.

You can ignore warning messages related to multiple go commands because these are not relevant to the plug-in.

3. Make sure that contacts are created by manual entry (i.e. the API plug-in works properly) as follows:

a. To check that, navigate to Analytics > Registrations, click the Per Contact Source tab and set the Source of database entry to Manual registration.

b. Go to Contacts > Segments and click Create Segment.

c. Name your segment as follows: Magento - Data Flow Test - registration date.

d. Select the Date of first registration contact criteria and set it to Was in the last 2 day(s).

4. Create another segment as follows:

a. Name your segment as follows: Magento - Data Flow Test - predict last session date.

b. Select the predict last session date contact criteria and set it to Was in the last 2 day(s).

Testing contact Opt-in subscription

To check that subscription works properly, proceed as follows:

Before performing the test, make sure that the following prerequisites are fulfilled:

Magento prerequisites:

- Magento customer attributes have to be configured.

Emarsys prerequisites:

- Customer import has to be activated and

- Customer data field mapping has to be configured as described in Customers.

1. Subscribe to marketing campaigns by using your test email address.

2. Check if the contact has been created in the Emarsys contact database by searching for their email address.

3. Check if the contact's Opt-In status is True.

After subscribing to your marketing campaigns, the contact's Opt-In status must be True.

4. Create a segment as follows:

a. Go to Contacts > Segments and click Create Segment.

b. Name your segment as follows: Magento - Subscription Test.

c. Select the following fields:

- predict last session date contact criteria and set it to Was in the last 2 day(s).

- Opt-in and set it to EqualTrue.

Testing customer creation during checkout

To check that contacts are properly created during checkout, proceed as follows:

Before performing the test, make sure that the following prerequisites are fulfilled:

Magento prerequisites:

- Magento customer attributes have to be configured.

- Customer and cart events fired by Magento should be based on website activity.

Emarsys prerequisites:

- Customer import has to be activated,

- Customer data field mapping has to be configured,

- Product upload has to be activated and if you have any custom products, then product data field mapping has to be configured as well and

- Order upload has to be activated.

For more information on the Emarsys prerequisites, see Supported functionality, prerequisites and synchronization.

If order sync is activated, then guest visitors will only be created during checkout.

1. Make a test purchase as a guest with your test email address and do not check the Consent to receive marketing materials checkbox.

Notes:

Follow the web shop's guidelines on how to make test purchases (e.g. purchase a test product for €1 or $1 by using a 99% discount, etc.).
Please note that the name of the checkbox may differ.

2. Check if the contact has been created in the Emarsys contact database by searching for their email address.

3. Check if the contact's Opt-In status is empty.

4. Create a segment as follows:

a. Go to Contacts > Segments and click Create Segment.

b. Name your segment as follows: Magento - Contact Creation Test.

c. Select the following fields:

- Date of first registration and set it to Was in the last 2 day(s).

- Opt-in and choose the filter Is empty.

Testing the purchase process for registered customers

To check that the purchase process works appropriately for registered customers, proceed as follows:

This test case is only relevant for clients with the Advanced Package who are using Smart Insight.

Before performing the test, make sure that the following prerequisites are fulfilled:

Magento prerequisites:

- Magento customer attributes have to be configured.

- Customer and cart events fired by Magento should be based on the website activity.

Emarsys prerequisites:

- Customer import has to be activated,

- Customer data field mapping has to be configured,

- Product upload has to be activated and if you have any custom products, then product data field mapping has to be configured as well,

- Order upload has to be activated.

- You need to have an up and running Smart Insight implementationn.

For more information on the Emarsys prerequisites, see Supported functionality, prerequisites and synchronization.

1. Make a test purchase as a registered customer.

Follow the web shop's guidelines on how to make test purchases (e.g. purchase a test product for €1 or $1 by using a 99% discount, etc.).

2. Create a Smart Insight segment by using the corresponding filters:

a. Go to Contacts > Segments and click Create Segment.

b. Name your segment as follows: Magento - SI Test.

c. Select the corresponding filters.

For example:

- Days since last purchase 1-1

- Price 1-1

3. Check if the segment contains your test email address.

Testing the Abandoned Cart automation (Tactic)

To check if the Abandoned Cart automation (Tactic) works properly, proceed as follows:

1. Register and log in to the client's website with your test email address.

2. Create a segment that contains only your test email address as follows:

a. Go to Contacts > Segments and click Create Segment.

b. Name your segment as follows: Magento - testing mails.

c. Select the Email contact criteria, choose the operator Is Equal and specify your test email address.

3. Create an Abandoned Cart automation by choosing one of the following options:

If you are using Tactics, then select the Abandoned cart Tactic.
If you are not using Tactics, then create an Interactions program.

Make sure that the Tactic or automation program only includes the test segment that contains just your test email address.

4. Abandon a product and check the contact's Predict fields as follows:

a. Put a product in your cart and abandon it by closing the tab in your browser.

b. Check if the corresponding email is delivered the next day.

If the email has not been delivered, please describe the steps you have performed in the ticket.

c. Check the content of the email, the recommendations must be logically related to the specific product that you have abandoned.

If the content of the email is different than expected, please attach it to the ticket.

Release notes

The following table lists all the important fixes and features related to the Magento 2 (v2) plug-in extension versions.

If you synchronize order data with Smart Insight via the Magento plug-in, please note that plug-in version 1.10.1 and earlier do not support refunds which are supported from version 1.11.0 on. When updating from version 1.10.1 or earlier to 1.11.0 or newer versions, please consider reloading your sales data into Smart Insight (because the new sales data will contain refund-related information as opposed to the historical sales data). If you need further information, please raise a support ticket or contact your Client Success Manager.

Magento 2 (v2) plug-in extension version	Date	Overview of fixes and features
2.0.2	12.12.2022	Improvement: The schema installer has been replaced via the `db_schema.xml` file. Fixes: The “`($query)` cannot be empty” error has been fixed. The password reset event has been fixed so that it includes all the relevant data.
1.16.0	14.02.2022	The plug-in no longer depends on Zend URI.
1.15.0	06.10.2021	Improvement: The memory usage of batch customer sync has been reduced. Fix: Resolved an issue where product categories were not retrieved through the API.
1.14.5	08.07.2021	Fixed the status of products that are not linked to a website.
1.14.4	30.06.2021	Resolved an issue where event retrieval resulted in database slowdown.
1.14.3	08.06.2021	Resolved an issue where the product price was determined incorrectly when content staging was used.
1.14.2	13.05.2021	Resolved an issue where the product price was incorrectly displayed as zero.
1.14.1	18.11.2020	Compatibility with MySQL 8+ databases has been improved in this release. The `auto_increment` reset is properly detected even if the database schema information was cached for a longer period.
1.14.0	15.10.2020	This release enables merchants to trigger custom events from their webshop and use those in Emarsys to create campaigns or build automated programs.
1.13.0	07.09.2020	This release contains improvements related to choice fields (drop-down selectors) in Magento customer and product entities. Those field values are now mapped to the text value of the selected option instead of the numeric ID. For example: In version 1.12.1 or earlier: State/Province: 1 or Color: 13 In version 1.13.0 or later: State/Province: Alabama or Color: blue
1.12.1	13.07.2020	Resolved an issue where product price discount periods were determined incorrectly.
1.12.0	24.06.2020	Feature: Product images are retrieved and added to the product catalog from all connected store views.
1.11.0	03.06.2020	This release contains changes in order to properly handle order refunds in sales data.
1.10.1	11.05.2020	Resolved an issue where web shops located in a sub-directory of the web-root were unable to establish connections.
1.10.0	15.04.2020	Flexible event handling: Events can be triggered on Emarsys or Magento side or on both sides.
1.9.2	19.02.2020	Fixed an issue where product categories may have been tracked in the wrong order on page views.
1.9.1	13.02.2020	Fixed an issue where the default product price was retrieved when catalog price scope was set to website.
1.9.0	21.01.2020	Feature: MSI support: the plug-in retrieves quantity data from all configured sources. Fix: The process of subscriber matching has been refined.
1.8.3	17.12.2019	Fixed an issue where newsletter_subscriber entries were left in the Magento database after deleting the corresponding customer entry.
1.8.2	25.11.2019	Fixed a critical issue where customers who did not belong to the website connected to Emarsys were also included in the synchronization process.
1.8.1	14.11.2019	Fixed a critical issue where customers who did not belong to the website connected to Emarsys were also included in the synchronization process.
1.8.0	13.11.2019	Feature: The extension now supports the synchronization of product EAV fields and those custom fields can be mapped to fields in the Emarsys product catalog on the UI. Fix: Fixed an issue where view events for child products that are set to be visible individually in the catalog were submitted with wrong identifiers to Web Extend.
1.7.2	03.11.2019	The Products API endpoint might return false stock availability for products in Commerce (Enterprise) edition installations. The Web Extend implementation submitted localized category names to view events instead of the admin store category names, which prevented Predict from correctly identifying the categories. That resulted in validation errors on the Data Sources page.
1.7.1	17.10.2019	Fixed an issue due to which the customer rp_token was not included in password reset and password reminder events. This prevented correct reset links from being generated in triggered email templates.
1.7.0	02.10.2019	A new feature enables you to synchronize custom fields of the customer entity (created via EAV) from Magento to Emarsys. The additional fields in the Magento instance are listed in the Field Matching dialog on the Emarsys UI, so that they can be mapped to Emarsys fields. Extra fields are also available in data related to triggered events.

Need assistance with your Emarsys product?
We'll get you the help you need!

Magento

Supported functionality

Prerequisites

How often is data synchronized from Magento to Emarsys?

Installing the module

Connecting to Emarsys

Events

Custom events in Emarsys

Prerequisites

Creating a custom event for Emarsys

Parameters

Error messages

Personalizing your message content

Magento events in Interactions

Typical use cases

Creating an Interactions program using the Magento event node

Products

Multi Stock Inventory

Setting up the Multi Stock Inventory

Product bundles

Status widget

History widget

Warning and error messages

Request failed with status code {code number}

Events not iterable

Shop was down

Shop was disconnected

Failed to synchronize subscriber because {cause of the error}

Failed to synchronize order with ID: {cause of the error}

Product synchronization warning because “{object name}” must be a string (entity_id: , SKU: )

Product synchronization warning because “{object name}” must be a valid uri (entity_id: , SKU: )

Testing synchronization

Testing contact Opt-in subscription

Testing customer creation during checkout

Testing the purchase process for registered customers

Testing the Abandoned Cart automation (Tactic)

Need assistance with your Emarsys product? We'll get you the help you need!

Magento

Supported functionality

Prerequisites

How often is data synchronized from Magento to Emarsys?

Installing the module

Connecting to Emarsys

Events

Custom events in Emarsys

Prerequisites

Creating a custom event for Emarsys

Parameters

Error messages

Personalizing your message content

Magento events in Interactions

Typical use cases

Creating an Interactions program using the Magento event node

Products

Multi Stock Inventory

Setting up the Multi Stock Inventory

Product bundles

Status widget

History widget

Warning and error messages

Request failed with status code {code number}

Events not iterable

Shop was down

Shop was disconnected

Failed to synchronize subscriber because {cause of the error}

Failed to synchronize order with ID: {cause of the error}

Product synchronization warning because “{object name}” must be a string (entity_id: , SKU: )

Product synchronization warning because “{object name}” must be a valid uri (entity_id: , SKU: )

Testing synchronization

Testing contact Opt-in subscription

Testing customer creation during checkout

Testing the purchase process for registered customers

Testing the Abandoned Cart automation (Tactic)

Need assistance with your Emarsys product?
We'll get you the help you need!