Java Version
Minimum Java version required: 17.
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.
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:
import android.app.Applicationimport 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>" ) }}
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>"); }}
The following samples show how to report different events after setting up:
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 )}
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 );}
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 */ } ) ) } }}
You can now mock AuctionsHttpService
in your tests using:
setMockService(...)resetToDefaultService()
The service is also now accessible with the @VisibleForTesting annotation.