Android SDK

Supported Android SDK Versions

This library is compatible with Android SDK versions 15 and up (4.0 ICE_CREAM_SANDWICH)

This section explains in detail all the available methods in our Android SDK and how it works.

Integrating SDK in your Application

To integrate, declare a dependency in the build.gradle of the app module

dependencies {
implementation 'ai.customfit:customfit-android-client:1.0.0'

And also make the following entries in the build.gradle of the project

allprojects {
repositories {
maven {
url ""

Once the SDK has been integrated, your application needs to be authorized by the client key to connect to Click here to know how to get Client key.

The following example shows the simplest way to create a single shared instance for a client.

CFUser user = new CFUser.Builder("user_customer_id")
CustomFit.init(getApplication(), "CLIENT_KEY", user, WAIT_TIME);

If a "WAIT_TIME" is provided then it will block the app up to "WAIT_TIME" seconds until config values are retrieved from the server.

When the application is launched for the first time and the "WAIT_TIME" is not provided then the fallback values will be loaded in the app until the client connects to the server and gets the config values

The best practice is to not invoke blocking code from the main thread of the Android app. The best method is shown below:

CustomFit.init(getApplication(), "CLIENT_KEY", user);

When your application is about to terminate, invoke CustomFit.reset() method. This method will make sure that all the client resources are released, pending tracked events and configs are flushed to the server. If the application terminates without invoking this method then tracked events list will not be updated in the dashboard.

The best practice is to invoke the Reset method every time before the init() method is invoked.

Never use server key in your application. Be sure client key is used in your application, which you can find in the app settings page from the dashboard.


In our Android SDK, we use a builder to easily construct user objects. The config values are determined by the user object you pass. For example :

CFUser user = new CFUser.Builder("user_customer_id")

Let's go through the code snippet. The first argument to the builder is the user customer id. The user customer id is used to uniquely identify the user. If user customer id is not passed then a random UUID will be generated for the user and passed as a user customer id.

The properties you pass in the builder will automatically appear in the dashboard. Some of the pre-defined user properties are listed below:

User Property

Method in user builder




Email id of the user



First name of the user



Last name of the user



Phone number of the user



Country code of the user phone number



Country of the user



Gender of the user



Timezone of the user



Date of Birth of user



Default location of the user

Custom Properties

Other than predefined user properties you can also pass your own user custom properties, like the age in the above example. supports various types of custom properties and they are listed below.

Custom Property type

Method in user builder


.customProperty(String key, Boolean value)


.customProperty(String key, String value)


.customProperty(String key, Number value)


.customProperty(String key, Date value)

Geo point

.customProperty(String key, GeoType value)

List string

.customPropertyString(String key, List<String> values)

List number

.customPropertyNumber(String key, List<Number> values)

List date

.customPropertyDate(String key, List<Date> values)

The first argument in each of the custom property method in the builder is the property key and the second argument is the property values. Custom property of users is most powerful, which decides the config variation value to be returned based on the rules executed on the property values. Once the custom properties are passed to user builder then they are instantly available on the dashboard.

Private Properties

In the Android SDK, you can define the private pre-defined user properties as well as private custom properties. If a user builder has any predefined or custom properties as private then the property data will not be stored on the server. If the properties are set as private then you cannot find the data in the dashboard. For example :

CFUser user = new CFUser.Builder("user_customer_id")
.privateCustomProperty("premium_user", true)

Anonymous users

Anonymous users are similar to regular users, except that they won't get created and appear in the dashboard when you call user builder. In Android SDK the anonymous users are defined as below :

CFUser user = new CFUser.Builder("user_customer_id")

You can leave the user_customer_id empty in the user builder. android SDK will automatically set the user customer id as the randomly generated UUID which is constant between app restart and reboot.


In Android SDK there is a method for each config. For example :

configResult = CustomFit.getString("config_id", "fallback value" ));

In all the config methods the first argument is the config id and the second argument is the fallback value. The fallback value will be returned in case if the SDK is not able to fetch the config from

The fallback value will be served when your app is launched for the first time and the "WAIT_TIME" is not provided. Different types of config methods supported by are as follows:

Config type

Config Method


CustomFit.getBoolean("config_id", "fallback_value" ))


CustomFit.getString("config_id", "fallback_value" ))


CustomFit.getNumber("config_id", "fallback_value" ))


CustomFit.getJson("config_id", Json Object ))


CustomFit.getString("config_id", "fallback_value" ))

Rich Text

CustomFit.getRichtext("config_id", "fallback_value" ))


CustomFit.getList("config_id", "fallback_value" ))


CustomFit.getImage("config_id", "fallback_value" ))

For boolean config make sure that you use boolean method. If we use other methods then you get fallback_value

Track Event

The trackEvent method allows you to track events that occur on your app.

CFTracker.trackEvent(new CFEvent.Builder("event_id")

In the above code snippet, you can see that the first argument to the event builder is the "event_id" and it is the only mandatory argument. The event_id is used to uniquely identify the event. In addition to event id, you can attach the event properties to the event to provide detailed information of why, how and when the event was generated. From the above code snippet, we can say that the event with event_id was tracked when the user by name Jhon triggered it during sign up. SDK caches events and syncs them with servers in batches. To know more about cache and sync events click here.

The event properties can be of different types and the supported types are listed below :

Event property type

Method in event builder


.eventProperty(String key, Boolean value)


.eventProperty(String key, String value)


.eventProperty(String key, Number value)


.eventProperty(String key, Date value)

Geo point

.eventProperty(String key, GeoType value)

List string

.eventPropertyString(String key, List<String> values)

List number

.eventPropertyNumber(String key, List<Number> values)

List date

.eventPropertyDate(String key, List<Date> values)

List geopoint

.eventPropertyGeoPoint(String key, List<GeoType> values)

Near Real-Time Updates

The changes made to configs on dashboard may not be reflected immediately in production because of the cache and sync policy. push notification validates the SDK cache and ensures to provide the latest config values. To setup push notification click here.

To receive real-time updates the app needs to register listeners to each config for which we need to get notified about the change.

CustomFit.CFConfigChangeObserver observer = new CustomFit.CFConfigChangeObserver() {
public void onChanged(final String key) {
//This callback will be invoked from the backend thread.
//Switch to the UI thread if needed
Handler uiHandler = new Handler(Looper.getMainLooper()); Runnable(){
public void run() {
CustomFit.getString(key,"fallback value");

Similarly you can unregister the listener for each config.


Multiple user contexts

A single app can be used by multiple users on a single device. Android SDK has the capability of storing multiple user caches. Based on the user customer id passed in the init method the SDK switches to the required user context.