Skip to main content
Topsort’s Kotlin library enables our clients to easily send auction requests and track events within Android applications.
Minimum requirements: Java 11, Kotlin 2.1, minSdk 24 and compileSdk 36.

Installation

Add the dependency to your build.gradle file:

Setup

Kotlin

UserIdentity.of turns a null or blank id into UserIdentity.Unidentified, in which case the SDK generates an id and keeps it across launches. Pass your own id whenever you have one, logged in or not. When a user logs in, call Analytics.setup again with UserIdentity.of(<their id>) so events are reported under your own id. A generated id does not match your audiences.

Java

Reporting Events

Renders

A render records that a sponsored ad was inserted into the page, separately from the impression, which records when the ad becomes visible. Renders are sponsored-only, so there is no organic variant.
To report several renders in one event, build them with Render.Factory and pass them to Analytics.reportRenders(list). Render.Factory.build has no defaults for resolvedBidId, placement, occurredAt (an RFC 3339 timestamp), opaqueUserId and id, so pass them for each render, with a unique id.

Impressions

An impression records that an ad or product became visible to the shopper.
For organic results, use Analytics.reportImpressionOrganic with entity = Entity(id = "<product id>", type = EntityType.PRODUCT) instead of resolvedBidId. Import Entity and EntityType from com.topsort.analytics.model: the banner click callback uses a different EntityType.

Clicks

A click records that the shopper clicked an ad or product.
For organic results, use Analytics.reportClickOrganic with an entity, as for impressions.

Purchases

A purchase records the products a shopper bought. Topsort attributes it to the ads the shopper interacted with.
unitPrice is required. It is the price of a single item in major units of your marketplace currency (13 means 13.00), not cents. In version 4.1.0 it is an Int, so only whole amounts can be sent.

Page Views

A page view records that the shopper navigated to a page. The API requires a pageId.

Event delivery

Reported events are stored on the device and sent in the background. They are retried after failures and across app launches. The SDK drops an event only if the API rejects it with a 4xx error (429 and 408 are retried), if the cache grows past 5,000 events and the oldest are evicted, or if a stored event can no longer be read. To count dropped events, register a listener:
The listener runs on the SDK’s worker thread, so keep it quick. Run an auction for products, a category or a search keyword, then report events with the resolvedBidId of each winner.
Other configs are AuctionConfig.CategorySingle, CategoryMultiple, CategoryDisjunctions and Keyword. All of them accept opaqueUserId and placementId (1 to 8). Add BannerView to your activity XML:
Setup in your activity:
BannerView reports the render as soon as the winner is displayed, the impression once the banner is on screen, and the click when it is tapped. Do not report these events yourself for banners it displays. For full documentation, see the GitHub repository.