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 "https://maven.customfit.ai/artifactory/gradle-release-local"
}
}
}

Once the SDK has been integrated, your application needs to be authorized by the client key to connect to CustomFit.ai. 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")
.build();
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 CustomFit.ai 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 CustomFit.ai 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 CustomFit.ai server. If the application terminates without invoking this method then the tracked events list will not be updated in the CustomFit.ai 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 CustomFit.ai dashboard.

Users

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")
.email("jhon@customfit.ai")
.firstName("jhon")
.lastName("wright")
.customProperty("age",26)
.build();

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 CustomFit.ai dashboard. Some of the pre-defined user properties are listed below:

User Property

Method in user builder

Description

email

.email("string")

Email id of the user

firstName

.firstName("string")

First name of the user

lastName

.lastName("string")

Last name of the user

phoneNumber

.phoneNumber("string")

Phone number of the user

countryCode

.countryCode("string")

Country code of the user phone number

country

.country("string)

Country of the user

gender

.gender("string")

Gender of the user

timeZone

.timeZone("string")

Timezone of the user

dob

.dob("date")

Date of Birth of user

defaultLocation

.defaultLocation("geopoint")

Default location of the use

Custom Properties

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

Custom Property type

Method in user builder

Boolean

.customProperty(String key, Boolean value)

String

.customProperty(String key, String value)

Number

.customProperty(String key, Number value)

Date

.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 CustomFit.ai 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 pre-defined or custom properties as private then the property data will not be stored on the CustomFit.ai server. If the properties are set as private then you cannot find the data in the CustomFit.ai dashboard. For example :

CFUser user = new CFUser.Builder("user_customer_id")
.privateEmail("jhon@customfit.ai")
.privateFirstName("jhon")
.privateLastName("wright")
.privateCustomProperty("premium_user", true)
.build();

Anonymous users

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

CFUser user = new CFUser.Builder("user_customer_id")
.anonymous(true)
.build();

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

Configs

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 CustomFit.ai.

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

Config type

Config Method

Boolean

CustomFit.getBoolean("config_id", true ))

String

CustomFit.getString("config_id", "fallback value" ))

Number

CustomFit.getNumber("config_id", 100 ))

Json

CustomFit.getJson("config_id", "fallback value" ))

Color

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

Rich Text

CustomFit.getRichtext("config_id", "fallback value" ))

List

CustomFit.getList("config_id", "fallback value" ))

Image

CustomFit.getImage("config_id", "fallback value" ))

Track Event

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

CFTracker.trackEvent(new CFEvent.Builder("event_id")
.eventProperty("sign_up",true)
.eventProperty("name","jhon")
.build());

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 in detail 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.

CustomFit.ai SDK caches events and syncs them with CustomFit.ai 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

Boolean

.eventProperty(String key, Boolean value)

String

.eventProperty(String key, String value)

Number

.eventProperty(String key, Number value)

Date

.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 CustomFit.ai dashboard may not be reflected immediately in production because of the cache and sync policy. CustomFit.ai push notification validates the SDK cache and ensures to provide the latest config values. To setup CustomFit.ai 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() {
@Override
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());
uiHandler.post(new Runnable(){
@Override
public void run() {
CustomFit.getString(key,"fallback value");
}
}
});
}};
CustomFit.registerConfigChange("config_id",observer);

Similarly you can unregister the listener for each config.

CustomFit.unregisterConfigChange("config_id",observer);

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.