iOS

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 SwiftUI
import Topsort

@main
struct 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.

Requesting Auctions

import Topsort

let products = try AuctionProducts(ids: ["p_dsad", "p_dvra", "p_oplf"])
let category = AuctionCategory(id: "c_fdfa")

let auctions = [
    Auction(type: "banners", slots: 1, slotId: "home-banner", device: "mobile", category: category),
    Auction(type: "listings", slots: 2, device: "mobile", products: products)
]

let result: AuctionResponse = try await Topsort.shared.executeAuctions(auctions: auctions)

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).

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 SwiftUI
import TopsortBanners

struct 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.