Install the Salesforce Commerce Cloud cartridge for SiteGenesis

Learn how to use the Dotdigital cartridge to integrate your Salesforce Commerce Cloud cartridge for SiteGenesis.

Overview

Our certified cartridge for Salesforce Commerce Cloud is developed and integrated with SiteGenesis. The Dotdigital cartridge extends SiteGenesis functionality by sending transactional emails using Dotdigital and captures user emails for sending newsletters.

Use the cartridge to:

• Capture user email addresses for sending newsletters
  You can do user subscriptions using your website footer, checkout, and user registration process.
• Send transactional emails
  You can send transactional emails for:
  • Registration emails
  • Profile updates
  • Password change requests
  • Password change confirmation
  • Order creation
  • Order shipments
• Track the content in an abandoned cart
  Identify users based on email address and trigger an abandoned cart program after an inactivity period that's defined in the configuration.
• Track site and ROI metrics
  Track the journey of contacts who go on to access the storefront through links in marketing campaigns.
• Track ROI values
  Track when customers pass orders originating from a campaign.
  

  To learn more about ROI tracking, check out the article Using site and ROI tracking.

Salesforce Commerce Cloud cartridge for SFRA

To learn about our integration for SFRA (3.2.0), check out our article Install the Salesforce Commerce Cloud cartridge for SFRA.

Before you start

Things you need to know:

• Cartridge installation is required for Web Behavior Tracking to be enabled.

Cartridge limitations

The cartridge doesn’t synchronize ecommerce data such as customers, orders and your product catalog. You can do this with our OCAPI integration.

Abandoned cart tracking for guests must be implemented separately by identifying the email address of a contact. Learn more in Abandonded carts.

Important

To use the cartridge, you must have an active Dotdigital account.

Step 1: Download the cartridge

To download the Dotdigital for Salesforce cartridge:

1. Go to the Dotdigital Salesforce Marketplace page.
2. Select DOWNLOAD INTEGRATION to download to your local computer.
3. Unzip the Dotdigital for Salesforce zip file. 

Step 2: Installing the cartridge

1: Import the cartridge

1. Import the int_dotdigital into the UXStuido workspace. 
2. Open UXStudio in Eclipse IDE.
3. Browse to the directory where the cartridge int_dotdigital are downloaded.
4. Select Finish and then OK to link the cartridge to the sandbox.
5. Repeat the above steps and import int_dotdigital_core.

2: Import metadata

1. Locate the folder site template in the installation package.
2. Archive the folder to site-template.zip.
3. Import the file by using Site Import & Export.

3: Configure the cartridge

1. Modify the site path in Business Manager > Administration > Manage Sites.
2. Add the cartridge name at the end of the path.

Configuration settings table

Setting	Recommended value
IsDotDigitalEnabled	Enable or disable the Dotdigital integration for the SiteGenesis integration.
Address Book for Registered User	The address book ID for capturing registered user email IDs.
Address Book for Guest User	The address book ID for capturing guest user email IDs.
API Username	To find your API username, go to Settings > Access > API Users.
API Password	To find your API password, go to Settings > Access > API Users.
API Endpoint	To find your API endpoint, go to Settings > Access > API Users.
Account Creation Campaign ID	The email template that's used for sending account creation emails.
Password Change Request Campaign ID	The email template that's used for sending password change requests.
Password Change Campaign ID	The email template that's used for sending a successful password change request.
Order Confirmation Campaign ID	The order confirmation campaign email ID.
Account Edited Campaign ID	The account profile edited email campaign ID.
Shipping Confirmation Campaign ID	The shipping confirmation campaign email ID.

Step 3: Modify your code

To complete the cartridge installation, you must make these 11 code modifications. 

Code modification 1

In the file
/app_storefront_core/cartridge/templates/default/components/footer/footer_UI.isml

Enter this code snippet
<isinclude template="dotdigital_snippets"/>

Where
Enter the code at the end of the file.

Code modification 2

In the file
/app_storefront_core/cartridge/scripts/util/Resource.ds

Enter this code snippet

ENABLE_DOTDIGITAL_ABANDONEDCART_TRACKING: Site.getCurrent().getCustomPreferenceValue('DMACEnableTracking'), 
ENABLE_DOTDIGITAL_ROI_TRACKING: Site.getCurrent().getCustomPreferenceValue('DMROIEnableTracking')

Where
Enter the code after the line
CHECK_TLS: Site.getCurrent().getCustomPrefferenceValue('checkTLS'),

Code modification 3

In the file
/app_storefront_core/cartridge/js/app.js

Enter this code snippet

//init dotdigital Abandoned Basket Tracking 
if (SitePreferences.ENABLE_DOTDIGITAL_ABANDONEDCART_TRACKING) {
 var dotdigital = require('./dotdigitalutils/dotdigital'); dotdigital.abandonBasketTracking(); 
} 
//init dotdigital ROI Tracking 
if (SitePreferences.ENABLE_DOTDIGITAL_ROI_TRACKING) {
 var roitracking = require('./dotdigitalutils/roitracking'); roitracking.init(); 
} 

Where
Enter the code after the code block

// Check TLS status if indicated by site preferences
if (Site Preferences.CHECK_TLS === true) {
 tls.getUserAgent();
}

Code modification 4

In the file
/app_storefront_core/cartridge/js/pages/product/addToCart.js

Enter this code snippet

if (SitePreferences.ENABLE_DOTDIGITAL_ABANDONEDCART_TRACKING) {
 var dotdigital = require('../../dotdigitalutils/dotdigital');
 dotdigital.abandonBasketTracking(response);
 } 

Where
Enter the code after the code block

// handle error in the response
if (response.error) {
 throw new Error(response.error);
} else {

And before the line
return response;

Code modification 5

Make the following changes to this folder:

1. Go to the folder /app_storefront_core/cartridge/js.
2. Create a folder named dotdigitalutils.
3. Move these two files into the dotdigitalutils folder:
   • /int_dotdigital/cartridge/scripts/dotdigital.js
   • /int_dotdigital/cartridge/scripts/roitracking.js

Code modification 6

In the file
/app_storefront_controllers/cartridge/scripts/models/CustomerModel.js

Enter this code snippet
new Customer.object.profile.custom.lastModifiedDateTime = new Date();

Where
Enter the code after the line addressBook.removeAddress(address);

Code modification 7

In the file
/app_storefront_controllers/cartridge/scripts/models/CustomerModel.js

Enter this code snippet
customer.profile.custom.lastModifiedDateTime = new Date();

Where
Enter the code after the code block

if (setCustomerPassword.error || !CustoemrModel.setLogin(customer, email, password) || !Form.get('profile.customer').copyTo(customer.profile)) {
 Transaction.rollback();
 return false;
)

Code modification 8

In the file
/app_storefront_controllers/cartridge/scripts/models/AddressModel.js

Where
In three different locations:

• Location 1
  Enter the code after the line
  addressBook.removeAddress(address);
  
• Location 2
  Enter the code after the code block

  if ('states' in addressForm) {
   if (!Form.get(addressForm.states).copyTo(address)) {
   return null;
   }
  }

  
• Location 3
  Enter the code after the block
  

  if ('states' in addressForm) {
    if (!Form.get(addressForm.states).copyTo(address)) {
      addressForm.invalidateFormElement();
      throw new Error('Unable to update address state');
    }
  }

  

Code modification 9

In the file
app_storefront_core/cartridge/forms/default/billing.xml

Enter this code snippet
customer.profile.custom.lastModifiedDateTime = new Date();

Where
Enter the code after the line
addressBook.setPreferredAddress(address);

Code modification 10

In the file
app_storefront_core/cartridge/forms/default/billing.xml

Enter this code snippet
<field formid="addToEmailList" label="checkout.addtoemaillist" binding="custom.acceptsMarketing" type="boolean" mandatory="false" />

Where
Enter the code after the line
<field formid="addToAddressBook" label="checkout.addtoaddressbook" type="boolean" mandatory="false" />

Code modification 11

In the file
app_storefront_core/cartridge/forms/default/profile.xml

Enter this code snippet
<field formid="addtoemaillist" label="profile.addemailtolist" binding="custom.acceptsMarketing" type="boolean"/>

Where
Enter the code after the line
<field formid="phone" label="profile.phone" type="string" description="profile.phoneexample" mandatory="false" binding="phoneHome" max-length="50"/>

Step 4: Check your firewall settings

You don't need to allow any IP addresses on your allow list for the cartridge to work.

Step 5: Test your installation

Use this checklist to test your installation is set up correctly:

• As a logged-in customer in your Salesforce Commerce Cloud storefront, check that the local storage DOTDIGITAL_AB_TRACKING exists.
• Add or remove items from your cart and check that the local storage data is updated accordingly.