Analytics & Reports
Analytics

Services

All services have configuration options, or alternatively can be turned off by being set to the boolean false.

A list of all services is available here. This list is automatically generated as the product core is updated, and thus is always up-to-date.

Here is an example of how to disable the logging and past purchase services:

new storefront({
  ...
  services: {
    logging: false,
    pastPurchases: false
  }
});

Adding a service

You can add a custom service by providing a key associated with your class. It will have the app instance passed through its constructor. When the services are initialized, their init functions are called with services as an argument, so you must include an init function in your custom service.

javascript
class MyService {
  constructor(app) {
    this.app = app;
  }

  init(services) {
    this.services = services;
  }
}

new storefront({
  ...
  services: {
    myService: MyService
  }
})

If you need to pass additional properties to your constructor you can also use the following example to create a custom service:

javascript
const opts = { a: 'b' };
class MyService {
  constructor(app, opts) {
    this.app = app;
    this.opts = opts;
  }

  init(services) {
    this.services = services;
  }
}

new storefront({
  ...
  services: {
    myService: (app) => new MyService(app, opts)
  }
})

Logging

Property Type Default Description
level string 'debug' Sets the logging level. Can be set to trace, debug, info, warn, or error.
debug boolean | string Set to true/false to turn all debug logging on/off. Can also be set to an object with properties lifecycle, aliasing, observer, flux, and tracker set to true/false to turn debug logging on for specific areas.

Search

The search service listens to store updates and triggers a search request. It also keeps a record of past searches.

Property Type Default Description
maxPastSearchTerms number 0 Sets the maximum number of past search terms to store.
storeDuplicateSearchTerms boolean false

Url

Property Type Description
beautifier object | function Read more
routes object Read more
history object Read more
redirects { [key: string]: string } Read more
urlHandler function Read more

Beautifier

URL beautifier object allows configuring URL beautification options. If a function is passed it will be used as a URL beautifier factory for creating a custom beautifier.

As a configuration object

Property Type Default
refinementMapping array []
params object { refinements: ‘refinements’, page: ‘page’, pageSize: ‘page_size’, sort: ‘sort’, collection: ‘collection’ }
queryToken string 'q'
suffix string ''
useReferenceKeys boolean true
details object { params: { area: ‘area’, collection: ‘collection’ } }

refinementMapping

Accepts objects in the form { <referenceKey>: <refinementName> }, where the referenceKey is the key to be used in the url path. The key must be a single character.

params

An object with the keys refinement, page, pageSize, sort, and collection, indicating the parameter name which will be used as a reference for these items as a URL parameter.

queryToken

A single character to be used as the query parameter in the URL.

suffix

A suffix to be pre-pended to the path.

useReferenceKeys

true to use referenceKeys in the URL, false to use params only.

details

An object containing params, which itself is an object with the keys area and collection. The values located at area and collection will be used as the names of the corresponding query string parameters when building details-type URLs.

Disable either area or collection with false as the key-value.

The following is an example of setting custom area and collection references:

javascript
...
services: {
    ...
    url: {
      beautifier: {
        ...
        details: {
          params: {
            area: 'yourCustomAreaReference',
            collection: 'yourCustomCollectionReference',
          },
        },
      },
    },
    ...
}
...

As a factory function

The function will receive the running instance of the StoreFront application and the generated routing table based off of the routes configuration.

beautifierFactory(app, routes)

  • app: StoreFront
  • routes: { [key: string]: string }
  • returns: { parse: function, build: function } - Must return an object with a build() function and a parse() function.

build(type, request)

  • type: string - The type of route to generate, either 'search' or 'details'.
  • request: object - The request data needed to generate the url.
  • returns string - The generated URL.

parse(url)

  • url: string - The URL to parse into state.
  • returns { route: string, request: } - The type of route found and the extracted request data. The URL service will trigger a request based on the provided route type. For example, returning { route: 'search', request: { query: 'hello' } } will trigger a search request with the query hello. To prevent StoreFront from dispatching a request, this function may return either:
  • an object with an unknown route key (ie. { route: 'home', request: {} }.
  • null (please note: StoreFront will print a warning when running in debug mode).

Routes

Property Type Default
search string '/search'
details string '/details'

A string indicating what path to use for search results page.

details

A string indicating what path to use for details page

History

Property Type Default Required
pushState function window.history.pushState
replaceState function window.history.replaceState
initialUrl string window.location.href
listener function window.addEventListener

pushState(data, title, url)

  • data: object - the state for the given history section. Will be used to re-build the store state.
  • title: string
  • url: string - the url for the state.

Serves the same purpose as the window.history.pushState function, but can be replaced with any function. Is called when the URL needs to be updated to reflect a change in history.

replaceState(data, title, url)

  • data: object - the state for the given history section. Will be used to re-build the store state.
  • title: string
  • url: string - the url for the state.

Serves the same purpose as the window.history.replaceState function, but can be replaced with any function. Is called when the state for the current history entry needs to be updated to reflect changes.

Under the Hood

StoreFront calls pushState prior to dispatching requests and replaceState after responses have been received from requests.

initialUrl

The url to use on initial page load.

listener(event, cb)

  • event: 'popstate' - the event type.
  • cb: function - the url service rewind function.

The history listener will fire history transitions, eg, window.history.back(), window.history.forward(), window.history.go(1), window.history.go(-1). It is the responsibility of the listener to trigger the callback for a given event. This is to allow easy integration with window.addEventListener, and also enables users to set up the url listener with a listener that has several responsibilities in addition to listening for popstate. Currently the callback is not configurable and always calls the url service rewind function.

Redirects

Causes a redirect to value path for each key when key matches the next url path. For example, the example configuration would cause a redirect from www.example.com/search/shoes/q to www.example.com/special-shoes-sale.

URL Handler - urlHandler(url)

  • url: string - the URL to navigate to

If supplied, this function will be called with every newly generated URL rather than using the single-page application style on-page routing native to StoreFront. This can be used to hard redirect to custom URLs not handled by StoreFront using window.location.assign().


Tracker

Property Type Default Description
warnings boolean true Read more
sendSearchEvent function Read more
sendViewCartEvent function Read more
sendAddToCartEvent function Read more
sendRemoveFromCartEvent function Read more
sendOrderEvent function Read more
sendViewProductEvent function Read more
sendMoreRefinementsEvent function Read more

warnings

true to return warnings from the tracker service, false to hide them.

Using an override function for Tracker events

All of the Tracker service methods can be modified by specifying functions in the service’s configuration object. The associated method will run first, then pass the relevant value and currentEvent to your override function, allowing you to modify the event before it is beaconed.

new storefront({
  ...
  services: {
    tracker: {
      sendSearchEvent: (id, event) => ({ ...event, metadata: event.metadata.concat({ key: 'gbi', value: true }) })
    }
  }
})
Adding `gbi` or `gbi_experience` related metadata

Storefront will automatically add the below metadata objects and replace any existing metadata objects whose keys are gbi or gbi_experience.

[
 {
   key: 'gbi',
   value: 'true'
 },
 {
   key: 'gbi_experience',
   value: 'storefront'
 }
];

sendSearchEvent(id, currentEvent)

  • id: string - The search request id.

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendViewCartEvent(currentEvent)

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendAddToCartEvent(currentEvent)

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendRemoveFromCartEvent(currentEvent)

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendOrderEvent(currentEvent)

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendViewProductEvent(record, currentEvent)

  • record: object - The record related to the view product event.

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.

sendMoreRefinementsEvent(id, currentEvent)

  • id: string - The refinements request id.

  • currentEvent: object - The built up tracker event that would be sent.

  • return value: The tracker event that will be sent.


Autocomplete

Property Type Default
useFirstResult boolean false

useFirstResult

true to use the first autocomplete suggestion as the string to search product images for, false to use the search string


Recommendations

Has no configuration options in this section, but may be turned off by setting to false.