Skip to content
Topsort Documentation
guides

Integrating Topsort and Algolia

Introduction

Algolia is a powerful search engine that allows you to navigate through your catalog with ease. It is a great tool to use when you want to serve your catalog to your users. In this guide, we will show you how the Topsort and Algolia integration works to provide a seamless auction-powered search experience to your users.

Most likely, your applications and/or website is already using Algolia. If not, you can sign up for a free account at Algolia and follow the steps to create an index.

Prerequisites

  1. Your catalog is stored in algolia
  2. You have a Topsort account
  3. You are using the Algolia SDKs to query the Algolia index

Integration steps

We will cover three main areas of integration: Catalog, Auctions and Events.

Catalog

  1. Reach out to your Topsort representative and share your Algolia index name. We will then configure the integration on our end.
  2. Create an api key in Algolia that has the browse permission. This key will be used by Topsort to query the Algolia index for import purposes.
  3. Topsort will verify that the Algolia index is accessible and will start importing the catalog. This is done by looking at the catalog structure and how to extract data such as product, category and vendor information.

Auctions

As part of the previous step, Topsort will additionally configure its proxy to support your Algolia index. After this is done, all that’s left is for you to change the hostname of your Algolia SDK to the Topsort proxy hostname:

import algoliasearch from 'algoliasearch/lite';


const client = algoliasearch('YourApplicationID', 'YourWriteAPIKey', {
  hosts: [{ url: 'myslug-sandbox.topsort.workers.dev' }],
});
const index = client.initIndex('your_index_name');

After this, your requests will flow through our proxy and automatically get augmented with a winner context (if there are winners).

As described in the proxy documentation, you can expect the resolvedBidId attribute to be present alongside the other attributes in the search results. Use this attribute to display the winner of the auction in your search results as a sponsored listing. In order to not have to look for this in every item, you can check for the presence of a topsort object in the root of the json response.

Events

The last thing you want to do is to send events such as impressions, clicks and purchases to Topsort. The easiest way to achieve this is to use analytics.js. This library will automatically send events to Topsort when a user interacts with your search results by checking for specific html elements.

By now, you should be ready to start testing the implementation. Reach out to your Topsort representative if you have any questions!