Salesforce (SFCC)

DataDome Salesforce Cartridge detects and protects against bot activity on Salesforce Commerce Cloud.

This cartridge enables setting up DataDome protection on Salesforce Commerce Cloud sites. It makes a call to the closest DataDome endpoint. Depending on the API response, the app either blocks the request or lets Salesforce Commerce Cloud proceed with the regular process.

The cartridge has been developed to protect the users' experience: if any errors were to occur during the process, or if the timeout is reached, the module will automatically disable its blocking process and allow the regular Salesforce Commerce Cloud process to proceed.

Compatibility

The DataDome cartridge has been tested against SFRA v5.0.1, SG v105.0.0 and in compatibility mode with v19.10, v18 and v10.

Prerequisites

A free trial must be started (through the sign-up form) or a DataDome representative must enable an account for the merchant, as part of which the merchant will be assigned a unique “API key” and “JS key”.

How to install

DataDome Cartridge can be downloaded here.

The DataDome integration uses the following cartridges: int_datadome, datadome_sg_changes (for SiteGenesis) and datadome_sfra_changes (for SFRA).

Step 1 - Upload (Manually) the cartridges

Navigate to: Administration > Site Development > Code Deployment. Create a new Code version. It will contain all the necessary cartridges.

Then click on the version ID you have just created. This version summary will give you a link to Webdav to upload your cartridges. Note: Datadome cartridges should be uploaded to the root folder of your version

1827

Version summary

Step 2 - Upload the Metadata and services

Navigate to: Administration > Site development > Site Import & Export

  • From the archive, upload the metadata.zip file
  • Next, select instance/metadata.zip and click on "Import" to complete the import process through the interface
  • You can check the import status at the bottom of the page
1881

Upload Status

How to configure

Step 1 - Cartridge Registration

Navigate to the following path: Administration dropdown > Sites > Manage Sites > Merchant Site > Settings.
Add the cartridge names to the "Cartridges" path (WARNING: there are 2 names to add) as shown in the screenshot below:

SiteGenesis - Controller Version

Add "datadome_sg_changes:int_datadome:" at the beginning of the Cartridges field:

SFRA Version

Add "datadome_sfra_changes:int_datadome:" at the beginning of the Cartridges field:

Step 2 - Configure DataDome Metadata and Services

  • The details on DataDome Services and Site Preferences are described below

Services Details

Navigate to: **Administration > Operations > Services.
After successfully importing the services, the following will be added:

NameProfileCredentials
int_datadome.http.protection.apiint_datadome.protection.api.profileint_datadome.http.protection.api.cred

🚧

About the HTTPForm type

The Type property must remain as HTTPForm for the cartridge to work.

Protection API Service

The URL for Protection API could be set in int_datadome.http.protection.api.cred

Note: "User" and "Password" are not required.

The default timeout configured in int_datadome.protection.api.profile is 150 milliseconds. Do not change this value unless advised otherwise by DataDome.

Custom Code SiteGenesis - Controllers

Controller version uses “onRequest” hook to capture each request and further uses Regexes (see section 4.4.4) to filter which request should be able to call the DataDome API. Controller version has one controller, DataDome.js, which is used to manage responses returned from the DataDome API.

Adding DataDome JavaScript

For protection purposes, DataDome’s JavaScript must be included in the storefront header file, i.e. htmlhead.isml:

<isinclude template="include/datadomeheader.isml" />

See the default overridden templates in the cartridge for reference:
“/datadome_sg_changes/cartridge/templates/default/common/htmlhead.isml”

Custom Code SFRA (StoreFront Reference Architecture)

Similarly to the SiteGenesis version, SFRA uses “onRequest” hook to capture each request and further uses Regexes (see section 5.1.1) to filter which request should be able to call the DataDome API. SFRA cartridge has one controller, DataDome.js, which is used to manage responses returned from the DataDome API.

Adding DataDome JavaScript

For DataDome protection to work, DataDome’s dynamic JavaScript must be included in the storefront header file, i.e. htmlhead.isml:

<isinclude template="include/datadomeheader.isml" />

See the default overridden templates in the cartridge for reference:
“/datadome_sfra_changes/cartridge/templates/default/common/htmlHead.isml”

External Interfaces

There are no external interfaces.

Business Manager

DataDome Site Preferences

The DataDome cartridge consists of the following configuration properties in
Site > Merchant Tools > Site Preferences > Custom Preferences > DataDome Configurations:

  1. Go to "Business Manager", "Merchant Tools" section
  2. Click on "Site preferences"
  3. Click on "Custom preferences"

  1. Click on "DataDome Configurations"
  2. Replace the License key with your own key from your dashboard
  3. Replace the JavaScript key with your own key from your dashboard
  4. Create the Regex for the content you want to exclude from the protection (assets for instance). We recommend adding, and updating accordingly, the following regex if you are using the SFCC analytics system.
^\/on\/demandware\.store/Sites-.*-Site\/[a-z][a-z]_[A-Z][A-Z]\/__Analytics-Start$
  1. Click on the "Save" button on the top-right

Congrats! Your website is ready to be protected against bot traffic!

Settings documentation

SettingDescription
DataDome Cartridge EnabledEnables/disables DataDome cartridge
DataDome API KeyServer-side module Key for DataDome
DataDome JS KeyClient-side Key for DataDome
JS Tag OptionsJSON object describing JS Tag options (by default { sfcc: true })
JS Tag URLURL to retrieve the DataDome JS Tag file (by default https://js.datadome.co/tags.js)
JS Tag EndpointDataDome JS Tag API endpoint (by default https://api-js.datadome.co/js/)
DataDome Excluded Request RegexUsed to exclude static assets or pipelines from detection
DD Allowed Request RegexDefines the pipelines to be included in the detection. Empty means "All"
DataDome Service ProtocolThe protocol (HTTP or HTTPs) to use to access the DataDome service
DataDome Info Log EnabledEnables/disables "Info" level logs
DataDome Debug Log EnabledEnables/disables "Debug" level logs
DataDome Allowed Redirect originsOptional. The list of origins (separated by a "," .Eg: "https://mydomain.com, http://otherdomain.com") that are allowed in the redirect url of the CAPTCHA. By default, only the current origin is allowed.

Note: The default values are already set. Therefore, you don’t need to change any values unless otherwise needed.

Caching policy

DataDome module doesn't change the default caching policy.

However, the module adds a tracking cookie on all requests, which may impact some custom policies.

Feel free to contact our support for any specific needs.

First party JS tag

If you need to setup DataDome JS tag as a first party, please contact our support team and use the following two settings to setup the tag:

  • JS Tag URL
  • JS Tag Endpoint

Migrating from version 19.x to version 20.x

When migrating from DataDome cartridge you must know the cartridge names to be changed to comply with the new SFCC best practices.
Be sure your cartridge registrations are migrated from this:

1911

SiteGenesis version 19.x

1909

SFRA version 19.x

to this:

1144

SiteGenesis version 20.x

1039

SFRA version 20.x

By clicking on the Code version you will have a the WebDAV url. At the root of your Code version, please upload datadome_sfra_changes datadome_sg_changes and int_datadome folders.