Skip to main content
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:
Or import it from a CDN inside a module 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

A listings auction takes at least one and at most two of products, category and searchQuery, for example category: { id: "c_shoes" }. Category ids and product ids must match the ones in your catalog exactly. With category: { ids: [...] } a product must belong to all of the categories, and with category: { disjunctions: [[...], [...]] } it must belong to at least one category in each group. Since 0.6.0, listings also accept filter: { operator: "and", attributes: ["brand:nike"] } (up to 5 key:value attributes). For banners, leave category and searchQuery empty for a landing page banner, set category for a category banner, and set searchQuery for a keyword banner. Each auction in results has its own error flag, so check result.error even when the call succeeds. See the auctions API reference for every field.

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.

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.

Impressions

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

Clicks

A click records that the shopper clicked an ad or product.
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.
unitPrice is a decimal in the major unit of your marketplace currency (49.99, not 4999). Set vendorId on an item when the product is sold by several vendors or you want halo attribution.

Pageviews

A pageview records that the shopper visited a page.
Each event array accepts at most 50 events per request. See the events API reference for every event field.

Error Handling

Failed calls reject with an AppError (exported by the package) that has the fields status, statusText, body and retry. AppError is not a subclass of Error, so check it with instanceof AppError. reportEvent resolves with { ok: false, retry: true } when the response status is 429 or any 5xx and the response body is JSON. Retry the call with the same event object, so every event keeps its id. The id makes event reporting idempotent, so never generate a new one for a retry:
Every other failure rejects, and retry is false. This includes a 400 (body holds the API error), a missing apiKey (401), a network failure, a timeout, and a 5xx response whose body is not JSON. Network failures and timeouts reject with an AppError with status 500, and body holds the error message. createAuction never resolves with retry: for a 429 or 5xx it rejects with an AppError whose retry is true. The TopsortClient constructor accepts these options besides apiKey:
  • host: API host, defaults to https://api.topsort.com.
  • timeout: timeout in milliseconds. There is no default timeout.
  • userAgent: a string appended to the X-UA header that the SDK sends.
  • fetchOptions: options merged into the fetch call. The SDK sets keepalive: true by default, so pass { keepalive: false } to turn it off.
The type definitions currently require page.value, items[].quantity and the winner campaignId, although the API treats them as optional. For full documentation and end-to-end examples, see the GitHub repository.