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:
- Go to the Dotdigital Salesforce Marketplace page.
- Select DOWNLOAD INTEGRATION to download to your local computer.
- Unzip the Dotdigital for Salesforce zip file.
Step 2: Installing the cartridge
1: Import the cartridge
- Import the int_dotdigital into the UXStuido workspace.
- Open UXStudio in Eclipse IDE.
- Browse to the directory where the cartridge int_dotdigital are downloaded.
- Select Finish and then OK to link the cartridge to the sandbox.
- Repeat the above steps and import int_dotdigital_core.
2: Import metadata
- Locate the folder site template in the installation package.
- Archive the folder to site-template.zip.
- Import the file by using Site Import & Export.
3: Configure the cartridge
- Modify the site path in Business Manager > Administration > Manage Sites.
- 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 lineCHECK_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 linereturn response;
Code modification 5
Make the following changes to this folder:
- Go to the folder /app_storefront_core/cartridge/js.
- Create a folder named dotdigitalutils.
- 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 snippetnew 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 snippetcustomer.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 lineaddressBook.removeAddress(address);
- Location 2
Enter the code after the code blockif ('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 snippetcustomer.profile.custom.lastModifiedDateTime = new Date();
Where
Enter the code after the lineaddressBook.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.