EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual...

37
Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained. For the latest version of this manual, please visit our online help portal: https://help.emarsys.com/hc/en-us/articles/115003673625-Magento-2-Integration-Manual

Transcript of EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual...

Page 1: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 1

EMARSYS FOR MAGENTO 2

Integration Manual

July 2017

Important Note: This PDF was uploaded in July, 2017 and will not be maintained. For the latest version of this

manual, please visit our online help portal:

https://help.emarsys.com/hc/en-us/articles/115003673625-Magento-2-Integration-Manual

Page 2: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 2

CONTENTS

Introduction...................................................................................................................... 4

1 Prerequisites .................................................................................................... 4

1.1 Magento 2 requirements ................................................................................ 4

1.2 Emarsys requirements..................................................................................... 4

2 Installing the integration .................................................................................. 6

2.1 Install the Emarsys module.............................................................................. 6

2.2 Check the installation ...................................................................................... 6

2.3 Enable web behavior data collection ............................................................... 7

2.4 Enable product recommendations ................................................................. 8

3 Contact data .................................................................................................... 9

3.1 Preparing your contact data ............................................................................ 9

3.1.1 Enable the integration and configure the API settings ............................... 9

3.1.2 Configure the WebDAV connection................................................................ 10

3.1.3 Customer Mapping ........................................................................................ 10

3.1.4 Prepare the Emarsys auto-import ................................................................. 12

3.2 The initial contact data load .......................................................................... 13

3.2.1 Define the opt-in settings ............................................................................... 13

3.2.2 Perform the initial data load........................................................................... 14

3.3 Synchronizing contact data ........................................................................... 14

4 Product data .................................................................................................. 17

4.1 Preparing your product data .......................................................................... 17

4.1.1 Configure the SFTP connection ...................................................................... 17

4.1.2 Product Mapping ........................................................................................... 17

4.1.3 Configure the Feed Export ............................................................................. 18

4.2 The initial product catalog load ..................................................................... 20

4.3 Synchronizing your product catalog.............................................................. 20

5 Order data ...................................................................................................... 21

5.1 Preparing your order data .............................................................................. 21

5.2 The initial order data load ............................................................................ 21

5.3 Synchronizing order data .............................................................................. 22

6 Configuring your transactional messages ..................................................... 24

6.1 Prepare your Emarsys campaigns .................................................................. 24

6.2 Personalizing your message content ....................................................................... 24

6.3 Define your opt-in strategy ............................................................................. 25

6.3.1 Single opt-in .................................................................................................... 25

6.3.2 Double opt-in .................................................................................................. 26

6.3.3 The double opt-in confirmation link ......................................................................... 26

Page 3: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 3

6.4 Map the events .............................................................................................. 27

6.4.1 Available Magento events .............................................................................. 27

6.5 Map the placeholders .................................................................................... 29

6.6 Enable transactional emails ........................................................................... 29

6.7 Check the JSON ............................................................................................... 30

7 Testing the integration ..................................................................................... 32

8 Maintaining the integration .......................................................................... 33

8.1 Data monitoring in Emarsys ........................................................................ 33

8.2 Keeping your Magento schema updated ...................................................... 33

8.3 Making a bulk export ..................................................................................... 34

9 Logs ................................................................................................................ 35

10 Support .......................................................................................................... 37

Page 4: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 4

INTRODUCTION

Here you can find all the information you need to set up and work with the Emarsys for Magento 2

integration. Some steps are only relevant to users of Smart Insight or Predict and are clearly marked.

1 PREREQUISITES

1.1 Magento 2 requirements

From Magento you will need:

A Magento store of version 2.1.x or higher.

PHP versions 5.6.0 and 7.0.17.

php5-curl must be installed on your Magento server.

PHP SOAP extension must be enabled.

TCP port 21, 32000-35000 must be open.

Set your Magento crons to run every 1 minute.

Make sure your server’s PHP memory limit is set to a minimum of 512 MB. This is because some extension jobs are large and require increased PHP memory.

Make sure that the following path is excluded from any caching mechanism you are using: app/code/Emarsys/Emarsys/view/frontend/templates/emarsys/ javascripttracking.phtml. This is where the dynamic data collection scripts will reside and caching will break their operation.

AOE Scheduler (or similar) is not mandatory but highly recommended as this exposes the scheduled tasks visually and will help us to support you.

1.2 Emarsys requirements

From Emarsys you will need:

A fully set up and working Emarsys Marketing Cloud account.

Your Emarsys merchant ID.

An Emarsys WebDAV folder and credentials (for the initial contact data upload and bulk exports).

Emarsys API credentials (for ongoing contact data synchronization).

An Emarsys SFTP folder and credentials (Smart Insight and Predict customers only).

Emarsys

account.

Page 5: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 5

The .zip file containing the installation package (available from Emarsys Support). In addition to these, you will need to create the following in your Emarsys account:

An external event and mail stream for each one of your mapped Magento events (see below).

All the custom data fields that you need to map to Magento Customer fields.

Custom fields of the type Short Text field (max. 60 characters) with the following names:

Magento Customer ID

Magento Customer Unique ID

Magento Subscriber ID

Page 6: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 6

2 INSTALLING THE INTEGRATION

2.1 Install the Emarsys module

In order to install the Emarsys module in Magento 2, proceed as follows:

1. Unzip the installation package and copy the app/code/Emarsys folder into your app/ code directory in

Magento.

2. Open a command line, open the project root folder and run the following command to install the

WebDAV dependency: composer require sabre/dav ~3.2.0.

3. In the same folder, then run the command: composer Update.

4. In the Magento marketplace, enter your Magento authentication keys (both public and private).

Instructions for this can be found here.

5. Now install the Emarsys module with the command: php bin/magento setup:upgrade.

6. Then deploy the rest of the required files (js and other static files) to the pub folder with the command:

php bin/magento setup:static-content:deploy.

7. Update the permissions for the var and pub folders with the command: sudo chmod 777 -R var pub.

8. Finally clear the cache with the command: php bin/magento cache:flush.

2.2 Check the installation

Once you have run the commands as described above you can check the status of your Magento system

before you proceed. You can do this via the new Emarsys menu available in your Magento backend.

Page 7: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 7

Go to the Emarsys menu, Operations, Installation Checklist. Here you can see the status of your installation.

System Requirements - Checks that the Magento prerequisites have been met.

Extension Settings - At first these will show the default values set by the installation package. You

will configure those to your own specifications later in the installation workflow.

Mandatory Emarsys Customer Fields - Shows Yes if the fields have been found and mapped by the

extension during the installation. If not, you will be able to create them in Emarsys directly from the checklist.

2.3 Enable web behavior data collection

As part of the integration package, the Emarsys data collection scripts will be installed on your Magento

site. These track a variety of browse and purchase activity. For more information on these JavaScript

commands and where they are installed, see:

Data Collection JavaScript API Reference

For all Emarsys users, they provide the values for the standard set of behavior fields.

Page 8: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 8

To enable these scripts, go to the Emarsys menu, Settings, Web Extend.

Merchant ID - Your Emarsys merchant ID.

Enable Web Extend JavaScript Integration - Set this to Yes.

2.4 Enable product recommendations

If you are a Predict customer, you can also define which widgets will be used to display the product

recommendations on your various web pages.

To do this, go to the Emarsys menu, Settings, Predict.

For every page type, select the widget you want installed there. For more information, see:

The Predict Web Recommender

Page 9: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 9

3 CONTACT DATA

You will need to ensure that your Magento contacts (customers and subscribers) are correctly

synchronized with your Emarsys contact database, and that you have the right fields mapped for your

segmentation requirements. This is done in three steps.

3.1 Preparing your contact data

The initial contact data load is performed via your Emarsys WebDAV folder. After that, contact data is kept

synchronized via the API, with the WebDAV used for bulk exports and as a failsafe backup.

3.1.1 Enable the integration and configure the API settings

In the Magento backend, go to the Emarsys menu, Settings, Connection to bring up the Emarsys Settings

screen.

Select Yes in the first field to enable the integration.

Enter your API credentials.

Click Test Connection to verify everything is working. If the connection is working, the button turns

green:

, otherwise it will turn red:

Page 10: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 10

Click Save Config when you are done.

3.1.2 Configure the WebDAV connection

In the same screen, configure your WebDAV settings.

Enter your WebDAV credentials.

Click Test Connection to verify everything is working. If the connection is working, the button turns

green, otherwise it will turn red.

Click Save Config again when you are done.

3.1.3 Customer Mapping

Magento 2.0 no longer requires both customers and subscribers to have their data fields mapped

separately. Instead, you first map all the contact data fields and then you map the values for the single-

and multi-choice fields. The mapping that you define here will be used for both the initial data load and all

subsequent synchronization, for both types of contact. Proceed as follows:

First, go to the Emarsys menu and select Mappings, Customer.

On the Emarsys - Customer Mapping page open the Select Mapping drop-down and select Customer.

Page 11: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 11

Click Update Schema to load the Emarsys fields to the Emarsys Customer Attributes column.

In the Magento Customer Attribute table, select the appropriate Emarsys field for each entry.

When you are done, save your changes and select Customer-Field from the Select Mapping drop-

down.

All the single-and multi-choice fields that have been mapped are shown and you must now map the values for each one.

Page 12: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 12

3.1.4 Prepare the Emarsys auto-import

Once you have mapped all your fields, you will need to set up two auto-imports in your Emarsys account,

one for Magento customers and one for subscribers. You must set this up as follows:

Source File Settings (the first page of the wizard)

Where to look for the import file - Select Emarsys WebDAV and enter the path.

Import file settings / File name - The Magento initial load files will be named

customers_<timestamp>_default.csv and subscribers_<timestamp>_default.csv, so you should enter customers_*_default.csv and subscribers_*_default.csv for your two auto- import profiles.

Sample File (second page)

You will need to upload a sample file containing the header and at least one line of the file you will use for your initial load, with all your mapped fields. You may have this from your staging system, otherwise you can make an initial export to the WebDAV and use that file.

Match Fields (third page)

Check that the fields are correctly mapped and select your unique identifier.

When you have finished, make sure that the status is set to Enabled on the Auto-imports on the overview

page!

Page 13: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 13

3.2 The initial contact data load

Once you have prepared your customer data as described above, you can perform the initial data load to

import all your Magento customers and subscribers to Emarsys.

3.2.1 Define the opt-in settings

Before you perform the initial customer data load, you must define how the opt-in settings will be defined in

Emarsys. Proceed as follows:

Go to the Emarsys menu, Settings, Contact Synchronization.

In the Initial DB Load section and select the opt-in status to apply, choosing from:

Set opt-in status for all users to true - Enables Emarsys to send to all imported contacts straight

away.

Set opt-in status for all users to empty - You cannot send to any contacts from Emarsys until their

opt-in has been confirmed by another method (i.e. double opt-in).

Set opt-in status true for all users depending on attribute - The opt-in value is contained for each

contact in a mapped database field.

Page 14: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 14

3.2.2 Perform the initial data load

When you have set your opt-in status, and click Export on the Initial DB Load page to trigger the initial data load.

3.3 Synchronizing contact data

Once the initial data load has been performed, you will need to define the settings for the ongoing

synchronization of new data.

To configure your synchronization settings, go the Emarsys menu, Settings, Contact Synchronization.

Do not save any Contact Synchronization Settings before you make the initial upload,

Page 15: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 15

There are two methods for keeping contact data synchronized, Realtime-failsafe and Background.

Realtime-failsafe (recommended)

This maintains contact synchronization in real time, sending every update to Emarsys as it occurs in

Magento. This option is suitable for use cases where Emarsys needs the data immediately (e.g. for

automated engagement programs). In case of unsuccessful updates (e.g. due to network downtime or

excessive volume), they are placed in a failsafe queue and are processed once a day at the specified

Background Runtime (see below).

To enable this option, set Realtime-failsafe to Yes.

Background only

This collects all contact updates that have occurred over 24 hours and synchronizes them together at the

specified Background Runtime. This option is suitable when there is no urgency for the data to be

transferred to Emarsys, and there is no limit to the volume of data being synchronized.

To enable this option, set Realtime-failsafe to No.

Background Runtime

Here you enter the time of day (in HH:MM:SS) when your failsafe export will run (if you are using the

Realtime-failsafe option), or when your regular Background export.

Background Frequency

The options are Daily and Hourly. If you select hourly, the sync will run at the minutes and seconds past

each hour as defined above.

Unique Field

This is the unique identifier that will ensure the data is synchronized to the right contact in Emarsys. You

can choose from the email address, the Magento ID or a combination of email address, website ID and

store ID.

Page 16: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 16

Notification secret key

Here you can enter any password or secret you like. It is purely an internal security code to protect your

data files from external interference.

What Data is synchronized?

From Magento to Emarsys

The Magento contact database is considered the master database for contact details, and all values

synchronized for the mapped fields will overwrite the existing values in the Emarsys application.

New contacts will be exported to Emarsys with the same fields as per the initial export.

From Emarsys to Magento

Once a day, at the specified Background runtime, Emarsys also checks if the Opt-in field of any Magento

contacts has been modified. If so, this change is synchronized back to Magento.

Email#WebsiteID#StoreId is our recommended option, but bear in mind that if you

Page 17: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 17

4 PRODUCT DATA

If you are using Smart Insight and/or Predict, you will need to ensure that your Magento product catalog is

correctly loaded to Emarsys and kept synchronized.

Unlike contact and order data, the entire product catalog is always exported rather than simply the delta.

Therefore, the initial load and ongoing synchronization are actually the same process.

4.1 Preparing your product data

4.1.1 Configure the SFTP connection

Your product and order data is synchronized with Emarsys via an SFTP server. To configure this connection, go

to the Emarsys menu, Connection to open the FTP Settings page.

Enter the Hostname, Port, Username and Password as provided by Emarsys Support.

Bulk Export Directory - If you have created a sub-directory on the server to separate the Bulk

(manual) exports from the regular scheduled exports, enter that folder name here (preceded by /).

Use FTP over SSL(FTPS) - Set to Yes (recommended).

Use passive mode - Set to Yes or No as per your IT requirements.

4.1.2 Product Mapping

First, go to the Emarsys menu, Mappings, Product. Here you map your Magento product attributes

fields to the Emarsys product catalog fields, ensuring that your product catalog has the correct columns

and field types to conform to our product catalog standards.

If you want to include custom fields, you must create them in Emarsys using the c_* naming convention.

For more information, please see:

Page 18: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 18

Preparing Your Product Catalog

Proceed as follows:

Click Update Schema to make sure that all your custom Emarsys fields are available in the Emarsys

Attributes column.

Map each appropriate Magento attribute to an Emarsys field.

If you leave a field as Please Select it will be ignored and not loaded to Emarsys.

4.1.3 Configure the Feed Export

When you have mapped your fields, go to the Emarsys menu, Settings, Predict to configure the catalog

export.

You must map at least the mandatory fields: Item, Available, Title, Link, Image, Category

Price.

Page 19: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 19

Enable nightly product feed export - Set this to Yes. It does not matter if a scheduled export occurs

before you have made your initial load as the entire catalog is always overwritten every time.

Include Bundle Product - Defines whether bundles are included or not, see below.

Exclude Categories - Here you can exclude entire categories or sub-categories of products from the

export if you so wish (for instance, if they are irrelevant to your Emarsys marketing activities).

Execute and Export at - Sets the time of day for the catalog export (in HH:MM:SS).

Frequency - Set to Hourly or Daily as you wish.

When you click Save Config the product catalog will be exported from Magento to Emarsys according to

your defined schedule.

Product bundles

If you set the field Include Bundle Product to No, your export file will contain only the product data:

If you set the field to Yes, then the Bundles will be included as an extra line in addition to the product data:

Page 20: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 20

4.2 The initial product catalog load

Once you have configured your catalog fields, go to the Emarsys menu, Operations, Bulk Export to make

the first manual export of your catalog.

Select Product as Export Entity Type.

Define whether to Include Bundle Products or not.

Exclude any categories you want (make sure that these match any categories excluded in the Feed Export settings above.

Click Export.

The entire product catalog will then be exported to Emarsys.

4.3 Synchronizing your product catalog

As long as you have enabled your catalog Feed Export as described above, Magento will push your entire

product catalog to Emarsys according to the schedule you have defined.

With every export the entire catalog will be overwritten with the new one.

Page 21: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 21

5 ORDER DATA

If you are using Smart Insight, you will need to ensure that your Magento order (sales) data is correctly

loaded to the Emarsys Smart Insight database and that you have the right attributes mapped for your Smart

Insight segmentation requirements.

As with contact data, this is done in the same three steps.

5.1 Preparing your order data

First, go to the Emarsys menu, Mappings, Order. Here you give the Magento order columns the names that

will appear in the Smart Insight screens as Purchase attributes.

There is a fixed default set of columns already mapped - these are named in the Emarsys Order Attribute

column and cannot be changed.

You can add any other columns to the export by entering an attribute name. If you leave this field empty,

that column will not be included in the export file.

5.2 The initial order data load

When you have named all the columns in the export file, you should make a bulk export of your historical

order data. Proceed as follows:

Go to the Emarsys menu, Operations, Bulk Export.

If you have not already configured your Emarsys SFTP connection as described above,

Page 22: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 22

Export Entity Type - Select Order.

From and To fields - Select the time range for the order data.

Export To - Select CSV.

Click Export. The order data will now be loaded to the Smart Insight database and will be available

for Smart Insight segmentation in Emarsys.

5.3 Synchronizing order data

After your initial order data load, you must configure the ongoing load of new order data. Proceed as

follows:

Go to the Emarsys menu, Settings, Smart Insight.

This step is required by Emarsys customers who are using Smart Insight.

Do not save any Smart Insight Settings before you make the initial upload, as this will

Page 23: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 23

Smart Insight Enabled - Set this to Yes.

Export using email as identifier - If set to Yes, the email address of the Magento contact will be

added to the export file and used to map the order data to an Emarsys contact, instead of the Magento Customer ID. This is important if you are including Magento Subscribers in your marketing campaigns, as you do not have a Magento Customer ID for them.

Export guest checkout orders - Defines whether or not guest (i.e. anonymous) orders will be

exported. These cannot be used for Smart Insight segmentation but they will help to improve the product affinity model.

Frequency - Hourly or Daily. We recommend to set this to hourly as this will keep the export files

smaller.

Order Export for Statuses - This lists all the status values that an order can have. Orders with a

selected status will be exported. Multiple selection is possible.

When you click Save Config, Magento will export all the orders which have transitioned to one of the

selected statuses since the last export, at the appointed time.

Page 24: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 24

6 CONFIGURING YOUR TRANSACTIONAL MESSAGES

Magento 2 has a number of customer-facing events, some of which can be used as triggers for

transactional campaigns in Emarsys. You will need to map these events to the external events in Emarsys

which will trigger the campaign. You can also map Magento variables to placeholders in Emarsys and

personalizes your message content. Proceed as follows:

6.1 Prepare your Emarsys campaigns

For every Magento event you want to map, you will need to create the following in your Emarsys account:

One external event per Magento event.

One campaign per external event. These should be created directly in the campaign creation interface for that channel (Triggered Email, SMS or Mobile Engage) rather than using an Automation Center program (programs should only be used if you intend to follow up the initial message with further actions, which is typically not the case for transactional messages).

A list of personalization placeholders that you can map to the Magento variables for each event (see below).

6.2 Personalizing your message content

Since your Magento contacts are synchronized with Emarsys, you can of course include in your message

content all the regular personalization options available in Emarsys, including conditional content and block

targeting. However, there may be important information about the event that is only available in Magento

(for example, the URL of the confirmation link in a confirmation email).

To add this Magento content to your Emarsys message, you must add special Magento placeholders to the

content. These are written with a double % either side (for example, the variable first_name should be

written in the message content as %%first_name%%).

You will need to map these for each event so you should carefully track which placeholder you have

included in which transactional message.

Page 25: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 25

6.3 Define your opt-in strategy

This integration allows you to use Emarsys to trigger confirmation messages for newsletter subscriptions.

To do this, go to the Emarsys menu, Settings, Opt-in.

Enable Opt-in = No - There are no automatic triggers from Magento to Emarsys (you can manage the

confirmation from Magento, and there are still options to trigger emails from within Emarsys based on the change in value of a database field).

Enable Opt-in = Yes - Magento can automatically trigger transactional messages from Emarsys

confirming the opt-in for the following subscription points:

Customer Registration Page - Triggered by activating the checkbox during the registration

process.

Checkout process - Triggered by activating the checkbox during the purchase process (a code

snippet is provided for this checkbox).

Newsletter Box on every page - Triggered by entering and email address in the subscription field

in the footer of every page.

If you do enable this, you will then need to define which opt-in strategy to use for each subscription

method.

6.3.1 Single opt-in

With this strategy, a subscription event in Magento will create or update a contact in Emarsys with their

opt-in status set to , and you can optionally map an Emarsys event to trigger a confirmation message.

TRUE

Page 26: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 26

FALSE

TRUE

6.3.2 Double opt-in

This is our recommended strategy as it ensures that the person who subscribes is the same as the person

who owns the email address used.

The initial subscription will create or update a contact in Emarsys, but their opt-in status will be

until they click the confirmation link.

You can then select up to two Emarsys events:

External Event id for Double-Opt-in Event - Mandatory; this message will be triggered after the initial

subscription and will contain the confirmation link.

External Event id After Opt-in confirmation - Optional; this message will be triggered after the

confirmation link has been clicked.

6.3.3 The double opt-in confirmation link

Whenever you create a campaign in Emarsys which contains a confirmation link for double opt- in, you

need to include the same placeholder that will set the contact opt-in status to and trigger the

follow-up message (if one has been defined).

This placeholder is: %%subscriber_confirmationlink%%.

Since this pulls the URL for the confirmation link, you will need to build this into your HTML link tag, for

example:

<a href=“%%subscriber_confirmationlink%%”>I confirm my subscription</a> This is a global placeholder

and does not need to be mapped to any event.

Page 27: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 27

6.4 Map the events

When you have prepared your campaigns in Emarsys, go to the Emarsys menu, Mappings, Events.

For every available Magento event, select the appropriate external event in Emarsys.

If you create a new external event in Emarsys, click Update Scheme to make that available in

Magento.

6.4.1 Available Magento events

The following Magento events are currently available for mapping:

• Contact Form

• Credit Memo Update

• Credit Memo Update for Guest

• Forgot Admin Password

• Forgot Password

• Gift Registry Sharing

• Gift Registry Update

• Invoice Update

Page 28: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 28

• Invoice Update for Guest

• New Credit Memo

• New Credit Memo for Guest

• New Invoice

• New Invoice for Guest

• New Order

• New Order for Guest

• New RMA

• New RMA for Guest

• New Shipment

• New Shipment for Guest

• New Account

• New Account Confirmation Key

• New Account Confirmed

• Newsletter Subscription Confirmation

• Newsletter Subscription Success

• Newsletter Unsubscribe Success

• Order Update

• Order Update For Guest

• RMA Admin Comments

• RMA Admin Comments for Guest

• RMA Authorization

• RMA Authorization for Guest

• RMA Customer Comments

• Remind Password

Page 29: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 29

• Rewards Points Balance Update

• Rewards Points Expiry Warning

• Send Product to a Friend

• Share Wish List

• Shipment Update

• Shipment Update for Guest

• Store Credit Update

6.5 Map the placeholders

When you have mapped your events, you can map Magento variables with the placeholders

you added to your Emarsys campaign content. For each event, click Placeholders.

Now write the Emarsys placeholder, without the double %, in the field next to each Magento variable you want to include in the message content.

6.6 Enable transactional emails

When you have finished your mapping, go to the Emarsys menu, Settings, Transaction Email

and enable this functionality.

Page 30: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 30

Enable Emarsys Transaction Emails - Set this to Yes.

From this point on, all the mapped events in Magento will trigger the corresponding campaign

in Emarsys. This is not restricted to email - you can also map events to SMS or Mobile Engage campaigns.

6.7 Check the JSON

It is a good idea to check the JSON payload that will be transmitted to Emarsys, to make sure all

the placeholders have been correctly mapped. To do this, click JSON Request next to each event.

Page 31: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 31

Page 32: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 32

7 TESTING THE INTEGRATION

To test that the contact data synchronization is working, proceed as follows:

1. Create a new dummy account in your Magento store.

2. Log in to the shop with the dummy account.

3. Make a test order.

4. Update the user profile.

5. Monitor the Emarsys database to track the data changes.

To test that the e-commerce data synchronization is working, proceed as follows:

1. Add a new product to your Magento store.

2. Wait for the product data to be synchronized (as per your configuration).

3. Query the data in Emarsys to see that the new product has been imported correctly.

Page 33: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

Magento 2 Integration Manual Page 33

8 MAINTAINING THE INTEGRATION

8.1 Data monitoring in Emarsys

Once you have made your initial data loads and set up the schedule for regular synchronization

of new data, you can take advantage of the data monitoring tools that Emarsys provides to make sure that the data flow is working properly.

These tools validate every data import into Emarsys. If an issue is identified, this is highlighted and a suggested solution offered.

The tools are located in your Emarsys application on the Data Sources page.

8.2 Keeping your Magento schema updated

If you create new assets (fields, external events, etc.) in Emarsys, you can update your Magento

interface at any time by clicking Update Schema.

You can also set up a regular check to run in the background to see if any new assets have been

created. To do this, go to the Emarsys menu, Settings, Transactional Email and set the time and

schedule for the check.

If the check finds a new asset, you will receive a notification prompting your to update your schema again.

Page 34: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

VIENNA • LONDON • MUNICH • BERLIN • PARIS • HONG KONG • MOSCOW • ISTANBUL • BEIJING • SINGAPORE

8.3 Making a bulk export

Under the Emarsys menu, Operations, Bulk Export you can make a one-off manual export of your Magento data at any time.

Use cases for this include:

Customers and Subscribers - Select these if you want to update your Magento

contacts in Emarsys, for example after you have added a new Magento field or changed the field mapping.

For Customers, you will need to enter a time range. All customers registered

during this time range will be exported.

For Subscribers, you do not define any time range. All subscribers in your

Magento account will be exported.

Order - Use this option to upload offline sales data.

Product - Since the entire product catalog is uploaded every time, this is only

useful if you want to make an immediate export of your product catalog and not wait for the scheduled sync.

Page 35: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

VIENNA • LONDON • MUNICH • BERLIN • PARIS • HONG KONG • MOSCOW • ISTANBUL • BEIJING • SINGAPORE

9 LOGS

Under Emarsys, Operations, Logs you can find a list of all the integration events

between Magento and Emarsys. This will help you debug the integration during

installation, and monitor it afterwards.

For more details on an individual event, click View.

Page 36: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

VIENNA • LONDON • MUNICH • BERLIN • PARIS • HONG KONG • MOSCOW • ISTANBUL • BEIJING • SINGAPORE

Under Emarsys, Settings, Logs you can define how long to store the logs for, clean up your log files, set up a schedule for log reports and download the current log files.

Page 37: EMARSYS FOR MAGENTO 2...Magento 2 Integration Manual Page 1 EMARSYS FOR MAGENTO 2 Integration Manual July 2017 Important Note: This PDF was uploaded in July, 2017 and will not be maintained.

VIENNA • LONDON • MUNICH • BERLIN • PARIS • HONG KONG • MOSCOW • ISTANBUL • BEIJING • SINGAPORE

10 SUPPORT

Under Emarsys, Help, Support you can open a support ticket directly from your Magento

interface.