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

Install the package from npm and import it in your code:

npm install @topsort/sdk

import { TopsortClient } from "@topsort/sdk";

Or import it from a CDN inside a module script:

<script type="module">
  import { TopsortClient } from "https://unpkg.com/@topsort/sdk@0.5.0/dist/index.js";

  // The examples below go here.
</script>

The examples on this page are ES modules: they use import and top-level await, so run them in a <script type="module"> or in your bundled code.

Creating an Auction

const topsortClient = new TopsortClient({ apiKey: "TSE_XXXXXXXXXXXX" }); // Replace with your Topsort API key

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

let auctionResult;
try {
  auctionResult = await topsortClient.createAuction(auctionDetails);
} catch (error) {
  console.error("Auction Error", error);
}

Reporting Events

Report a render when you insert a winner into the page, and an impression when that winner becomes visible to the shopper. Send the same opaqueUserId for a shopper on every auction and event, for example an id you keep in a cookie or your login session. A new id per event breaks attribution.

If the page also loads analytics.js, it already reports renders, impressions and clicks for every element with data-ts-resolved-bid. Do not report those events again with the SDK.

const opaqueUserId = "<YOUR_OPAQUE_USER_ID>"; // The same persistent id for this shopper
const placement = { path: "/search/winter" };
const winners = auctionResult?.results.flatMap((result) => result.winners || []) ?? [];

function toEvent(winner) {
  return {
    resolvedBidId: winner.resolvedBidId,
    id: crypto.randomUUID(),
    occurredAt: new Date().toISOString(),
    opaqueUserId,
    placement,
  };
}

Renders

A render records that a sponsored ad was inserted into the page, whether or not it ever becomes visible. Renders are sponsored-only, so resolvedBidId is required and there is no entity field.

// Right after inserting the winners into the page
topsortClient
  .reportEvent({ renders: winners.map(toEvent) })
  .then((result) => console.log("Event Result", result))
  .catch((error) => console.error("Event Error", error));

Impressions

An impression records that an ad or product became visible to the shopper.

// When a winner becomes visible, for example from an IntersectionObserver callback
function reportImpression(winner) {
  topsortClient
    .reportEvent({ impressions: [toEvent(winner)] })
    .then((result) => console.log("Event Result", result))
    .catch((error) => console.error("Event Error", error));
}

Clicks

A click records that the shopper clicked an ad or product.

// From the click handler of a winner's element
function reportClick(winner) {
  topsortClient
    .reportEvent({ clicks: [toEvent(winner)] })
    .then((result) => console.log("Event Result", result))
    .catch((error) => console.error("Event Error", error));
}

For organic results, send entity: { type: "product", id: "<product id>" } instead of resolvedBidId, in impressions and clicks.

Purchases

A purchase records the products a shopper bought. Topsort attributes it to the ads the shopper interacted with.

topsortClient
  .reportEvent({
    purchases: [
      {
        id: "<Marketplace id for the purchase>",
        occurredAt: new Date().toISOString(),
        opaqueUserId,
        items: [{ productId: "p_Mfk11", quantity: 1, unitPrice: 49.99 }],
      },
    ],
  })
  .then((result) => console.log("Event Result", result))
  .catch((error) => console.error("Event Error", error));

See the events API reference for every event field.

Retryable Errors

reportEvent resolves with retry: true for 429 and 5xx responses. Other errors, such as a 400 or a network failure, reject the promise, so catch them too:

function reportWithRetry(event) {
  return topsortClient
    .reportEvent(event)
    .then((result) => {
      if (result.retry) {
        console.warn("Transient error. Retry the call.");
      }
      return result;
    })
    .catch((error) => console.error("Event Error", error));
}

For full documentation and end-to-end examples, see the GitHub repository.