Integrate with Salesforce Commerce Cloud

read
Last updated at:

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-timed 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.

Klaviyo integrates with both SFCC Controller-based Site Genesis (SG) and Storefront Reference Architecture Site Genesis (SFRA). Each framework requires a different cartridge and different snippets described below.

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

When you're ready to start integrating, please reach out to us here to get connected with a representative on our end to review Klaviyo and pass along the cartridge for your framework.

Site Genesis (SG) Cartridge

The cartridge can be added via either Commerce Cloud Studio or Business Manager

Commerce Cloud Studio Cartridge Installation

  1. First, import the cartridge by selecting int_klaviyo on the import screen.
  2. Next, link the cartridge to your sandbox. Select the Salesforce Commerce Cloud connection and select Properties then Project References and check in int_klaviyo.

Business Manager Cartridge Installation

  1. First, navigate to Administration > Import > General > Existing Projects into Workspace.
  2. Select the int_klaviyo directory from provided Klaviyo cartridge.
  3. Install the cartridge.

Add the Cartridge to the Cartridge List

Once the cartridge is imported, it needs to be added to the list of cartridges in your site.

  1. Navigate to the Business Manager: Administration > Sites > Manage Sites.
  2. Select your site then select the Settings tab.
  3. At the end of the cartridge path, add int_klaviyo.

Import services XML file

In order to start tracking events and list signups, you’ll need to import the services file that comes with the cartridge (int_klaviyo\metadata\klaviyo-services.xml) into the Business Manager. This creates the service definitions for the Klaviyo Track API and server-side Lists API.

  1. Navigate to Administration > Operations > Import and Export > Services.
  2. Upload and import the klaviyo-services.xml file.

This will create three services:

  • KlaviyoSubscriptionService
  • KlaviyoTrackService
  • KlaviyoCheckSubscriptionService

For the KlaviyoSubscriptionService and KlaviyoCheckSubscriptionService, replace the ID in the service URL with the Klaviyo List ID that you will be using to subscribe users. For example, the import file will have the service URL as https://a.klaviyo.com/api/v2/list/LIST_ID/members. Replace the LIST_ID with the List ID of your newsletter list in Klaviyo.

Import custom attribute XML file

In order to start tracking events and list signups, you’ll need to import the metadata file (int_klaviyo\metadata\custom_atribute_klaviyo.xml). This creates site-level custom attributes for storing the Klaviyo public and private API keys.

  1. Navigate to Administration > Site Development > Import and Export.
  2. Under the metadata section, upload and import the custom_atribute_klaviyo.xml file.

This creates the following attributes in Site Preferences:

  • Klaviyo Account: This is your public API key used for sending events and profile data.
  • Klaviyo API Key: This is the private API key used for sending list subscriptions.
  • Klaviyo Enabled: This enables the Klaviyo Service.

Storefront Reference Architecture (SFRA) Cartridge

The cartridge can be added via either Commerce Cloud Studio or Business Manager.

Commerce Cloud Studio Cartridge Installation

  1. First, import the cartridge by selecting plugin_klaviyo on the import screen.
  2. Next, link the cartridge to the sandbox. Select the Salesforce Commerce Cloud connection and select Properties. Select Project References and check in plugin_klaviyo.

Business Manager Cartridge Installation

  1. First, navigate to: Administration > Import > General > Existing Projects into Workspace.
  2. Select the plugin_klaviyo directory from provided Klaviyo cartridge.
  3. Install the cartridge.

Add the Cartridge to the Cartridge List

Once the cartridge is imported, it needs to be added to the list of cartridges in your site.

  1. Navigate to the Business Manager: Administration > Sites > Manage Sites.
  2. Select your site then select the Settings tab.
  3. At the end of the cartridge path, add plugin_klaviyo.

Import Services XML File

In order to start tracking events and list signups, you’ll need to import the services file that comes with the cartridge (plugin_klaviyo\metadata\klaviyo-services.xml) into the Business Manager. This creates the service definitions for the Klaviyo Track API and server-side Lists API.

  1. Navigate to Administration > Operations > Import and Export > Services.
  2. Upload and import the klaviyo-services.xml file.

This will create three services:

  • KlaviyoSubscriptionService
  • KlaviyoTrackService
  • KlaviyoCheckSubscriptionService

For the KlaviyoSubscriptionService and KlaviyoCheckSubscriptionService, replace the ID in the service URL with the Klaviyo List ID that you will be using to subscribe users. For example, the import file will have the service URL as https://a.klaviyo.com/api/v2/list/LIST_ID/members. Replace the LIST_ID with the List ID of your Newsletter list in Klaviyo.

Import Custom Attribute XML File

In order to start tracking events and list signups, you’ll need to import the metadata file (plugin_klaviyo\metadata\custom_atribute_klaviyo.xml). This creates site-level custom attributes for storing the Klaviyo public and private API keys.

  1. Navigate to Merchant Tools > Administration >Site Development->Import and Export.
  2. Under the metadata section, upload and import the custom_atribute_klaviyo.xml file.

This creates the following attributes in Site Preferences:

  • Klaviyo Account: This is your public API key used for sending events and profile data.
  • Klaviyo API Key: This is the private API key used for sending list subscriptions.
  • Klaviyo Enabled: This enables the Klaviyo Service.

Add Integration-Enablement Snippets

Site Genesis Installation

  1. Add the following code to the end of your minicart.isml file: 
    <isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction == 'update'}">
<isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>
  2. Add  the following code to your footer_UI.isml file after the includes for jquery-1.11.1.min.js & jquery-ui.min.js: 
    <script src="${URLUtils.staticURL('/js/klaviyoFooterUtils.js')}"></script>
     
  3. Add the following code to the end of your footer_UI.isml file: 
    <isinclude
url="${URLUtils.url('Klaviyo-RenderKlaviyo',
'title', request.pageMetaData.title,
    'pagecontexttype', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.type : null,
      'pagecontexttitle', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.title : null,
      'searchterm', request.httpParameterMap.q.stringValue,
      'searchresultscount', (!empty(pdict.ProductSearchResult) ? ''+pdict.ProductSearchResult.count : null),
      'productid', (!empty(pdict.Product) ? pdict.Product.ID : null),
      'pagecgid',  request.httpParameterMap.cgid.stringValue,
      'orderno', (!empty(pdict.Order) ? pdict.Order.orderNo : null)
)}" />
     
  4. Change the storefront controllers cartridge name to your cartridge name wherever referenced in the Klaviyo.js and EmailUtils.js files. For example, in line 5 of the Klaviyo.js file, replace the app_controllers with your controller cartridge name.

Storefront Reference Architecture Installation

  1. Add the following code to the AddProduct function in the Cart.js controller file, just before the res.json({……}); 
    if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
    var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils');
    KlaviyoUtils.trackAddToCart();
   }
  2. Add the following code to the end of pageFooter.isml file: 
    <isscript>
var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils');
var context = KlaviyoUtils.getContext(); 
</isscript>
<isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyo',
'title', request.pageMetaData.title,
      'pagecontexttype', (!empty(context)) ? ''+context : null,
     'pagecontexttitle', ('pageContext' in this && !empty(pageContext)) ? ''+pageContext.title : null,
      'searchterm', request.httpParameterMap.q.stringValue,
'searchresultscount', (!empty(pdict.productSearch) ? ''+pdict.productSearch.count : null),
'productid', (!empty(pdict.product) ? pdict.product.id : null),
'pagecgid',  request.httpParameterMap.cgid.stringValue,
'orderno', (!empty(pdict.order) ? pdict.order.orderNumber : null)
)}"/>
  3. Add the following code to homepage.isml and remove the existing subscription form code. The below code will render a subscription form. 
    <iscomponent pipeline ="Klaviyo-FooterSubscribe" />

Enable OCAPI Integration

Endpoints

In order to integrate with SFCC for product catalog and historic order data, Klaviyo makes use of two 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.

  • /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

  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 the OCAPI.
  2. Once the API client is added, navigate to Administration > Open Commerce API Settings (under Site Development) in the SFCC Business Manager.
  3. For the below snippets, expose the API to only a specified client ID by substituting API_VERSION for your OCAPI version (currently 19.5 but we can use 18.8 as well) and replacing the CLIENT_ID with the API Client ID (should look something like "xxxx-xxxx-xxxx-xxxx-xxxx"). Please note that the OCAPI version is reflected in the URL you call as well.

    If the client already has an OCAPI setting, only add the highlighted sections below to the existing clients JSON array.

    Add the following JSON under the type shop and context Global (Organization Wide).
    { 
 "_v":"API_VERSION",
 "clients":[ 
    { 
     "client_id":"CLIENT_ID",
     "resources":[ 
      { 
       "resource_id":"/order_search",
       "methods":[ 
          "post"
       ],
       "read_attributes":"(**)",
       "write_attributes":"(**)"
      }
     ]
    }
 ]
}
    Add the following JSON under the type data and context Global (Organization Wide).
    { 
 "_v":"API_VERSION",
 "clients":[ 
    { 
     "client_id":"CLIENT_ID",
     "resources":[ 
      { 
       "resource_id":"/product_search",
       "methods":[ 
          "post"
       ],
       "read_attributes":"(**)",
       "write_attributes":"(**)"
      }
     ]
    }
 ]
}

Klaviyo-side Setup

  • Navigate directly to the SFCC integration page in your account and add the following data:
    • Store Name: your website domain (example.com)
      • This will be the domain to create the URL from, so for the dev site it would be something like dev03-na01-example.demandware.net
    • Site Id: your demandware store name (usually company name)
    • Auth token: create an Auth Token for this integration that will be used to request a bearer token

dem.png

Test your SFCC Integration

To test out your plugin, 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. Go to the checkout page
  7. Place a test order
  8. 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.
  • Started Checkout: Event fired when someone initiates a checkout.
  • Placed Order: Event fired when the someone places an order (wholistic order data).
  • Ordered Product: Event(s) fired when the someone places their order (specific product data).

In addition to these events, when a customer subscribes to your mailing list via a default SFCC subscription form, they will be added to the list designated by the LIST_ID entered in the Import services XML file step.

Additional Resources 

x
Was this article helpful?
2 out of 2 found this helpful