Skip to content
Toposort Logo
guides

Integrating Topsort and Algolia

Introduction

Algolia is a powerful search engine that provides fast, relevant results for navigating catalogs. By integrating Topsort, you can monetize your catalog search by including auction-powered listings that promote specific products.

This guide outlines two integration options for Topsort and Algolia:

  1. Option 1: Single-Index Integration: Use your existing Algolia index (primary index) to serve both organic and auctioned products.
  2. Option 2: Dual-Index Integration: Use a separate index (secondary index) for promoted products alongside your organic index.

Each option has different implementation steps, pros, and cons to help you choose the most suitable method for your use case.

Prerequisites

  1. Your catalog is stored in an Algolia index
  2. You have a Topsort account
  3. You are using the Algolia SDK to query your Algolia index
  4. You have an Algolia API key with the required permissions (search, browse, add, delete records)

Option 1: Single-Index Integration

In this option, Topsort will work directly with your primary Algolia index, which contains both organic and auctionable products. This is the simpler integration method, ideal if you want to keep everything within one index.

Integration Steps:

  1. Reach out to Topsort with your Algolia index name.

  2. Create an API key with browse permissions so Topsort can access your Algolia index to import your catalog.

  3. Topsort Proxy Configuration: You will need to adjust the Algolia SDK to point to the Topsort proxy. The proxy will augment search results with auction data automatically. Example code:

    import algoliasearch from 'algoliasearch/lite';
    

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

  4. Auction Winners: Topsort will automatically include a resolvedBidId attribute in the search results to identify auction winners. You can use this to display sponsored products alongside organic results.

  5. Events: You will need to integrate Topsort’s event tracking (impressions, clicks, purchases) using analytics.js or any of the Topsort SDK’s.

Option 2: Dual-Index Integration

This option introduces a secondary index in Algolia for promoted products. This method allows for more fine-grained control over the integration by separating the organic and promoted products into different indices. This approach is ideal if you want more control over how promoted products are handled and auctioned.

Integration Steps:

  1. Primary Index Configuration: The primary index holds your organic products and should be kept in sync with your catalog in Topsort.

    • API Key: You need an Algolia API key with search and browse permissions for the primary index.
    • Ensure Consistency: The objectID in Algolia should match the product id field in Topsort.

  2. Create a Promoted Products Secondary Index:

    • Topsort will create a secondary index for promoted products.
    • Whenever a campaign is created or updated, the secondary index is populated with promoted products, keeping the same structure as the primary index.
    • API Key: You need an Algolia API key with search, browse, add, and delete permissions for the secondary index.

  3. Multi-query Setup: Your system will need to query both the primary and secondary indices at the same time. Example:

    Terminal window
    curl -X POST \\
    -H "Content-Type: application/json" \\
    -H "X-Algolia-API-Key: marketplace_algolia_api_key" \\
    -H "X-Algolia-Application-Id: algolia_instance_id" \\
    --data '{"requests": [{"indexName": "organic_index_name", "params": "query=sq_test&hitsPerPage=1000"}, {"indexName": "promoted_index_name", "params": "query=sq_test&hitsPerPage=10"}]}' \\
    "<http://topsort.proxy/1/indexes/*/queries>"

    This request retrieves results from both indices, allowing Topsort to merge auction winners into the organic results.

  4. Auction Winners: Topsort will run an auction on the promoted products retrieved from the secondary index. Winning products will be merged with the organic results from the primary index, appearing at the top of the search results.

  5. Events: As in Option 1, you need to track impressions, clicks, and purchases using analytics.js or any of the Topsort SDK’s.