Interaction Studio: Interaction Definition

Understanding "Interaction Definitions" in Salesforce Interactions SDK

Overview:

The Salesforce Interactions SDK is used to track specific user interactions on your website, particularly those related to catalog items, shopping carts, and orders. These interactions are identified using reserved names that are predefined in the SDK. These reserved names help Salesforce Personalization (formerly Evergage) understand how to process and handle the event data.

Key Concepts:

1. Interactions and Reserved Names:

   • Interactions: These are specific user actions on your website, such as adding an item to a cart, viewing a product, or placing an order.

   • Reserved Name Property: Each interaction has a name property, which is a reserved keyword recognized by Salesforce Personalization. This reserved name tells the system how to process the event data.

2. Namespaces:

   • SalesforceInteractions: This is the namespace used in the Salesforce SDK for tracking interactions. The interactions here are called Interactions.

   • Evergage: In the older Evergage SDK, similar interactions are referred to as Item Actions.

3. Event API Integration:

   • The SDK allows you to send interaction events via the Event API. These events are often triggered by user actions, such as clicking a button on your website.

   • Example: In the provided code sample, a listener is set up to detect when a user clicks an "Add to Cart" button. When this click is detected, an "AddToCart" event is sent to Salesforce Personalization.

4. Interaction Objects:

   • SalesforceInteractions.CatalogObjectInteractionName: Tracks interactions related to catalog objects, like viewing a product.

   • SalesforceInteractions.CartInteractionName: Tracks interactions related to the shopping cart, like adding or removing items.

   • SalesforceInteractions.OrderInteractionName: Tracks interactions related to orders, such as placing an order or canceling it.

Example Code Breakdown:

listeners: [

    SalesforceInteractions.listener("click", ".add-to-cart", () => {

        let lineItem = SalesforceInteractions.mcis.buildLineItemFromPageState("select.quantity-select option:checked");

        SalesforceInteractions.sendEvent({

            interaction: {

                name: SalesforceInteractions.CartInteractionName.AddToCart, // Reserved interaction name for "Add to Cart"

                lineItem: lineItem // The specific item being added to the cart

            }

        });

    })

],

• SalesforceInteractions.listener("click", ".add-to-cart", ...):

  • This sets up a listener to detect when the user clicks an element with the class .add-to-cart.

• SalesforceInteractions.mcis.buildLineItemFromPageState(...):

  • This method extracts information about the product being added to the cart, such as quantity and product ID, based on the current state of the page.

• SalesforceInteractions.sendEvent({ interaction: { name: SalesforceInteractions.CartInteractionName.AddToCart, ... } }):

  • This sends an "Add to Cart" event to Salesforce Personalization, using the reserved interaction name AddToCart.

Reserved Interaction Values:

• SalesforceInteractions.CatalogObjectInteractionName: Used for interactions with catalog objects (e.g., viewing or searching for a product).

• SalesforceInteractions.CartInteractionName: Used for interactions with the shopping cart (e.g., adding, removing, or updating items in the cart).

• SalesforceInteractions.OrderInteractionName: Used for interactions related to orders (e.g., placing or canceling an order).

Understanding "Special Interaction Values" in Salesforce Interactions SDK

Overview:

In the Salesforce Interactions SDK, special interaction values are used to handle specific scenarios where a user might be interacting with multiple items on a webpage simultaneously, such as when they are viewing a product in a "Quick View" window while browsing a product category. These special interactions help track user behavior more accurately by managing timers that monitor how long a user spends viewing different items.

Key Concepts:

1. Quick View vs. Regular View:

   • Quick View: This refers to a scenario where a user is viewing a product in a pop-up or overlay window while still technically being on the category page.

   • Regular View: This refers to viewing a product by navigating to its dedicated page, typically stopping any timer associated with viewing the category.

2. Timers for View Duration:

   • Background Item: The item or page that the user was viewing before opening the Quick View. In the context of an e-commerce site, this is usually the category or product listing page.

   • Foreground Item: The item that the user is currently viewing in Quick View. This is typically a specific product.

3. Special Interaction Values:

   • SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject:

     • This starts a timer for the "foreground" item (e.g., a product) when the user views it in Quick View. It simultaneously stops the timer for the "background" item (e.g., the category).

   • SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject:

     • This stops the timer for the "foreground" item when the user exits the Quick View and resumes the timer for the "background" item.

Example Breakdown:

The provided code sample illustrates how these special interaction values are used on an e-commerce site.

Example 1: Tracking Category Page Views

{

    name: "Category",

    isMatch: () => new Promise((resolve, reject) => {

        let isMatchCat = setTimeout(() => {

            resolve(false);

        }, 50);

        return SalesforceInteractions.DisplayUtils.pageElementLoaded("#product-search-results", "html").then(() => {

            clearTimeout(isMatchCat);

            resolve(SalesforceInteractions.cashDom(".breadcrumb").length > 0);

        });

    }),

    interaction: {

        name: SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject,  // Tracks the view of the category page.

        catalogObject: {

            type: "Category",

            id: SalesforceInteractions.DisplayUtils.pageElementLoaded(".breadcrumb .breadcrumb-item a", "html").then((ele) => {

                return SalesforceInteractions.resolvers.buildCategoryId(".breadcrumb .breadcrumb-item a", 1, null, (categoryId) => categoryId.toUpperCase());

            })

        }

    }

}

• Purpose: This part of the code tracks when a user is viewing a category page.

• Key Elements:

  • isMatch: This function checks if the current page is a category page.

  • SalesforceInteractions.CatalogObjectInteractionName.ViewCatalogObject: This interaction value is used to track the view of the category page.

  • catalogObject.type: Specifies the type of object being viewed (e.g., "Category").

  • catalogObject.id: Identifies the specific category being viewed by resolving its ID.

Example 2: Handling Quick View Events

listeners: [

    SalesforceInteractions.listener("click", ".quickview", (e) => {

        const pid = SalesforceInteractions.cashDom(e.target).attr("href").split("pid=")[1];

        if (!pid) {

            return;

        }

        SalesforceInteractions.sendEvent({

            interaction: {

                name: SalesforceInteractions.CatalogObjectInteractionName.QuickViewCatalogObject,  // Starts the Quick View timer.

                catalogObject: {

                    type: "Product",

                    id: pid

                }

            }

        });

    }),

    SalesforceInteractions.listener("click", "body", (e) => {

        if (SalesforceInteractions.cashDom(e.target).closest("button[data-dismiss='modal']").length > 0) {

            SalesforceInteractions.sendEvent({

                interaction: {

                    name: SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject,  // Stops the Quick View timer.

                }

            });

        } else if (SalesforceInteractions.cashDom(e.target).closest("#quickViewModal").length > 0

            && SalesforceInteractions.cashDom(e.target).find("#quickViewModal .modal-dialog").length > 0) {

            SalesforceInteractions.sendEvent({

                interaction: {

                    name: SalesforceInteractions.mcis.CatalogObjectInteractionName.StopQuickViewCatalogObject,  // Stops the Quick View timer.

                }

            });

        }

    })

]

• Purpose: This part of the code manages Quick View interactions.

• Key Elements:

  • Quick View Start (QuickViewCatalogObject):

    • Triggered when a user clicks on an element with the class .quickview, indicating they want to view a product in Quick View.

    • The timer for the background item (e.g., the category page) is stopped, and a new timer for the foreground item (e.g., the product) starts.

  • Quick View Stop (StopQuickViewCatalogObject):

    • Triggered when the user closes the Quick View (e.g., by clicking a "close" button).

    • The timer for the foreground item stops, and the background item's timer resumes.

Summary:

• Quick View and Stop Quick View interactions allow you to accurately track how long a user views different items when they use features like Quick View on your website.

• Timers: The SDK manages timers to track view duration for both the item being viewed in Quick View (foreground) and the item the user was originally viewing (background).

• Practical Use: These interactions are particularly useful on e-commerce sites where users might want to view product details without leaving the category or search results page.

• Code Implementation: The provided code examples show how to set up these interactions using event listeners that detect user actions like clicking on a Quick View button or closing the Quick View window.

Scenario: Shopping on Amazon

1. Regular View (Browsing a Category or Search Results)

• What You Do: You go to Amazon's homepage, search for "laptops," and start scrolling through the list of laptops in the search results.

• How It's Tracked:

  • Interaction Name: ViewCatalogObject

  • What Salesforce Sees: You're viewing the "Laptops" category page. Salesforce tracks this as you browsing the "Laptops" category.

2. Quick View (Previewing a Product Without Leaving the Page)

• What You Do: As you scroll through the list, you see a laptop that interests you. Instead of clicking on the product link, you hover over it or click a "Quick View" button (if Amazon had this feature). A pop-up appears showing more details about that specific laptop (price, specs, etc.), but you’re still on the search results page.

• How It's Tracked:

  • Interaction Name: QuickViewCatalogObject

  • What Salesforce Sees: You are viewing more details about the laptop in a "Quick View" window. The laptop becomes the "foreground" item (what you're focusing on), while the search results page is the "background" item.

3. Stop Quick View (Closing the Quick View Window)

• What You Do: After looking at the laptop in the Quick View, you decide to close the pop-up and continue browsing the other laptops in the search results.

• How It's Tracked:

  • Interaction Name: StopQuickViewCatalogObject

  • What Salesforce Sees: You’ve closed the "Quick View" pop-up. Salesforce stops tracking the time you were viewing that specific laptop and resumes tracking your activity on the search results page.

4. Regular View (Viewing a Product Page)

• What You Do: Later, you find a laptop that you really like. You click on the laptop's title or image, and Amazon takes you to that laptop's dedicated product page where you can see all the details, reviews, etc.

• How It's Tracked:

  • Interaction Name: ViewCatalogObject

  • What Salesforce Sees: You’re now on the product page for the laptop. Salesforce tracks this as a full product view, where the laptop is now the main focus (no background).

Summary with Amazon

• Browsing Laptops: When you're scrolling through search results or a category like "Laptops," Salesforce uses ViewCatalogObject to track that you're viewing the category page.

• Quick View: If you preview a laptop using a "Quick View" pop-up without leaving the search results page, Salesforce tracks this with QuickViewCatalogObject to note that you’re temporarily focusing on that laptop.

• Stop Quick View: When you close the "Quick View" pop-up and go back to browsing the search results, Salesforce uses StopQuickViewCatalogObject to stop tracking that temporary focus.

• Product Page View: When you click through to a specific laptop’s product page, Salesforce again uses ViewCatalogObject but this time for the individual product, as you’re now fully viewing that item.

This approach allows Salesforce to track exactly what you're focusing on at any given time—whether you're casually browsing, taking a quick look at an item, or fully diving into a product's details.

Best Practices For Using Interactions 

When using interactions, it’s important to keep the following best practices in mind:

• Only track interactions if they're necessary for personalization and targeting. Think about the personalization use cases you wish to execute and only map the interactions required for those specific use cases.

• Map no more than a few thousand unique interactions per dataset. Mapping any more leads to challenges when using the Personalization UI, including difficulties in selecting interactions from dropdown menus and slower report generation.

• Ensure interaction names have values you can reuse across users and sessions.

• When defining interaction names, avoid dynamically populating them to prevent inflated names with unexpected prefixes and suffixes.

• If you dynamically populate interaction names, ensure they stay consistent across sessions for any user.

• Refrain from automatically sending all events from other site analytics tools to Personalization, as it can result in a higher volume of events than necessary for personalization.

• Incorporating dynamic user information in interaction names can cause issues and must be avoided whenever possible.