Algolia Search Integration

Algolia is an extremely fast search solution popular among eCommerce stores. This module replaces the default product search on Product Listing and Search pages with Algolia-powered search, providing superior search performance and advanced features.

Installation

From the root of your Storefront project, run the following command:

npx @vsf-enterprise/storefront-cli add-module search-algolia

Follow the instructions in the command line to complete the installation. This command will:

• install the Algolia API package @vsf-enterprise/algolia-api in the Middleware
• configure the Algolia integration in your middleware configuration
• set up the unified extension to override search methods with Algolia implementation
• create example environment variables for your Algolia credentials

Algolia Setup

The starting point is to feed Algolia with data from your eCommerce instance. A place where Algolia stores the data is called an index, and a single index can contain multiple records. The data structure in Algolia largely depends on the data import option you chose. If you used a ready-made data import plugin, the data structure will be pre-determined based on the existing solution. To fully control the data structure, you can create a .json file yourself, which you will use to feed the Algolia index. Learn more about this in the Algolia documentation.

Data Import

To integrate Algolia with Commercetools, we recommend using the Algolia Commercetools Integration. This integration will handle the data import and index creation for you, and it will also reindex the data automatically when changes are made in Commercetools.

As a result you should have an index in Algolia, you can call it for instance commercetools_products. It should match the default schema.

Sorting

Once the data from your eCommerce is in Algolia, create additional indexes that will contain sorted data. First, decide how many and what sorting options you want to provide to your storefront users, then create a Replica Index for each of these options. Algolia itself recommends this approach to sorting - see more in the documentation. As a result you could have:

• products - a default index with products sorted by relevance
• products_price_asc - a replica index with products sorted by price ascending
• products_price_desc - a replica index with products sorted by price descending

Environment Variables

After installation, update your environment variables in .env file in the Middleware directory:

# search-algolia module
ALGOLIA_API_KEY=your_algolia_search_api_key
ALGOLIA_APP_ID=your_algolia_app_id

Configuration Options

The module installation automatically configures the Algolia integration with platform-specific settings. You can customize these settings in your unified extension configuration file:

The available configuration options are:

• facets - string[]
  • The facets that will be returned by the Algolia search. Make sure to include facets in the Algolia dashboard..
• getFacetLabel - (facet: AlgoliaFacet) => string
  • The function receives the facet and should return the label for the facet.
• indexName - string | (args: SearchProductArgs) => string
  • String name of the Algolia index or a function that returns the name of the Algolia index based on the arguments. A function can be used to return different indexes based on the request, for example, to return a different index based on sorting.
• integrationName - string
  • The name of the integration registered in middleware.config.ts file that will be used to get the Algolia client.
• categoryFacet - string (only for SAPCC and SFCC)
  • The name of the category facet. The facet should contain ids of categories. It is used to populate the category names during the normalization, so if the value is provided, the normalized category SfFacet will include the category id and name.
• normalizeAlgoliaProductCatalogItem - (context: Context, algoliaRecord: AlgoliaRecord) => SfProductCatalogItem
  • A function that normalizes the Algolia record into the Unified Data Layer format. If not provided, the default normalization will be used.
• normalizeAlgoliaFacet - (context, algoliaFacet: AlgoliaFacet) => SfFacet
  • A function that normalizes the Algolia facet into the Unified Data Layer format. If not provided, the default normalization will be used.
• normalizeAlgoliaPagination - (algoliaResponse: AlgoliaResponse) => SfPagination
  • A function that normalizes the Algolia response into the Unified Data Layer format. If not provided, the default normalization will be used.

Custom Normalization

Algolia gives you the flexibility to define the data structure you want to store in the index. If you decide to customize the data structure, or if you use an integration that doesn't provide a ready-made data import plugin (like SAPCC), you will need to provide a custom normalizer.

An example .json structure of the Algolia record may look as follows:

[
  {
    "productID": "30404",
    "sku": "30404",
    "slug": {
      "en": "30404-shades-von-zipper-papa-g-black-gloss-black-gloss-grey",
      "de": "30404"
    },
    "name": {
      "en": "Shades Von Zipper Papa G black gloss black gloss/grey"
    },
    "categories": [
      {
        "name": "Clothes",
        "id": "clothes"
      },
      {
        "name": "Sunglasses",
        "id": "sunglasses"
      }
    ],
    "attributes": {
      "size": {},
      "color": {},
      "ean": "299052695"
    },
    "images": "/medias/?context=bWFzdGVyfGltYWdlc3wxMzUyNXxpbWFnZS9qcGVnfGFHSXlMMmcxWXk4NE56azJOalF3TnpNNU16VTR8ODkzYTA5NjRlMGQ2ZjZjNDE5OTBlZGRhYTUwZjM5YTU5NGNjZDVlNGI2NDI4MTdlMzRkMWMwOTI0MTdiNzlhMQ",
    "prices": {
      "EUR": 7788,
      "USD": 10533
    },
    "gender": ["FEMALE"],
    "stores": ["Cambridge University", "Edinburgh University"]
  }
]

The normalizer should transform given Algolia record into the Unified Data Layer format. The SfProductCatalogItem interface looks as follows:

export interface SfProductCatalogItem {
  id: SfId;
  sku: Maybe<string>;
  name: Maybe<string>;
  slug: string;
  price: Maybe<SfDiscountablePrice>;
  primaryImage: Maybe<SfImage>;
  rating: Maybe<{
    average: number;
    count: number;
  }>;
  quantityLimit: Maybe<number>;
}

To override the built-in normalization, provide the normalizeAlgoliaProductCatalogItem function in the Unified Extension for Algolia:

export const unifiedApiExtension = {
  //...
  algolia: {
    normalizeAlgoliaProductCatalogItem(context, algoliaRecord) {
      // Custom normalization logic. You should return the object matching SfProductCatalogItem interface.
    }
  }
};

You can also override the normalizeAlgoliaFacet and normalizeAlgoliaPagination functions.

Next Steps

After setting up the Algolia module, your Product Listing and Search pages will automatically use Algolia for search functionality. The integration overrides the default search implementation with Algolia's powerful search capabilities, providing faster and more relevant search results for your customers.