What are the implementation steps for Merchandising?

Merchandising allows partners to implement a merchandised store front on their websites. This is usually for Product Listing Pages and Microsites.

This document will cover the important steps required to set this up. Actual implementation of Merchandising is entirely performed by partners, however Spotler does provide an open source reference implementation written in node.js, TypeScript, and React, and also Postman API documentation with examples to assist them in this endeavour:

For an overview of the configuration options with merchandising, read about it in this article: Merchandising. Read below for the implementation steps:

  1. Create an Activate Search account
  2. Set up and import your data
  3. Configure important search features
  4. Configure merchandised pages
  5. Test the API using Postman
  6. Build the client implementation

1. Create an Activate Search account

The initial step is to setup an Activate Search account. Merchandising is built on top of Activate Search, and although a partner can use Merchandising endpoint independently of the Search Endpoint, the underlying data and its configuration are the same for Search and Merchandising. Follow the standard procedure to set up a search account using the Sign Up page, or the Site Creation button if you already have an account, and following the steps described. For more information, read here how to set up your Spotler Activate Search account.

2. Set up and import your data

Before development, it is necessary to understand your data and how to import it into Activate Search. This article describes the supported XML feed format: What should my data feed look like?

During account creation, you would have been prompted to enter your feed URL. Ensure that any custom fields in the feed that are used for sorting or filtering are enabled in the Custom Fields page. Keep in mind that you will need to import your feed again after changing any Custom Fields configuration.

3. Configure important search features

Although merchandising can be integrated into a bespoke solution entirely independent of Activate Search and has its own dedicated endpoint, there are some basic search features that can assist that endeavour. These are demonstrated in the demo-shop application code

The main search features that provide useful functionality that can be leveraged for merchandising are Sort Fields and Filters.

The merchandising service requires the currect context of the page to return the merchandised results correctly. On these listing pages there is usually a sorting option, and sometimes a filter section available, to narrow the list of the product items. By configuring them in Activate Search, these options will be in the response from merchandising, allowing the custom client to change the merchandised page's product sorting and filtering.

4. Configure merchandised pages

Set up your merchandised pages. This is achieved with these basic steps:

  1. Click the +Add a new page button;
  2. Enter the page name and page identifier. Use a name for the page that is easy to understand. The identifier os the value that is sent by the client to receive this merchandised page. It can be any string, and could reflect the breadcrumb of the listing page;
  3. Click the Add merchandising state button;
  4. Add the Manual Merchandising and Ranking Rules that should apply for this page;
  5. If you add more merchandising states, then the first active state will be the one applied to the results.

For more info on the configuration options for merchandising, read this article: Merchandising.

5. Test and explore the merchandising setup using the API

Take a look at the API reference documentation for the Merchandising endpoint. Try out the API using the configured merchandising page. Try modifying the merchandising state to see the response change.

Try applying a Sort Field if one is configured for your project, and perhaps a Filter if one is configured for your project.

Note that the format of filtering and sorting requests are the same for the merchandising endpoint, as for the Search endpoint. This is described in the OpenAPI documentation.

6. Build the client implementation

This is entirely down to the partner, however, Activate Search provides a reference implementation, written in node.js, TypeScript and React, so that partners can inspect how an implementation can work.

The demo shop reference implementation web application can be run locally by following the instructions in the project's README file.

Things to consider during client development

State maintenance
The client needs to maintain the state of the filters and the sorting currently applied, and other such state. The endpoint itself is stateless.

Client sessions and reporting
Activate Search reporting processes anonymised user behaviour based upon "user sessions". However, the service endpoint is entirely stateless. As such, the client needs to maintain its own session and provide unique session identifier in the user_session_id attribute in the request message to ensure that user behaviour reporting remains valid. Note: do not use a hard coded session in production, as all requests will be seen as the same user and will distort reporting.