NAV
Kotlin Java

Introduction to Android SDK

Welcome to the Flagship Android SDK documentation!

The following documentation helps you to run Flagship on your native Android app.

The sdk helps you :

Feel free to contact us if you have any questions regarding this documentation.

App prerequisites

Make sure your app compiles with at least the minSdkVersion 21 in the build.gradle file of your app module:

android {

    compileSdkVersion 28
    defaultConfig {

        minSdkVersion 21
        ...
    }

Make sure your app has permission to use the Internet in the <application> tag in the AndroidManifest.xml file of your app:

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

Getting started

Follow these steps to compile with the Flagship library.

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

allprojects {
    repositories {
        maven {
            url "https://dl.bintray.com/abtasty/flagship-android"
        }
    }
}

Adding the repository

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

https://dl.bintray.com/abtasty/flagship-android




Adding the dependency

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

dependencies {
	implementation 'com.abtasty:flagship-android:1.2.2'
}

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


com.abtasty:flagship-android:x.x.x





Initialize and start the library

Call the init function from the class Flagship to initialize and start the library.

class MyActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Flagship.builder(applicationContext, ENV_ID).start()
    }
}
public class MyActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        Flagship.Companion.builder(getApplicationContext(), ENV_ID).start();
    }
}

To initialize and start the library, just call the init function of the Flagship class, and call the start method from the returned Builder in the most appropriate location for your application.

fun builder(appContext: Context, envId: String) : Builder

This function return the main Builder which initialize the library.

Parameter Type Description
context Context Application context of your app.
envId String Environment id provided by Flagship.


Builder instance

Flagship.builder(applicationContext, "my_env_id")

            .withFlagshipMode(Flagship.Mode.BUCKETING)
            .withLogEnabled(Flagship.LogMode.ALL)
            .withVisitorId("my_visitor_id)
            .withReadyCallback {
                Hit.Event(Hit.EventCategory.ACTION_TRACKING, "sdk-android-ready").send()
                runOnUiThread { update() }
            }
            .withAPACRegion("my_api_key")
            .start()
Flagship.Companion.builder(this.getApplicationContext(), "my_env_id")

                .withFlagshipMode(Flagship.Mode.BUCKETING)
                .withLogEnabled(Flagship.LogMode.ALL)
                .withVisitorId("my_visitor_id")
                .withReadyCallback(() -> {
                    new Hit.Event(Hit.EventCategory.ACTION_TRACKING, "sdk-android-ready").send();
                    MainJava.this.runOnUiThread(new Runnable() {
                        @Override
                        public void run() {
                            updateView();
                        }
                    });
                    return null;
                })
                .withAPACRegion("my_api_key")
                .start();

The Builder instance helps you to configure and initialize the SDK via the following optional methods :

fun withFlagshipMode(mode: Mode) : Builder

Start Flagship SDK in BUCKETING mode (client-side) or in DECISION_API mode (server-side). Default is DECISION_API

Parameter Type Description
mode Mode DECISION_API(default) or BUCKETING.


fun withReadyCallback(lambda: (() -> Unit)): Builder

Set a code to apply when the SDK has finished to initialize.

Parameter Type Description
lambda (() -> Unit) lambda to call when the sdk has finished to initialize.


fun withVisitorId(visitorId: String = ""): Builder

Set an id for identifying the current visitor.

Parameter Type Description
visitorId String id which identify the current visitor. If no visitorId is passed as parameter, a unique id will be generated by the SDK).


fun withLogEnabled(mode: LogMode): Builder

Enable logs of the SDK

Parameter Type Description
mode LogMode type of log to display


fun withAPACRegion(apiKey : String): Builder

Use APAC region endpoints

Parameter Type Description
apiKey String Authentication api key


fun start()

Build and start the Flagship SDK.


Flagship Mode


DECISION API Mode

When the SDK is running in DECISION_API MODE, the allocation and its targeting validation will take place on server side. Therefore each call to the method synchronizeModifications to refresh the modifications will lead to an http request.

BUCKETING Mode

When the SDK is running in BUCKETING MODE, the SDK will download all the campaigns configurations at once in a single bucket file and will make the allocation and its targeting validation on client-side. This bucket file will be stored in cache and will only be downloaded again if there are some modifications made on the Flagship interface.

Campaign integration

Updating the visitor Context

The visitor context is a property dataset which defines the current user of your app. This dataset is sent and used by the Flagship decision API as targeting for campaign allocation. For example, you could pass a VIP status in the context and then the decision API would enable or disable a specific feature flag.



The SDK provides some methods to push new visitor context values:

These functions update the visitor context value matching the given key. A new context value associated with this key will be created if there is no previous matching value.

Flagship.updateContext("vipUser", vipUser)
Flagship.updateContext("age", age) {
  this@MainActivity.runOnUiThread { applyChanges() }
}
Flagship.Companion.updateContext("vipUser", currentVisitor.vip);
      Flagship.Companion.updateContext("age", currentVisitor.age, () -> {
      MainJava.this.runOnUiThread(this::applyChanges);
      return null;
      });
Parameter Type Description
key String key to associate with the following value
value String, Number, Boolean new context value
sync String (optional : null by default) If a lambda is passed as a parameter, it will automatically call synchronizeModifications() and then update the modifications from the server for all campaigns with the updated current context. The given lambda will be invoked when finished. You can also update it manually: synchronizeModifications()

Preset visitor context

The Flagship SDK contains predefined visitor context keys and for some of them the value will automatically be set. They are nevertheless overridable at anytime. Then these predefined context keys/values will be sent to the server and be editable in the “Persona” section of the Flagship platform. The list of the predefined keys is available in the appendices.

Synchronizing campaigns

Flagship.synchronizeModifications {
    this@MainActivity.runOnUiThread { applyChanges() }
}
Flagship.Companion.synchronizeModifications( () -> {
    MainJava.this.runOnUiThread(this::applyChanges);
    return null;
    });

Synchronizing campaign modifications allows you to automatically call the Flagship decision API (or bucketing file), which makes the allocation according to user context and gets all their modifications.

All the applicable modifications are stored in the SDK and are updated asynchronously when synchronizeModifications() is called.


fun synchronizeModifications(callback: () -> (Unit) = {}) : Deferred<Unit>

Parameter Type Required  Description
callback () -> (Unit) Yes Lambda to be invoked when the SDK has finished to update the modifications from the server.

Retrieving modifications

Once the campaign has been allocated and synchronized all the modifications are stored in the SDK. Then, you can retrieve them with the following functions:

val color = Flagship.getModification("btnColor", "#0e5fe3")
button.setBackgroundColor(Color.parseColor(color))
String color = Flagship.Companion.getModification("btnColor", "#FFFFFF");
button.setBackgroundColor(Color.parseColor(color));


Parameter Type Required Description
key String, Boolean, Int, Float, Double Yes key associated to the modification.
default String, Boolean, Int, Float, Double Yes default value returned when the key doesn’t match any modification value.
activate Boolean  No false by default Set this parameter to true to automatically report on our server that the current visitor has seen this modification. If false, call the activateModification() later.

Get campaign information

Flagship.getModificationInfo("modification_key")
Flagship.Companion.getModificationInfo("modification_key")

Sometimes you could need to send campaign ids to a third party provider. It is now possible to retrieve campaigns ids for a specific modification key.

fun getModificationInfo(key: String) : JSONObject?

Parameter Type Description
key String key which identifies the modification

Return JSONObject containing ‘campaignId’, ‘variationGroupId’, ‘variationId’ or null if the modification is not found (Not affected to the campaign)

Activating modifications

Once a modification has been printed on the screen for a user, you must send an activation event to tell Flagship that the user has seen this specific variation.

val color = Flagship.getModification("btnColor", "#0e5fe3", true)
button.setBackgroundColor(Color.parseColor(color))

---OR---

Flagship.activateModification("btnColor")
String color = Flagship.Companion.getModification("btnColor", "#FFFFFF", true);
button.setBackgroundColor(Color.parseColor(color));

Flagship.Companion.activateModification("btnColor");

fun activateModification(key: String)

Parameter Type Description
key String key which identifies the modification

Hit Tracking

This section helps send tracking and learn how to build hits in order to aprove campaign goals.

The different types of Hits are:

They must all be built and sent with the following function:

fun <T> sendHit(hit: HitBuilder<T>)

Page

Flagship.sendHit(Hit.Page("MainActivity"))
Flagship.Companion.sendHit(
  new Hit.Page("MainActivity")
);

This hit should be sent each time a visitor arrives on a new interface.


class Page(origin: String) : HitBuilder<Page>()

Builder Parameter Type Required Description
origin String Yes interface name

Transaction

This hit should be sent when a user complete a Transaction.

Flagship.sendHit(Hit.Transaction("#4802982", "mobile_purchases")
                .withCouponCode("#PROMO")
                .withCurrency("EUR")
                .withItemCount(1)
                .withPaymentMethod("credit_card")
                .withShippingCost(2.99f)
                .withShippingMethod("express")
                .withTaxes(15.47f)
                .withTotalRevenue(279f)
            )
Flagship.Companion.sendHit(new Hit.Transaction("#4802982", "mobile_purchases")
                .withCouponCode("#PROMO")
                .withCurrency("EUR")
                .withItemCount(1)
                .withPaymentMethod("credit_card")
                .withShippingCost(2.99f)
                .withShippingMethod("express")
                .withTaxes(15.47f)
                .withTotalRevenue(279f)
        );


class Transaction(transactionId: String, affiliation: String) : HitBuilder<Transaction>()

Builder Parameter Type Required Description
transactionId String Yes Transaction unique identifier.
affiliation String Yes Transaction name. Name of the goal in the reporting.
totalRevenue Float No Total revenue associated with the transaction. This value should include any shipping or tax costs.
shippingCost Float No Specifies the total shipping cost of the transaction.
withShippingMethod String No Specifies the shipping method of the transaction.
taxes Float No Specifies the total taxes of the transaction.
currency String No Specifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code.
paymentMethod String No Specifies the payment method for the transaction.
itemCount Int No Specifies the number of items for the transaction.
couponCode String No Specifies the coupon code used by the customer for the transaction.

Item

Flagship.sendHit(Hit.Item("#4802982", "N_SWITCH_19")
                .withItemCategory("video_games")
                .withItemCode("#NS19AHLD")
                .withItemQuantity(1)
                .withPrice(279f))
Flagship.Companion.sendHit(new Hit.Item("#4802982", "N_SWITCH_19", "#NS19AHLD")
               .withItemCategory("video_games")
               .withItemQuantity(1)
               .withPrice(279f));

This hit is linked to a transaction. It must be send after the corresponding transaction.


class Item(transactionId: String, productName: String) : HitBuilder<Item>()

Builder Parameter Type Required  Description
transactionId String Yes Transaction unique identifier.
product name String Yes Product name.
itemCode String Yes Specifies the item code or SKU.
price Float No Specifies the item price.
itemCategory String No Specifies the item category.
itemQuantity Int No Specifies the item quantity

Event

Flagship.sendHit(Hit.Event(Hit.EventCategory.ACTION_TRACKING, "click")
                .withEventLabel("button_click")
                .withEventValue(12))
Flagship.Companion.sendHit(new Hit.Event(Hit.EventCategory.ACTION_TRACKING, "click")
                .withEventLabel("button_click")
                .withEventValue(12));

This hit can be anything you want: for example a click or a newsletter subscription.


class Event(category: EventCategory, action: String) : HitBuilder<Event>()

Builder Parameter Type Required  Description
category EventCategory Yes category of the event (ACTION_TRACKING or USER_ENGAGEMENT).
action String Yes the event action.
label String No label of the event.
value Number No Specifies a value for this event. must be non-negative.

Common parameters for hits

These parameters can be sent with any type of hit.


Parameter Type Description
userIp String optional User IP
screenResolution String optional Screen Resolution.
userLanguage String optional User Language
currentSessionTimeStamp Int64 optional Current Session Timestamp
sessionNumber Int optional Session Number

Releases

1.2.3 (Latest version)

1.2.2

Fixed

1.2.1

Fixed

1.2.0

Added

Changed

Appendices

Preset visitor context

The Flagship SDK contains predefined visitor context keys. The keys marked as Yes in the Auto-set by SDK column, will automatically be set, and the ones marked as No have to be set by the client. They are nevertheless overridable at anytime.Then these predefined context keys/values will be sent to the server and be editable in the “Persona” section of the Flagship platform.

SDK Variable Name Description Context variable name Type Auto-set by SDK Example
FIRST_TIME_INIT First init of the app sdk_firstTimeInit Boolean Yes TRUE (FALSE if the init isn’t the first one)
LOCALE Language of the device sdk_deviceLanguage String Yes fr_FR
DEVICE_TYPE Tablette / Mobile sdk_deviceType String Yes mobile
DEVICE_MODEL Model of the device sdk_deviceModel String Yes samsung E1200
LOCATION_CITY City geolocation sdk_city String No toulouse
LOCATION_REGION Region geolocation sdk_region String No occitanie
LOCATION_COUNTRY Country geolocation sdk_country String No France
LOCATION_LAT Current Latitude sdk_lat Double No 43.623647
LOCATION_LONG Current Longitude sdk_long Double No 1.445397
IP IP of the device sdk_ip String No 127.0.0.1
OS_NAME Name of the OS sdk_osName String Yes android / iOS
OS_VERSION Version of the OS sdk_osVersion String Yes pie
API_LEVEL Version of the API sdk_apiLevel Number (int) Yes 24
ANDROID_VERSION / IOS VERSION Version of Android sdk_androidVersion / sdk_iOSVersion String Yes 9
MVNO / carrierName(Mobile virtual network operator) Name of the operator sdk_carrierName String Yes orange
DEV_MODE Is the app in debug mode? sdk_devMode Boolean Yes TRUE
VISITOR_ID Visitor_id of the user sdk_visitorId String Yes toto2000
INTERNET_CONNECTION What is the internet connection sdk_internetConnection String No 3g
APP_VERSION_NAME Version name of the app sdk_versionName String No 1.1.2-beta
APP_VERSION_CODE Version code of the app sdk_versionCode Number (int) No 40
FLAGSHIP_VERSION Version of the Flagship SDK sdk_fsVersion String Yes 1.1.2
INTERFACE_NAME Name of the interface sdk_interfaceName String No ProductPage


Reference

android reference

Sources

Sources of the library SDK are available at : https://github.com/abtasty/flagship-android

Sources of the sample app demo is available at : https://github.com/abtasty/flagship-demo-android