NAV
kotlin java

Android SDK Documentation

Welcome to the AB Tasty server side ABTasty SDK documentation!

The ABTasty SDK project is an Android library that helps you perform server side tests on your Android app.

You can use this library to access AB Tasty endpoints, which can generate a unique visitor ID, allocate a visitor to a test, and push visits and conversions events in order to help you analyze the outcomes of your campaigns.

Should you have any question about this documentation, feel free to reach out to us.

App prerequisites

Be sure that your app compile with at least the minSdkVersion 16 in the build.gradle file of your app module :

android {

    compileSdkVersion 28
    defaultConfig {

        minSdkVersion 16
        ...
    }

Be sure that your app has the permission to use internet in the <manifest> tag in your AndroidManifest.xml file of your app :

    <uses-permission android:name="android.permission.INTERNET" />

Getting started

Follow these steps in order to compile and start the AB Tasty libraybyapi

Add the repository

Add a repository in the main build.gradle file of your Android project:

allprojects {
    repositories {
        maven {
            url "https://sdk.abtasty.com/android/"
        }
    }
}

First add the following repository in the main build.gradle of your project in order for gradle to find the library to build with.

https://sdk.abtasty.com/android/


Add the dependency

Add the following library dependency in the build.gradle file of your app module:

dependencies {
	implementation 'com.abtasty:librarybyapi:1.1.0'
}

Then add the following library dependency in the build.gradle file of your app module

com.abtasty:librarybyapi:x.x.x

See all versions in the releases section



Initialize and start the library

Call the function ABInitializer builder function and its inner function start from the class ABTasty to init and start the library

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY).start()
    }
}
public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY).start();
    }
}

Finally, you just have to call the ABInitializer function and its inner start function located in the ABTasty class. Insert it at the most appropriate location for your application to init and start the library.

fun ABInitializer(context: Context, token: String) : ABInitializer

@See: Initalization section for more details



Emergency situations

If you are facing an emergency situation in your app, for example if you notice a crash, and you are suspecting the Abtasty SDK, you can disable it from the settings in the framework section of your account without republishing your app.

How does it works

The status is set in the response header of each request sent from the SDK. Then, if you decide to deactivate it from the settings of your account, the SDK will automatically switch off at run time by the next request. Please note that it may take several minutes to apply while our servers process the new status.

The SDK sends requests :

So the SDK will check at each initialization if its status has changed. When disabled, the initialization will stop and the SDK will be off until the next initialization.

Note that if the device is offline during the checking it’s going to keep its previous status.

Reactivation

As the communication is off when disabled, the reactivation will only be possible when you re-activate the option in the settings of your account and the SDK is initialized again. Please note that it may take several minutes to apply while our servers process the new status.

Starting campaigns

This section of the documentation aims at helping you starting a new campaign in your app with the ABTasty android SDK.

Library Initialization

The first thing to do is to initialize the library. To do so, you just call the ABInitializer function in the ABTasty class located in the com.abtasty.librarybyapi.main package. For each new user, at the very first initialization, the library requests for a new visitor id to our servers and save it in a database. It is also going to get all the variation allocations from our api at each initialization.


Initialize

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY).start();
    }
}

fun ABInitializer(context: Context, token: String) : ABInitializer

This function is the main library initializer.

Parameter Type Description
context Context Application context of your app.
token String Access key provided by AB Tasty




Initialize with tracking data

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
                .withTrackingData(ABTracker.Builder().setDeviceType(DeviceType.MOBILE_PHONE).build())
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY)
                .withTrackingData(new ABTracker.Builder().setDeviceType(DeviceType.MOBILE_PHONE).build())
                .start();

    }
}

fun withTrackingData(tracker : ABTracker) : ABInitializer

This method lets you set default common tracking data to be shared between all your events.

Parameter Type Description
tracker ABTracker Tracker with default common data


Initialize with ready

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
                .withWhenReady {
                    System.out.println("> READY")
                }
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY)
                .withWhenReady(new Function0<Unit>() {
                    @Override
                    public Unit invoke() {
                        System.out.println("> READY");
                        return null;
                    }
                })
                .start();
    }
}

withWhenReady(lambda: () -> Unit) : ABInitializer

As the sdk is asynchronous and run in parallel, this method lets you set a lambda which is going to be executed when the library is ready.

Parameter Type Description
lambda lambda Lambda that is going to be invoked when the library has finished initializing.


Initialize with logs

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
                .withLogMode(LogMode.ALL)
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY)
                .withLogMode(LogMode.ALL)
                .start();

    }
}

fun withLogMode(mode : LogMode) : ABInitializer

This method aims at enabling logs from the library.

It can be one of the following (NONE by default) :

Parameter Type Description
mode LogMode(Enum) The log mode enum to enable


Initialize with onError

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
                .withOnError { tag: String, message: String ->
                    System.out.println("> ERROR : $tag - $message")
                }
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY)
                .withOnError(new Function2<String, String, Unit>() {
                    @Override
                    public Unit invoke(String tag, String message) {
                        System.out.println("> ERROR : " + tag + " - " + message);
                        return null;
                    }
                })
                .start();

    }
}

fun withOnError(lambda: (tag:String, message:String) -> Unit) : ABInitializer

This method lets you set a lambda which is going to be executed if an error occurs with the tag and the message as a parameters.

Parameter Type Description
lambda lambda Lambda that is going to be invoked if an error occurs associated with a tag and an error message.


Start

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ABTasty.ABInitializer(applicationContext, AB_TASTY_KEY)
                .withWhenReady {
                    System.out.println("> READY")
                }
                .withTrackingData(ABTracker.Builder().setDeviceType(DeviceType.MOBILE_PHONE).build())
                .withLogMode(LogMode.ALL)
                .withOnError { tag: String, message: String ->
                    System.out.println("> ERROR : $tag - $message")
                }
                .start()
    }
}
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ABTasty.Companion.ABInitializer(getApplicationContext(), AB_TASTY_KEY)
                .withWhenReady(new Function0<Unit>() {
                    @Override
                    public Unit invoke() {
                        System.out.println("> READY");
                        return null;
                    }
                })
                .withTrackingData(new ABTracker.Builder().setDeviceType(DeviceType.MOBILE_PHONE).build())
                .withLogMode(LogMode.ALL)
                .withOnError(new Function2<String, String, Unit>() {
                    @Override
                    public Unit invoke(String tag, String message) {
                        System.out.println("> ERROR : " + tag + " - " + message);
                        return null;
                    }
                })
                .start();

    }
}

fun start()

The start method builds the ABInitializer config and starts the initialization of the library.

Getting variations

 ABTasty.getVariationIdForCampaign("xxxxxx")
                .takeUnless { it -> it.isEmpty() }
                ?.let { variation : String ->
                    when (variation) {
                        "aaaaaa" -> System.out.println("Variation A")
                        "bbbbbb" -> System.out.println("Variation B")
                        "cccccc" -> System.out.println("Variation C")
                    }
                }
	String variation = ABTasty.Companion.getVariationIdForCampaign("xxxxxx");
        if (!variation.isEmpty()) {
            switch (variation){
                case "aaaaaa" : {
                    System.out.println("Variation A");
                } break;
                case "bbbbbb" : {
                    System.out.println("Variation B");
                } break;
                case "cccccc" : {
                    System.out.println("Variation C");
                } break;
            }
        }

Once the library is initialized and ready, each campaign will have a variation allocated. To know which variation that has been allocated, use the getVariationIdForCampaign method in the ABTasty class located in the com.abtasty.librarybyapi.main package.

fun getVariationIdForCampaign(campaignId: String) : String

It returns a string corresponding to the selected variation, or an empty string if the campaign can’t be found or if the library is not yet ready.

When you apply some changes according to your variation, dont forget to activate the campaign and its variation so the user will always see the same.

Parameter Type Description
campaignId String id of the campaign

Activate Campaign

ABTasty.getVariationIdForCampaign("xxxxxx")
                .takeUnless { it.isEmpty() }
                ?.let { variation : String ->

                    when (variation) {
                        "aaaaaa" -> System.out.println("Variation A")
                        "bbbbbb" -> System.out.println("Variation B")
                    }

                    ABTasty.sendTrackingEvent(ABCampaignActivationTracker.Builder()
                            .setCampaignId("xxxxxx")
                            .setVariationId(variation)
                            .setOrigin("LoginActivity")
                            .setDeviceType(DeviceType.MOBILE_PHONE)
                            .setTimestamp(System.currentTimeMillis() / 1000)
                            .build())
                }
String variation = ABTasty.Companion.getVariationIdForCampaign("xxxxxx");
        if (!variation.isEmpty()) {
            switch (variation){
                case "aaaaaa" : {
                    System.out.println("Variation A");
                } break;
                case "bbbbbb" : {
                    System.out.println("Variation B");
                } break;
            }
            ABCampaignActivationTracker activation = new ABCampaignActivationTracker.Builder()
                    .setCampaignId("xxxxxx")
                    .setVariationId("bbbbbb")
                    .setOrigin("LoginActivity")
                    .setDeviceType(DeviceType.MOBILE_PHONE)
                    .setTimestamp(System.currentTimeMillis() / 1000)
                    .build();
            ABTasty.Companion.sendTrackingEvent(activation);
        }

When you apply some changes according to your variation, you need to activate it. This way it tells AB Tasty that the current user saw this specific variation of the campaign so that the user always sees the same variation.

The allocation can be changed if you call getVariationIdForCampaign several times until you use ABCampaignActivationTracker to activate the campaign and freeze the variation.

@See ABCampaignActivationTracker in the tracking section

Sending events

The library also provides some functions to send events to ABTasty, for example to send objectives configured for a campaign.

To do so, use the sendTrackingEvent method and specify the expected tracker as a parameter.

All existing trackers are listed below.

Each tracker contains a Builder class that facilitates its build.


ABTracker

ABTracker is the generic tracker that contains common data and from which all others trackers inherit.

Parameter Type Description
device_type com.abtasty.librarybyapi.tracking.DeviceType Device used by the visitor to view the test. The devices currently supported are: "DESKTOP", "MOBILE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER". required
timestamp Long Unix epoch time of the event in seconds since the 1st of January 1970 required
origin String interface or page from where the event has been created required
geoPoint DoubleArray  Current latitude / longitude of the device for geolocation [-90:90][-180:180] optional
ip String current ip of the device optional
deviceResolution IntArray current screen resolution of the device optional (required for ABActionTracking Touch)


Campaign Activation Tracking

val tracker = ABCampaignActivationTracker.Builder()
                .setCampaignId("xxxxxx")
                .setVariationId("bbbbbbb")
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .setTimestamp(System.currentTimeMillis() / 1000)
                .setOrigin("LoginActivity")
                .build()
        ABTasty.sendTrackingEvent(tracker)
	ABCampaignActivationTracker activation = new ABCampaignActivationTracker.Builder()
                        .setCampaignId("xxxxxx")
                        .setVariationId("bbbbbb")
                        .setDeviceType(DeviceType.MOBILE_PHONE)
                        .setTimestamp(System.currentTimeMillis() / 1000)
                        .setOrigin("LoginActivity")
                        .build();
                ABTasty.Companion.sendTrackingEvent(activation);

This tracker activates a campaign and its variation.

Parameter Type Description
campaign_id String campaign id to be activated required
variation_id String variation id of the campaign to be activated required


Action Tracking

val tracker = ABActionTracker.Builder()
                .setName("nb_fingers_touch")
                .setActionType(ABActionTracker.ActionType.TOUCH)
                .setValue(2)
                .setTouchPosition(intArrayOf(347, 887))
                .setDeviceResolution(intArrayOf(1080, 1920))
                .setOrigin("PictureActivity")
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .build()
        ABTasty.sendTrackingEvent(tracker)
ABActionTracker tracker = new ABActionTracker.Builder()
                .setName("nb_fingers_touch")
                .setActionType(ABActionTracker.ActionType.TOUCH)
                .setValue(2)
                .setTouchPosition(new int[] {347, 887})
                .setDeviceResolution(new int[] { 1080, 1920})
                .setOrigin("PictureActivity")
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .build();
        ABTasty.Companion.sendTrackingEvent(tracker);

This tracker sends a click or a touch event

Parameter Type Description
name String Label of the click tracking/touch as displayed in the reporting. required
type ActionType Type of event CLICK or TOUCH required
value_string String String value attached to the action tracking event. optional
value_interger Integer Integer value attached to the action tracking event.optional
position IntArray Object that contains the position x/y where the touch occurred in the mobile page. required for TOUCH
resolution IntArray Object that contains the resolution in w/h of the screen where the touch occurred. required for TOUCH


Custom Tracking

val tracker = ABCustomEventTracker.Builder()
                .setName("nb_connection")
                .setValue("3")
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .setOrigin("LoginActivity")
                .build()
        ABTasty.sendTrackingEvent(tracker)
ABCustomEventTracker tracker = new ABCustomEventTracker.Builder()
                .setName("nb_connection")
                .setValue("3")
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .setOrigin("LoginActivity")
                .build();
        ABTasty.Companion.sendTrackingEvent(tracker);

This tracker sends a custom event and lets you track events that are specific to your business.

Parameter Type Description
name string Label of the custom event tracked as displayed in the reporting. required
value_string string String value attached to the action tracking event. optional
value_integer int Integer value attached to the action tracking event. optional


Transaction tracking

val item = ABTransactionTracker.Item.Builder()
                .setName("Android home")
                .setPrice(100)
                .build()

val tracker = ABTransactionTracker.Builder()
                .setName("purchase")
                .setTransactionId("#587837983")
                .setRevenue(10000)
                .setShipping(1999)
                .setOrigin("Basketactivity")
                .addItem(item)
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .build()
        ABTasty.sendTrackingEvent(tracker)
Item item = new ABTransactionTracker.Item.Builder()
                .setName("Android home")
                .setPrice(100)
                .build();

        ABTransactionTracker tracker = new ABTransactionTracker.Builder()
                .setName("purchase")
                .setTransactionId("#587837983")
                .setRevenue(10000)
                .setShipping(1999)
                .setOrigin("Basketactivity")
                .addItem(item)
                .setDeviceType(DeviceType.MOBILE_PHONE)
                .build();
        ABTasty.Companion.sendTrackingEvent(tracker);

The ABTransactionTracker lets you track any purchase on your mobile app.

Parameter Type Description
name string Label of the Transaction as displayed in the reporting.required
id string Unique identifier of the transaction.required
revenue int Total amount of money spent by the visitor expressed in cents. required
shipping int Shipping cost - expressed in cents.required
tax_total int Total tax expressed in cents. optional
payment_method string  Means of payment. optional
items_count int Total number of products purchased on the mobile app. optional
discount int Total discount in cents optional
currency object Money used for the payment. optional
currency.name string Name of the money used for the payment. required
currency.rate float Change rate between USD in cents (used as a reference) and the money used for the payment. required
items object Products purchased on the web site/mobile app. optional


Item object

Parameter Type Description
items.name string Label of the product. required
items.price int Price of the item expressed in cents.required
items.sku string Identifier of the item. optional
items.category string Category of product the item belongs to.
items.quantity int Number of identical products purchased at the same time on the mobile app. optional
items.tax_amount int Tax amount applied to the item. optional
items.tax_rate float Percentage of tax applied to the item. optional


Visit tracking

val tracker = ABVisitTracker.Builder()
                .setOrigin("VisitActivity")
                .setDeviceType(DeviceType.TABLET)
                .setIp("192.168.0.1")
                .build()
        ABTasty.sendTrackingEvent(tracker)
ABVisitTracker tracker = new ABVisitTracker.Builder()
                .setOrigin("VisitActivity")
                .setDeviceType(DeviceType.TABLET)
                .setIp("192.168.0.1")
                .build();
        ABTasty.Companion.sendTrackingEvent(tracker);

The ABVisitTracker lets you track any visit occurring on a mobile app.

Parameter Type Description
Device_type string Device used by the visitor to view the test. The devices currently supported are: "DESKTOP", "MOBILE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER". required
origin string Original page where the event occurred (can be a URI or a screen name). required
timestamp Long Unix epoch time of the event in seconds since the 1st of January 1970 optional
ip string IP address of the visitor’s device to determine the geolocation.
geoPoint DoubleArray  Current latitude / longitude of the device for geolocation [-90:90][-180:180] optional


Reference

Reference

Releases

1.1.0