Overview

This guide is designed to help you integrate your X instance autonomously once it has been fully instrumented.

It provides detail on all the aspects of the integration, including initialization, accepted configurations, analytics and custom code hooking.

Table of contents

Step-by-step guide

Integrating X into your website is a straightforward process that consists of two steps:

1. Loading the X JavaScript resource

2. Initializing X

Loading the X JavaScript resource

The first step for integrating X is loading the X JavaScript resource.

This resource contains a webpack bundle with all the logic, templates, styles and dependencies.

X resources are served by a CDN through the following URLs:

Where {INSTANCE} is a unique identifier provided by EmpathyBroker.

Please note that X and Search are totally independent, which means that staging resources for X will still consume production endpoints by default. We will see how to switch API endpoints later on.

The recommended way to load the X JavaScript resource is by using the following tag in your HTML structure:

<script defer src="https://assets.empathybroker.com/empathyx/{INSTANCE}/app.js"></script>

The defer attribute help to keep it blazing fast by loading the resource asynchronously and without blocking the page load. Once the script is ready, X will automatically call the global initEmpathyX function (see the Initializing X section).

Initializing X

The second step for integrating X is setting up the initEmpathyX callback function. Having a callback function allows X to be loaded and initialized asynchronously.

Inside of the initEmpathyX function, the global EmpathyX object is already available and X is ready to be initialized. To do that, you can use the init function:

function initEmpathyX() {
  EmpathyX.init({
    instance: '{API_INSTANCE}',
    lang: 'en',
    scope: 'mobile',
    currency: 'EUR',
    consent: false
  });
}

Please note that the initEmpathyX function should be defined and available by the time the X resource finishes loading. Also, it is not recommended to call this function manually.

Both the script and the initialization snippet must be present in the HTML of all pages where search is available.

Dynamic configurations

As you can see in the example above, the init function receives a configuration object. This object contains all the dynamic parameters needed by X in runtime.

If you need to change this configuration once X is already initialized, check the Changing the dynamic configuration section.

This is the list of parameters that are currently supported:

Changing the dynamic configuration

There are some situations where the configuration X was initialized with is not valid anymore, for instance when the user changes the language or the currency.

If these actions trigger a page reload on your site, then you are covered: X will initialize again with the correct values. However, if you need to change this configuration on the fly, you can use the EmpathyX.setConfig function.

The EmpathyX.setConfig function receives an object that can contain any of the configurations above. Once executed, it will update the internal configuration and reflect the changes in the interface.

One example of how this function may be used is setting the consent parameter to true as soon as the user accepts the usage of cookies, so that the first session is tracked already:

EmpathyX.setConfig({
  consent: true
});

Event callbacks parameters

This is the list of parameters that are sent in the data object to each callback function in the eventCallbacks object:

Integrating X with Google Analytics and other external analytics platforms

So you are going back from product page. Or opening the URL your best friend just shared with you. Or just reloading the page after your laptop ran out of battery. In all those situations, X needs to be able to store and recreate its previous state. And to do so, it uses the URL query string.

In order to make search as fast and interactive as possible, X does not refresh the page when it modifies the query string. Looking at it from an analytics perspective, this means X will not trigger page view events in platforms that depend on page reload (such as Google Analytics).

If that happens, all those valuable search insights will be lost. What can we do then?

Fortunately, this is easy to prevent by using the eventCallbacks object, which gives you a lot of control on how and when you want to track your data:

eventCallbacks: {
  query: function(data) {
    // Filter out queries that were loaded from the URL, such as page reloads 
    // or going back from product page (those are automatically tracked by GA)
    if (data.origin !== 'linked') {
      // Push the page view event manually in any other situation
      window.dataLayer.push({...});
    }
  }
}

In the example above, we can see one of the most typical approaches:

1. First, we define a custom callback function bound to the query event.
2. Inside of that function, we perform a basic check to filter out all those situations that trigger a page reload (those are automatically tracked by GA).
3. Once we have filtered out the undesired query events (which could contain additional checks if necessary), we manually push the page view event.
   • The specific syntax for pushing the event may vary depending on the platform and its implementation.

Identifying a product page and integrating add2Cart and checkout

EmpathyX public API offers ways to identify a page as a product one and facilitates tracking of add2Cart and checkout.

Identifying a product page

In order to allow EmpathyX identify the current page as a product page, our public API has a productPage function that only requires a string parameter (the product id the page belongs to).

Please note that the productId must be an existing field in the feed and should be specified before hands to our team.

function initEmpathyX() {
  EmpathyX.init({
    instance: '{API_INSTANCE}',
    lang: 'en',
    scope: 'mobile',
    currency: 'EUR',
    consent: false
  });
  EmpathyX.productPage('{PRODUCT_ID}');
}

Integrating add2Cart

// HTML approach
<button class="add2Cart" onclick="EmpathyX.addToCartOnProductPageClicked()"/>

// JS addEventListener approach
<script>
	document.querySelector('{ADD_TO_CART_SELECTOR}').addEventListener('click', function() {
		EmpathyX.addToCartOnProductPageClicked();
	});
</script>

Integrating checkout

<script>
document.querySelector('<checkout>').addEventListener('click', function() {
	// Get the product ids from your basket/checkout in any manner (your custom implementation)
	var productsIds = getCheckoutProductsIds();
	EmpathyX.checkout(productsIds);
});
</script>

Polyfills and browser support

X supports (at least) the following browsers:

To achieve this degree of support while using advanced JS and CSS features, X uses polyfills. Those polyfills are loaded dynamically only when needed, which means users on modern browsers will save those additional KBs.

If you are experiencing any issue with X in any of the above, please file a ticket using EmpathyBroker's Support Platform.

Troubleshooting (FAQs)

I am A/B testing the solution and I need to load X dynamically. What can I do?

In order to load X dynamically, you can just follow the regular process as long as the initEmpathyX function is defined by the time the X resource finishes loading. The initEmpathyX function will still be automatically called in those situations.

This becomes really handy when your A/B testing tool forces you to embed the dynamic code for that branch in the head.

How can I load X synchronously?

Loading X synchronously is not recommended, since it will probably slow your page load.

If you still need to do so, you can remove the async and defer attributes from the script tag and write subsequent script tags assuming that the resource is already loaded.

This will cause the loading of the resource to block until it is downloaded, so you don't need to wrap the EmpathyX.init function inside of the initEmpathyX callback function in this situation.

<script src="https://assets.empathybroker.com/empathyx/{INSTANCE}/app.js"></script>
<script>
  EmpathyX.init({...});
</script>

A wild double scroll appeared in my search results page!

Well, this is most likely our fault, but please check if any of the following potential causes might be happening on your end: 

• The main scrollable element is html instead of body: X is mounted in the body element and uses a special class called ebx-empathy-x--opened to disable its scroll while opened. This will not work if the scrollable element is html.
• The default scroll behavior is overriden with JavaScript and interfering with X.