JavaScript library¶

The JavaScript library, esales-api, is built on top of the HTTP Storefront API v3 and it is designed to make it easy to communicate with Voyado Elevate via a browser or Javascript Runtime (like NodeJS, Deno, and more). It provides methods to make HTTP requests available in the API as well as TypeScript models of the response objects.

Installation¶

The @apptus/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 IDs for both market and locale. Additionally, a touchpoint with either 'desktop' or 'mobile' must be set. Below, the API object is instantiated as a constant, api.

import { elevate } from '@apptus/esales-api';

const api = elevate({
  clusterId: 'w1A2B3C45',
  market: 'UK',
  locale: 'en-GB',
  touchpoint: 'desktop',
  session: () => ({
    customerKey: '306c9b32-d361-43e0-a8ad-ec25eceec7ad',
    sessionKey: '767e867f-bece-4836-b230-16fbde4066cb'
  })
});

Key handling¶

The esales-api should be instantiated with a session property, that should be a function that returns the session- and customer key to use. For more information on the key format and about identifying visitors, see Visitor identification.

Synchronous usageUsage with Promise

const api = elevate({
  ...config,
  session: () => {
    const { id, session } = loadUserInfo();
    return { customerKey: id, sessionKey: session };
  }
});

const api = elevate({
   ...config,
  session: async () => {
    const { id, session } = await loadUserInfo();
    return { customerKey: id, sessionKey: session };
  }
});

Additionally, the library offers a way to automatically handle session- and customer key in the browser. They will be generated and locally persisted upon request to localStorage, and there are methods to update or reset keys, which should be used when visitors signs in or out.

Create localStorage session handlerRetrieve sessionKey and customerKeyUpdate customerKeyReset keys

import { elevate, localStorageBackedSession } from '@apptus/esales-api';

const api = elevate({
  ...config,
  session: localStorageBackedSession()
});

import { localStorageBackedSession } from '@apptus/esales-api';

const session = localStorageBackedSession();
const { customerKey, sessionKey } = session();

console.log(customerKey, sessionKey);
// => 'fb91cf58-a5d7-cca9-f30f-50f745ddd46b', '77661ff6-fba3-4ce4-9da4-609323ea22d1'

import { localStorageBackedSession } from '@apptus/esales-api';

const session = localStorageBackedSession();
session.updateCustomerKey('822c7ed1-30a6-4ea2-9768-540ae06dbfe1');

console.log(session().customerKey);
// => '822c7ed1-30a6-4ea2-9768-540ae06dbfe1'

import { localStorageBackedSession } from '@apptus/esales-api';

const session = localStorageBackedSession();
session.reset();

console.log(...Object.values(session()));
// => '85f6104e-6763-4b6e-92f9-a3063d2a3cc8', '31276284-3fa3-45f1-a6cb-fe91ec016244'

Notifications¶

The Javascript library includes methods for making notifications of each type. Once the API object has been instantiated, notifications can easily be made, as session- and customer keys are automatically applied. Notifications are made via fetch() with the keepalive flag, so that browsers do not terminate the requests before being completed, such as when sending click notification when a link is pressed.

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

ClickAdd to cartAdd favoriteRemove favorite

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

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

// @param productKeyOrPayload a `Product.key` or object with variant or product key
await api.notify.addFavorite("1001-100")
await api.notify.addFavorite({ variantKey: "vk_234567"})

// @param productKeyOrPayload a `Product.key` or object with variant or product key
await api.notify.removeFavorite("1001-100")
await api.notify.removeFavorite({ variantKey: 'vk_234567' })

Queries¶

Queries can be made by passing query parameters as an object and, for most types of queries, an optional body. The body is used to configure the types of data that will be returned from the API.

All examples below have instantiated the API object as a constant, api, and will therefore automatically include query parameters for market, locale, 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.

AutocompleteCart pageContent informationContent search page

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

API reference: Autocomplete query

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

API reference: Cart page query

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

API reference: Content information query

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

API reference: Content search page query

Landing pageNavigation treeProduct pageSearch page

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

API reference: Landing page query

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

API reference: Navigation tree query

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

API reference: Product page query

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

API reference: Search page query