JavaScript library¶

The JavaScript library, esales-api, is built on top of the HTTP API and it is designed to make it easy to communicate with Voyado Elevate from a site. It provides methods to make HTTP requests available in the API as well as TypeScript models of the response objects.

The library additionally facilitates the generation and handling of session key, customer keys, and methods for notifications.

Installation¶

The esales-api package is available for installation via npm. For more information about installation, requirements, usage and more, see esales-api at npm.

API instantiation¶

To work with the esales-api, the clusterId received during the customer onboarding (or in the credentials tab in the Elevate app) is required as well as the correct id's for both market and locale. Below, the API object is instantiated as a constant, api.

const api = esales({ clusterId: 'w1A2B3C45', market: 'UK', locale: 'en-GB' });

Key handling¶

The esales-api offers support for working with session keys and customer keys, which are needed when making various requests. Keys are generated and locally persisted upon request and can be set or reset, which should be used when visitors signs in or out. For more information about identifying visitors, see Visitor identification.

All examples below have instantiated the API object as a constant, api.

api.session.sessionKey;

// => 'fb91cf58-a5d7-cca9-f30f-50f745ddd46b'

api.session.customerKey;

// => '77661ff6-fba3-4ce4-9da4-609323ea22d1'

api.session.customerKey = '822c7ed1-30a6-4ea2-9768-540ae06dbfe1'

// => '822c7ed1-30a6-4ea2-9768-540ae06dbfe1'

api.session.reset();
console.log(api.session.sessionKey, api.session.customerKey);
// => '85f6104e-6763-4b6e-92f9-a3063d2a3cc8', '85f6104e-6763-4b6e-92f9-a3063d2a3cc8'

Notifications¶

The JavaScript library provides methods for making notifications using sendBeacon as this avoids cancelled notification requests during navigations when page is unloaded. Once the API object have been instantiated, notifications can easily be made, as session- and customer keys are automatically applied.

All examples below have instantiated the API object as a constant, api.

// @param ticket is present on product and variant
api.notify.click("L2FkLWluZm9ybWF0aW9uO2FkX2tleTthZDEwcm9kdWN0X2tleTtQMjs")

// @param ticket is present on product and variant
api.notify.addToCart("L2FkLWluZm9ybWF0aW9uO2FkX2tleTthZDEwcm9kdWN0X2tleTtQMjs")

// @param productKey is present on product
api.notify.addFavorite("1001-100")

// @param productKey is present on product
api.notify.removeFavorite("1001-100")

Queries¶

The JavaScript library provides methods for making queries. It is recommended to provide methods to catch errors when making queries.

All examples below have instantiated the API object as a constant, api, and will therefore automatically include query parameters for market, touchpoint, sessionKey, and customerKey. The examples show very basic/minimum usage examples, with only required parameters specified without any request body. For more information, including a complete list of parameter and body options, see the API specification.

const result = await api.query.autocomplete({ q: 'lawnm' });
// Use the autocomplete result

const result = await api.query.cartPage({ cart: '31-8764-0|41-2103-0' });
// Use the cart page result

const result = await api.query.contentInformation({ contentKeys: ['storeinfo_2253'] });
// Use the content information result

const result = await api.query.contentSearchPage({ q: 'stores london' });
// Use the content search page result

const result = await api.query.landingPage({ pageReference: '/tools/power-tools/drills' });
// Use the landing page result

const result = await api.query.navigationTree();
// Use the navigation tree result

const result = await api.query.productPage({ productKey: '31-5053-0' });
// Use the product page result

const result = await api.query.searchPage({ q: 'frying pan' });
// Use the search result