SDK Android

import com.kameleoon.KameleoonClient;
import com.kameleoon.KameleoonClientConfig;
import com.kameleoon.KameleoonClientFactory;
import com.kameleoon.KameleoonException;

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
                .trackingIntervalMillisecond(1000) // in milliseconds, 1000 ms by default, optional
                .dataExpirationIntervalMinute(1440 * 365) // in minutes, infinity by default, optional
                .environment("staging") // optional
                .isUniqueIdentifier(false) // optional, false by default. Set to true if the visitorCode corresponds to your customer's unique userId.
                .networkDomain("example.com") // optional
                .defaultDataFile("{...}") // optional
                .activityTrackingIntervalMillisecond(20_000) // optional, 15_000 milliseconds by default
                .build();
            String siteCode = "a8st4f59bj";
            String visitorCode = "yourVisitorCode";
            kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, getApplicationContext());
            // or, if you want, the visitor code will be generated automatically
            kameleoonClient = KameleoonClientFactory.create(siteCode, config, getApplicationContext());
        } catch (KameleoonException.SiteCodeIsEmpty | KameleoonException.VisitorCodeInvalid exception) {
            // Exceptions indicate that provided siteCode is empty or visitorCode is invalid
        } catch (Exception exception) {
            // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
        }
    }
    public KameleoonClient getKameleoonClient() {
        return kameleoonClient;
    }
}

// Initialize `KameleoonClient` on application startup and use it as a singleton later
try {
    KameleoonClient kameleoonClient = KameleoonClientFactory.create("<siteCode>", getApplicationContext());
} catch (KameleoonException ignored) {}

// Example: Apply a discount percentage based on an feature flag variable's value
void applyDiscountIfApplicable() {
    kameleoonClient.runWhenReady(1000, result -> {
        double discount = 0.0;
        try {
            if (result.getOrThrow()) {
                Variation variation = kameleoonClient.getVariation("discount");
                discount = (double) variation.getVariables().get("discount_value").getValue();
            }
        } catch (Exception ignored) { }

        if (discount > 0) {
            applyDiscount(discount);
        }
    });
}

// Initialize `KameleoonClient` on application startup and use it as a singleton later
try {
    val kameleoonClient = KameleoonClientFactory.create("<siteCode>", applicationContext)
} catch (ignored: KameleoonException) {}

// Example: Apply a discount percentage based on a feature flag variable's value
suspend fun applyDiscountIfApplicable() {
    kameleoonClient.runWhenReady(1000).getOrNull() ?: return // Exit if initialization fails

    val discount = runCatching {
        val variation = kameleoonClient.getVariation("discount")
        variation.variables["discount_value"]?.value as? Double
    }.getOrNull() ?: 0.0

    if (discount > 0) {
        applyDiscount(discount)
    }
}

// In this example, `91` represents the Custom Data's index,
// configured as a unique identifier in Kameleoon.
final int MAPPING_INDEX = 91;
final String FEATURE_KEY = "ff123";

// 0. Initializing anonymous KameleoonClient

// Assume `anonymousVisitorCode` is the randomly generated ID for that visitor.
KameleoonClient anonymousKameleoonClient = KameleoonClientFactory.create(siteCode, anonymousVisitorCode, getApplicationContext());
anonymousKameleoonClient.runWhenReady(result -> {
    // ...
});

// 1. Before the visitor is authenticated

// Retrieve the variation for an unauthenticated visitor.
Variation anonymousVariation = anonymousKameleoonClient.getVariation(FEATURE_KEY);

// 2. After the visitor is authenticated

// Assume `userId` is the authenticated visitor's visitor code.
anonymousKameleoonClient.addData(new CustomData(MAPPING_INDEX, userId));
anonymousKameleoonClient.flush(true);

KameleoonClient userKameleoonClient = KameleoonClientFactory.create(
    siteCode, userId,
    (new KameleoonClientConfig.Builder())
        .isUniqueIdentifier(true) // Indicate that `userId` is a unique identifier
        .build(),
    getApplicationContext()
);
userKameleoonClient.runWhenReady(result -> {
    // ...
});

// 3. After the visitor has been authenticated

// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
Variation userVariation = userKameleoonClient.getVariation(FEATURE_KEY);
boolean isSameVariation = userVariation.getKey().equals(anonymousVariation.getKey()); // true

// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
kameleoonClient.trackConversion(123, 10.0f);

// Additionally, the linked visitors will share all fetched remote visitor data.
kameleoonClient.getRemoteVisitorData(result -> {
    // ...
});

// In this example, `91` represents the Custom Data's index
// configured as a unique identifier in Kameleoon.
val MAPPING_INDEX = 91
val FEATURE_KEY = "ff123"

// 0. Initializing anonymous KameleoonClient

// Assume `anonymousVisitorCode` is the randomly generated ID for that visitor.
val anonymousKameleoonClient = KameleoonClientFactory.create(siteCode, anonymousVisitorCode, applicationContext)
anonymousKameleoonClient.runWhenReady()

// 1. Before the visitor is authenticated

// Retrieve the variation for an unauthenticated visitor.
val anonymousVariation = anonymousKameleoonClient.getVariation(FEATURE_KEY)

// 2. After the visitor is authenticated

// Assume `userId` is the authenticated visitor's visitor code.
anonymousKameleoonClient.addData(CustomData(MAPPING_INDEX, userId))
anonymousKameleoonClient.flush(true)

val userKameleoonClient = KameleoonClientFactory.create(
    siteCode, userId,
    KameleoonClientConfig.Builder()
        .isUniqueIdentifier(true) // Indicate that `userId` is a unique identifier
        .build(),
    applicationContext
)
userKameleoonClient.runWhenReady()

// 3. After the visitor has been authenticated

// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
val userVariation = userKameleoonClient.getVariation(FEATURE_KEY)
val isSameVariation = userVariation.getKey() == anonymousVariation.getKey() // true

// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
userKameleoonClient.trackConversion(123, 10.0f)

// Additionally, the linked visitors will share all fetched remote visitor data.
userKameleoonClient.getRemoteVisitorData()

kameleoonClient.addData(new CustomData(index, "newVisitorCode"));

try {
    // Calling a method of the SDK
} catch (KameleoonException e) {
    // Handling expected exceptions
} catch (Exception e) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}

// The `NONE` log level does not allow logging.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.NONE);

// The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.ERROR);

// The `WARNING` log level allows logging issues which may require additional attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.WARNING);

// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.INFO);

// The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
// with more granular. diagnostic output.
// This information is not intended for end-user interpretation but can be sent to our support team
// to assist with internal troubleshooting.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.DEBUG);

public class CustomLogger implements com.kameleoon.logging.Logger {
    // `log` method accepts logs from the SDK
    @Override
    public void log(com.kameleoon.logging.LogLevel level, String message) {
        // Custom log handling logic here. For example:
        switch (level) {
            case ERROR:
                android.util.Log.e("your-log-tag", message);
                break;
            case WARNING:
                android.util.Log.w("your-log-tag", message);
                break;
            case INFO:
                android.util.Log.i("your-log-tag", message);
                break;
            case DEBUG:
                android.util.Log.d("your-log-tag", message);
                break;
            default:
        }
    }
}


// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.DEBUG); // Optional, defaults to `LogLevel.WARNING`.
com.kameleoon.logging.KameleoonLogger.setLogger(new CustomLogger());

@Composable
fun KameleoonCookieWebView(url: String, kameleoonClient: KameleoonClient) {
    AndroidView(
        factory = { context ->
            WebView(context).apply {
                configureWebView(url, kameleoonClient)
                loadUrl(url)
            }
        },
    )
}

private fun WebView.configureWebView(url: String, kameleoonClient: KameleoonClient) {
    val COOKIE_NAME = "kameleoonVisitorCode"
    val COOKIE_DOMAIN = ".example.com"

    CookieManager.getInstance().apply {
        setCookie(
            url,
            "$COOKIE_NAME=${kameleoonClient.visitorCode}; Domain=$COOKIE_DOMAIN; Path=/; Secure"
        )
        flush()
    }
}

public class WebViewActivity extends AppCompatActivity {

    private WebView webView;

    private static final String DEFAULT_URL = "https://example.com";
    private static final String COOKIE_NAME = "kameleoonVisitorCode";
    private static final String COOKIE_DOMAIN = ".example.com";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        webView = new WebView(this);
        setContentView(webView);
        configureWebView(webView, DEFAULT_URL, kameleoonClient);
        webView.loadUrl(url);
    }

    private void configureWebView(WebView webView, String url, KameleoonClient kameleoonClient) {
        CookieManager cookieManager = CookieManager.getInstance();
        cookieManager.setCookie(
                url,
                COOKIE_NAME + "=" + kameleoonClient.getVisitorCode() + "; Domain=" + COOKIE_DOMAIN + "; Path=/; Secure"
        );
        cookieManager.flush();
    }
}

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
        .isUniqueIdentifier(false) // optional, false by default. Set to true if the visitorCode corresponds to your customer's unique userId.
        .environment("staging") // optional
        .build();
    String visitorCode = "yourVisitorCode";
    KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode, config, getApplicationContext());
} catch (KameleoonException.SiteCodeIsEmpty | KameleoonException.VisitorCodeInvalid exception) {
    // Exception indicates that the provided siteCode is empty or the visitorCode is invalid
} catch (Exception exception) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}

try {
    // generate visitorCode automatically and read client configuration from a file 'kameleoon-client.properties'
    KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, getApplicationContext());
} catch (KameleoonException.SiteCodeIsEmpty | KameleoonException.VisitorCodeInvalid exception) {
    // Exception indicates that the provided siteCode is empty or the visitorCode is invalid
} catch (Exception exception) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}

boolean ready = kameleoonClient.isReady();

kameleoonClient.runWhenReady(1000, result -> {
    int recommendedProductsNumber = 5; // Default control number for recommended products
    try {
        if (result.getOrThrow()) {
            Variation variation = kameleoonClient.getVariation("featureKey");
            recommendedProductsNumber = (int) variation.getVariables().get("recommendedProductsNumber").getValue();
        }
    } catch (Exception ignored) {
        // The user will not be included in the experiment results and should see the control variation
    }

    applyVariation(recommendedProductsNumber);
});

viewModelScope.launch {
    kameleoonClient.runWhenReady(1000).getOrNull() ?: return@launch
    val recommendedProductsNumber = runCatching {
        val variation = kameleoonClient.getVariation("featureKey")
        variation.variables["recommendedProductsNumber"]?.value as? Int
    }.getOrNull() ?: 5 // Default control number for recommended products

    applyVariation(recommendedProductsNumber)
}

String featureKey = "new_checkout";

boolean hasNewCheckout = false;
try {
    hasNewCheckout = kameleoonClient.isFeatureActive(featureKey);
    // disabling tracking
    hasNewCheckout = kameleoonClient.isFeatureActive(featureKey, false);
} catch (KameleoonException.SDKNotReady e) {
    // Exception indicating that the SDK has not completed its initialization yet.
} catch (KameleoonException.FeatureNotFound e) {
    // SDK not initialized, or feature toggle not yet activated in Kameleoon - we consider the feature inactive
} catch (Exception exception) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}
if (hasNewCheckout)
{
    // Implement new checkout code here
}

final String featureKey = "featureKey";
Variation variation = null;

try {
    variation = kameleoonClient.getVariation(featureKey);
    // disabling tracking
    variation = kameleoonClient.getVariation(featureKey, false);
} catch (KameleoonException.SDKNotReady ex) {
    // Exception indicating that the SDK has not completed its initialization yet.
} catch (KameleoonException.FeatureNotFound ex) {
    // The feature key is not in the configuration file that has been fetched by the SDK.
} catch (KameleoonException.FeatureEnvironmentDisabled ex) {
    // The feature flag is disabled for the environment.
}

if (variation != null) {
    String title = (String) variation.getVariables().get("title").getValue();

    switch (variation.getKey()) {
        case "on":
            // Main variation key is selected for visitorCode
            break;
        case "alternative_variation":
            // Alternative variation key
            break;
        default:
            // Default variation key
            break;
    }
}

try {
    Map<String, Variation> variations = kameleoonClient.getVariations();
    // only active variations
    Map<String, Variation> variations = kameleoonClient.getVariations(true);
    // disable tracking
    Map<String, Variation> variations = kameleoonClient.getVariations(false, false);
} catch (KameleoonException.SDKNotReady ex) {
    // Exception indicating that the SDK has not completed its initialization yet.
}

final int experimentId = 9516;
try {
    // Forcing the variation "on" for the experiment 9516 for the visitor
    kameleoonClient.setForcedVariation(experimentId, "on");

    // Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
    kameleoonClient.setForcedVariation(experimentId, "on", false);

    // Resetting the forced variation for the experiment 9516 for the visitor
    kameleoonClient.setForcedVariation(experimentId, null);
} catch (KameleoonException e) {
    // Handling the exception
}

try {
    kameleoonClient.evaluateAudiences();
} catch (KameleoonException e) {
    // Handling the exception
}

try {
    DataFile dataFile = kameleoonClient.getDataFile();
} catch (KameleoonException.SDKNotReady e) {
    // Exception indicates that the SDK has not completed its initialization yet.
} catch (Exception e) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}

final int goalId = 83023;
kameleoonClient.trackConversion(goalId); // default revenue

kameleoonClient.trackConversion(goalId, 10); // provided revenue == 10

kameleoonClient.trackConversion(goalId, new CustomData(1, "metadata")); // Add metadata

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
    }
});

String visitorCode = kameleoonClient.getVisitorCode();

// Add a single data item (tracked by default)
kameleoonClient.addData(new CustomData(1, "value"));

// Add multiple data items (tracked by default)
kameleoonClient.addData(new CustomData(1, "value"), new Geolocation("France"));

// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoonClient.addData(false, new CustomData(1, "value"), new Geolocation("France"));

kameleoonClient.addData(Device.phone());
kameleoonClient.addData(new Conversion(32, 10f, false));

kameleoonClient.flush(); // Interval tracking (most performant tracking method)

kameleoonClient.flush(true); // Instant tracking

kameleoonClient.getRemoteData("key", result -> {
    try {
        JSONObject jsonObject = result.getOrThrow();
        // jsonObject contains result of request
    } catch (Exception ex) {
        // request failed with an exception
    }
});

viewModelScope.launch {
    val jsonObject = kameleoonClient.getRemoteData("key").getOrNull() ?: return@launch
}

// Visitor data will be fetched and automatically added for `visitorCode`.
kameleoonClient.getRemoteVisitorData(result -> {
    if (result.isSuccess()) {
        // Data was successfully retrieved from the Kameleoon servers and added to the visitor.
    } else {
        // The request failed due to an 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.getOrThrow();
        // visitorData contains the fetched visitor data from Kameleoon servers, which can be manually added.
    } catch (Exception ex) {
        // The request failed due to an 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, result -> {
    if (result.isSuccess()) {
        // Data was successfully retrieved from the Kameleoon servers and added to the visitor.
    } else {
        // The request failed due to an exception.
    }
});

// Visitor data will be fetched and automatically added for `visitorCode`
viewModelScope.launch {
    kameleoonClient.getRemoteVisitorData() ?: return@launch
}

// If you only want to fetch data and add it yourself manually, set shouldAddData == `false`
viewModelScope.launch {
    kameleoonClient.getRemoteVisitorData(shouldAddData = false)
        .onSuccess { visitorData ->
            // visitorData contains the fetched visitor data from Kameleoon servers, which can be manually added.
        }.onFailure { ex ->
            // request failed with exception
        }
}

viewModelScope.launch {
    val filter = RemoteVisitorDataFilter.builder()
        .previousVisitAmount(25)
        .experiments(true)
        .conversion(true)
        .build()
    // In general, we recommend checking only if the request fails.
    kameleoonClient.getRemoteVisitorData(filter) ?: return@launch
}

// Visitor data will be fetched and automatically added for the visitor
kameleoonClient.getVisitorWarehouseAudience(customDataIndex, result -> {
    if (result.isSuccess()) {
        // Due to method called before this callback, data was automatically added to the visitor.
    } else {
        Exception exception = result.failure();
        // The request failed due to an exception.
    }
});

// If you need to specify warehouse key
kameleoonClient.getVisitorWarehouseAudience("warehouseKey", customDataIndex, result -> {
    // Due to method called before this callback, data was automatically added to the visitor,
    // but you can evaluate the added data if necessary.
    try {
        CustomData data = result.getOrThrow();
    } catch (Exception exception) {
        // The request failed due to an exception.
    }
});

// Visitor data will be fetched and automatically added for the visitor
viewModelScope.launch {
    // As a result of the method call, the data was automatically added to the visitor.
    kameleoonClient.getVisitorWarehouseAudience(customDataIndex = customDataIndex) ?: return@launch
}

// If you need to specify warehouse key
viewModelScope.launch {
    // As a result of the method call, the data was automatically added to the visitor.
    kameleoonClient.getVisitorWarehouseAudience("warehouseKey", customDataIndex)
        .onSuccess { customData ->
            // But you can evaluate the added data if you need to check it.
        }
        .onFailure { ex ->
            // The request failed due to an exception.
        }
}