Integrate Interface X Archetype into an existing website

10 min read

In this tutorial, you'll learn how to integrate the Interface X Archetype project in your commerce store in a matter of minutes. You can use the X Archetype as is or you can extend the search and discovery interface experience to meet your business needs.

To integrate the Interface X Archetype layer in your commerce store, just load the generated Interface X JavaScript file and initialize it.

IMPORTANT

If the X Archetype script is hosted by Empathy, all the X resources are provided by a CDN through the following environment URLs:

Production: https://x.empathy.co/{INSTANCE}/app.js
Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

Where {INSTANCE} is the name of your commerce store. If you require any assistance, contact Empathy Support.

Depending on your business needs, Interface X supports two initialization types:

Automatic initialization
On-demand initialization

Frameworks & libraries integration

You can integrate the X Archetype into any existing website regardless of the technology used (i.e. React, Vue, Svelte, etc.), as the bundle includes all the dependencies you need for a correct implementation.

Initializing the Interface X project automatically

Automatic initialization is the easiest way to integrate the Interface X project in a website.

Steps to initialize the project automatically

Configure the JavaScript snippet to define either an initialization object or a function.
Load and initialize the Interface X script.

Configuring the snippet

First, add the JavaScript snippet configuration to define multiple initialization options, i.e. the API to use, the language or currency to display, or even the tagging parameters to collect search-related data to generate conversational search features and analytics.

Depending on whether you are retrieving static or dynamic configuration values in your snippet configuration, you define an object or a function to initialize Interface X:

To retrieve static configuration values, define an initialization object as follows:

window.initX = {
  instance: 'my-store',
  scope: 'desktop',
  lang: 'en',
  currency: 'EUR',
  consent: false
};

To retrieve configuration values dynamically, use an initialization function:

window.initX = function () {
  return {
    instance: 'my-store',
    env: location.href.includes('.pre.') ? 'staging' : undefined,
    scope: 'web',
    lang: localStorage.get('lang'),
    currency: localStorage.get('currency'),
    consent: localStorage.get('consent')
  };
};

note

You can change the snippet configuration values once the project is deployed. Use the /x-archetype/public/snippet-script.js file to perform hot changes for the snippet parameters. For more information on the supported parameters, check out Snippet configuration.

Loading the script

Once the snippet configuration is ready, add the Interface X script to your webpage. The script is hosted in a URL with the following syntax:

Production: https://x.empathy.co/{INSTANCE}/app.js
Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

For example, to load the production version script for the instance my-store, you need to add the following scripts to your HTML:

<script>
  window.initX = {
    instance: 'my-store',
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false
  };
</script>
<script src="https://x.empathy.co/my-store/app.js" type="module"></script>

In the case you want to load the script for the staging environment, you just modify the script attribute src so that it points to the staging environment as follows:

<script>
  window.initX = {
    instance: 'my-store',
    env: 'staging', // By removing this param you would be using a production API with the staging version of Interface X
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false
  };
</script>
<script src="https://x.staging.empathy.co/my-store/app.js" type="module"></script>

Thus, when the Interface X JavaScript file is loaded, it retrieves the configuration from the defined object or function.

Initializing the Interface X project on demand

On-demand initialization allows you to control when Interface X is loaded.

Steps to initialize the project on demand

Load the Interface X script.
Initialize Interface X.

Loading the script

Add the Interface X script hosted in a URL with the following syntax:

Production: https://x.empathy.co/{INSTANCE}/app.js
Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

For example, to load the production version script for the instance my-store, you need to add the following script to your HTML:

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

In the case you want to load the script for the staging environment, you just modify the script attribute src so that it points to the staging environment as follows:

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

Initializing Interface X

Since no initialization configuration is defined when loading the script, you need to invoke the initialization function created automatically in the X API (opens new window) object to provide the initialization options:

<script src="https://x.empathy.co/my-store/app.js" type="module"></script>
<script>
  window.InterfaceX.init({
    instance: 'my-store',
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false
  });
</script>

For this example, the initialization function is called immediately after loading the script, but it can be called at any time. Note that you need to call this function only once.

interact

Check out the X API section to learn more about the functions and parameters supported.

Notes on X Archetype integration

To successfully integrate Interface X in your commerce store using the X Archetype, check out further information about:

Initialization options supported in snippet configuration
Callbacks and X event types available to subscribe to when initializing
Functions supported by the X API object to initialize Interface X
Notes on how to set up the preview of query results for determined queries at the pre-search stage
Tracking options for add to cart events from product detail pages

Snippet configuration

The snippet configuration (opens new window) allows you to configure multiple initialization options for the Interface X project such as language, currency, and shopper's personal data consent. The snippet configuration supports the following configuration parameters:

Parameter	Type	Description
`instance`	`string`	Required. ID of the API client instance. It's provided by Empathy.
`env`	`staging`	Optional. API environment to use. Note that if you do not declare this parameter, you'll use the production API. Instead, use `env: 'staging'` to point to the staging API.
`scope`	`string`	Optional. Context where the search interface is executed, i.e. `mobile`, `mobile-app`, `tablet`, `desktop`.
`lang`	`string`	Required. Language to use. By default, it's used for both the interface messages and the API requests.
`uiLang`	`string`	Optional. Language to use for the interface messages only.
`consent`	`boolean`	Required. Determines whether the shopper has accepted the use of cookies so that the `sessionId` is sent to the Empathy's Search and Tagging APIs or not.
`documentDirection`	`'ltr'` \| `'rtl'`	Optional. Writing direction script that the X Components should, i.e. left-to-right or right-to-left.
`currency`	`string`	Required. Currency identifier to configure how prices are displayed.
`callbacks`	`Record<XEventName, (payload: XEventPayload<Event>, metadata: WireMetadata) => void`	Optional. Callback record where the key is the event to listen and the value is the callback to be executed whenever the event is emitted. E.g. to listen to the `UserAcceptedAQuery` event: `{ UserAcceptedAQuery({ eventPayload }) { console.log('UserAcceptedAQuery', eventPayload); }`
`isSpa`	`boolean`	Optional. Enables single-page application model. You set it to `true` when the X Archetype runs on top of a SPA website.
`filters`	`string[]`	Optional. Filters to be applied at the start of the application and start to searching with those filters selected.
`queriesPreview`	`QueryPreviewInfo[]`	Optional. List of queries to preview. Every query defined includes a preview of related product results before shoppers type a search term in the search box. E.g. to preview results for the queries `backpacks` and `watches`, you add the following: `[{query: "backpack", title: "Back to school"}, {query: "watch", title: "Get on time"}]`. See Dynamic query results preview for more information.
`<extra parameters>`	`any`	Optional. Any other parameters to sent to the API calls directly. E.g. to filter the search catalogue with a warehouse parameter, you add `warehouse: <your-warehouse-identifier>` to the snippet configuration.

Consent parameter

When the consent parameter is set to false, the sessionId is not generated nor sent to the Tagging API. Only shoppers' behavioral data (wisdom of the crowd) is inferred from the current session. The consent parameter is set to true as soon as the shopper accepts the use of cookies. If page reload is not triggered after accepting cookies, update the consent parameter (window.initX.consent = true) to start tracking the current session.

Although cookie acceptance is bound to the generation of the sessionId in local storage, Empathy does not use any cookies in its libraries.

The sessionId lasts until there are 30 minutes of inactivity. However, every time the shopper interacts with the commerce search (e.g. queries, clicks, etc.), the session expiration time is reset by adding 30 minutes from the time of that interaction. After 30 minutes of shopper inactivity, a new sessionId is generated.

Callbacks and Interface X events types

You can use a callback to subscribe to specific X events types to perform particular actions when triggered.

For example, you subscribe to the UserClickedResultAddToCart event to add a product result to the shopping cart:

<script src="https://x.empathy.co/my-store/app.js" type="module"></script>
<script>
  window.InterfaceX.init({
    instance: 'my-store',
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false,
    callbacks: {
      UserAcceptedAQuery: query => {
        doSomethingInWebApp(query);
      },
      UserClickedResultAddToCart: result => {
        addToCartInWebApp(result);
      }
    }
  });
</script>

Interface X is built on an event-based architecture. There are more than one hundred of events available to subscribe to via callbacks to trigger different actions in your app. Check out the complete X events types list (opens new window) in the open source repository in GitHub.

X events types can be triggered from different modules in the X Components project. However, every module has its own sort of components (e.g. Empathize X events, Search Box X events, etc.). See the corresponding events.types.ts file for each module in the X Components library in GitHub (opens new window).

X API

The X API (opens new window) object allows your commerce store to communicate with Interface X. It supports multiple functions to integrate Interface X in your website. You can access these functions inside the window.InterfaceX object.

Function	Parameters	Description
`init`	snippet configuration params - Required. Initialization options	Initializes Interface X on demand.
`search`	`query` - Optional. Query to open Interface X	Executes Interface X and triggers a search with the given query.
`close`	none	Closes Interface X search layer.
`getSnippetConfig`	none	Returns the current initialization options.
`setSnippetConfig`	snippet configuration params - Required. Initialization options	Changes initialization options so that all components react to the changes, i.e. changing both search engine and language without reloading the page.
`addProductToCart`	`productId` - Optional. Id of the product added to cart	Sends tracking of the `AddToCart` event to the Empathy Tagging microservice for the product displayed on screen. This function is called from the product detail page (PDP) when the shopper clicks on the add-to-cart button. If the `productId` is not provided, the URL detects whether the shopper found the product via a search session or not.

Dynamic query results preview

The queriesPreview parameter settings can be changed to dynamically preview product results from the queries you define according to your brand's strategy.

You may set the queriesPreview in two ways:

In the initialization object as parameter.
Later on , using the setSnippetConfig function in the X API object to determine the queries to be previewed dynamically depending on the section the shopper is visiting in your commerce store, for instance, or any other scenario.

The following example shows you how to change dynamically the preview of query results in the kids and adult sections:

<script>
  if (yourCommerceStoreEnvironment.section === 'kids') {
    InterfaceX.setSnippetConfig({
      queriesPreview: [
        {
          query: 'backpack',
          title: 'Back to School!'
        },
        {
          query: 'pencil',
          title: 'Write with style!'
        }
      ]
    });
  } else if (yourCommerceStoreEnvironment.section === 'adult') {
    InterfaceX.setSnippetConfig({
      queriesPreview: [
        {
          query: 'watch',
          title: 'Get on time!'
        }
      ]
    });
  }
</script>

Adding filters

The queriesPreview accept additional parameters that allow to filter the result set. See the following example:

<script>
  InterfaceX.setSnippetConfig({
    queriesPreview: [
      {
        query: 'backpack',
        title: 'Back to School!',
        filters: ['brand:acme', 'collection:summer']
      }
    ]
  });
</script>

note

The syntax to each filter is the same one as the one sent to the search request when selecting a filter in the interface.

Adding extra params

On top of that, extra parameters can be added to the search request of the queriesPreview, for instance:

<script>
  InterfaceX.setSnippetConfig({
    queriesPreview: [
      {
        query: 'backpack',
        title: 'Back to School!',
        extraParams: {
          sort: 'price desc'
        }
      }
    ]
  });
</script>

Tracking events for add to cart on product detail pages

Empathy Platform Interface X allows you to track shoppers' add-to-cart interactions from any product detail page (PDP) in your commerce store, regardless of whether your commerce store is running on a single-page application or not.

Tracking add-to-cart events on non-SPA webpages

To track your shoppers' add-to-cart interactions from any PDP based on a non-spa structured webpage, follow these steps:

Add the productId parameter when initializing the script.

window.InterfaceX.init({ instance: "instanceName", lang: "es", documentDirection: "ltr", scope:
'desktop', currency: "EUR", consent: true, isSPA: false, queriesPreview: [] { query: 'coats',
title: 'Winter Coats' } ], callbacks: { UserClickedAResult: function(a, b, e, t) {} }, productId:
'11776347-ES' // Add this parameter })

Call the InterfaceX.addProductToCart('11776347-ES') function to track the event when the add-to-cart button is clicked.

yourCommerceStoreEnvironment.addToCartButton.addEventListener('click', () =>
InterfaceX.addProductToCart('11776347-ES'); );

Tracking add-to-cart events on SPA webpages

To track your shoppers' add-to-cart interactions from any PDP based on a SPA structured webpage, follow these steps:

Call the InterfaceX.bus.emit('PDPIsLoaded') function any time a new PDP-type page is loaded.

if (yourCommerceStoreEnvironment.isPDP && window.initX.isSpa) {
InterfaceX.bus.emit('PDPIsLoaded') }

Call the InterfaceX.addProductToCart() function to track the event when the add-to-cart button is clicked:

yourCommerceStoreEnvironment.addToCartButton.addEventListener('click', () =>
InterfaceX.addProductToCart(); );