The Empathy Platform Pixel app is a VTEX IO app that injects the Empathy Platform Interface X search widget into your VTEX storefront. Once installed and configured,the app provides the following out of the box:

• Search UI injection: loads the Interface X search widget into your store via VTEX Pixel, without modifying your store theme directly.
• Cart and wishlist integration: wires shopper interactions in the search UI, such as adding or removing products, to your store's cart and wishlist.
• Analytics event tracking: sends custom Google Analytics 4 (GA4) events for every cart and wishlist interaction triggered from search results, so you can track search-driven conversions in your GA4 dashboard.

This guide walks you through cloning and configuring the Pixel app, adding the Empathy search components to your store theme, and connecting the widget to your VTEX cart and wishlist.

Steps to getting started with the search widget

1. Set up and install the Pixel app
2. Wire up search interactions to your VTEX store
3. Verify your integration

warning

This app is maintained separately from the core Empathy Platform product. Steps and configuration options may vary in later versions of the app. Always check the original Empathy Platform Pixel app repository documentation (opens new window) and VTEX app documentation (opens new window) (v0.0.6) for the most up-to-date information

Before you begin

Make sure you have the following before installing the Pixel app:

• The Empathy Platform Feed connector installed, configured, and with at least one full catalog update completed.
• The Empathy Platform script URL (app.js) for your client and environment. Contact your Empathy Platform key account manager if you haven't received it.
• VTEX Toolbelt CLI (opens new window) installed and authenticated against your VTEX account.
• A GitHub account to fork the Empathy Platform Pixel app repository (opens new window).

Setting up the Empathy Platform Pixel app

The Empathy Platform Pixel app is designed to run as a private application under your VTEX account. Unlike the Feed connector, you can't install it directly from the VTEX app store. You need to fork and clone the repository, configure it for your account, and publish it yourself to install it into your VTEX storefront.

The setup process covers the following main steps:

1. Clone the repository
2. Configure the app
3. Add the search components
4. Test and publish
5. Install and verify

Cloning the repository

To get started, first authenticate into your VTEX account, fork the archetype, and clone it locally:

1. Authenticate into your VTEX account using VTEX Toolbelt CLI.

   vtex login {your-account-name}
   

2. Test your connection. If you're correctly logged into VTEX, your username and workspace show up.

   vtex whoami
   

3. Fork the Pixel app repository from GitHub following this URL: https://github.com/empathyco/empathy-pixel-app-archetype/fork.

4. Clone your fork and navigate into the project folder.

   git clone https://github.com/{your-github-username}/empathy-pixel-app-archetype
   cd empathy-pixel-app-archetype
   

Configuring the Pixel app

Once the repository is forked and cloned into your project, set your vendor, update the Empathy script URL, and configure the widget initialization parameters:

1. Configure your vendor account name. Open manifest.json in the root of the project and set the vendor field to your VTEX account name.

   // manifest.json
   {
     "name": "empathy-pixel-app",
     "vendor": "{your-account-name}",
     "version": "0.0.x"
   }
   

   Setting the vendor field changes the app ID to {your-account-name}.empathy-pixel-app, scoping it to your account.

   Version control

   If you want to keep the app's versioning control, set the version field to 0.0.1.

   App dependencies

   The manifest.json file also declares the dependencies required by the Empathy Platform Pixel app. These are installed automatically when you install the app. Go to the Installing and verifying step for the full dependency list.

2. Define the Empathy script. Open pixel/head.html and replace the script src with the Empthy script URL provided by the Empathy Platform team.

   <script src="https://x.empathy.co/x-{INSTANCE}/app.js" type="module"></script>
   

   Where instance is the instance identifier assigned to your store in Empathy Platform. You can find it in the Empathy Platform Playboard's Instance Management Console (IMC) (top right corner).

   
   

   For example:

   <script src="https://x.empathy.co/x-myVTEXstore/app.js" type="module"></script>
   

3. Configure the app's initizaliation object. Open react/Components/EmpathySearchbar/index.tsx and update the initX configuration object to match your store's settings so the Pixel app loadd the Interface X widget by injecting a script tag into the store's <head>:

   • instance: Define the instance identifier assigned to your store in Empathy Platform.
   • lang: Set the language code that matches your store's locale.
   • currency: Set the currency code used in your store.
   • scope: Choose desktop or mobile depending on your store's target device.
   • callback: Review the callbacks object and remove any callbacks for features your store doesn't use. See Wring up search interactions to your VTEX store for details.

       (window as any).initX = {
        instance: "{instance}",      // Instance identifier assigned to your store in Empathy Platform
        lang: "es",                  // Language code: "es", "en", "pt", etc.
        scope: "desktop",            // "desktop" or "mobile"
        currency: "MXN",             // Currency code: "EUR", "USD", "MXN", etc.
        consent: false,
        viewMode: "embedded",
        callbacks: { ... }
      };
   

Adding the search components to your store theme

The Pixel app provides two components that you need to add to your VTEX store theme: empathy-searchbar and empathy-results. When the app is already configured, declare these components in your store theme:

1. Add the empathy-searchbar and empathy-results components to your VTEX store theme. You can place them independently across different templates depending on your store's layout:

   • empathy-searchbar: Renders the search box and initializes the Interface X widget. Add it to the header or any template where you need to place the search bar.
   • empathy-results: Renders the search results overlay. Add it to the templates where you want results to appear, such as the homepage, search page, or category page.

   How empathy-results component works

   The empathy-results component renders a <div>`` container withdata-teleport="empathy-results-container"`. When a shopper performs a search, Interface X injects the results into this container and automatically hides all its sibling elements in the DOM, so the results grid embeds into the page content without additional CSS.

   For this to work correctly, declare the page content you want hidden during a search as children of empathy-results, thus turning them into sibling elements of the search results. Elements you want to keep visible, such as footer components or chatbots, can stay outside the children declaration. See search components integration examples below for reference configurations.

   Example - Adding the search bar to the header and results to the homepage

   This example shows how to add the search box to the header and the results grid to the homepage, declaring the content to hide as its children:

   Header - before:

   {
     "header": {
       "blocks": [
         "header-layout.desktop"
       ]
     },
     "flex-layout.row#desktop": {
       "children": [
         "logo",
         "minicart"
       ]
     }
   }
   

   Header - after:

   {
     "header": {
       "blocks": [
         "header-layout.desktop"
       ]
     },
     "flex-layout.row#desktop": {
       "children": [
         "logo",
         "empathy-searchbar",
         "minicart"
       ]
     }
   }
   

   After adding empathy-searchbar to the header, you now find the search box between the store logo and the cart icon up in the header section.

   Homepage template - before:

   {
     "store.home": {
       "blocks": [
         "flex-layout.row#hero",
         "flex-layout.row#integrate",
         "flex-layout.row#promises"
       ]
     }
   }
   

   Homepage template - after:

   {
     "store.home": {
       "blocks": [
         "empathy-results",
         "flex-layout.row#promises"
       ]
     },
     "empathy-results": {
       "children": [
         "flex-layout.row#hero",
         "flex-layout.row#integrate"
       ]
     }
   }
   

   After integrating empathy-results, the flex-layout.row#hero and flex-layout.row#integrate components are hidden when results appear, but flex-layout.row#promises remain visible as it's been declared outside empathy-results children.

   Example - Adding both components to the search page

   This example shows how to add both the search box and the results to the same search page template:

   Search page template - before:

   {
     "store.search": {
       "blocks": [
         "flex-layout.row#products"
       ]
     }
   }
   

   Search page template - after:

   {
     "store.search": {
       "blocks": [
         "empathy-searchbar",
         "empathy-results"
       ]
     },
     "empathy-results": {
       "children": [
         "flex-layout.row#products"
       ]
     }
   }
   

   Here, when integrating empathy-searchbar and empathy-results in the same page template, the original search page content is declared as children of empathy-results and hidden automatically when the search results appear.

Testing and publishing the app in VTEX

After integrating the search components, you test the app locally before publishing to catch issues early. Then publish it to the VTEX registry to make it available in your account.

If something isn't working, check the VTEX integration troubleshooting before proceeding.

1. Test the app locally to verify it loads correctly in your VTEX store before publishing.

   vtex link
   

2. Publish the app to the VTEX registry to make it available in your account.

   vtex publish
   

Installing and verifying the app's performance

Install the Empathy Platform Pixel app published in your workspace and check it's running:

1. Install the app published version in your current workspace.

   vtex install
   

2. Verify the installation.

   vtex ls | grep pixel-app
   

App dependencies

The following dependencies are installed automatically with the Empathy Platform Pixel app:

• vtex.pixel-interfaces
• vtex.order-items
• vtex.order-manager
• vtex.styleguide
• vtex.pixel-manager
• vtex.session-client
• vtex.wish-list (Optional. Only required if your store includes wishlist)

Remove vtex.wish-list from manifest.json before publishing if your store doesn't use wishlists. See Connecting the wishlist for more information.

Wiring up search interactions to your VTEX store

The Empathy Platform Pixel app connects shopper interactions in the search UI to your store's cart and wishlist through a set of callbacks defined in the initX configuration. Each callback maps a specific search interaction to a VTEX operation.

Note that each callback uses the window.InterfaceX.setSnippetConfig method to update the widget's snippet configuration dynamically after initialization. So, it keeps the Interface X widget in sync with the current state of your store without requiring a full initialization, for example, updating the cart contents or wishlist items after a shopper interacts with search results. For more information, check the snippet configuration parameters.

Connecting the cart

The Empathy Platform Pixel app uses the VTEX Order Manager and Order Items APIs to add and remove products from the cart when shoppers interact with search results. The following callbacks handle cart operations:

Callback	Triggered when...
UserClickedResultAddToCart	A shopper adds a product without variants to the cart.
UserClickedResultVariantAddToCart	A shopper adds a product with variants to the cart.
UserClickedResultRemoveFromCart	A shopper removes a product without variants from the cart.
UserClickedResultVariantRemoveFromCart	A shopper removes a product with variants from the cart.

Since the cart state stays in sync with the Interface X widget through setSnippetConfig, call the setSnippetConfig method to update the widget with the current cart contents after each operation:

(window as any).InterfaceX.setSnippetConfig({
  cart: {
    "{sku-id}": 2,  // SKU ID mapped to quantity
    "{sku-id}": 1
  }
});

Example:

(window as any).InterfaceX.setSnippetConfig({
    cart: { 
        "123": 2,      
        "456": 1 
    },           
});

note

Remove the variant callbacks if your store's products don't have variants, and remove the cart callbacks entirely if your store doesn't support add-to-cart from search results.

Connecting the wishlist

Wishlist integration is optional and requires the vtex.wish-list app to be installed in your store. The UserClickedResultWishlist callback fires when a shopper selects the wishlist icon on a search result, and uses GraphQL to add or remove the product from their wishlist.

Since the wishlist state stays in sync with the Interface X widget through setSnippetConfig, call the setSnippetConfig method to update the widget with the current wishlist contents after each operation:

(window as any).InterfaceX.setSnippetConfig({
  wishlist: ["{sku-id}", "{sku-id}"]  // Array of SKU IDs currently in the wishlist
});

Example:

(window as any).InterfaceX.setSnippetConfig({
  wishlist: ["789", "101112"],  
});

note

If your store doesn't use wishlists, remove the UserClickedResultWishlist callback from initX and remove vtex.wish-list from the app's dependencies in manifest.json.

Verifying the integration

Once the app is installed and configured, verify that the widget loads and operates correctly before going live.

Open your browser console and run the following checks:

1. Verify that the Empathy Interface X widget loaded correctly:

   console.log(window.InterfaceX);
   

2. Check the current widget configuration:

   console.log(window.InterfaceX.getSnippetConfig());
   

3. Check the cart state synced to the widget:

   console.log(window.InterfaceX.getSnippetConfig()?.cart);
   

4. Check the wishlist state synced to the widget:

   console.log(window.InterfaceX.getSnippetConfig()?.wishlist);
   

5. Check that GA4 events are being pushed to window.dataLayer:

   console.log(window.dataLayer);
   

GA4 analytics events

Empathy Platform Pixel app pushes the following GA4 events to window.dataLayer automatically. Use them to verify that search-driven interactions are tracked correctly in your GA4 dashboard:

Event	Fired when...
add_to_cart_empathy	A shopper adds a product from search results.
remove_from_cart_empathy	A shopper removes a product from search results.
add_to_wishlist_empathy	A shopper adds a product to their wishlist from search results.

Each event includes the search term (search_term) that generated the interaction and the product data (ecommerce.items[]) in GA4 ecommerce item format.

---

Next steps

The Empathy Platform search widget is now integrated into your VTEX store. Run through the pre-launch checklist before going live.

If something isn't working as expected, check the VTEX integration troubleshooting for a full list of common issues before going live.