JavaScript SDK

Overview of Topsort’s JavaScript SDK for auctions and event tracking

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.