Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topsort.com/llms.txt

Use this file to discover all available pages before exploring further.

The Topsort JavaScript SDK is the official client library to integrate with Topsort’s auction and event tracking APIs. Built in TypeScript, this SDK simplifies the integration, allowing the creation of an end-to-end flow in minutes.

​
Installation

<script
  async
  type="module"
  src="https://unpkg.com/@topsort/sdk@latest/dist/index.mjs"
></script>
<script>
  window.TS = {
    token: "TSE_XXXXXXXXXXXX", // Replace with your Topsort API key
  };
</script>

​
Creating an Auction

import { TopsortClient } from "https://unpkg.com/@topsort/sdk@latest/dist/index.mjs";

const topsortClient = new TopsortClient({ apiKey: window.TS.token });

const auctionDetails = {
  auctions: [
    {
      type: "listings",
      slots: 3,
      searchQuery: "winter",
    },
    {
      type: "banners",
      slots: 1,
      device: "desktop",
      slotId: "slot123",
    },
  ],
};

topsortClient
  .createAuction(auctionDetails)
  .then((result) => console.log("Auction Result", result))
  .catch((error) => console.error("Auction Error", error));

​
Reporting Events

const winners = auctionResult.results.flatMap((result) => result.winners || []);

if (winners.length > 0) {
  const impressions = winners.map((winner) => ({
    resolvedBidId: winner.resolvedBidId,
    id: crypto.randomUUID(),
    occurredAt: new Date().toISOString(),
    opaqueUserId: crypto.randomUUID(),
    placement: { path: "/search/winter" },
  }));

  topsortClient
    .reportEvent({ impressions })
    .then((result) => console.log("Event Result", result))
    .catch((error) => console.error("Event Error", error));
}

​
Retryable Errors

The reportEvent function returns retry: true for 429 or 5xx errors: 
topsortClient.reportEvent(eventPayload).then((result) => {
  if (result.retry) {
    console.warn("Transient error. Retry the call.");
  }
});
For full documentation and end-to-end examples, see the GitHub repository.