The Emarsys Salesforce B2C Commerce plug-in was certified by Salesforce in August 2021. The integration and documentation are available on Salesforce Marketplace.
The Emarsys integration can be enabled or disabled from Business Manager using the toggle on/off feature. In order to turn on/off the integration, navigate to Merchant Tools > Site Preferences > Custom Preferences > Emarsys > Enable Emarsys Services.
When the integration is disabled and the end-user tries to subscribe to a newsletter using the global footer or my account subscription method, they will be redirected to a custom page which will show the message that states the subscriptions are not active.
Even if the integration is disabled, as long as the cartridge is still installed, the end-user has the option to unsubscribe from newsletters, from their Salesforce B2C Commerce account (only registered users) or by clicking the unsubscribe link present in the emails received through the Emarsys platform.
Business Manager
A new Business Manager extension has been created in order to allow the merchant to configure the behavior for newsletter subscriptions and to define the Salesforce Commerce Cloud fields that will be added to transactional emails (order and shipping confirmation emails) that will be sent through the Emarsys Platform. The extension will also allow the merchant to map Salesforce Commerce Cloud with Emarsys fields for the initial database load feature.
If the Emarsys Integration screen is not displayed, then please compare the Salesforce Commerce Cloud code with the Emarsys code and make sure that they are implemented at the appropriate level.
Newsletter subscription box - global footer
Perform the following steps to configure the Newsletter subscription in Business Manager:
1. Log in to Business Manager.
2. Go to Merchant Tools > Emarsys Integration.
3. Select the Newsletter subscriptions item.
4. The page opens with the Global footer tab selected by default.
5. The merchant needs to select the Opt-in strategy. There are two options available:
-
Single Opt-In (the recipient's
opt-insystem field is set totrueimmediately in the Emarsys platform). Optionally, the merchant can select an external event that is fired after the user record was transmitted to Emarsys.
-
Double Opt-In (the recipient needs to click a confirmation link in an email to set the system field
opt-in totruein the Emarsys platform). If double opt-in is selected, then the merchant must select the external event that should be triggered in the Emarsys platform to send out the confirmation email. Optionally, the merchant can set a second event that will be triggered as soon an end-user clicks the confirmation link (e.g. to send a welcome email).
6. Click the Apply button to save the configuration.
Newsletter subscription - checkout process
1. Log in to Business Manager.
2. Go to Merchant Tools > Emarsys Integration.
3. Select the Newsletter subscriptions item.
4. Click the Checkout page tab.
5. The merchant needs to select the Opt-in strategy. There are two options available:
-
Single Opt-In (the recipient's
opt-in system field is set totrueimmediately in the Emarsys platform). Optionally, the merchant can select an external event that is fired after the user record was transmitted to Emarsys.
-
Double Opt-In (the recipient needs to click a confirmation link in an email to set the system field opt-in to
truein the Emarsys platform). If double opt-in is selected, then the merchant must select the external event that should be triggered in the Emarsys platform to send out the confirmation email. Optionally the merchant can set a second event that will be triggered as soon an end-user clicks the confirmation link (e.g. to send a welcome email).
6. Hit the Apply button to save the configuration.
Newsletter subscription - My account page
1. Log in to Business Manager.
2. Go to Merchant Tools > Emarsys Integration.
3. Select the Newsletter subscriptions item.
4. Click the Account page tab.
5. You need to select the Opt-in strategy. There are two options available:
-
Single Opt-In (the recipient's
opt-insystem field is set totrueimmediately in the Emarsys platform). Optionally, you can select an external event that is fired after the user record was transmitted to Emarsys.
-
Double Opt-In (the recipient needs to click a confirmation link in an email to set the system field
opt-intotruein the Emarsys platform). If double opt-in is selected, then you must select the external event that should be triggered in the Emarsys platform to send out the confirmation email. Optionally, you can set a second event that will be triggered as soon an end-user clicks the confirmation link (e.g. to send a welcome email).
6. Click the Apply button to save the configuration.
Transactional emails - order confirmation
As soon as an end-user finishes a transaction, the order data should be transmitted to the Emarsys platform and the corresponding external event must be triggered. The external event will trigger an order confirmation email. Salesforce B2C Commerce will check in the Emarsys platform if the user record already exists and based on the result it will update the record or create a new one. Also, the merchant has the option to choose what fields will be included in the order confirmation email.
To configure and map the Salesforce B2C Commerce fields, that will be added to the order confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for order confirmation emails:
1. Navigate to Business Manager > Merchant Tools > Emarsys Integration > Order Confirmation configuration.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce B2C Commerce available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the order is placed and the record is created or updated in the Emarsys platform.
5. To remove some of the defined Salesforce B2C Commerce field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and click the Apply button.
Transactional emails - shipping confirmation
As soon as a shipment is finished, an email should be sent to the end-user and the corresponding external event must be triggered. The external event will trigger a shipping confirmation email.
To configure and map the Salesforce B2C Commerce fields that will be added to the shipping confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for shipping confirmation emails:
- Navigate to Business Manager > Merchant Tools > Emarsys Integration > Shipping Confirmation configuration.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce B2C Commerce available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the shipment is finished.
5. To remove some of the defined Salesforce B2C Commerce field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and hit the Apply button.
Transactional emails - order cancelled
As soon as a shipment is finished, an email should be sent to the end-user and the corresponding external event must be triggered. The external event will trigger an order cancelled email.
To configure and map the Salesforce B2C Commerce fields that will be added to the shipping confirmation email, with the defined Emarsys placeholders, a custom configuration screen has been created. Please find below the steps you need to follow to make the necessary configurations for an order cancelled email:
- Navigate to Business Manager > Merchant Tools > Emarsys Integration > Order Cancelled Configuration Email.
2. Click the Add fields button.
3. From the dropdown, select the Salesforce B2C Commerce available field and then define the placeholder name in the right column.
4. Select the external event that will be triggered after the shipment is finished.
5. To remove some of the defined Salesforce B2C Commerce field and Emarsys placeholder name pairs, select the corresponding Remove checkbox and hit the Apply button.
Initial Database Load - configuration screen
The initial database load feature will upload the existing Salesforce B2C Commerce customers to the Emarsys platform. Please find below the steps required to accomplish this:
- Create the mapping between the Salesforce B2C Commerce and Emarsys fields using the initial database load configuration screen. The fields must be mapped by the end-user. The mapping will be used to generate an auto-import profile on the Emarsys side and to create a CSV file with the Salesforce B2C Commerce customers.
To generate the mapping, a new configuration screen has been created.
1. Go to Merchant Tools > Emarsys Integration > Database Load Configuration.
2. Click Add fields.
3. Use the dropdown to map Emarsys fields with Salesforce B2C Commerce available attributes.
4. Click the Apply button to save the configuration.
Once the settings for the initial database load feature has been made, the Initialize Emarsys Database job schedule needs to be configured and run. The customers will be exported to the Emarsys platform in bulks of configurable sizes. The default size of a bulk is set to 10.000 customers, but the merchant has the option of updating this value inside Business Manager, by navigating to Administration > Operations > Jobs > Emarsys-InitDatabase > ExportCustomerInfo and setting the value for the Profiles export threshold field.
Important:
- Please keep in mind that setting a high value for the bulk size might affect the performance. Also, the bulk size should never be set to a value higher than 20.000 customers to avoid Salesforce B2C Commerce quota violations.
- The recommendation is to schedule the job to run during low traffic periods.
- Set the recurrence according to the number of exported customers per iteration.
When the job schedule is finished, the merchant will have to manually disable it. The Export Status field is used to prevent customers exporting data after the initial database load was done, so that even if the job is not disabled, the export will be skipped. The value of Export Status field is automatically set once all the customers from Salesforce B2C Commerce were loaded into the Emarsys platform.
Send Order Confirmation Email - send email
You can manually send order confirmation emails to customers at the order number via the Emarsys service.
After sending the message, the order changes the status of (sendEmarsysShippingEmail).
External events page
After successful execution of the Emarsys-Setup job all initial event configuration is already set. External events page is developed to change the event configuration easily. To get there, you should:
- Log in to Business Manager.
- Select your site in the top-left corner of the page.
- Go to Merchant Tools > Emarsys Integration > External Events.
All external events are separated by their type into two tables: Newsletter Subscription Events and Other Events. Events mapping are taken from the appropriate fields of the EmarsysExternalEvents custom object.
Each table has an Add event button over the top-right corner. You should use this button to map new SFCC events. Depending on the type of the event, a new SFCC event should be listed in one of the EmarsysExternalEvents source fields (newsletterSubscriptionSource or otherSource) but should not be on the page (should not yet be mapped). If you want to change the configuration of a mapped SFCC event, you should click the Change button in the appropriate row.
After clicking the Add event button, the Create event dialog appears. Use the upper selector to choose the SFCC event you want to map. Events from the newsletterSubscriptionSource field you can map with any allowed Emarsys event (of the same type), while events from the otherSource field are allowed to be mapped only with an appropriate Emarsys event. Click the Add button to apply mapping for a selected SFCC event.
If the appropriate Emarsys event is chosen for mapping, this event will be created using the Emarsys API. If there are any issues during the request, an error notification will be shown at the top of the events page.
The interface of the page allows to map SFCC Newsletter Subscription Events with any of Emarsys Newsletter Subscription Events. Events of other type may be mapped only with the appropriate Emarsys events or to be disabled. To disable any SFCC event, choose the none option in the mapping. To apply mapping changes, click Apply button.
Do not run the Emarsys-Setup job after making custom event mapping configurations because the job will rewrite the mapping. It means that all SFCC events will be mapped to the appropriate Emarsys events even if they were not mapped or disabled before running.
Storefront functionality (SFRA)
By installing the Emarsys cartridge, the retailers will provide their end-users with the option of subscribing to newsletters from their website storefront. There are 3 ways for an end-user to accomplish this:
- using the newsletter subscription box displayed on the global footer,
- during the checkout process, by selecting the Please add me to the Salesforce B2C Commerce Cloud's email list. Salesforce B2C Commerce does not share or sell personal info checkbox on the Billing page,
- from the Salesforce B2C Commerce My Account page.
All these options are detailed in the following sections.
Newsletter subscription box - global footer
The end-user can subscribe to newsletters from the footer on every page of the storefront. There are 2 ways to do that:
- Subscribe directly by typing the email address in the subscription box and clicking the Subscribe button.
- Clicking the Subscribe button without entering any data into field. This will redirect the user to the Sign-up form. The user will subscribe by completing all the necessary fields and clicking the Sign me up for email button. The data is sent to Emarsys.
Newsletter subscription during checkout process
The end-user also has the option to subscribe to a newsletter during the checkout process, as described below but you need to add this option to the default subscription (is false).
1. As a guest or registered user add a product to the cart.
2. Proceed to checkout.
3. In the checkout step, type in your email address in the email field.
4. Select the Please add me to Salesforce B2C Commerce email list. Salesforce B2C Commerce does not share or sell personal info and I have read the Privacy Policy and I agree checkboxes.
5. Complete all the mandatory fields and proceed to the next step, so that the end-user data is sent to the Emarsys platform.
Newsletter subscription or unsubscription - My Account
Registered users has the option to subscribe to or unsubscribe from newsletters from the My Profile page but this functionality needs to be added in the Storefront.
1. Open the storefront and log in.
2. In the left navigation bar, click the Email Settings link.
3. Clicking the Subscribe button will open an email sign-up form. Complete the fields and click the Sign me up for email button to subscribe to newsletters.
4. Clicking the Unsubscribe button will unsubscribe the end-user from newsletters.
Salesforce B2C Commerce landing pages
Depending on which opt-in strategy has been configured for the subscription methods and depending on the unsubscription strategy (direct or indirect), the end-user can be redirected to several landing pages as follows:
- Thank you page - Single Opt-in strategy
- Data submitted page - Double Opt-in strategy
- Thank you page - Double Opt-in strategy
- Thank you page - Unsubscribe
Storefront functionality (SG)
By installing the Emarsys cartridge, the retailers will provide their end-users with the option of subscribing to newsletters from the website storefront. There are 3 ways for an end-user to accomplish this:
- using the newsletter subscription box displayed on the global footer,
- during the checkout process, by selecting the Please add me to the B2C Commerce email list. B2C Commerce does not share or sell personal info checkbox on the billing page,
- from the Salesforce B2C Commerce My Account page.
All these options are detailed in the following sections.
Newsletter subscription box – global footer
The end-user can subscribe to newsletters from the footer on every page of the storefront. There are 2 ways to do that:
- Subscribe directly by typing the email address in the subscription box and clicking the subscribe button.
- Clicking the subscribe button without entering any data into the field. This will redirect the user to the Sign up form. The user will be subscribed by completing all the necessary fields and clicking the Sign me up for email button. The data is sent to Emarsys.
Newsletter subscription during checkout process
The end-user also has the option to subscribe to newsletters during the checkout process, as described below but you need to add this option to the default subscription (is false).
- As a guest or registered user add a product to your cart.
- Proceed to checkout.
- In the checkout step type in your email address in the email field.
- Select Please add me to the B2C Commerce email list. B2C Commerce does not share or sell personal info and I have read the Privacy Policy and I agree checkboxes.
- Complete all the mandatory fields and proceed to the next step, so that the end-user's data is sent to the Emarsys platform.
Newsletter subscription/unsubscription – My Account
Registered users can subscribe to or unsubscribe from newsletters in the Salesforce My Account section.
- Open the storefront and log in.
- In the left navigation bar click the Email Settings link.
- Clicking the Subscribe button will open an email sign-up form. Complete the fields and clock the Sign me up for email button to subscribe to newsletters.
- Clicking the Unsubscribe button will unsubscribe the end-user from newsletters.
B2C Commerce landing pages
Depending on which opt-in strategy has been configured for the subscription methods and depending on the unsubscription strategy (direct or indirect), the end-user can be redirected to several landing pages, as following:
- Thank you, page - Single Opt-in strategy
- Data submitted page - Double Opt-in strategy
- Thank you, page - Double Opt-in strategy
- Action page - Indirect unsubscribe
- Thank you, page - Unsubscribe
Emarsys SmartInsight
Introduction
SmartInsight is an integrated solution for marketers that utilizes customer data from various touchpoints to provide actionable intelligence focused on customer engagement. This data can be uploaded from external sources as well as collected by the Web Extend scripts directly from your website.
Purpose
Emarsys needs a daily sales item CSV feed with new orders (new order items) of the last 24 hours. This feed must be delivered to an FTPS server on a daily basis. For this, it is required to set logon credentials for this server in the Salesforce B2C Commerce back-end (hostname, username, password, destination folder).
BM Settings for the Emarsys SmartInsight attribute configuration for export
Log in to Business Manager where the Emarsys integration is enabled.
Emarsys SmartInsight Extension Configuration
Navigate to Merchant Tools > Emarsys Integration. Here you should see the SmartInsight Configuration link:
On the SmartInsight Configuration page, users can add and remove mapped fields. These fields are used to create the CSV file with this data. These fields will be displayed as columns in the exported files.
The sales items CSV has to contain at least these columns:
- order - order number
- date - date of the order (YYYY-MM-DD)
If you use the date format YYYY-MM-DD, then you will not be able to use Smart Insight as the data source for Revenue Attribution and you cannot use Emarsys Loyalty at all. If you would like to use these features, change the date to timestamp in your sales date file. For more information, see timestamp in Standard field set.
- customer - unique customer ID (this ID must be available in the Emarsys platform as well)
If you are using a unique customer ID other than email, then you need to ensure that the setCustomerId Web Extend command is used.
- item - ProductId of the sold item (this ID must be in the product CSV as well)
- quantity - quantity of the ordered item
- price - price of the sold items (this value must be negative if an order was cancelled)
The customer can add additional order attributes to the data feed. For this, they should click the Add fields link and fill the Attribute name and the name that will we displayed in the file. The column name of these additional columns must start with a prefix specifying the data type. The prefix then must be followed by an underscore (_) and the name of the custom column. If the field's name consists of multiple words, then each word must start with a lowercase letter and should be separated by an underscore. For more information on how to format custom fields in your sales data file, see Custom fields.
You can find the lists of SI Loyalty Fields and Catalog Loyalty Fields below:
SI Loyalty Fields
If you are using Emarsys Loyalty, you will also need to have these fields in your sales data file.
| Field | Required | Type | Example | Description |
|---|---|---|---|---|
| f_original_price | Yes | Float | 3549.92 |
The total price of the items (the unit price multiplied by the quantity) in the original currency. Always use the
period ( Do NOT use any thousand separators (i.e. 2000, not 2,000). Do NOT include the currency. For refunds, always submit a negative value. |
| s_original_currency | Yes | String | USD |
The original currency the sale was made in. Always use the three-letter abbreviation which you can find here: Currency, Acronyms and Abbreviations. |
| s_coupon | Yes | String | AX692374 | Please insert here all coupons and voucher codes your user used at checkout. If the user used more than one, you could add multiple codes by separating them with a comma. If the coupon was not used for a specific item, you can send the same coupon code for all items purchased, we will only consider the unique codes per each order. Loyalty uses this field for the referral program to know that the user referred made a purchase with the coupon code received from a loyalty member. For more information, see Referral Program. |
Catalog Loyalty Fields
The following fields are required to fully support catalog promotion.
| Field | Required | Type | Example | Description |
|---|---|---|---|---|
| brand | Yes | String | Calvin Klein | The brand of the item. |
| category | Yes | String | Shirts | The category of the item. An item can be in more than one category. In case of multiple categories, separate the categories using the pipe delimiter (|). |
Elements that were added on the Site Preferences > Custom Site Preferences > Emarsys SmartInsight Configuration page are displayed in the Available elements drop-down list.
Job for SmartInsight that exports all orders in CSV format and uploads them to the FTPS server
Navigate to Administration > Job Schedules and click Edit for the Emarsys Export Orders job.
On this page, the user can set up Emarsys Export Order Job configurations:
- Enabled - Checkbox which enabled or disabled the Emarsys Export Orders job on the site.
- Name - The job’s Name.
- Description - The description of this Job.
- Runtime - The user can set up the time and period when the job will run automatically.
To run the job, the user should click the Run button.
After finishing the successful ‘Job’, go to the SFTP server and check the folder that was set up on the Emarsys SmartInsight Configuration page. The new exported file with orders should be in this folder.
The file name should be in such format: sales_items_<YYYYMMDDHHiiss>_< shopinfo >.csv
Please make sure that your sales data file follows the naming convention above.
Open the new exported file with orders. All the orders that fit the set timeframe are displayed in the file with certain columns that were added on the Merchant Tools > Emarsys Integration > SmartInsight Configuration page:
Emarsys export catalog
Introduction
Emarsys Catalog is used in Predict, Emarsys' predictive recommendation engine, which uses machine learning algorithms to offer your customers the best products wherever they interact with your business. The data used by the Catalog to make these recommendations is collected by the Web Extend scripts.
Purpose
Emarsys Catalog is being used to recommend products based on a self-learning algorithm. Recommended products can be rendered within shop pages and emails. To get this working, Catalog requires a CSV product data feed which will be fetched from a remote location (HTTP / FTP / SFTP).
BM settings for Emarsys Catalog
Log in to BM where the Emarsys integration is enabled.
BM Settings for Emarsys Catalog Configuration
Navigate to Merchant Tools > Emarsys Integration > Export Catalog Configuration:
On the SmartInsight Catalog configuration page, users can add and remove mapped fields. These fields will be used to create the CSV file with this data. These fields will be displayed as columns in the exported files.
The sales items CSV has to contain at least these columns:
- Item - Unique product ID
- Available - Is the product available (and can be recommended)? Available values: true or false.
- Title - Product title
- Link - Deep link to the product
- Image - URL of the product image
- Category - Category path to the product separated by "
>", e.g. books > scifi > startrek - Price - Product price (float value 1234.99)
To send multi language values, in case if there are several locales configured, a value from the Placeholder field must be adjusted with the '_multilang' prefix.
The customer can add additional order attributes to the data feed. For this, they should click the Add fields link and fill the Attribute name and the name that will we displayed in the file. The column name of these additional columns must start with "c_".
Elements that were added on the Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration page are displayed in the Available elements dropdown list.
You can choose the Export type:
- Export only the main product (no product version) - (default setting)
- Export each product version or each combination of product versions
If you need to export child products, then select the Export each product version or each combination of product versions option. This setting cannot be changed after saving the configuration.
You can create a new instance of the custom object in BM for individual configurations.
You can choose them as individual configurations.
You should click Add fields to add a new field.
For more information on how to set up the step for the job, see section Emarsys-ExportCatalog.
BM Settings for Emarsys Catalog custom object
Navigate to Merchant Tools > Custom Objects > Custom Objects > catalogConfig - General and verify the Mapped fields text box. In this field, all selected fields from Merchant Tools > Emarsys Integration > Catalog Configuration are displayed.
Job for Emarsys ExportCatalog that exports all orders in CSV format and uploads them to the FTP
Navigate to Administration > Job Schedules and click Edit for the Emarsys ExportCatalog job.
On this page, the user can set up the Emarsys ExportCatalog job configurations:
- Enabled - Checkbox which enabled or disabled the Emarsys Export Orders job on the site.
- Name - The job’s Name.
- Description - The description of this Job.
- Runtime - The user can set up the time and period when the job will run automatically.
To run the job, the user should click the Run button.
After finishing the Job successfully, go to the SFTP server and check the folder that was set up on the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration page. The new exported file with products is in this folder.
The file name should be in such format: products_<siteName>.csv
Open the new exported file with orders. All the orders that fit the set timeframe are displayed in the file with certain columns that were added into Merchant Tools > Emarsys Integration > Catalog Configuration:
JavaScript tracking code and JavaScript recommendations
Introduction
The Web Extend JavaScript API is a data collection system that captures the activity and behavior of website visitors. This information is used to enrich your Emarsys contact database with Web Extend fields and to generate personalized product recommendations for the Predict solutions.
JavaScript recommendation code
Log in to BM where the Emarsys integration is enabled.
Settings for JavaScript recommendation code
Navigate to the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration link:
On this page, the user can set up the Emarsys JS Configuration:
- Predict: Enable tracking code - Checkbox which enabled or disabled JavaScript tracking code on the site.
- User can select the widget type that will be shown on the storefront for different pages:
- Thank You, For Your Order Page
- Product Detail Page
- Home Page
- Cart Page
- Search Page
- Category Page
- Widget types:
- Personal - The Personal widget offers targeted recommendations which match a visitor’s known characteristics and interests, based on their own browsing history and the wisdom of the crowd. It helps them to find products they are interested in before they even know they want them.
- Related - The Related widget suggests alternative products to the items currently being viewed. It does this by looking at the browsing behavior for the whole web shop and identifying product-to-product relationships.
- Also Bought - The classic 'people who bought X, also bought Y' widget, Also Bought offers recommendations based on items that have frequently been bought with the item currently being viewed. This is a more targeted version of the Related widget and can be used well in combination with it.
- Cart - Similar to Also_Bought, the Cart widget offers recommendations based on the current selection of items in the customer's shopping cart. It looks for relationships between these items and then makes additional cross- and up-sell recommendations (e.g. a spare power cord for cars, an extra SD card, etc.).
- Category - Similar to the Personal widget, the Category widget directs customers to the right products, but within a particular category, depending on the specific category page they are on.
Open the Storefront and visit pages where recommendation widgets must be shown.
Settings for the JavaScript tracking code
Navigate to the Merchant Tools > Site Preferences > Custom Site Preferences > Emarsys Catalog Configuration link:
On this page, the user can set up the Emarsys JS Configuration:
- Predict: Enable tracking code - Checkbox which enables or disables the JavaScript tracking code on the site.
Navigate to the storefront and visit pages where the tracking code is supposed to run (category page, search page, pdp, etc.). Check the Emarsys Predict dashboard, here you should see a real-time chart that shows what action you've performed.
SFRA:
SG:
