Skip to content
Toposort Logo
ad-platform

Android

Topsort’s Kotlin library enables our clients to easily send auction requests and track events within Android applications.

Java Version

Minimum Java version required: 17.

How it Works

We recommend installing the library via Gradle, adding the dependency to your build.gradle file:

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

The library is distributed through Maven central, which is usually included by default in your repositories. You can also add it directly, if needed:

repositories {
    mavenCentral()
}

The following sample code shows how to setup the analytics library before reporting any event or making auction requests:

Kotlin

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


class KotlinApplication : Application() {


    override fun onCreate() {
        super.onCreate()


        // A consistent opaque user Id should be used to correlate events
        // Either create one, hash an existing one or pass as null to have
        // the SDK generate for you.


        opaqueUserId : String? = "<YOUR_OPAQUE_USER_ID>"?


        Analytics.setup(
            application = this,
            opaqueUserId = opaqueUserId,
            token = "<API token>"
        )
    }
}

Java

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


public class JavaApplication extends Application {


    @Override
    public void onCreate() {
        super.onCreate();


        Analytics
                .INSTANCE
                .setup(this, "<opaqueUserId>", "<API token>");
    }
}

Reporting Events

The following samples show how to report different events after setting up:

Kotlin

fun reportPurchase() {
    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),
    )
}


fun reportPurchaseWithResolvedBidId() {
    val item = PurchasedItem(
        resolvedBidId = "<The bid id from the auction winner>",
        productId = "<Marketplace id for the item>",
        unitPrice = 1295,
        quantity = 20
    )


    Analytics.reportPurchase(
        items = listOf(item),
        id = "<Marketplace id for the entire purchase>",
    )
}


fun reportClickOrganic() {
    val placement = Placement(
        path = "search_results",
        location = "position_1",
    )


    val entity = Entity(
        id = "<Marketplace id for the item>",
        type = EntityType.PRODUCT
    )


    Analytics.reportClickOrganic(
        placement = placement,
        entity = entity,
    )
}


fun reportClickPromoted() {
    val placement = Placement(
        path = "search_results",
        location = "position_1"
    )


    Analytics.reportClickPromoted(
        id = "<Marketplace id for the item>",
        resolvedBidId = "<The bid id from the auction winner>",
        placement = placement
    )
}


fun reportImpressionOrganic() {
    val placement = Placement(
        path = "search_results",
        location = "position_1"
    )


    val entity = Entity(
        id = "<Marketplace id for the item>",
        type = EntityType.PRODUCT
    )


    Analytics.reportImpressionOrganic(
        id = "<Marketplace id for the item>",
        placement = placement,
        entity = entity
    )
}


fun reportImpressionPromoted() {
    val placement = Placement(
        path = "search_results",
        location = "position_1"
    )


    Analytics.reportImpressionPromoted(
        id = "<Marketplace id for the item>",
        resolvedBidId = "<The bid id from the auction winner>",
        placement = placement
    )
}

Java

private void reportPurchase() {


    PurchasedItem item = new PurchasedItem(
            "<Marketplace id for the item>",
            20,
            1295
    );


    Analytics
            .INSTANCE
            .reportPurchase(
                Collections.singletonList(item),
                "<Marketplace id for the entire purchase>"
            );
}


private void reportPurchaseWithResolvedBidId() {
    PurchasedItem item = new PurchasedItem(
        "<Marketplace id for the item>",
        20,
        1295,
        "<The bid id from the auction winner>"
    );


    Analytics
            .INSTANCE
            .reportPurchase(
                Collections.singletonList(item),
                "<Marketplace id for the entire purchase>"
            );
}


private void reportClickOrganic() {
    Placement placement = Placement.Companion.build(
            "search_results"
    );


    Entity entity = new Entity("<Marketplace id for the item>", EntityType.PRODUCT)


    Analytics
            .INSTANCE
            .reportClickOrganic(
                entity,
                placement
            );
}


private void reportClickPromoted() {
    Placement placement = Placement.Companion.build(
            "search_results"
    );


    String resolvedBidId = "<The bid id from the auction winner>";


    Analytics
            .INSTANCE
            .reportClickPromoted(
                resolvedBidId,
                placement
            );
}


private void reportImpressionOrganic() {
    Placement placement = Placement.Companion.build(
            "search_results"
    );


    Entity entity = new Entity("<Marketplace id for the item>", EntityType.PRODUCT)


    Analytics
            .INSTANCE
            .reportImpressionOrganic(
                entity,
                placement
            );
}


private void reportImpressionPromoted() {
    String resolvedBidId = "<The bid id from the auction winner>";
    Placement placement = Placement.Companion.build(
            "search_results"
    );
    Analytics
            .INSTANCE
            .reportImpressionPromoted(
                resolvedBidId,
                placement
            );
}

Auction Requests for Banners

You should first add the BannerView into your activity xml. You can do so with Android Studio’s visual editor, but the end file should like like the following

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <com.topsort.analytics.banners.BannerView
        android:id="@+id/bannerView"
        android:layout_width="353dp"
        android:layout_height="103dp"
        android:layout_marginTop="40dp"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/textView"
        tools:srcCompat="@tools:sample/backgrounds/scenic" />
</androidx.constraintlayout.widget.ConstraintLayout>

Then, you have to call the BannerView.setup() function with your auction parameters. Notice that since this makes network calls, we need to launch it in a co-routine.

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(
                bannerConfig = bannerConfig,
                screenName = "sample_activity",
                opaqueUserId = null,
                onClick = { id, entityType -> onBannerClick(id, entityType) },
                callbacks = BannerCallbacks(
                    onError = { error -> /* Handle general error */ },
                    onAuctionError = { auctionError -> /* Handle auction-specific error */ },
                    onNoWinners = { /* Handle no winners returned */ },
                    onImageLoad = { /* Handle successful banner image load */ }
                )
            )
        }
    }
}

Testing Utilities

You can now mock AuctionsHttpService in your tests using:

setMockService(...)
resetToDefaultService()

The service is also now accessible with the @VisibleForTesting annotation.