/
How to integrate X into your website

How to integrate X into your website

Dec 16, 2019

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:

LIVE

https://assets.empathybroker.com/empathyx/{INSTANCE}/app.js

STAGING

https://preassets.empathybroker.com/empathyx/{INSTANCE}/app.js

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:

Parameter

Type

Required

Default

Description

Parameter

Type

Required

Default

Description

instance

string

Yes

'ebdemo'

Unique identifier of your Search API instance.

consent

boolean

Yes

false

This parameter is used to let X know whether the user has accepted the usage of cookies and therefore the user, session and user type cookies can be used and sent to the Search API.

If this parameter is configured with false value, then the cookies will be deleted and removed from all Search API calls.

No consent means results will not be personalized and signals (Related Tags, Next Queries, etc.) will not be inferred from that session.

This parameter should be set to true as soon as the user accepts the usage of EmpathyBroker's cookies.

If accepting the cookies does not trigger a page reload, please consider using the EmpathyX.setConfig function (see the section below) to update the consent parameter so that the current session is tracked already.

scope

string

Yes

'mobile'

The value of this parameter is sent to the Tagging API to be able to segment user sessions by device in analytics and reporting.

The typical values for this field are 'desktop', 'tablet' and 'mobile', but any value is accepted, so pick the ones that best fit your necessities.

Examples:

'desktop'

'tablet'

'mobile'

documentDirection

'ltr', 'rtl' 

No

'ltr'

This value tells EmpathyX if it should handle the layout in a right to left way or left to right way.

env

string

No

 

This parameter can be used to switch the Search and Tagging API environment.

Production endpoints are used by default when this parameter is omitted.

To use the STAGING environment, the value for this configuration would be 'staging'.

Examples:

'staging'

lang

string

No

'en'

Language to be used by X for internationalizing messages (i.e. language of the search interface).

If there are no translations for the specified language, the fallback language ('en') will be used.

Examples:

'es'

'en_UK'

searchLang

string

No

'en'

Language to be used by X for Search API requests (i.e. language of all catalog related information, such as results or filters).

By default, if searchLang is omitted, all catalog related information is presented in the language specified in lang.

Please note this parameter should only be used when messages and catalog are in different languages.

Examples:

'es'

'en_UK'

currency

string

No

'EUR'

Currency code (ISO 4217) to be used by X for price formatting, both for products and the price filter.

Examples:

'USD'

'CAD'

filters

object

No

{}

This parameter allows pre-selecting filters even before the user launches the first search.

Pre-selected filters are particularly useful for keeping consistency between navigation and search in those situations where the user is asked to pick an option before starting the journey, such as MAN / WOMAN in fashion or PERSONAL / BUSINESS in services and telecommunications. If this is not required, the usage of pre-selected filters is discouraged.

Please note pre-selected filters behave as radio buttons in the sense that the user can change their values but not de-select them, so use them wisely.

The configured filters must match the names and values in the catalog, which means that values have to be adapted to the selected language (e.g. 'Woman' for English vs 'Mujer' for Spanish).

Examples:

{
  // name: 'value'
  section: 'Woman',
  category: 'Jeans'
}

eventCallbacks

object

No

 

The eventCallbacks object is a way to run custom JavaScript code when certain user events happen.

This object accepts a callback function for each of the following events: query, click, add2cart, checkout, filter, clearFilters, sort, columnsChange, resultsEnd, open and close.

Every time one of those events happen, the corresponding callback is executed, sending an object containing all relevant information to that event.

You can check the map of current events and parameters in the data object in the Event callbacks parameters section:

This is useful for situations such as:

  • Integrating with an external analytics platform like Google Analytics (see this section for more details)

  • Fetching asynchronous data in query time from external services

  • Adding a product to the cart when the add to cart button is displayed in the search results page

Examples:

{
  query: function(data) {
    // Send analytics event if the query was not loaded from the URL
    if (data.origin !== 'linked') {
      window.dataLayer.push({...});
    }
  },
  add2cart: function(data) {
    // Add product to the cart if the event was triggered in the search results page
    if (data.context === 'SRP') {
      myAwesomeCart.add(data.productId);
    }
  },

  checkout: function(data) {

    // In this case data is a set of results, ie: { resultId1: resultData1, resultId2: resultData2 }

  }
}

section

string

No

 

Section identifier used by X for the Discovery Wall feature

Not applicable to all instances

store

string

No

 

Store identifier used by X when querying the Search API.

Not applicable to all instances.

catalog

string

No

 

Catalog identifier used by X when querying the Search API.

Not applicable to all instances.

warehouse

string

No

 

Warehouse identifier used by X when querying the Search API.

Not applicable to all instances.

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:

Parameter

Description

query, filter, clearFilters, resultsEnd, sort, columnChange, open, close

click

add2cart

checkout

Parameter

Description

query, filter, clearFilters, resultsEnd, sort, columnChange, open, close

click

add2cart

checkout

catalog

Catalog identifier provided to X in the snippet.

X

X

X

X

context

Page where the add2cart event was triggered.

The possible values for this parameter are:

  • 'SRP': search results page

  • 'PDP': product details page

This parameter is typically used as a discriminator to determine whether to add a product to the cart when the add to cart button is present in the search results page.

 

 

X

 

contextualize

Whether the query has been contextualized.

X

X

X

X

filtered

Whether the query has been filtered.

X

X

X

X

follow

Whether the user has been redirected to the product page after tracking the event.

 

X

X

X

lang

Language identifier provided to X in the snippet.

X

X

X

X

origin

Origin of the query that originated the event.

The possible values for this parameter are:

  • 'default'

  • 'empathize_category'

  • 'empathize_term'

  • 'history'

  • 'next_query'

  • 'next_query_grid'

  • 'linked'

  • 'partial'

  • 'related_tag'

  • 'spellcheck'

  • 'no_results'

  • 'empty_search'

  • 'empathize_recommendations'

X

X

X

X

page

Page number where the event was originated.

In case of the query event, it means the page number that was loaded (1 for the initial query; 2, 3, 4... for the subsequent pages as the user scrolls down or paginates).

For product-related events, it means the page number of the result that triggered the event.

X

X

X

X

position

Specific grid position (starting at 1) of the result that triggered the event.

 

X

X

X

productId

Unique identifier of the product in the feed.

 

X

X

X

q

Query that originated the event.

X

X

X

X

scope

Scope provided to X in the snippet.

X

X

X

X

session

Unique identifier of the user session (only present if consent was set to true in the configuration).

X

X

X

X

spellcheck

Whether spellcheck has been applied to the query.

X

X

X

X

store

Store provided to X in the snippet.

X

X

X

X

title

Name of the result that triggered the event.

 

X

X

X

totalHits

Number of results matching the query.

X

 

 

 

url

URL of the result that triggered the event.

 

X

X

X

user

Unique identifier of the user (only present if consent was set to true in the configuration).

Comments