Skip to content

Component Library

Installation

The Apptus eSales for Fashion library files are hosted at https://cdn.esales.apptus.com/integration/v1/. Two versions of the library are available; one for modern browsers and one that supports legacy browsers (i.e. the es5 version).

Modern

Browsers that support es2015 JavaScript features are considered as Modern. The majority of users are running newer versions of Google Chrome, Mozilla Firefox, Microsoft Edge, or Apple Safari, which supports es2015.

Legacy (es5)

Legacy support includes older browsers such as Apple Safari 9 and Microsoft Internet Explorer 11.

Initialisation

Before the components are registered, the library needs to be initialised with an eSales cluster ID, market, and more. This is set in the InitConfig interface. A specification of required and available settings that can be seen in the API section.

Make sure to call esales.init() after including the esales-fashion.js library from the CDN. It's also possible to configure scripts to be non-blocking by deferring script loading.

Example

<script>
esales.init({
  webApiId: 'abc123',
  market: 'UK',
  productPageUrlPrefix: 'https://www.site.com/product/',
  searchPageUrlPrefix: 'https://www.site.com/search/',
  touchPoint: 'DESKTOP',
  theme: {
    fontFamily: 'Roboto, sans-serif'
  }
});
</script>

API

The Esales and InitConfig interfaces are used to define the properties that must be set to initiate the eSales for Fashion components.

Esales interface

/** Global variable `esales` */
declare const esales = Esales;

interface Esales {
  /** Used to bootstrap the eSales components */
  init(config: InitConfig): void;
  session: {
    /**
     * Current `customerKey` in use. Can be used with payment notifications.
     * Can be set with a new value. Must be a non-empty string.
     */
    customerKey: string;
    /** Current `sessionKey` in use. Can be used with Payment notifications. */
    readonly sessionKey: string;
  }
}

InitConfig interface

interface InitConfig {
  /** Provided by Apptus and points to a specific eSales cluster */
  webApiId: string;
  /** The market the current page should be rendered for */
  market: string;
  /**
   * Used in conjunction with the `url` attribute on products to create clickable links
   *
   * @example
   * productPageUrlPrefix: 'https://site.com/product/'
   * product.attr.url: 'P123456789'
   * url-result: 'https://site.com/product/P123456789'
   */
  productPageUrlPrefix: string;
  /**
   * The url to the page where the `<esales-search-results>` component is.
   * A search param `q` will be appended to this string with the
   * search phrase for searches from the `<esales-search-assistant>`.
   */
  searchPageUrlPrefix: string;
  /**
   * Configuration and some UI elements change based on used `touchPoint`.
   * If not provided (or `undefined`), will automatically determine the touchpoint to use.
   */
  touchPoint?: 'DESKTOP' | 'MOBILE' | undefined;
  /** Configuration object for theming */
  theme?: SiteTheme;
}

Theming API

The full list of options for theme can be seen in the Theming API specification.

Event tracking

Custom tracking (e.g. with Google Analytics) can be performed by listening to events that are emitted on certain actions. This way, tracking can be supported for almost any use case. The tracking events are currently bubbling, and cannot be prevented. This means that an event listener can be attached on any parent to the component or components in question.

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

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.

Additional events

Tracking of additional events with an eSales for Fashion component will be added largely based upon customer demand. To make a request or provide feedback, please contact support@apptus.com.

Browser support

The list below shows which browsers we are currently supporting with the .es5.js version of the library. Older browsers may be supported, but they are not actively tested against.

  • Google Chrome v49+
  • Mozilla Firefox v46+
  • Microsoft Internet Explorer 11
  • Microsoft Edge v14+
  • Apple Safari v9+
  • Opera (latest two versions)

Deferring script loading

Due to <script> tags default behaviour of blocking parsing of the HTML, it might be desired to use the defer attribute. To use defer, one needs to make sure esales.init({ ... }) is only called after the esales-fashion.js script has been executed.

Deferring can be performed by either using a script file or via an inline script.

Defer via script file

Keep the initialization in its own script file, and load the scripts in the correct order with all script tags having the defer attribute.

<script defer src="https://cdn.esales.apptus.com/integration/v1/esales-fashion-polyfills.js"></script>
<script defer src="https://cdn.esales.apptus.com/integration/v1/esales-fashion.js"></script>
<script defer src="esales-init.js"></script>
// esales-init.js

esales.init({
  // ...
});

Defer via inline script

The DOMContentLoaded event can be used to preserve the correct execution order, since defer has no effect on inline scripts. The defer scripts are executed right before DOMContentLoaded. This way inline scripts can be paused until the deferred scripts have run.

<script defer src="https://cdn.esales.apptus.com/integration/v1/esales-fashion-polyfills.js"></script>
<script defer src="https://cdn.esales.apptus.com/integration/v1/esales-fashion.js"></script>
<script>
window.addEventListener('DOMContentLoaded', function() {
  esales.init({
    // ...
  });
});
</script>

Polyfills

Polyfills are bits of code that are meant to fill in support for features that may not be available in all browsers yet. This is typically done by performing a check whether the API exists and possibly check that it is implemented correctly. If not, the script will add the API manually so that it will exist for forthcoming code.

Feature Package / Repository Legacy (es5) Modern
URL url-polyfill
URLSearchParams url-polyfill
KeyboardEvent.key Custom (based on keyboardevent-key)
es2015 API core-js/es6
array.includes() core-js/es7.array.includes
Object.entries() core-js/es7.object.entries
fetch() whatwg-fetch
IntersectionObserver IntersectionObserver
Web Components webcomponentsjs

Web components

The term "web components" is an umbrella term that refers to several technologies working together. The main parts of this are "custom elements", "template tags" and "shadow DOM". The webcomponentsjs includes all these in the bundle it provides.

  • Custom elements - A way to package lifecycle hooks and logic into a re-usable tag, e.g. <product-card>.
  • Template tags - A <template> element contains inert content. That means it won't be rendered and links/sources won't be fetched. The content can be easily cloned and inserted into the DOM.
  • Shadow DOM - Provides a way to encapsulate DOM content inside a node, so that outside styling will not affect it.

Support for these three features needs to exist natively in the browser or be provided by webcomponentsjs for eSales for Fashion components to work correctly.

×