Need help with your Topsort integration?
Talk to us, the integrations engineering team.
Reach us via your dedicated messaging channel or at{" "}
support@topsort.com.
If you're not a customer yet,{" "}
book a demo with our
sales team instead.
;
};
The [Topsort JavaScript SDK](https://github.com/Topsort/topsort.js) 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
```html theme={null}
```
## Creating an Auction
```javascript theme={null}
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
```javascript theme={null}
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:
```javascript theme={null}
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](https://github.com/Topsort/topsort.js).
