auctions

Topsort Proxy

At Topsort, we are continuously pushing the boundaries to develop innovative and efficient solutions for our clients. Our latest endeavor focuses on streamlining the integration process by proxying your catalog or search engine requests, allowing for a more seamless experience with our platform.

We understand that every client has unique needs and technologies, and our new proxy solution is designed to be highly adaptable. It acts as a middleman – a proxy – between your marketplace’s search or filtering results and the origin server, merging relevant auction data into the results while maintaining top-notch performance and compatibility with various tech stacks.

High level overview of the proxy architecture

In order to start using the proxy you only need to update the hostname in your request from your existing host to the hostname set up for you by Topsort. For instance, https://api.site.com/catalog/query?taxonomy=clotheswould instead point to https://site.proxy.topsort.com/catalog/query?taxonomy=clothes. Our proxy will then handle the catalog request, match any auctions, and augment your results.

Currently, our proxy solution supports responses with a content-type of application/json, but we’re committed to expanding our capabilities to include XML and GraphQL-type responses in the near future.

Our proxy solution also offers several unique features:

Caching successful origin responses
Routing and shaping traffic based on auction confidence with a “staging mode.”
Providing the scraper with information to maintain a populated catalog.
Storing analytics about products, auctions, and performance metrics.

We’ve been testing the compatibility of our proxy solution with various clients and technologies, such as VTEX, Algolia, and Salesforce, among others.

If you are interested to try this out, please reach out to us! Our team is eager to collaborate with you in revolutionizing the way you integrate with Topsort and optimizing your marketplace performance.

How do we augment your catalog results with promoted products?

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

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

The response from the origin 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" }
  ]
}

Once the proxy is receiving traffic, the upstream response may contain promoted products, assuming valid campaigns for these products are active. For more details, see campaign creation documentation.

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 should 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 your response, it would look something like this:

{
  "products": [
      {"id": "3", "name": "Ergonomic Swivel Office Chair", "rank": 1, "resolvedBidId":"WyJWSlBGSXJXayIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0="},
      {"id": "6", "name": "Multi-drawer Filing Cabinet",  "rank": 2, "resolvedBidId": "WyI5aG1YY1RYQSIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0="},
      {"id": "7", "name": "Noise-Cancelling Headset with Microphone",  "rank": 3, "resolvedBidId": "WyI5aG1YY1RYQSIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0="},
      {"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": "WyJWSlBGSXJXayIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0=" },
           {"rank": 2, "type": "product", "id": "6", "resolvedBidId": "WyI5aG1YY1RYQSIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0=" },
           {"rank": 3, "type": "product", "id": "7", "resolvedBidId": "WyJ2OTlIZHhpWCIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0="}
         ]
    }
}

All properties of the response from the origin server remain unchanged except for the product order. This means that if you already use the ordering of items from the list, you don’t have to do any changes to get sponsored listings in the right place!

In addition, we include product properties and attributes that provide insights into the auction result, which justifies the presence of promoted products. A promoted product in the catalog response is characterized by two new properties set by the proxy:

rank: Indicates the product’s ranking among the auction winners. Use this value as a reference for where this product should be displayed to the end user.
resolvedBidId: An identifier for the product’s participation in a Topsort auction. This value is required for using the analytics.js library or reporting events to track campaign performance and analytics. See our analytics.js library documentation for more details.

An additional attribute added at the root level of the origin server response is the topsort object. This object appears only when the catalog response includes promoted products and summarizes the auction results. If this object is absent, the proxy made no changes to the catalog response. The topsort object looks like this:

"topsort": {
     "winners": [
          { "rank": 1 , "type": "product", "id": "3", "resolvedBidId": "WyJWSlBGSXJXayIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0=" },
         { "rank": 2, "type": "product", "id": "6", "resolvedBidId": "WyI5aG1YY1RYQSIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0=" },
         { "rank": 3, "type": "product", "id": "7", "resolvedBidId": "WyJ2OTlIZHhpWCIsIjA2NDVkNGU1LTliOTYtNzQ3MC05MzA0LTQ4MDZmMGM1MzQxZSIsImxpc3RpbmdzIiwiIiwiIl0="}
      ]
}

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 do I implement analytics and event tracking with the proxy?

The information added to your origin server 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.

To enable the analytics.js library, use the id and resolvedBidId values from the topsort object provided by the proxy to enrich your product container. Here’s an example of how these markups might look in your product container:

<div
     class="product"
     data-ts-product="<productId>"
     data-ts-auction="<auctionId>"
     data-ts-resolved-bid="<resolvedBidId>">
  ...
</div>

For more detailed information on setting up the analytics.js library, please visit our analytics.js library documentation.