EMARSYS FOR MAGENTO 2

Transcription

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: Magento 2 Integration Manual Page 1

2 CONTENTS Introduction Prerequisites Magento 2 requirements Emarsys requirements Installing the integration Install the Emarsys module Check the installation Enable web behavior data collection Enable product recommendations Contact data Preparing your contact data Enable the integration and configure the API settings Configure the WebDAV connection Customer Mapping Prepare the Emarsys auto-import The initial contact data load Define the opt-in settings Perform the initial data load Synchronizing contact data Product data Preparing your product data Configure the SFTP connection Product Mapping Configure the Feed Export The initial product catalog load Synchronizing your product catalog Order data Preparing your order data The initial order data load Synchronizing order data Configuring your transactional messages Prepare your Emarsys campaigns Personalizing your message content Define your opt-in strategy Single opt-in Double opt-in The double opt-in confirmation link Magento 2 Integration Manual Page 2

3 6.4 Map the events Available Magento events Map the placeholders Enable transactional s Check the JSON Testing the integration Maintaining the integration Data monitoring in Emarsys Keeping your Magento schema updated Making a bulk export Logs Support Magento 2 Integration Manual Page 3

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 and php5-curl must be installed on your Magento server. PHP SOAP extension must be enabled. TCP port 21, 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. account. Emarsys 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). Magento 2 Integration Manual Page 4

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 Magento 2 Integration Manual Page 5

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 ~ 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. Magento 2 Integration Manual Page 6

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. Magento 2 Integration Manual Page 7

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 Magento 2 Integration Manual Page 8

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 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: Magento 2 Integration Manual Page 9

10 Click Save Config when you are done 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 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 singleand 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. Magento 2 Integration Manual Page 10

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 dropdown. All the single-and multi-choice fields that have been mapped are shown and you must now map the values for each one. Magento 2 Integration Manual Page 11

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! Magento 2 Integration Manual Page 12

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 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. Magento 2 Integration Manual Page 13

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. Do not save any Contact Synchronization Settings before you make the initial upload, 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. Magento 2 Integration Manual Page 14

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 address, the Magento ID or a combination of address, website ID and store ID. Magento 2 Integration Manual Page 15

16 #WebsiteID#StoreId is our recommended option, but bear in mind that if you 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. Magento 2 Integration Manual Page 16

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 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 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: Magento 2 Integration Manual Page 17

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. You must map at least the mandatory fields: Item, Available, Title, Link, Image, Category Price Configure the Feed Export When you have mapped your fields, go to the Emarsys menu, Settings, Predict to configure the catalog export. Magento 2 Integration Manual Page 18

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: Magento 2 Integration Manual Page 19

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. Magento 2 Integration Manual Page 20

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. If you have not already configured your Emarsys SFTP connection as described above, 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. Magento 2 Integration Manual Page 21

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. Do not save any Smart Insight Settings before you make the initial upload, as this will 5.3 Synchronizing order data This step is required by Emarsys customers who are using Smart Insight. 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. Magento 2 Integration Manual Page 22

23 Smart Insight Enabled - Set this to Yes. Export using as identifier - If set to Yes, the 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. Magento 2 Integration Manual Page 23

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 , 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 ). 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. Magento 2 Integration Manual Page 24

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 s 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 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 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 TRUE, and you can optionally map an Emarsys event to trigger a confirmation message. Magento 2 Integration Manual Page 25

26 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 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. FALSE 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 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 TRUE 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. Magento 2 Integration Manual Page 26

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 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 Magento 2 Integration Manual Page 27

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 Magento 2 Integration Manual Page 28

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 s When you have finished your mapping, go to the Emarsys menu, Settings, Transaction and enable this functionality. Magento 2 Integration Manual Page 29

30 Enable Emarsys Transaction s - 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 - 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. Magento 2 Integration Manual Page 30

31 Magento 2 Integration Manual Page 31

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. Magento 2 Integration Manual Page 32

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 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. Magento 2 Integration Manual Page 33

34 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. VIENNA LONDON MUNICH BERLIN PARIS HONG KONG MOSCOW ISTANBUL BEIJING SINGAPORE

35 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. VIENNA LONDON MUNICH BERLIN PARIS HONG KONG MOSCOW ISTANBUL BEIJING SINGAPORE

36 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. VIENNA LONDON MUNICH BERLIN PARIS HONG KONG MOSCOW ISTANBUL BEIJING SINGAPORE

37 10 SUPPORT Under Emarsys, Help, Support you can open a support ticket directly from your Magento interface. VIENNA LONDON MUNICH BERLIN PARIS HONG KONG MOSCOW ISTANBUL BEIJING SINGAPORE