Skip to content

Events API

This section lists available events and event details for custom usage. This can for example be used for custom tracking for Google Analytics or third party vendors. For each event an example of how to listen and print the details of the event in the console, along with a specification of the event details.

Additional events

Tracking of additional events with an eSales Lifestyle component will be added largely based upon customer demand. To make a request or provide feedback, a retailer must contact their appointed Apptus service personnel.

Event specification

esales-product-suggestion

The event esales-product-suggestion is dispatched whenever a customer clicks on a product suggestion in the search assistant.

Usage example

document.addEventListener('esales-product-suggestion', function(e) {
  console.log(e.detail);
});

Detail specification

Event details Type Description
productKey string The product key of the clicked product suggestion.
searchPhrase string The search phrase used, resulting in the product suggestion.

Asynchronous code

Please note that since some events (e.g. esales-product-suggestion) will be followed by a navigation to a new page, it is not certain that asynchronous code has time to complete. There are various ways to handle this, e.g. navigator.sendBeacon(), LocalStorage queue, synchronous XMLHttpRequest. Google Analytics has an option transport: 'beacon' which should send events correctly.

esales-active-category

The event esales-active-category is dispatched whenever a category page is loaded, or when switching category through navigational components. This event can be used to implement changes to the <title> element of a category page or to for example change banners on a page.

Usage example

document.addEventListener('esales-active-category', function(e) {
  console.log(e.detail);
});

Detail specification

Event details Type Description
categoryName string The name of the category that was loaded.

esales-products-rendered

The event esales-products-rendered is dispatched whenever a product list of any sort is loaded, such as a search result, results for a navigation page, or recommendations.

Usage example

document.addEventListener('esales-products-rendered', function(e) {
  console.log(e.detail);
});

Detail specification

Event details Type Description
productKeys [string] An array of all product keys to the resulting products.

All product keys in the listing are always returned. For example, given a search result initially displaying 60 products, with 60 additional products being displayed upon a user pressing 'Load more', two events will be dispatched. The first event containing an array of 60 product keys and the second event an array containing 120 product keys.

esales-product-quick-buy

The event esales-product-quick-buy is emitted whenever a visitor clicks a Quick buy button in a product card.

Usage example

document.addEventListener('esales-product-quick-buy', function(e) {
  console.log(e.detail);
});

Detail specification

Event details Type Description
productKey string The product key of the product with the clicked Quick buy button.
productGroup string The product group of the product with the clicked Quick buy button.
elementRect DOMRect object The returned Quick buy button coordinates and dimensions as a DOMRect object.

esales-write-url

The event esales-write-url allows for client side URL customisation and is emitted whenever a state changes that should be preserved in a URL. This includes facet information such as product colours, prices, and the product path.

A customised URL created using esales-write-url must always be used together with a corresponding esales-read-url on a page. Any identifiers or values provided to esales-read-url must exactly match those provided from the esales-write-url event.

Detail specification

Event details Type Description
detail.path string The path of the URL. Relative to origin and always start with a forward slash, /.
detail.facets Facets An object with the selected facets of the page.
detail.overrideUrl({ url, facetsUsed }) method The customised URL format to be read with esales-read-url. An options object with the properties url and facetsUsed should be provided as a parameter.
url string The options.url property can either be a full URL starting with https:// or a relative path to the current site origin starting with a forward slash, /.
facetsUsed string[ ] The options.facetsUsed property should be string[] where each string is facetId, and should list facets that have been encoded into the options.url property.
Facets

An object with key/value-pairs for selected facets. The value is either expressed as a range { min: number, max: number }, or a list of values string[]. The facets' keys and lists of values are all identifiers. Only keys and values returned by the API are eligible values. Any facets provided to esales-read-url must exactly match those provided from the esales-write-url event.

Facet syntax example
  {
    'custom.season': ['Winter'],
     brand: ['nike', 'adidas'],
     color: ['black', 'red'],
     price: { min: 1, max: 999 }
  };

Usage example

document.addEventListener('esales-write-url', (event) => {
  const { path, facets, overrideUrl } = event.detail;
  console.log(path, facets);
  //URL Encoding
  overrideUrl({ url: customUrl, facetsUsed: ['price', 'custom.fit'] });
});

esales-read-url

The event esales-read-url allows for client side URL customisation and is emitted whenever a page is loaded and allows custom parsing of the URL to load the components in a given state. Customised URL:s created by esales-write-url must be read using esales-read-url.

Any identifiers or values provided to esales-read-url must exactly match the those provided from the esales-write-url event.

Detail specification

Event details Type Description
detail.url string The current location.href, i.e. path including parameters.
detail.updateRouteState(RouteState) method An object with the route data parsed from the custom URL, matching the format provided by the esales-write-url event.
RouteState
Name Type Description
path string The path of the page, exactly as provided by the esales-write-url event.
facets Facets The selected facets of the page, exactly as provided by the esales-write-url event.

Usage example

document.addEventListener('esales-read-url', (event) => {
  const { url, updateRouteState } = event.detail;
  console.log(url);
  // Decode customised URL: decoding and pass path and facets
  updateRouteState({ path: parsedPath, facets: parsedFacets });
});

esales-navigation

The event esales-navigation is emitted whenever a link in the search assistant is clicked, or when a search is being made. This event can be used to alter the click behaviour of the link and allows for Single page application routing.

Detail specification

Name Type Description
url object The url object of the clicked link.
behavior Behavior The click behaviour for the clicked link. Can be replaceState, pushState, or navigation.
setNavigationBehavior method Updates the current behaviour for the navigation to a new behaviour.

Behavior

Name Description
navigation The default behaviour. Normal navigation, i.e. the URL is updated and the new pages is reloaded when a link is clicked.
pushState Prevents a page reload when a link is clicked, while still updating the URL.
replaceState Prevents a page reload when a link is clicked, while still updating the URL without adding a new entry in the browser history.

Usage example

document.addEventListener('esales-navigation', function(e) {
  console.log(e.detail);
});

Example integrations

Google Analytics

The following example shows a sample integration of sending product suggestion clicks to Google Analytics.

document.addEventListener('esales-product-suggestion', function(event) {
  ga('send', {
    hitType: 'event',
    eventCategory: 'product-suggestion',
    eventAction: 'click',
    eventLabel: event.detail.productKey,
    transport: 'beacon'
  });
});

Client side URL customisation

The following example shows how the name of the price facet query parameters can be customised, and how the brand facet can be placed in the URL path instead of looking as a regular query parameter.

Before

https://esalesdrivensite.com/men/shoes?f.brand=Nike&f.price.min=200&f.price.max=500

Encode URL

The script is present on the page/s that encode the URLs using esales-write-url.

document.addEventListener('esales-write-url', (event) => {
  const { path, facets } = event.detail;
  const { brand, price } = facets;

  const brandPath = brand ? `/${brand.join('-')}` : '';
  const priceParam = price ? `?price-interval=${price.min}-${price.max}` : '';

  detail.overrideUrl({ url: `${path}${brandPath}${priceParam}`, facetsUsed: ['brand', 'price'] });
});

After

https://esalesdrivensite.com/men/shoes/Nike?price-interval=200-500

Decode URL

The script is present on the page/s that decode and use the URL content using esales-read-url.

document.addEventListener('esales-read-url', ({ detail }) => {
  const url = new URL(detail.url);
  const segments = url.pathname.split('/');
  // External method `isBrand`, to ensure the last path segment is a brand
  const brandSegment = isBrand(segments[segments.length - 1]) ? segments[segments.length - 1] : undefined;

  const path = url.pathname.replace(brandSegment ?? '', '');

  const [min, max] = url.searchParams.get('price-interval')?.split('-').map(Number) ?? [];
  const facets = {
    brand: brandSegment?.split('-'),
    price: min >= 0 || max >= 0 ? { min, max } : undefined
  };

  detail.updateRouteState({ path, facets });
});

Single page application routing

To make eSales Lifestyle behave like an SPA, a single page application, the esales-navigation event can be used.

Custom routing on all pages

The following example shows how to modify the navigation behaviour for all pages.

document.addEventListener('esales-navigation', e => {
  e.detail.setNavigationBehavior('pushState');
  // Your custom code to ensure the router re-renders views.
  syncRoute();
  // syncRoute(e.detail.url);
});

Custom routing on selected pages

The following example shows how to modify the navigation behaviour on a selection of pages.

document.addEventListener('esales-navigation', e => {
  const url = new URL(e.detail.url);
  // Only modify behaviour for search and product page.
  if (url.pathname.startsWith('/search') || url.pathname.startsWith('/product')) {
    // Your custom code to ensure the router re-renders views.
    e.detail.setNavigationBehavior('pushState')
    syncRoute();
    // syncRoute(e.detail.url);
  }
});

Last update: May 6, 2021
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE