Integrate Interface X Archetype into an existing website

Integrate Interface X Archetype into an existing website

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:

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

  1. Configure the JavaScript snippet to define either an initialization object or a function.
  2. 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',
  env: 'live',
  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' : 'live',
    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: https://x.<environment?>.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',
    env: 'live',
    scope: 'desktop',
    lang: 'en',
    currency: 'EUR',
    consent: false
  };
</script>
<script src="https://x.empathy.co/my-store/app.js"></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: 'live', // Note that here you are 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"></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

  1. Load the Interface X script.
  2. Initialize Interface X.

Loading the script

Add the Interface X script hosted in a URL with the following syntax: https://x.<environment?>.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"></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"></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"></script>
<script>
  window.X.init({
    instance: 'my-store',
    env: 'live',
    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:

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 options:

Name Type Description
instance string Required. ID of the API client instance. It's provided by Empathy.
env 'live' | 'staging' Optional. API environment to use. You can use the Interface X production version with the staging API, and vice versa.
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 frontend and the API requests.
searchLang string Optional. Language to use for the API requests 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.
<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.

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"></script>
<script>
  window.X.init({
    instance: 'my-store',
    env: 'live',
    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.

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.
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 (opens new window) 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.
We are cookie-less

This is a cookie-free area. Who needs cookies when you can have trust? Feel free to browse our site and the only cookies you need to worry about are the edible kind.