Topsort Kotlin library

topsort.kt is an Android library for interacting with the Topsort APIs. We currently support sending events and making auction calls but will add more features shortly.

Installation / Getting started

We recommend installing the library via Gradle. Simply add the dependency to your build.gradle file:

dependencies {
    ...

    implementation 'com.topsort:topsort-kt:1.1.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()
}

Usage/Examples

Setup

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 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() {
    Placement placement = Placement.Companion.build(
            "search_results"
    );

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

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