Topsort Proxy

The proxy is a middle layer between the marketplace backend and the results server (Algolia’s server, for example). It acts as a bridge between the marketplace, the search engine and Topsort. This allows the proxy to ingest auction winners retrieved from Topsort into the response provided by the search engine, and return the final merged response to the marketplace.

The proxy is compatible with most tech stacks, and it has been tested with platforms like VTEX, Algolia, and Salesforce.

How to Use the Proxy

To start using the proxy, you only need to change the hostname in your existing API call, from your catalog or search engine to our proxy. For example, change from:

https://api.site.com/catalog/query?taxonomy=clothes

to:

https://site.proxy.topsort.com/catalog/query?taxonomy=clothes

And we take it from there. We send the request to Topsort’s auction engine and to the catalog or search engine. If any of the products returned by the catalog or search engine is promoted, we will indicate it in the merged response we’ll build, which will be returned to the marketplace.

Currently, the proxy supports application/json responses. Support for XML and GraphQL is planned.

How Promoted Products Are Added

Consider the following request, which fetches products from the ‘office’ taxonomy:

GET https://api.site.com/catalog/query?taxonomy=office

The response from the catalog or search server without Topsort’s proxy integration follows this schema:

{
  "products": [
      { "id": "1", "name": "High-Speed Color Laser Printer" },
      { "id": "2", "name": "Adjustable Height Standing Desk" },
      { "id": "3", "name": "Ergonomic Swivel Office Chair"},
      { "id": "4", "name": "Wireless Keyboard and Mouse Combo" },
      { "id": "5", "name": "Magnetic Whiteboard with Marker Set" },
      { "id": "6", "name": "Multi-drawer Filing Cabinet" },
      { "id": "7", "name": "Noise-Cancelling Headset with Microphone" }
  ]
}

For this example, assume that campaigns have been created to promote products with IDs 3, 6, and 7. These products are then eligible to be returned as the winners of a sponsored listings auction request to our API. This means they could be presented as advertisements to the end user. The proxy integration ensures that these promoted products appear first in your catalog taxonomy response without the need for manual integration with Topsort’s auctions API. After merging promoted products into the response, it would look something like this:

{
  "products": [
      {"id": "3", "name": "Ergonomic Swivel Office Chair", "rank": 1, "resolvedBidId":"..."},
      {"id": "6", "name": "Multi-drawer Filing Cabinet",  "rank": 2, "resolvedBidId": "..."},
      {"id": "7", "name": "Noise-Cancelling Headset with Microphone",  "rank": 3, "resolvedBidId": "..."},
      {"id": "1", "name": "High-Speed Color Laser Printer" },
      {"id": "2", "name": "Adjustable Height Standing Desk" },
      {"id": "4", "name": "Wireless Keyboard and Mouse Combo" },
      {"id": "5", "name": "Magnetic Whiteboard with Marker Set" }
    ],
  "topsort": {
       "winners":[
           {"rank": 1 ,"type": "product", "id": "3", "resolvedBidId": "..." },
           {"rank": 2, "type": "product", "id": "6", "resolvedBidId": "..." },
           {"rank": 3, "type": "product", "id": "7", "resolvedBidId": "..."}
         ]
    }
}

Only the order of the products is changed. The original structure and product fields remain the same.

Understanding the New Fields

These are the new fields added to the response:

• rank: The position of the promoted product in the auction.
• resolvedBidId: A unique ID used to track the product in analytics.

A new object named topsort is added at the root level only when promoted products are included. It lists all auction winners with their details. The topsort object contains a winners array, holding information for each promoted product as a winner of an auction. Each winner has the following properties:

• rank: Indicates the product’s ranking among the auction winners.
• type: Specifies the type of entity to be promoted. Currently, this value is always “product”.
• id: The product’s ID.
• resolvedBidId: An identifier for the product’s participation in a Topsort auction.

How to Track Events (Impressions, Clicks, Purchases)

If you use Topsort’s analytics.js library or Events API, use the product id and resolvedBidId fields to track user interactions (clicks and impressions) with promoted products.

Example of the markup needed:

<div
  class="product"
  data-ts-product="3"
  data-ts-resolved-bid="resolvedBidId">
  ...
</div>

The information added to your catalog or search response simplifies the installation of the analytics.js library or an integration with Topsort’s events API for tracking ad interactions or events such as impressions, clicks, and purchases. The analytics library requires certain markups to be added to your HTML code to automate event tracking for promoted products. These attributes allow the library to automatically track impressions, clicks, and conversions. For more information, see the analytics.js documentation.

Proxy Features

• Response Caching: Reduces latency by caching successful responses from the catalog or search engine.
• Staging Mode: Allows testing before going live.
• Catalog Sync Support: Sends information to keep Topsort’s catalog up to date.
• Built-in Logging: Collects data on products, auctions, and performance.