Skip to main content
Topsort’s Swift library enables our clients to easily send auction requests and track events within iOS applications.
Minimum requirements: Swift 6 toolchain (Xcode 16) and iOS 15.

Installation

Install using package.swift:

Configuration

Call Topsort.shared.set(opaqueUserId:) after configuring whenever you have your own id for the user, logged in or not. Without one, the SDK generates an id and keeps it across launches. To tune the SDK, build the Configuration first:
identity controls the id the SDK generates when you do not supply one. .persisted (default) stores it on the device. .ephemeral keeps it in memory for the current process only and deletes any stored id, which suits signed-out users or withdrawn consent. Call set(opaqueUserId:) after configure, not before. onEventsDiscarded is called each time the SDK gives up on events (rejected by the API with a 4xx, retried 50 times, evicted from a full queue, or impossible to serialize). configure throws for an invalid url, flushAt below 1 or flushInterval of 0 or less.

Requesting Auctions

Pass the same opaqueUserId to auctions and events. Topsort uses it to attribute purchases to the ads the shopper saw, and Auction does not fill it in for you. device must be "desktop" or "mobile"; any other value is rejected by the API. placementId is a number from 1 to 8 agreed with Topsort; other values are rejected with 400 (invalid_placement_id). It is not your banner slot: use slotId for that. A request carries 1 to 5 auctions, and executeAuctions throws AuctionError (see Error Handling below).

Reporting Events

Renders

A render records that a sponsored ad was inserted into the view hierarchy, separately from the impression, which records when it becomes visible. Report it as soon as the ad is placed on the screen, before the impression. Renders are sponsored-only, so resolvedBidId is required. winner is one of the winners in the auction response (result.results[i].winners).
Topsort.shared sends only the first render and the first impression of each resolvedBidId for a user and drops any repeat, so reporting from onAppear is safe when a view reappears, for example while scrolling a lazy list.

Impressions

An impression records that an ad or product became visible to the shopper.
For organic results, build the event with Event(entity: Entity(type: .product, id: product.id), occurredAt: Date.now) instead.

Clicks

A click records that the shopper clicked an ad or product.
Organic clicks use the same Event(entity:occurredAt:) initializer as impressions.

Purchases

A purchase records the products a shopper bought. Topsort attributes it to the ads the shopper interacted with.
id is your order id. Always pass it: it makes delivery idempotent when a request is retried, and without it the SDK generates a random UUID that matches nothing in your system. unitPrice is the price of one item as a decimal in major currency units (9.99, not 999). PurchaseItem also takes quantity and vendorId.

Page Views

A page view records that the shopper navigated to a page.

Event Delivery

track queues the event and returns. The queue is sent when it reaches flushAt events, every flushInterval seconds, when the app goes to the background or terminates, and when connectivity returns. Failed sends are retried with exponential backoff and survive app restarts. Call Topsort.shared.flush() to send the queue immediately. Events accept an optional deviceType, which must be "desktop" or "mobile".

Error Handling

executeAuctions throws AuctionError:
Until configure succeeds, track drops events and executeAuctions throws .notConfigured.

Displaying Banners

TopsortBanner reports the render when the auction returns a winner, the impression when the image loads, and the click when it is tapped. Do not report these events yourself for banners it displays. deviceType must be "desktop" or "mobile", and the banner sends the SDK’s current opaqueUserId with its auction.

Using TopsortClient

If you run your own event pipeline, TopsortClient makes one request per call and keeps nothing: no queue, retry or persistence. A thrown error means you still own the events. Pass opaqueUserId to every event, because the default reaches for Topsort.shared.
Topsort.shared remains the recommended path, since it provides batching, retries and delivery across launches. For full documentation, see the GitHub repository.