Integrate Topsort’s Swift library for auction requests and event tracking in mobile applications
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:
dependencies: [ .package(url: "https://github.com/Topsort/topsort.swift.git", from: "1.4.1"),],targets: [ .target( name: "YourApp", dependencies: [ .product(name: "Topsort", package: "topsort.swift"), .product(name: "TopsortBanners", package: "topsort.swift"), // Only if you display banners ] ),]
Configuration
import SwiftUIimport Topsort@mainstruct MyApp: App { init() { do { try Topsort.shared.configure(Configuration(apiKey: "your-api-key")) } catch { print("Topsort not configured: \(error.localizedDescription)") } } var body: some Scene { WindowGroup { ContentView() } }}
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.
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).
let render = RenderEvent(resolvedBidId: winner.resolvedBidId, occurredAt: Date.now)Topsort.shared.track(render: render)
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.
var body: some View { VStack { AsyncImage(url: self.product.imageURL) Text(self.product.name) } .onAppear { Topsort.shared.track(impression: Event(resolvedBidId: self.winner.resolvedBidId, occurredAt: Date.now)) }}
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.
var body: some View { VStack { AsyncImage(url: self.product.imageURL) Text(self.product.name) } .onTapGesture { Topsort.shared.track(click: Event(resolvedBidId: self.winner.resolvedBidId, occurredAt: Date.now)) }}
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.
Button("Purchase me!") { let item = PurchaseItem(productId: myProduct.id, unitPrice: myProduct.price) let event = PurchaseEvent(items: [item], occurredAt: Date.now) Topsort.shared.track(purchase: event)}
Displaying Banners
import SwiftUIimport TopsortBannersstruct ContentView: View { var body: some View { TopsortBanner(bannerAuctionBuilder: .init(slotId: "slotId", deviceType: "device")) .contentMode(.fill) .onNoWinners({ }) .onError({ error in }) .onImageLoad({ }) .buttonClickedAction({ response in }) .frame(maxHeight: 50) .clipped() }}
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.For full documentation, see the GitHub repository.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.