URL Parameters Mapping

In our integration we heavily rely on the synchronization of the URL parameters with the state o the search interface. Alokai storefront uses different query parameters than Coveo Headless expects. To make the integration work, we need synchronize search parameters with URL. Thanks to that, Coveo Headless can understand the URL parameters and update the search interface state accordingly.

Mappers

Under the hood, Alokai uses buildSearchParameterManager because it gives us the full control over how the URL parameters are serialized and deserialized.

All parameter mappers are defined in files in the mappers/paramMappers directory of the coveo module. Each query parameter has its own mapping function that handles the serialization and deserialization of the parameter value.

Let's take a look at the q parameter mapper: The q parameter mapper is defined in the queryParamMapper.ts file in the mappers/paramMappers directory of the coveo module and it implements ParamMapper interface.

Below you can see the implementation of the q parameter mapper: This function deserialize the URL parameters and returns the object with the search query. search is the Alokai specific query parameter, q is the Coveo Headless specific query parameter

export const queryParamMapper: ParamMapper = {
  deserialize(url) {
    const query = url.searchParams.get('search');
    if (!query) {
      return {
        q: '',
      };
    }
    return {
      q: query,
    };
  },

  serialize({ q }, url) {
    if (!q) {
      return '';
    }
    url.searchParams.set('q', q);
  },
};

Creating a new mapper

To create a new mapper, you need to create a new file in the mappers/paramMappers directory of the coveo module. The file should export an object that implements the ParamMapper interface.

Params mapper factory

Params mapper factory function is responsible for creating a facade for all the mappers passed to it. It is defined in the paramMapperFactory.ts file in the mappers directory of the coveo module.

It exposes serialize and deserialize functions that are responsible for serializing and deserializing the URL parameters using all the mappers passed to it.