Dynamic Configurations

Created by Iván Tajes · last update December 16, 2019

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
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 servicesAdding a product to the cart when the add to cart button is displayed in the search results page.
section string No   Section identifier used by X for the Discovery Wall featureNot 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:

1
2
3
EmpathyX.setConfig({
  consent: true
});