Android

Overview of Topsort’s Kotlin library for auction requests and event tracking in Android applications

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:

dependencies {
    implementation 'com.topsort:topsort-kt:4.1.0'
}

Setup

Kotlin

import android.app.Application
import com.topsort.analytics.Analytics
import com.topsort.analytics.UserIdentity

class KotlinApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Analytics.setup(
            application = this,
            identity = UserIdentity.of("<YOUR_OPAQUE_USER_ID>"),
            token = "<API token>"
        )
    }
}

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.

Java

import android.app.Application;
import com.topsort.analytics.Analytics;
import com.topsort.analytics.UserIdentity;

public class JavaApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Analytics.INSTANCE.setup(this, UserIdentity.of("<opaqueUserId>"), "<API token>");
    }
}

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.

import com.topsort.analytics.Analytics
import com.topsort.analytics.model.Placement

Analytics.reportRender(
    resolvedBidId = "<The bid id from the auction winner>",
    placement = Placement(path = "search_results", position = 1)
)

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.

Analytics.reportImpressionPromoted(
    resolvedBidId = "<The bid id from the auction winner>",
    placement = Placement(path = "search_results", position = 1)
)

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.

Analytics.reportClickPromoted(
    resolvedBidId = "<The bid id from the auction winner>",
    placement = Placement(path = "search_results", position = 1)
)

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.

import com.topsort.analytics.model.PurchasedItem

val item = PurchasedItem(
    productId = "<Marketplace id for the item>",
    unitPrice = 1295,
    quantity = 20
)
Analytics.reportPurchase(
    id = "<Marketplace id for the entire purchase>",
    items = listOf(item),
)

Banner Ads

Add BannerView to your activity XML:

<com.topsort.analytics.banners.BannerView
    android:id="@+id/bannerView"
    android:layout_width="353dp"
    android:layout_height="103dp" />

Setup in your activity:

class SampleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.sample_activity)

        this.lifecycleScope.launch {
            val bannerView = findViewById<BannerView>(R.id.bannerView)
            val bannerConfig = BannerConfig.CategorySingle(slotId = "slot", category = "category")

            bannerView.setup(
                config = bannerConfig,
                path = "sample_activity",
                location = "hero-banner"
            ) { id, entityType -> onBannerClick(id, entityType) }
        }
    }
}

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.