Android SDK
With the Kameleoon Android SDK, you can run activate feature flags on native mobile Android applications. The Android SDK is compatible with both Kotlin and Java. The SDK is easy to integrate into your applications, and its memory and network usage are low.
Getting started: For help getting started, see the developer guide.
Changelog: Latest version of the Android SDK: 4.2.1 Changelog
Reference
This is the full reference documentation for the Kameleoon Android SDK.
Initialization
Once you have installed the SDK in your application, the first step is to initialize Kameleoon. All of your application's interactions with the SDK, such as triggering an experiment, are accomplished using this Kameleoon client object.
create()
Call this method before any others to initialize the SDK. This method is in com.kameleoon.KameleoonClientFactory
. Your app conducts all interactions with the SDK using the resulting KameleoonClient
object that this method creates.
You can customize the behavior of the SDK (for example, the environment, the credentials, and so on) by providing a configuration object. Otherwise, the SDK tries to find your configuration file and uses it instead.
- Java
- Kotlin
String siteCode = "a8st4f59bj";
try {
// pass client configuration and visitorCode as arguments
KameleoonClientConfig config = new KameleoonClientConfig.Builder()
.refreshIntervalMinute(15) // in minutes, 1 hour by default, optional
.defaultTimeoutMillisecond(10_000) // in milliseconds, 10 seconds by default, optional
.dataExpirationIntervalMinute(1440 * 365) // in minutes, infinity by default, optional
.environment("staging") // optional
.build();
String visitorCode = "yourVisitorCode";
KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, getApplicationContext());
} catch (SiteCodeIsEmpty | VisitorCodeInvalid exception) {
// Exception indicates that the provided siteCode is empty or the visitorCode is invalid
} catch (Throwable exception) {
// Any other error
}
try {
// generate visitorCode automatically and read client configuration from a file 'kameleoon-client.properties'
KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, getApplicationContext());
} catch (SiteCodeIsEmpty exception) {
// Exception indicates that the provided siteCode is empty or the visitorCode is invalid
} catch (Throwable exception) {
// Any other error
}
val siteCode = "a8st4f59bj"
try {
// pass client configuration and visitor code as arguments
val config = new KameleoonClientConfig.Builder()
.refreshIntervalMinute(15) // in minutes, 1 hour by default, optional
.defaultTimeoutMillisecond(10_000) // in milliseconds, 10 seconds by default, optional
.dataExpirationIntervalMinute(1440 * 365) // in minutes, infinity by default, optional
.environment("staging") // optional
.build();
val visitorCode = "yourVisitorCode"
val kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, applicationContext);
} catch (e: SiteCodeIsEmpty) {
// Exception indicates that the provided siteCode is empty
} catch (e: VisitorCodeInvalid) {
// Exception indicate that the provided visitorCode is invalid
} catch (e: Throwable) {
// Any other error
}
try {
// generate visitorCode automatically and read client configuration from the 'kameleoon-client.properties' file
val kameleoonClient = KameleoonClientFactory.create(siteCode, applicationContext);
} catch (e: SiteCodeIsEmpty) {
// Exception indicates that the provided siteCode is empty
} catch (e: VisitorCodeInvalid) {
// Exception indicates that the provided visitorCode is invalid
} catch (e: Throwable) {
// Any other error
}
isReady()
For mobile SDKs, the Kameleoon Client can't initialize immediately as it needs to perform a server call to retrieve the current configuration for the active feature flags. Use this method to check if the SDK is ready by calling this method before triggering any feature flags.
Alternatively, you can use a callback (see the runWhenReady()
method for details).
- Java
- Kotlin
Boolean ready = kameleoonClient.isReady();
val ready = kameleoonClient.isReady
Return value
Type | Description |
---|---|
boolean | Boolean representing the status of the SDK. true if client is fully initialized and false if it is not yet ready to be used. |
runWhenReady()
For mobile SDKs, the Kameleoon Client can't initialize immediately as it needs to perform a server call to retrieve the current configuration for all active feature flags. Use the runWhenReady()
method of the KameleoonClient
class to pass a callback that will be executed as soon as the SDK is ready for use. It also allows you to set a timeout.
The callback given as the first argument to this method must be an instance of a class that implements the ResultCompletion<Boolean, TimeoutException>
interface. If the result.get()
equals true
, the Kameleoon client is ready and should contain code that triggers a feature flags and implements variations. Otherwise, the specified timeout will occur before the client is initialized. The callback should contain code that implements the reference variation, as the user will be excluded from the feature flag if a timeout occurs.
- Java
- Kotlin
kameleoonClient.runWhenReady(1000, result -> {
int variationID;
int recommendedProductsNumber;
try {
if (result.get().equals(true)) {
variationID = kameleoonClient.getFeatureVariationKey("featureKey");
} else {
variationID = 0;
}
} catch (Throwable exception) {
// The user will not be included in the experiment results and should see the reference variation
variationID = 0;
}
if (variationID == 0) {
// This is the default / reference number of products to display
recommendedProductsNumber = 5;
}
else if (variationID == 148382) {
// We are changing number of recommended products for this variation to 10
recommendedProductsNumber = 10;
}
else if (variationID == 187791) {
// We are changing number of recommended products for this variation to 8
recommendedProductsNumber = 8;
}
applyVariation();
});
private void applyVariation()
{
mTextMessage.setText("Number of recommended products displayed: " + recommendedProductsNumber + " product");
}
client.runWhenReady(1000) { result ->
var variationID = 0
var recommendedProductsNumber = 0
variationID = try {
if (result.get().equals(true)) {
variationID = kameleoonClient.getFeatureVariationKey("featureKey");
} else {
variationID = 0;
}
} catch (exception: Exception) {
// The user will not be included in the experiment results and should see the reference variation
variationID = 0;
}
when (variationID) {
0 -> {
// This is the default / reference number of products to display
recommendedProductsNumber = 5
}
148382 -> {
// We are changing number of recommended products for this variation to 10
recommendedProductsNumber = 10
}
187791 -> {
// We are changing number of recommended products for this variation to 8
recommendedProductsNumber = 8
}
}
applyVariation()
}
private fun applyVariation() {
mTextMessage!!.text = "Number of recommended products displayed: $recommendedProductsNumber products."
}
Feature flags and variations
isFeatureActive()
- 📨 Sends Tracking Data to Kameleoon
This method was previously named activateFeature
, which was removed in SDK version 4.0.0
release.
To activate a feature toggle, call this method. This method accepts a featureKey
as required argument to check if the specified feature will be active for a visitor.
If the visitor has never been associated with this feature flag, this method returns a random boolean value (true
if the visitor should be shown this feature, otherwise false
). If the visitor is already registered with this feature flag, this method returns the previous featureFlag
value.
Make sure to set up proper error handling as shown in the example code to catch potential exceptions.
- Java
- Kotlin
String featureKey = "new_checkout";
try {
hasNewCheckout = kameleoonClient.isFeatureActive(featureKey);
} catch (SDKNotReady e) {
// Exception indicating that the SDK has not completed its initialization yet.
} catch (FeatureNotFound e) {
// SDK not initialized or feature toggle not yet activated on Kameleoon's side - we consider the feature inactive
} catch (Throwable exception) {
// Any other error
}
if (hasNewCheckout)
{
// Implement new checkout code here
}
val featureKey = "new_checkout"
var hasNewCheckout = false
try {
hasNewCheckout = kameleoonClient.isFeatureActive(featureKey)
} catch (e: SDKNotReady) {
// Exception indicating that the SDK has not completed its initialization yet.
hasNewCheckout = false
} catch (e: FeatureNotFound) {
// SDK not initialized or feature toggle not yet activated on Kameleoon's side - we consider the feature inactive
hasNewCheckout = false
} catch (e: Throwable) {
// Any other error
hasNewCheckout = false
}
if (hasNewCheckout) {
// Implement new checkout code here
}
Arguments
Name | Type | Description |
---|---|---|
featureKey | String | Unique key of the feature you want to expose to a user. This field is required. |
Return value
Type | Description |
---|---|
Boolean | Value of the feature that is registered for a visitor. |
Exceptions thrown
Type | Description |
---|---|
SDKNotReady | Exception indicating that the SDK has not completed its initialization yet. |
FeatureNotFound | Exception indicating that the requested feature ID was not found in the internal configuration of the SDK. This usually means the feature flag has not been activated on the Kameleoon side (but code implementing the feature is already deployed in the application). |
getFeatureVariationKey()
- 📨 Sends Tracking Data to Kameleoon
Use this method to get the feature variation key for a visitor. This method takes a featureKey
as required argument to retrieve the variation key for the specified user.
If the visitor has never been associated with this feature flag, the SDK returns a randomly assigned variation key (according to the feature flag rules). If the visitor is already registered with this feature flag, this method returns the previous variation key. If the user does not match any of the rules, the default value will be returned, which is defined in your customer's account.
Make sure you set up proper error handling as shown in the example code to catch potential exceptions.
- Java
- Kotlin
String featureKey = "new_checkout";
String variationKey = "";
try {
variationKey = kameleoonClient.getFeatureVariationKey(featureKey);
} catch (SDKNotReady e) {
// Exception indicates that the SDK has not completed its initialization yet.
} catch (FeatureNotFound e) {
// The error is happened, feature flag isn't found in current configuration
} catch (FeatureEnvironmentDisabled e) {
// The feature flag is disabled for the environment
} catch (Throwable e) {
// Any other error
}
switch (variationKey) {
case "on":
//main variation key is selected for visitorCode
break;
case "alternative_variation":
//alternative variation key
break;
default:
//default variation key
break;
}
val featureKey = "new_checkout"
var variationKey = ""
try {
variationKey = kameleoonClient.getFeatureVariationKey(featureKey)
} catch (e: SDKNotReady) {
// Exception indicates that the SDK has not completed its initialization yet.
} catch (e: FeatureNotFound) {
// Exception indicates that the SDK not initialized or the feature toggle is not yet activated on Kameleoon's side. We consider the feature inactive.
} catch (e: FeatureEnvironmentDisabled) {
// The feature flag is disabled for the environment
} catch (e: Throwable) {
// Any other error
}
when (variationKey) {
"on" -> {}
"alternative_variation" -> {}
else -> {}
}
getFeatureList()
This method was previously named obtainFeatureList
, which was removed in SDK version 4.0.0
release.
Returns a list of the feature flag keys that are currently available for the SDK.
Return value
Type | Description |
---|---|
List<String> | List of all available feature flag keys. |
Example code
- Java
- Kotlin
List<String> allFeatureFlagListId = kameleoonClient.getFeatureList();
val allFeatureFlagListId = kameleoonClient.getFeatureList();
getActiveFeatures()
Previously named: getFeatureListForVisitorCode
which was removed in SDK version 4.0.0
release.
getActiveFeatures
method retrieves information about the active feature flags that are available for the visitor.
Return value
Type | Description |
---|---|
Map<String, Variation> | A dictionary that contains the assigned variations of the active features using the keys of the corresponding active features. |
Example code
- Java
- Kotlin
Map<String, Variation> listActiveFeatureFlags = kameleoonClient.getActiveFeatures();
val listActiveFeatureFlags = kameleoonClient.getActiveFeatures();
Variables
getFeatureVariable()
- 📨 Sends Tracking Data to Kameleoon
This method gets a variable value of variation key for a specific user. It takes a featureKey
, and variableKey
as required arguments.
If the visitor has never been associated with the featureKey
, the SDK returns a randomly assigned variable value for the specified variation key (according to the feature flag rules). If the visitor is already registered with this feature flag, this method returns the variable value for previously registered variation. If the user does not match any of the rules, the default variable value is returned.
Make sure you set up proper error handling as shown in the example code to catch potential exceptions.
- Java
- Kotlin
String featureKey = "feature_key";
String variableKey = "variableKey";
try {
var variableValue = kameleoonClient.getFeatureVariable(featureKey, variableKey);
// your custom code depending of variableValue
} catch (SDKNotReady e) {
// Exception indicates that the SDK has not completed its initialization yet.
} catch (FeatureNotFound e) {
// The error is happened, feature flag isn't found in current configuration
} catch (FeatureVariableNotFound e) {
// Requested variable not defined on Kameleoon's side
} catch (FeatureEnvironmentDisabled e) {
// The feature flag is disabled for the environment
} catch (Throwable e) {
// Any other error
}
val featureKey = "new_checkout"
val variableKey = "var"
try {
val variableValue = kameleoonClient.getFeatureVariable(featureKey, variableKey)
// your custom code depending of variableValue
} catch (e: SDKNotReady) {
// Exception indicating that the SDK has not completed its initialization yet.
} catch (e: FeatureNotFound) {
// The error is happened, feature flag isn't found in current configuraiton
} catch (e: FeatureVariableNotFound) {
// Requested variable not defined on Kameleoon's side
} catch (e: FeatureEnvironmentDisabled) {
// The feature flag is disabled for the environment
} catch (e: Throwable) {
// Any other error
}
Arguments
Name | Type | Description |
---|---|---|
featureKey | string | Key of the feature you want to display to a user. This field is required. |
variableName | string | Name of the variable you want to get a value for. This field is required. |
Return value
Type | Description |
---|---|
object | Value of variable of variation that is registered for the specified visitorCode for this feature flag. Valid types: bool , int , double , string , JObject , JArray |
Exceptions thrown
Type | Description |
---|---|
SDKNotReady | Exception indicating that the SDK has not completed its initialization yet. |
FeatureNotFound | Exception indicating that the requested feature key was found in the internal configuration of the SDK. This usually means that the feature flag has not been activated on Kameleoon's side (but code implementing the feature is already deployed in the application). |
FeatureVariableNotFound | Exception indicating that the specified variable was not found. Check that the variable key in the Kameleon app matches the one in your code. |
FeatureEnvironmentDisabled | Exception indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development). |
getFeatureVariationVariables()
This method was previously named: getFeatureAllVariables
, which was removed in SDK version 4.0.0
release.
To retrieve all of the variables for a feature, call this method. You can modify your feature variables in the Kameleoon app.
This method takes one input parameter: featureKey
. It returns the data as a Map<String, Object>
type, as defined in the Kameleoon app. It throws an exception (FeatureNotFound
) if the requested feature was not found in the internal configuration of the SDK.
- Java
- Kotlin
String featureKey = "myFeature";
try {
Map<String, Object> variables = kameleoonClient.getFeatureVariationVariables(featureKey);
} catch (SDKNotReady e) {
// Exception indicating that the SDK has not completed its initialization yet.
} catch (FeatureNotFound e) {
// The feature is not yet activated on Kameleoon's side
} catch (FeatureEnvironmentDisabled e) {
// The feature flag is disabled for the environment
} catch (Exception e) {
// This is a generic Exception handler which will handle all exceptions.
System.out.println("Exception occurred");
}
val featureKey = "myFeature"
try {
val variables = kameleoonClient.getFeatureVariationVariables(featureKey)
} catch (e: SDKNotReady) {
// Exception indicating that the SDK has not completed its initialization yet.
} catch (e: FeatureNotFound) {
// The feature is not yet activated on Kameleoon's side
} catch (e: FeatureEnvironmentDisabled) {
// The feature flag is disabled for the environment
} catch (e: Exception) {
// This is a generic Exception handler which will handle all exceptions.
println("Exception occurred")
}
Arguments
Name | Type | Description |
---|---|---|
featureKey | String | Unique identifier of the feature you need to obtain. This field is required. |
Return value
Type | Description |
---|---|
Map<String,Object> | Data representing the variables associated with this feature flag. The values can be int , string , boolean , JSONObject or JSONArray (depending on the types defined on the web interface). |
Exceptions thrown
Type | Description |
---|---|
SDKNotReady | Exception indicating that the SDK has not completed its initialization yet. |
FeatureNotFound | Exception indicating that the requested feature was not found in the internal configuration of the SDK. This usually means that the feature flag has not yet been activated on Kameleoon's side. |
FeatureVariableNotFound | Exception indicating that the specified variable was not found. Check that the variable key in the Kameleoon app matches the one in your code. |
FeatureEnvironmentDisabled | Exception indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development). |
Goals
trackConversion()
- 📨 Sends Tracking Data to Kameleoon
This asynchronous method tracks conversions in your application. This method requires goalID
to track conversion for a particular goal. In addition, this method also accepts revenue
as a second optional argument to track revenue.
This method doesn't return any values. This method is non-blocking as the server call is made asynchronously.
- Java
- Kotlin
int goalID = 83023;
kameleoonClient.trackConversion(goalID); // default revenue
kameleoonClient.trackConversion(goalID, 10); // provided revenue == 10
val goalID = 83023
kameleoonClient.trackConversion(goalID) // default revenue
kameleoonClient.trackConversion(goalID, 10); // provided revenue == 10
Arguments
Name | Type | Description |
---|---|---|
goalId | int | ID of the goal. This field is mandatory. |
revenue | double | Revenue of the conversion. This field is optional. |
Events
onUpdateConfiguration()
This method was previously named updateConfigurationHandler
, which was removed in SDK version 4.0.0
release.
This method allows you to handle the event when the configuration has updated data. It takes one input parameter completion
, which is the handler that will be called when the configuration is updated using a real-time configuration event.
Arguments
Name | Type | Description |
---|---|---|
completion | Result<Long, Exception> | The completion that the SDK should call when the configuration is updated using a real-time configuration event. The value of result is a Unix time (number of seconds that have elapsed since January 1, 1970) when configuration was updated. |
Example code
- Java
- Kotlin
kameleoonClient.onUpdateConfiguration(result -> {
if (result.isSuccess()) {
// result value contains the value of Unix time (number of seconds that have elapsed since January 1, 1970) when configuration was updated
}
});
kameleoonClient.onUpdateConfiguration { result ->
if (result.isSuccess) {
// result value contains the value of Unix time (number of seconds that have elapsed since January 1, 1970) when configuration was updated
}
};
Visitor data
addData()
The addData()
method adds targeting data to storage so other methods can use the data to decide whether or not to target the current visitor.
The addData()
method does not return any value and does not interact with Kameleoon back-end servers on its own. Instead, all the declared data is saved for future transmission using the flush method. This approach reduces the number of server calls made, as the data is typically grouped into a single server call that is triggered the flush. Note that the trackConversion method also sends out any previously associated data, just like the flush method. The same is true for getFeatureVariationKey and getFeatureVariable methods.
Each visitor can only have one instance of associated data for most data types. However, CustomData
is an exception. Visitors can have one instance of associated CustomData
per customDataIndex
.
- Java
- Kotlin
kameleoonClient.addData(new Data.Custom(1, "some custom value"), Data.Device.TABLET);
kameleoonClient.addData(new Data.Conversion(32, 10f, false));
kameleoonClient.addData(Data.CustomData(1, "some custom value"), Data.Device.TABLET);
kameleoonClient.addData(Data.Conversion(32, 10f, false))
Arguments
Name | Type | Description |
---|---|---|
dataTypes | Data | Custom data types. Pass them separated by a comma. |
flush()
- 📨 Sends Tracking Data to Kameleoon
Data associated with the current user via the addData()
method is not sent immediately to the server. It is stored and accumulated until it is sent automatically by the trackConversion()
method, or manually sent by calling the flush()
method. This allows you to control exactly when the data is flushed to our servers. For example, if you call the addData()
method a dozen times, it would waste resources to send data to the server after each addData()
invocation. Just call flush()
once at the end.
The flush()
method doesn't return any value. This method is non-blocking as the server call is made asynchronously.
- Java
- Kotlin
kameleoonClient.addData(Data.Device.PHONE);
kameleoonClient.addData(new Data.Conversion(32, 10f, false));
kameleoonClient.flush();
kameleoonClient.addData(Data.Device.PHONE)
kameleoonClient.addData(Data.Conversion(32, 10f, false))
kameleoonClient.flush()
getRemoteData()
This method was previously named retrieveDataFromRemoteSource
, which was removed in SDK version 4.0.0
release.
Use this method to retrieve data from a remote Kameleoon server based on your active siteCode
and the key
argument (or the active visitorCode
if you omit the key
). The visitorCode
and siteCode
are specified in KameleoonClientFactory.create()
. You can quickly and conveniently store data on our highly scalable remote servers using the Kameleoon Data API. Your application can then retrieve the data using this method.
Note that since a server call is required, this mechanism is asynchronous, and you must pass a Result<JSONObject, Exception>
object as an argument to the method.
- Java
- Kotlin
kameleoonClient.getRemoteData("test", result -> {
try {
JSONObject jsonObject = result.get();
// jsonObject contains result of request
} catch (Exception ex) {
// request failed with an exception
}
});
kameleoonClient.getRemoteData("test") { result ->
try {
val jsonObject = result.get()
// jsonObject contains result of request
} catch (e: Exception) {
// request failed with exception
}
}
Arguments
Name | Type | Description |
---|---|---|
key | String | The key that the data you try to get is associated with. This field is optional. |
completion | ResultCompletion<JSONObject, Exception> | The callback that processes the received data. This field is required. |
getRemoteVisitorData()
The getRemoteVisitorData
method allows you to retrieve custom data stored on remote Kameleoon servers for a visitor. If shouldAddData is true, this method automatically adds the retrieved data to a visitor without requiring you to make a separate addData
call. You must call KameleoonClientFactory.create
to provide your siteCode before calling this method.
You also must have previously stored data on our remote servers, which you can add with any of the following tracking calls in the SDK:
flush
getFeatureVariationKey
getFeatureVariable
isFeatureActive
Using the getRemoteVisitorData
method along with the availability of our highly scalable servers provides a convenient way to quickly access and synchronize large amounts of data across all of the visitor's devices.
- Java
- Kotlin
// Visitor data will be fetched and automatically added for `visitorCode`
kameleoonClient.getRemoteVisitorData(result -> {
try {
List<Data> visitorData = result.get();
// visitorData contains fetched visitor data from the Kameleoon servers
} catch (Exception ex) {
// request failed with exception
}
});
// If you only want to fetch data and add it yourself manually, set shouldAddData == `false`
kameleoonClient.getRemoteVisitorData(false, result -> {
try {
List<Data> visitorData = result.get();
// visitorData contains fetched visitor data from the Kameleoon servers
} catch (Exception ex) {
// request failed with exception
}
});
// If you want to fetch custom list of data types
RemoteVisitorDataFilter filter = RemoteVisitorDataFilter.builder()
.previousVisitAmount(25)
.experiments(true)
.conversion(true)
.build();
kameleoonClient.getRemoteVisitorData(filter, true, result -> {
try {
List<Data> visitorData = result.get();
// visitorData contains fetched visitor data from the Kameleoon servers
} catch (Exception ex) {
// request failed with exception
}
});
// Visitor data will be fetched and automatically added for `visitorCode`
kameleoonClient.getRemoteVisitorData { result ->
try {
val visitorData = result.get()
// visitorData contains fetched visitor data from our servers
} catch (e: Exception) {
// request failed with exception
}
}
// If you only want to fetch data and add it yourself manually, set shouldAddData == `false`
kameleoonClient.getRemoteVisitorData(false) { result ->
try {
val visitorData = result.get()
// visitorData contains fetched visitor data from the Kameleoon servers
} catch (e: Exception) {
// request failed with exception
}
}
val filter = RemoteVisitorDataFilter.builder()
.previousVisitAmount(25)
.experiments(true)
.conversion(true)
.build()
kameleoonClient.getRemoteVisitorData(false) { result ->
try {
val visitorData = result.get()
// visitorData contains fetched visitor data from the Kameleoon servers
} catch (e: Exception) {
// request failed with exception
}
}
Arguments
Name | Type | Description |
---|---|---|
filter | RemoteVisitorDataFilter | Filter that selects which data should be retrieved from visit history. By default, getRemoteVisitorData retrieves CustomData from the current and latest previous visit (RemoteVisitorDataFilter.builder().build() or new RemoteVisitorDataFilter() ). All other filters parameters default to false . This field is optional. |
shouldAddData | boolean | A boolean indicating whether the method should automatically add retrieved data for a visitor. If not specified, the default value is true. This field is optional. |
completion | ResultCompletion<List<Data>, Exception> | The callback that processes the received visitor data.This field is required. |
Here is the list of available RemoteVisitorDataFilter
options:
Name | Type | Description | Default |
---|---|---|---|
previousVisitAmount (optional) | int | Number of previous visits to retrieve data from. Number between 1 and 25 | 1 |
currentVisit (optional) | boolean | If true, current visit data will be retrieved | true |
customData (optional) | boolean | If true, custom data will be retrieved. | true |
geolocation (optional) | boolean | If true, geolocation data will be retrieved. | false |
conversions (optional) | boolean | If true, conversion data will be retrieved. | false |
experiments (optional) | boolean | If true, experiment data will be retrieved. | false |
kcs (optional) | boolean | If true, KCS heat data will be retrieved. | false |
getVisitorWarehouseAudience()
Retrieves all audience data associated with the visitor in your data warehouse. The optional warehouseKey
parameter is typically your internal user ID. The customDataIndex
parameter corresponds to the Kameleoon custom data that Kameleoon uses to target your visitors. You can refer to the warehouse targeting documentation for additional details. The method passes the result to the completion
as a CustomData
object, confirming that the data has been added to the visitor and is available for targeting purposes.
Since a server call is required, this mechanism is asynchronous, and you must pass a completion
as an argument to the method.
- Java
- Kotlin
kameleoonClient.getVisitorWarehouseAudience(customDataIndex, result -> {
// As a result of the method before this callback is called, data was automatically added to the visitor.
// In general, we recommended that you check only when the request fails.
if (result.isFailure()) {
Exception exception = result.failure();
// Request failed with an exception.
}
});
// If you need to specify warehouse key
kameleoonClient.getVisitorWarehouseAudience("warehouseKey", customDataIndex, result -> {
// As a result of the method before this callback is called, data was automatically added to the visitor
// but you can evaluate the added data if you need to check it.
try {
CustomData data = result.get();
} catch (Exception exception) {
// request failed with exception
}
});
// Visitor data will be fetched and automatically added for `visitorCode`
kameleoonClient.getVisitorWarehouseAudience(customDataIndex) { result ->
// As a result of the method before this callback is called, data was automatically added to the visitor
// In general, we recommend you check only the request fails.
if (result.isFailure()) {
val exception = result.failure();
// Request failed with an exception
}
}
// If you need to specify warehouse key
kameleoonClient.getVisitorWarehouseAudience("warehouseKey", customDataIndex) { result ->
// As a result of the method before this callback is called, data was automatically added to the visitor
// but you can evaluate the added data if you need to check it.
try {
val data = result.get();
} catch (e: Exception) {
// Request failed with an exception
}
}
Arguments
Name | Type | Description |
---|---|---|
warehouseKey | String | A unique key to identify the warehouse data (usually, your internal user ID). This field is optional. |
customDataIndex | int | An integer representing the index of the custom data you want to use to target your BigQuery Audiences. |
completion | ResultCompletion<CustomData, Exception> | The callback that processes the received data. This field is required. |
Return value
Type | Description |
---|---|
Task<CustomData> | A CustomData instance confirming that the data has been added to the visitor. |
Exceptions thrown
Type | Description |
---|---|
HttpRequestException | Exception indicating that the request was failed for any reason. |
Exception | Exception indicating that the request timed out or any other reason of failure. |
setLegalConsent()
You must use this method to specify whether the visitor has given legal consent to use their personal data. Setting the legalConsent
parameter to false
limits the types of data that you can include in tracking requests. This helps you adhere to legal and regulatory requirements while responsibly managing visitor data. You can find more information on personal data in the consent management policy.
Arguments
Name | Type | Description |
---|---|---|
legalConsent | boolean | A boolean value representing the legal consent status. true indicates the visitor has given legal consent, false indicates the visitor has never provided, or has withdrawn, legal consent. This field is required. |
Example code
- Java
- Kotlin
kameleoonClient.setLegalConsent(true);
kameleoonClient.setLegalConsent(true)
Data types
This section lists the com.Kameleoon.Data
types supported by Kameleoon. We provide several standard data types as well as the CustomData
type that allows you to define custom data types.
Conversion
Store information about conversion events.
Field name | Type | Description |
---|---|---|
goalID | int | ID of the goal. This file is required. |
revenue | float | Conversion revenue. This field is optional. |
negative | boolean | Defines if the revenue is positive or negative. This field is optional. |
- Java
- Kotlin
kameleoonClient.addData(new Data.Conversion(32, 10f, false));
kameleoonClient.addData(Data.Conversion(32, 10f, false))
Device
Store information about the user's device.
Field name | Type | Description |
---|---|---|
device | Device | List of devices: PHONE, TABLET, DESKTOP. This field is required. |
- Java
kameleoonClient.addData(Data.Device.DESKTOP);
Geolocation
Geolocation
contains the visitor's geolocation details.
Each visitor can only have one Geolocation
. Adding a second Geolocation
overwrites the first one.
Name | Type | Description |
---|---|---|
country | string | The country of the visitor. This field is required. |
region | string | The region of the visitor. This field is optional. |
city | string | The city of the visitor. This field is optional. |
postalCode | string | The postal code of the visitor. This field is optional. |
latitude | float | The latitudinal coordinate for the position of the visitor. Coordinate number represents decimal degrees (a double that can be negative). This field is optional. |
longitude | float | The longitudinal coordinate for the position of the visitor. Provide the coordinate number in decimal degrees (a double that can be negative). This field is optional. |
- Java
- Kotlin
kameleoonClient.addData(new Geolocation("France", "Île-de-France", "Paris"));
kameleoonClient.addData(Geolocation("France", "Île-de-France", "Paris"))
CustomData
Define your own custom data types in the Kameleoon app or the Data API and use them from the SDK.
Name | Type | Description |
---|---|---|
index | int | An index or unique ID of the custom data to be stored. This field is required. |
values | String... or String[] or List<String> | Value(s) of the custom data to be stored. This field is optional. |
The index (ID) of the custom data is available in the Kameleoon app, in the Custom data configuration page. Be careful: this index starts at 0, so the first custom data you create for a given site would have the ID 0, not 1.
- Java
- Kotlin
kameleoonClient.addData(new CustomData(1, "some custom value"));
kameleoonClient.addData(new CustomData(1, "first value", "second value"));
kameleoonClient.addData(new CustomData(1, new String[]{ "first value", "second value" }));
kameleoonClient.addData(CustomData(1, "some custom value"))
kameleoonClient.addData(CustomData(1, "first value", "second value"))
kameleoonClient.addData(CustomData(1, arrayOf("first value", "second value")))
Developer guide
Follow this section to install and configure the Android SDK in your Android app as well as learn about advanced features.
Getting started
Follow these steps to install and configure the Kameleoon Android SDK in your application for the first time.
Installation
You can install the Android SDK by adding the following dependency to the build.gradle
file in your Android app:
dependencies {
implementation 'com.kameleoon:kameleoon-client-android:4.1.0'
}
Additional configuration
To customize the SDK behavior, create a .properties
configuration file. The name and location of the properties file are important:
- Create the file in the
assets/
directory of your app. - Name the file
kameleoon-client.properties
.
These are the available properties that you can set:
refresh_interval_minute
(optional): Specifies the frequency, in minutes, that active experiments and feature flags are fetched from the Kameleoon servers. The initial fetch is performed on the first application launch and subsequent fetches are processed at the defined refresh interval. Once you launch an experiment, pause the experiment, or stop the experiment, the change won't propagate to each of your visitors' iOS devices until their next refresh. This means if you set the refresh interval to 30 minutes, it may take up to 30 minutes before all devices receive the update. If not specified, the default interval is 60 minutes.data_expiration_interval_minute
(optional): Designates the predefined time period, in minutes, that the SDK stores the visitor and their associated data. Each data instance is evaluated individually. This allows you to set the amount of time the SDK saves the data before automatically deleting it. If no interval is specified, the SDK does not automatically delete data from the device. The default value isInteger.MAX_VALUE
.default_timeout_millisecond
(optional): Specifies the time interval, in milliseconds, that it takes for network requests from the SDK to time out. Set the value to 30000 milliseconds (30 seconds) or more if you do not have a stable connection. The default value is 10000 milliseconds. Some methods have additional parameters for method-specific timeouts, but if you do not specify them explicitly, the default value is used.environment
(optional): For customers using multi-environment feature flagging, this option specifies which feature flag configuration to use. By default, each feature flag has the optionsproduction
,staging
,development
. If not specified, the default value isproduction
. More informationis_unique_identifier
(optional): Indicates that the specifiedvisitorCode
is a unique identifier. If not provided, the default value is false.
If you specify a visitorCode
and set the isUniqueIdentifier
parameter to true
, the SDK methods use the visitorCode
value as the unique visitor identifier, which is useful for cross-device experimentation. The SDK links the flushed data with the visitor that is associated with the specified identifier.
The isUniqueIdentifier
can be useful in other edge-case scenarios, such as when you can't access the anonymous visitorCode
that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.
Example properties file:
refresh_interval_minute = 60
default_timeout_millisecond = 15000
environment = "staging"
While executing, the KameleoonClientFactory.create()
method initializes the client, but it is not immediately ready for use. This is because the Kameleoon Client must retrieve the current configuration of feature flags (along with their traffic repartition) from a Kameleoon remote server. This requires network access, which is not always available. Until the Kameleoon Client is fully ready, you should not attempt to run other methods in the Kameleoon Android SDK. Note that once the first configuration of feature flags is fetched, it is then periodically refreshed, but even if the refresh fails for any reason, the Kameleoon client will continue to function using the previous configuration.
You can use the isReady()
method to check if the Kameleoon client initialization is finished.
Alternatively, you can use a helper callback to encapsulate the logic of feature flag triggering and variation implementation. The best approach (isReady()
or callback) depends on your own preferences and on the exact use case. As a rule of thumb, we recommend using isReady()
when you expect that the SDK will be ready for use. For example, when you are running an feature flag on a dialog that users likely wouldn't access for the first few seconds or minutes of navigating within the app. We recommend using the callback when there is a high probability that the SDK is still in the process of initialization. For example, an feature flag that would appear on screen at the application launch would be better suited to a callback that makes the application wait until either the SDK is ready or a specified timeout has expired.
It's your responsibility as the app developer to ensure the logic of your application code is correct within the context of A/B testing using Kameleoon. A good practice is to always assume that the application user can be left out of the feature flag when the Kameleoon client is not yet ready. This is easy to implement, because this corresponds to the implementation of the default or reference variation logic. The code samples in the next paragraph show examples of this approach.
You're now ready to implement feature management and features flags. See the Reference section for details about additional methods.
Initialize the Kameleoon Client
After installing the SDK in your application and setting up the app properties, the next step is to create the Kameleoon Client. A Client is a singleton object that acts as a bridge between your application and the Kameleoon platform. It includes all the methods and properties you need to run an feature flag.
- Java
- Kotlin
import com.kameleoon.KameleoonClient;
import com.kameleoon.KameleoonClientFactory;
public class MyApplication extends Application
{
private KameleoonClient kameleoonClient;
@Override
public void onCreate() {
super.onCreate();
try {
KameleoonClientConfig config = new KameleoonClientConfig.Builder()
.refreshIntervalMinute(15) // in minutes, 1 hour by default, optional
.defaultTimeoutMillisecond(10_000) // in milliseconds, 10 seconds by default, optional
.dataExpirationIntervalMinute(1440 * 365) // in minutes, infinity by default, optional
.environment("staging") // optional
.isUniqueIdentifier(false) // false by default, optional
.build();
String siteCode = "a8st4f59bj";
String visitorCode = "yourVisitorCode";
kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, getApplicationContext());
// or if you want that visitor code will be generated automatically
kameleoonClient = KameleoonClientFactory.create(siteCode, config, getApplicationContext());
} catch (SiteCodeIsEmpty | VisitorCodeInvalid exception) {
// Exceptions indicate that provided siteCode is empty or visitorCode is invalid
} catch (Throwable exception) {
// Any other error
}
}
public KameleoonClient getKameleoonClient() {
return kameleoonClient;
}
}
import com.kameleoon.KameleoonClient
import com.kameleoon.KameleoonClientFactory
class MyApplication : Application() {
var kameleoonClient: KameleoonClient? = null
private set
override fun onCreate() {
super.onCreate()
try {
val config = new KameleoonClientConfig.Builder()
.refreshIntervalMinute(15) // in minutes, 1 hour by default, optional
.defaultTimeoutMillisecond(10_000) // in milliseconds, 10 seconds by default, optional
.dataExpirationIntervalMinute(1440 * 365) // in minutes, infinity by default, optional
.environment("staging") // optional
.build();
val siteCode = "a8st4f59bj"
val visitorCode = "yourVisitorCode"
kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, applicationContext)
// or if you want that visitor code will be generated automatically
kameleoonClient = KameleoonClientFactory.create(siteCode, config, applicationContext);
} catch (e: SiteCodeIsEmpty, VisitorCodeInvalid) {
// Exceptions indicate that provided siteCode is empty or visitor code is invalid
} catch (e: Throwable) {
// Any other error
}
}
}
Targeting conditions
The Kameleoon SDKs support a variety of predefined targeting conditions that you can use to target users in your campaigns. For the list of conditions supported by this SDK, see use visit history to target users.
You can also use your own external data to target users.
Error Handling
Handling errors is considered a good practice to make your application more stable and avoid technical issues. Most KameleoonClient
methods can throw a KameleoonException
error.
Since it can be difficult to patch the SDK version on the Android client side, we recommended that you enclose every SDK method in a try
clause that catches the KameleoonException
as well as the Throwable
error type to prevent other fatal errors.
For example:
- Java
- Kotlin
try {
// Calling a method of the SDK
} catch (KameleoonException e) {
// Handling expected exceptions
} catch (Throwable e) {
// Any other error
}
try {
// Calling a method of the SDK
} catch (e: KameleoonException) {
// Handling expected exceptions
} catch (e: Throwable) {
// Any other error
}