Installation
Install the package from npm and import it in your code:import and top-level await, so run them in a <script type="module"> or in your bundled code.
Creating an Auction
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 sameopaqueUserId 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.
Renders
A render records that a sponsored ad was inserted into the page, whether or not it ever becomes visible. Renders are sponsored-only, soresolvedBidId 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.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.Error Handling
Failed calls reject with anAppError (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:
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 tohttps://api.topsort.com.timeout: timeout in milliseconds. There is no default timeout.userAgent: a string appended to theX-UAheader that the SDK sends.fetchOptions: options merged into thefetchcall. The SDK setskeepalive: trueby default, so pass{ keepalive: false }to turn it off.
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.