How to Integrate with Salesforce Commerce Cloud

Overview

The Klaviyo Cartridge and API integration allows websites using Salesforce Commerce Cloud (formerly Demandware) to quickly connect and send both real-time and historic data to Klaviyo. When Salesforce Commerce Cloud (SFCC) is integrated, Klaviyo will start tracking actions people take in real-time like website navigation, search tracking, viewing products, viewing categories, adding items to a cart, checking out, and ordering.

There are three main steps to integrating Salesforce Commerce Cloud (SFCC) with Klaviyo:

1. Installing the Klaviyo Cartridge in SFCC.
2. Adding enablement snippets to SFCC.
3. Enabling the SFCC OCAPI integration in Klaviyo.

This guide covers these steps and the related tasks for integrating SFCC stores.

If you'd like to start by integrating your development environment first, you can create a linked Klaviyo account using the method described here and connect your development environment with that account. We recommend including the word "Dev" or "Staging" in the company name you use when setting up the account in order to better differentiate between the accounts when logged in. 

Cartridge Setup

The Klaviyo cartridge setup consists of three main cartridges due to the nature of SFCC's different infrastructures. These cartridges include:

• int_klaviyo: for SiteGenesis-based websites
• int_klaviyo_sfra: for SFRA-based websites
• int_klaviyo_core: for both types of infrastructure, containing some basic, overlapping functionality

You will only need to use two of the three cartridges provided, int_klaviyo_core and the cartridge specific to the framework of your SFCC website. Both your relevant cartridge and the core cartridge are required for the integration to work correctly.

You can find our cartridges in a zip archive available for download on the Commerce Cloud XChange.

Import the Cartridges

The first step is to import the cartridges in Eclipse so they're available to link with your SFCC instance

1. In Eclipse, navigate to Administration > Import > General > Existing Projects into Workspace.
2. Import the int_klaviyo_core directory using the import wizard.
3. Select the SFCC instance with which to connect the cartridge.
4. Select Properties.
5. Select Project References.
6. Check in the int_klaviyo_core cartridge.
7. Repeat steps 2 through 6 for the other cartridge specific to your framework (either int_klaviyo or int_klaviyo_sfra).

Add the Cartridges to the Cartridge Path

Once the cartridges are imported, they need to be added to the list of cartridges used by your site using SFCC's Business Manager.

• Navigate to Administration > Sites > Manage Sites.
• Select your site.
• Select the Settings tab.
• At the end of the cartridge path input labelled Cartridges, add the names of the imported Klaviyo cartridges with the core cartridge last (either, int_klaviyo:int_klaviyo_core or int_klaviyo_sfra:int_klaviyo_core).
• Click Apply.

Once you've clicked Apply, you should now see the two cartridges at the end of the field labelled Effective Cartridge Path.

Add Services

After importing the cartridges and adding them to the site cartridge path, the Klaviyo service must be added to enable settings configuration for the cartridge. In the root directory of the Klaviyo cartridges zip file is another zip file called metadata.zip. The following directions will reference this zip file.

1. Navigate to Administration > Site Development > Site Import & Export > Services.
2. Upload then import metadata.zip file.
   
   
3. When you're prompted to confirm whether you'd like to import the selected archive, select OK.
   

You should now see the import running under the Status section near the bottom of the page.

You will now have access to a preferences page at Merchant tools > Site Preferences > Custom Preferences > klaviyo.

from which you can manage the following settings:

• Klaviyo Enabled: Must be set to "Yes" to enable cartridge the cartridge
• Klaviyo Private Key: Your Klaviyo Private API Key
• Klaviyo Account: Your Klaviyo Public API Key/Account ID
• Image Type: The product image type you would like the to be used in event data sent to Klaviyo

The metadata.zip file will also create a new service in SFCC. Navigating to Administration > Operations > Services, you should now see a new entry under the Services, Profiles, and Credentials tabs called KlaviyoTrackService, KlaviyoTrackProfile, and KlaviyoTrackCredentials, respectively.

Add Snippets

The last part of the cartridge setup is to add some snippets to website template files in order to enable the cartridge to communicate with the site. These steps differ slightly for Site Genesis (SG) and Storefront Reference Architecture (SFRA) infrastructures so make sure to follow the instructions for your setup.

Site Genesis

1. Add the following code to the bottom of your footer_UI.isml file:

   <isinclude template="klaviyo/klaviyoFooter"/>

2. Include the following in the minicart.isml, cart.isml and any other "cart" isml files the site uses:

   <isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction == 'update'}">
     <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
   </isif>

Storefront Reference Architecture

1. Add the following code to the bottom of your footer_UI.ismlfile:

   <isinclude template="components/footer/klaviyoFooter"/>

2. Add the following code to the AddProduct function in the Cart.js controller file, just before the line with res.json({...});:

   if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
     var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils');
     KlaviyoUtils.trackAddToCart();
   }

Enable OCAPI Integration

Endpoints

In order to integrate with SFCC for product catalog and historic/ongoing order data, Klaviyo makes use of three OCAPI endpoints:

• /order_search: Syncs historical order data to Klaviyo and continues to sync ongoing order events every 30 minutes. The Ordered Product and Placed Order events will sync additional data for segmentation and flow filtering, so is ideal for enhanced personalization not available from the Order Confirmation event.

  For real-time order confirmation emails, use the Order Confirmation event from the cartridge.

• /sites: Allows you to select from which site Klaviyo syncs data during your integration setup.
• /product_search: Connects your catalog to Klaviyo to enable functionality/features including product recommendation blocks in emails.

  If you have a product catalog of greater than 10,000 items, please tell your account representative before integrating your catalog, as the OCAPIs have limits, and you may require a configuration-level setting to limit sync rate.

  Similarly, if you are unable to update your OCAPI to version 18.3, please let us know during integration discussions.

SFCC-side Setup

Before we can communicate with SFCC's OCAPI, some premissions and settings must be set up in SFCC.

1. Navigate to https://account.demandware.com/dw/account/APIAdmin and add an API client for Klaviyo. The API Client ID and password will be required to generate the bearer token for OCAPI.
2. Once the API client is added, navigate to Administration > Site Development > Open Commerce API Settings in the SFCC Business Manager.
3. Add the following snippets, replacing the API version and Client ID. We support API versions 19.5 and above as well as 18.8. Replace CLIENT_ID with the API Client ID generated from the API client setup in the previous step (this should look something like "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").

   If the settings already exist for these APIs, you may only need to add the highlighted sections below to the existing clients JSON array.

   1. Add the following JSON under the type Shop and context Global (Organization Wide), replacing SHOP_API_VERSION with your OCAPI Shop API version, then click Save.

      {
               "_v":"SHOP_API_VERSION",
               "clients":[
                  {
                   "client_id":"CLIENT_ID",
                   "resources":[
                    {
                     "resource_id":"/order_search",
                     "methods":["post"],
                     "read_attributes":"(**)",
                     "write_attributes":"(**)"
                    }
                   ]
                  }
               ]
              }

      
      

      Once added, the settings should appear similar to this:
      

   2. Add the following JSON under the type data and context Global (Organization Wide), replacing DATA_API_VERSION with your OCAPI Data API version, then click Save.

      {
           "_v":"DATA_API_VERSION",
           "clients":[
              {
               "client_id":"CLIENT_ID",
               "resources":[
                {
                 "resource_id":"/product_search",
                 "methods":["post"],
                 "read_attributes":"(**)",
                 "write_attributes":"(**)"
                },
                {
                 "resource_id":"/sites",
                 "methods":["get"],
                 "read_attributes":"(**)",
                 "write_attributes":"(**)"
                }
               ]
              }
           ]
          }

      
      

      Once added, the settings should appear similar to this:
      

Klaviyo-side Setup

Navigate to the SFCC integration page in your account and add the following data:

• Store URL: your website domain (eg. example.com or dev03-na01-example.demandware.net)
• Auth token: create an auth token for this integration that will be used to request a bearer token. The auth token is generated by base-64 encoding the client ID and password joined by a colon (:) (eg. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:password).
• Data API Version: The version of your Data API for which you added access in the SFCC-side Setup step (e.g. v19_10)
• Shop API Version: The version of your Shop API for which you added access in the SFCC-side Setup step (e.g. v19_10)
• Catalog ID: The ID of the SFCC catalog to sync with Klaviyo (eg. * or something more specific like storefront-catalog-en)

Once you've entered these credentials, click the "Click here to retrieve the list of sites" link to retrieve a list of sites on your SFCC instance.

After the sites are retrieved, select the site to integrate with this account and click "Connect to Salesforce Commerce Cloud".

Your integration should now start syncing your order, catalog, and customer data.

Test your SFCC Integration

To test out your cartridge setup, go to your website and follow these instructions:

1. Cookie yourself by adding the url parameter utm_email as your email address to your address bar. For example: https://www.example.com/?utm_email=your@email.com
2. Search your catalog
3. View a category page
4. View a product page
5. Add an item to your cart
6. Place a test order
7. Navigate to your Klaviyo Dashboard's Activity Feed or to the profile of the email you used to cookie yourself, you should see your actions begin to appear as events.

Review and Understand Your Salesforce Commerce Cloud Data

The Salesforce Commerce Cloud integration will enable tracking of the following datapoints:

• Searched Site: Event fired when someone initiates a search. 
• Viewed Product: Event fired when someone views a product page.
• Viewed Category: Event fired when someone views a category page.
• Added to Cart: Event fired when someone adds/modifies their cart.
• Placed Order: Event fired when someone places an order (wholistic order data).
• Ordered Product: Event(s) fired when someone places their order (specific product data).
• Order Confirmation: Similar to Placed Order but fires on the front-end once the checkout is completed.
• Started Checkout: Event fired when someone begins the checkout process.

Additional Resources 

• Getting Started Handbook
• Getting Started Training Recordings