Algolia Setup

Introduction

Styla Frontend relies on Algolia in order to offer 2 functionalities:

Search
Product Sorting / Filtering (in category page)

This document explains how to setup an Algolia integration.

We will divide these instructions in 2 main steps:

Configuring the Algolia account
Setup Algolia inside Styla

Configuring the Algolia Account

First of all you need to create an Algolia account.

Plan selection

Choosing the Algolia plan depends on the expected amount of records and traffic.

To calculate the approximate number of records that you will need, you need to know the following data:

Number of product variants	How many product variants are in the catalog. We are, in fact, going to create a record for each variant (Example: 10 products, with 4 variants each, will total up to 40)
Number of static pages	This includes the number of static pages that are going to be created via Styla (landing pages, FAQ, blog posts etc.) and also the number of categories, since we are going to create a page for each category
Number of sorting criteria	The user can decide how many sorting criteria will be available in the listing page (check this table for reference)

Once this data is known, we can calculate how many records we will need using the following formula:

N. of records = (N. of variants + N. of static pages) * N. of sorting criteria

Once this number is known, you can determine whether you fit in the free plan or not

Algolia pricing as of February 2023

More info on Algolia pricing here: https://www.algolia.com/pricing/

Index creation

After the account has been created, the first thing to do is to create an index.

Instructions for creating a new index can be found here. Index can be named based on our preference, we just need to note down the name that we choose because it will be needed in the upcoming steps.

We experienced some issues with index names containing spaces. For this reason we recommend using “url friendly” names. Underscores and dashes are also ok.

Index configuration

Once the index has been created, we need to configure it in order to make it work with Styla Frontend.

All the following settings can be found under the “Configuration” tab of the index that we just created

Relevance Essentials → Ranking and sorting

We need to set the default sorting criteria for this index. For consistency reasons, we recommend to set this with the same criteria being used as default on the Styla category page. If no overwrite was manually set (by Styla, in the category base DB) it means that the default criteria is going to be updated_at_desc.

To create a new sorting criteria:

Click on “Add sort-by attribute”
type the name of the field that will be used for sorting (more on that in the table below)
Define if the sorting will be ascending or descending (more on that in the table below)
Make sure that this criteria is the main one. This can be achieved by dragging the newly created attribute to the top

In this example we are sorting by the “title” attribute ascending. This setup is mapped to “Alphabetically A to Z” in Styla frontend

In the following table a recap of the allowed sorting criteria:

Criteria ID	Description	Data field	ASC or DESC

Criteria ID	Description	Data field	ASC or DESC
`alpha_asc`	Alphabetically: A to Z	`title`	ASC
`alpha_desc`	Alphabetically: Z to A	`title`	DESC
`price_asc`	Price: Low to High	`min_price`	ASC
`price_desc`	Price: High to Low	`min_price`	DESC
`best_selling`	Best Selling First	`total_sold`	DESC
`sort_order_asc`	Featured Items	`sort_order`	ASC
`updated_at_desc`	Newest Arrivals	`updated_at`	DESC

Filtering and Faceting → Facets

Facets are used in order to be able to properly filter records when sending the API requests.

To create a Facet go to “Attributes for faceting” and then to “Add an attribute”.

These are the attributes that you need to setup as attributes for faceting:

categories
entity_type
options
product_data

Search behavior → Deduplication and grouping

This setting defines how results are being grouped.

Example: let’s say that we have a product available in multiple variants (T-shirt available in multiple colors)

In this case we can deal with the results in 2 different ways:

a) All variants are being shown in the results

b) Only one variant will be shown per product. In this case we will show the variant that matches the active filters (for example if “Color: yellow” is active on the filters, the yellow variant of that T-shirt will be show)

Based on the desired behavior we will need to set up Algolia accordingly:

For case a:

In this case deduplication is not necessary. This setting can be left as it is

For case b:

In deduplication settings, use the following configuration:

Distinct: true
Attribute for distinct: top_level_SKU (This will only work if the merchant has filled out the SKU field for all products in BigCommerce, but this field is not mandatory and not all merchants use it.
Alternative attribute for distinct: title. Use this if not all products have SKUs and titles are unique

Replicas

Algolia is pre-sorting data in the index in order to grant high performance. This means that, for each sorting parameter that we want to offer to the end user, we need to create an index replica.

To create a new replica go to:

Replicas → Create replica index

You can choose any name (we suggest to name it as the sorting criteria, in order to find it easily when needed)

After the replica has been created, it can be accessed by clicking on the corresponding link.

After accessing the replica, it will look exactly like an index. Now all we need to do is go to:

Configuration → Relevance Essentials → Ranking and sorting and modify the sorting criteria based on what we want for this replica.

Please repeat the steps listed on Ranking and Sorting for each of the desired replica.

Data for Styla configuration

Before moving to the Styla configuration, we need to note down some important information about our Algolia account:

All index names

The main index name + all the replica names that we created

API keys

Click on the gear icon on the bottom left. Then go to “API keys”.

Note down these 3 keys:

Application ID
Search-Only API Key
Admin API Key

They will be needed on the next step.

Setup Algolia inside Styla

Log into the Organization Manager and select the front where we want to apply the Algolia configuration.

Then go into Front Configuration and check if the integrations key is already there at the root level of the JSON config. If not it needs to be created. Otherwise we can just append here the Algolia-related information.

A fully setup integrations config looks like this:

"integrations": {
    "searchEngine": "algolia",
    "services": {
        "algolia": {
            "searchOnlyAPIKey": "<insert key here>",
            "adminAPIKey": "<insert key here>",
            "applicationId": "<insert id here>",
            "index": "stage_STYLA",
            "sortedIndexes": {
                "alpha_asc": "stage_STYLA",
                "alpha_desc": "stage_STYLA_alpha_desc",
                "price_asc": "stage_STYLA_price_asc",
                "price_desc": "stage_STYLA_price_desc",
                "best_selling": "stage_STYLA_best_selling",
                "sort_order_asc": "stage_STYLA_sort_order_asc",
                "updated_at_desc": "stage_STYLA_updated_at_desc"
            }
        },
        ... // other integrations go here
    }
}

Here’s a brief description of the fields:

Field name	Description

Field name	Description
`searchEngine`	Here we define which service we want to use for the search feature. At this moment we only support Algolia, therefore `algolia` is currently the only accepted value.
`searchOnlyAPIKey`	Search-Only API Key that we noted down earlier. This information will be exposed in the frontend and doesn’t allow any data editing on the Algolia account. It’s a read-only key.
`adminAPIKey`	Admin API Key that we noted down earlier. This will be used by our backend services in order to update the Algolia account. This information will not be exposed in the frontend, therefore only Styla has access to it.
`applicationId`	Application ID that we noted down earlier.
`index`	This is the main index. It’s the one that will be filled with data from our backend. It’s also used for the search functionality.
`sortedIndexes`	These indexes are the ones that will be used for the products filtering and sorting, in the category page. They will include as well the replicas that we created in the previous step. Please note that you can still use the main index here. In that case, just make sure that the sorting criteria matches with the one that we defined in Algolia. For the allowed keys please refer to the sorting table. Also keep in mind that not all keys are required. You can define which keys to use based on the sorting criteria we want to allow for this front. Example: a client only wants to have “Alphabetical sorting (A to Z)” and “Newest Arrivals”. In that case, the config will look like this: `"sortedIndexes": { "alpha_asc": "stage_STYLA", "updated_at_desc": "stage_STYLA_updated_at_desc" }`

Once the configuration is ready you can trigger a full re-index of the website by using the re-index button on the Organization Manager:

When this is done, results should start to appear in the Algolia account.

You can now test the full functionality on the rendered front:

Search
Product sorting (via dropdowns)
Product filtering