Integrating the Motive Commerce Search Engine

In order to finish setting up Motive Commerce Search, you need to integrate the MotiveX layer into your eCommerce site. This page provides you with the necessary instruction to load MotiveX's JavaScript resource and initialise it.

Prerequisites

MotiveX uses polyfills to support most available browsers. These polyfills are loaded dynamically only when necessary, allowing the most efficient runs for those using modern browsers.

Among the supported browsers are the following ones:

Browser	Version(s)	Notes
Chrome	Latest 5	Includes Chrome for Android
Firefox	Latest 5	Includes Firefox for Android
Opera	Latest 5	Includes Opera Mobile
Safari	9+	Includes iOS Safari
Edge	All
Internet Explorer	10+
Android Browser	4+

Loading the JavaScript Resource

The first step to integrate MotiveX layer is to load the JavaScript resource. In order to do it, include the following tag in your HTML structure:

<script defer src="https://assets.motive.co/motive-x/latest/app.js"></script>

The defer Attribute

The defer attribute is used to speed up the process by loading the resource asynchronously, preventing the blocking of the page load. 

Once the tag has been included and the script is up and running, Motive will automatically call the global initMotiveX function.

Initializing MotiveX

The next step is to set up the initMotiveX callback function, used to load and initialize MotiveX asynchronously. Here's a snippet of the initMotiveX callback function:

function initMotiveX() {
  MotiveX.init({
    xEngineId: '00000000-0000-0000-0000-000000000000',
    lang: 'en',
    currency: 'USD',
    currencyFeed: 'EUR',
    currencyExchangeRates: {
      EUR: 1,
      USD: 1.21072
    },
    triggerSelector: '.search-input',
    cartUrl: '/cart',
    callbacks: {
      add2cart: result => new Promise(resolve => {
        setTimeout(() => {
          console.log('Result added to the cart:', result);
          resolve();
        }, 1000);
      }),
      getCartInfo: () => ({ productsCount: Math.floor(Math.random() * 20) + 1 })
    },
    searchDebug: false
  });
}

As seen in the snippet, this function contains a MotiveX object to initialize it.

Function Considerations

Note the following considerations when configuring the initMotiveX callback function:

• • The function must be defined and available by the time the MotiveX resource is loaded.
  • The function should not be called manually.

The initMotiveX receives a configuration object that allows for the dynamic configuration needed by MotiveX in runtime.

Dynamic Configurations Details

These are the dynamic parameters and their details.

Mandatory Parameters

Parameter	default	return	Description
xEngineId string	none	-	Unique identifier of your Search API engine. Example: 00000000-0000-0000-0000-000000000000

Optional Parameters

Parameter	default	return	Description
lang string	en	-	Language to be used by Motive for internationalizing messages (i.e. language of the search interface). Examples: es, en_UK
currency string	EUR	-	Currency code (ISO 4217) to be used by Motive for price exchanging and formatting, both for products and the price filter. Examples: USD, CAD
currencyFeed string	EUR	-	Feed currency code (ISO 4217) to define the source currency for price exchanging and formatting. Examples: USD, CAD
currencyExchangeRates object	none	-	Currency exchange rates. If you define it, at least the currency exchanges rates for the currency and currencyFeed should be defined, if not, MotiveX will manage it by you. Examples: {EUR: 1, USD: 1.21072}
triggerSelector string	#search_Widget	-	DOM selector which triggers the MotiveX Layer on its focus. Examples: .search-input , #search_widget form
cartUrl string	none	-	The URL to redirect on click in the cart button. Examples: /cart , https://my.awesome.site.com/cart
callbacks.add2cart function	none	Promise<void>	Callback function with the result data as a parameter for appending the result to the cart of the customer site. It must return a Promise. Examples: result => new Promise(resolve => { console.log(results); resolve(); })
callbacks.getCartInfo function	none	{ productsCount: number | string, [extra: string]: any; }	Callback function for getting the cart information of the customer site. This function must return an object with at least a key productsCount with the number of products. Examples: () => ({ productsCount: 5 })
searchDebug boolean	false	x	Search API flag for testing purposes on the back-end side. Example: true, false

Changing Dynamic Configurations

Some situations, like changes in the language and currency, may result in the initialized MotiveX configuration not being valid anymore. If changes like this trigger a page reload on your site, MotiveX will initialize again with the correct values.

However, when a manual configuration change is needed, use the MotiveX.setConfig function, which receives an object that can contain all the aforementioned configurations. 

Once executed, the MotiveX.setConfig function:

1. Updates the internal configuration.
2. Reflects the changes in the interface.

Here's an example of this function used to change the currency parameter:

MotiveX.setConfig({
  currency: 'USD'
});

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

<script defer src="https://assets.motive.co/motive-x/latest/app.js"></script>

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