Skip to main content

Flutter SDK

With the Kameleoon Flutter SDK, you can run experiments and activate feature flags on all platforms targeted by the Flutter application framework. Integrating our SDK into your applications is easy, and its footprint (in terms of memory and network usage) is low.

Getting started: For help getting started, see the developer guide.

Changelog: Latest version of the Flutter SDK: 3.0.0 Changelog.

SDK methods: For the full reference documentation of the Flutter SDK methods, see the reference section.

Developer guide

Getting started

This guide is designed to help you integrate our SDK in a few minutes and start running experiments in your Flutter applications. This tutorial will explain the setup of a simple A/B test to change the number of recommended products based on different variations.

Install the Flutter client

To install the Kameleoon Flutter client, declare a dependency on your pubspec.yaml file:

kameleoon_client_flutter: ^3.0.0

Initialize the Kameleoon client

After installing the SDK into your application and setting up a server-side experiment in the Kameleoon app, the next step is to create the Kameleoon client.

A KameleoonClient is a singleton object (per siteCode) that acts as a bridge between your application and the Kameleoon platform. It includes all the methods and properties you will need to run an experiment.

import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart';

class _HomePage extends State<HomePage> {
KameleoonClient kameleoonClient


void initState() {
super.initState();

try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // in minutes, 1 hour by default, optional
defaultTimeoutMilliseconds: 10000, // in milliseconds, 10 seconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // in minutes, infinity by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com" // web only option, optional
);

final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
// or if you want that visitor code will be generated automatically
final kameleoonClient = KameleoonClientFactory.create(siteCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}
}
}

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.

note

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.

Activating a feature flag

Retrieving a flag configuration

To implement a feature flag in your code, you must first create a feature flag in your Kameleoon account.

To determine if a feature flag is active for a specific user, you need to retrieve its configuration. Use the getFeatureVariationKey() or isFeatureActive() method to retrieve the configuration based on the featureKey.

The isFeatureActive() method can be used if you want to retrieve the configuration of a simple feature flag that has only an ON or OFF state, as opposed to more complex feature flags with multiple variations or targeting options.

The getFeatureVariationKey() method retrieves the configuration of a feature experiment with several feature variations. You can use the method to get a variation key for a given user by providing the visitorCode and featureKey as mandatory arguments.

Feature flags can have associated variables that are used to customize their behavior. To retrieve these variables, use the getFeatureVariationVariables() method after calling getFeatureVariationKey(), as you will need to obtain the variationKey for the user.

note

To check if a feature flag is active, you only need to use one method. Choose isFeatureFlagActive if you simply want to know if a feature flag is on or off. For more complex scenarios, like dynamically changing the feature's behavior, use getFeatureFlagVariables.

Adding data points to target a user or filter / breakdown visits in reports

To target a user, ensure you’ve added relevant data points to their profile before retrieving the feature variation or checking if the flag is active. Use the addData() method to add these data points to the user’s profile.

To retrieve data points that have been collected on other devices or to access past data points about a user (which would have been collected client-side if you are using Kameleoon in Hybrid mode), use the getRemoteVisitorData() method. This method asynchronously fetches data from our servers. However, it is important you call getRemoteVisitorData() before retrieving the variation or checking if the feature flag is active, as this data might be required to assign a user to a given variation of a feature flag.

To learn more about available targeting conditions, read our detailed article on the subject.

Additionally, the data points you add to the visitor profile will be available when analyzing your experiments, allowing you to filter and break down your results by factors like device and browser. Remember to call the flush() method to send saved data to the Kameleoon servers.

If you need to track additional data points beyond what's automatically collected, you can use Kameleoon's Custom Data feature. Custom Data allows you to capture and analyze specific information relevant to your experiments. To ensure your results are accurate, it's recommended to filter out bots by using the userAgent data type. You can learn more about this here. Don't forget to call the flush() method to send the collected data to Kameleoon servers for analysis.

Tracking flag exposition and goal conversions

Kameleoon will automatically track visitors’ exposition to flags as soon as you call one of these methods:

  • getFeatureVariationKey()
  • getFeatureVariable()
  • isFeatureActive()

When a user completes a desired action (for example, making a purchase), it counts as a conversion. To track conversions, you must use the trackConversion() method, and provide the visitorCode and goalId parameters.

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:

try {
// Calling a method of the SDK
} on KameleoonException {
// Handling expected exceptions
} on Exception {
// Any other error
}

Reference

This is a full reference documentation of the Flutter 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 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.

import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart'


final siteCode = "a8st4f59bj";
try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // in minutes, 1 hour by default, optional
defaultTimeoutMilliseconds: 10000, // in milliseconds, 10 seconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // in minutes, infinity by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com" // web only option, optional
);
final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}

try {
// generate visitorCode automatically and use default kameleoon client config
final kameleoonClient = KameleoonClientFactory.create(siteCode);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on Exception catch (ex) {
// Any other error
}
Arguments
NameTypeDescription
siteCodeStringThis is a unique key of the Kameleoon project you are using with the SDK. This field is mandatory.
visitorCodeStringUnique identifier of the user. This field is optional.
configKameleoonClientConfigConfiguration SDK object. This field is optional.
Exceptions thrown
TypeDescription
SiteCodeIsEmptyException indicating that the provided siteCode is empty.
VisitorCodeInvalidException indicates that the provided visitorCode is invalid.

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).

final ready = kameleoonClient.isReady();
Return value
NameTypeDescription
readyboolBoolean representing the status of the SDK (properly initialized, or 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 type of Function(bool ready). If the ready 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.

kameleoonClient.runWhenReady((ready) async {
final defaultProductsNumber = 5;
if (ready) {
late int recommendedProductsNumber;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable("feature_key", "product_number");
} on Exception {
recommendedProductsNumber = defaultProductsNumber;
}
} else {
recommendedProductsNumber = defaultProductsNumber;
}

setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
}, 2000);
Arguments
NameTypeDescription
callbackFunction(bool ready)Callback object with ready flag . This field is mandatory.
timeoutintTimeout (in milliseconds). This field is optional, if not provided, it will use the default value of defaultTimeoutMilliseconds (from KameleoonClientConfig) milliseconds.

Feature flags and variations

isFeatureActive()

  • 📨 Sends Tracking Data to Kameleoon

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 feature flag value.

Make sure to set up proper error handling as shown in the example code to catch potential exceptions.

String featureKey = "new_checkout";
bool hasNewCheckout = false;

try {
hasNewCheckout = await kameleoonClient.isFeatureActive(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error is happened, feature flag isn't found in current configuration
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error
}
if (hasNewCheckout) {
// Implement new checkout code here
}
Arguments
NameTypeDescription
featureKeyStringUnique key of the feature you want to expose to a user. This field is required.
Return value
TypeDescription
Future<bool>Value of the feature that is registered for a visitor.
Exceptions thrown
TypeDescription
SDKNotReadyException indicating that the SDK has not completed its initialization yet.
FeatureNotFoundException 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).
PlatformExceptionException indicating that the native plugin integration works incorrectly.

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.

String featureKey = "new_checkout";
String variationKey = "";

try {
variationKey = await kameleoonClient.getFeatureVariationKey(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error is happened, feature flag isn't found in current configuration
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// 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;
}
Arguments
NameTypeDescription
featureKeyStringKey of the feature you want to expose to a user. This field is mandatory.
Return value
TypeDescription
Future<String>Variation key of the feature flag that is registered for a visitor.
Exceptions thrown
TypeDescription
SDKNotReadyException indicating that the SDK has not completed its initialization yet.
FeatureNotFoundException 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).
PlatformExceptionException indicating that the native plugin integration works incorrectly.

getFeatureList()

Returns a list of feature flag keys currently available for the SDK.

try {
final allFeatureFlagKeys = await kameleoonClient.getFeatureList();
} on PlatformException {
// Generic exception in native plugin integration happened.
}
Return value
TypeDescription
Future<List<String>>List of feature flag keys.

getActiveFeatures()

note

This method was previously named getFeatureListActive, which was removed in SDK version 3.0.0.

getActiveFeatures method retrieves information about the active feature flags that are available for the visitor.

try {
final activeFeatures = await kameleoonClient.getActiveFeatures();
} on PlatformException {
// Generic exception in native plugin integration happened.
}
Return value
TypeDescription
Future<Map<String, Variation>>Map that contains the assigned variations of the active features using the keys of the corresponding active features.

Feature variables

getFeatureVariable()

  • 📨 Sends Tracking Data to Kameleoon
note

This method was previously named obtainFeatureVariable, which was removed in SDK version 3.0.0.

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.

String featureKey = "feature_key";
String variableKey = "product_number";
int recommendedProductsNumber = 5;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable(featureKey, variableKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error is happened, feature flag isn't found in current configuration
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment
} on FeatureVariableNotFound {
// Requested variable not defined on Kameleoon's side
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error
}

setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
Arguments
NameTypeDescription
featureKeyStringKey of the feature you want to expose to a user. This field is mandatory.
variableKeyStringName of the variable you want to get a value. This field is mandatory.
Return value
TypeDescription
Future<dynamic>Value of variable of variation that is registered for a visitor for this feature flag. Possible types: bool, int, double, String, List, Map
Exceptions thrown
TypeDescription
SDKNotReadyException indicating that the SDK has not completed its initialization yet.
FeatureNotFoundException 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).
FeatureEnvironmentDisabledException indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development).
FeatureVariableNotFoundException indicating that the specified variable was not found. Check that the variable key in the Kameleon app matches the one in your code.
PlatformExceptionException indicating that the native plugin integration works incorrectly.

getFeatureVariationVariables()

note

This method was previously named: getFeatureAllVariables, which was removed in SDK version 3.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.

final featureKey = "featureKey";
final variationKey = "variationKey";

try {
final allVariables = await client.getFeatureVariationVariables(featureKey, variationKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error is happened, feature flag isn't found in current configuration
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error
}
Arguments
NameTypeDescription
featureKeyStringIdentificator key of the feature you need to obtain. This field is mandatory.
variationKeyStringThe key of the variation you want to obtain. This field is mandatory.
Return value
TypeDescription
Future<Map<String, dynamic>>Data associated with this feature flag. The values of can be a int, double, bool, String, List or Map (depending on the type defined on the web interface).
Exceptions thrown
TypeDescription
FeatureNotFoundException indicating that the requested feature has not been found in the internal configuration of the SDK. This is usually normal and means that the feature flag has not yet been activated on Kameleoon''s side.
FeatureEnvironmentDisabledException indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development).
FeatureVariationNotFoundException indicating that the requested variation ID has not been found in the internal configuration of the SDK. This is usually normal and means that the variation's corresponding experiment has not yet been activated on Kameleoon's side.
PlatformExceptionException indicating that the native plugin integration works incorrectly.

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.

try {
kameleoonClient.trackConversion(goalId); // default revenue
kameleoonClient.trackConversion(goalId, 10); // provided revenue == 10
} on PlatformException {
// Generic exception in native plugin integration happened.
}
Arguments
NameTypeDescription
goalIdintID of the goal. This field is mandatory.
revenuedoubleRevenue of the conversion. This field is optional.

Events

onUpdateConfiguration()

note

This method was previously named updateConfigurationHandler, which was removed in SDK version 3.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.

kameleoonClient.onUpdateConfiguration((timestamp) {
// timestamp value contains the value of Unix time (number of seconds that have elapsed since January 1, 1970) when configuration was updated
});
Arguments
NameTypeDescription
handlerFunction(int)?The handler 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.

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.

tip

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.

try {
await kameleoonClient.addData([
Device(Devices.phone),
CustomData(1, "some custom value"),
Conversion(32, 10f, false),
]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
Arguments
NameTypeDescription
dataList<Data>one or more values conforming to the Data protocol which may be passed separated by a comma.
Exceptions thrown
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.

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.

try {
kameleoonClient.flush();
} on PlatformException {
// Generic exception in native plugin integration happened.
}
Exceptions thrown
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.

getRemoteData()

note

This method was previously named retrieveDataFromRemoteSource, which was removed in SDK version 3.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.

try {
final data = await kameleoonClient.getRemoteData("test");
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}
Arguments
NameTypeDescription
keyStringThe key that the data you try to get is associated with. This field is optional.
Return value
TypeDescription
Future<dynamic>Future with retrieving data for specific key (or visitorCode if key is omitted).
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.
ExceptionException indicating that the request timed out or any other reason of failure.

getRemoteVisitorData()

The getRemoteVisitorData method allows you to retrieve custom data stored on remote Kameleoon servers for a visitor. If addData 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.

// Visitor data will be fetched and automatically added for `visitorCode`
try {
final visitorData = await kameleoonClient.getRemoteVisitorData();
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}

// If you only want to fetch data and add it yourself manually, set addData == `false`
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(addData: false);
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}

// If you want to fetch custom list of data types
final filter = RemoteVisitorDataFilter.withValues(
previousVisitAmount: 25,
currentVisit: true,
conversions: true,
);
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(filter: filter, addData: false);
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}
Arguments
NameTypeDescription
filterRemoteVisitorDataFilterFilter that selects which data should be retrieved from visit history. By default, getRemoteVisitorData retrieves CustomData from the current and latest previous visit (RemoteVisitorDataFilter()). All other filters parameters default to false. This field is optional.
addDatabooleanA 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.
note

Here is the list of available RemoteVisitorDataFilter options:

NameTypeDescriptionDefault
previousVisitAmount (optional)intNumber of previous visits to retrieve data from. Number between 1 and 251
currentVisit (optional)booleanIf true, current visit data will be retrieved.true
customData (optional)booleanIf true, custom data will be retrieved.true
geolocation (optional)booleanIf true, geolocation data will be retrieved.false
conversions (optional)booleanIf true, conversion data will be retrieved.false
experiments (optional)booleanIf true, experiment data will be retrieved.false
pageViews (optional, web only)booleanIf true, page data will be retrieved.false
device (optional, web only)booleanIf true, device data will be retrieved.false
browser (optional, web only)booleanIf true, browser data will be retrieved.false
operatingSystem (optional, web only)booleanIf true, operating system data will be retrieved.false
Exceptions thrown
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.
ExceptionException indicating that the request timed out or any other reason of failure.

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 returns the result as a CustomData object, confirming that the data has been added to the visitor and is available for targeting purposes.

note

Since a server call is required, this mechanism is asynchronous.

try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex);
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}

// If you need to specify warehouse key
try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex, "warehouseKey");
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}
Arguments
NameTypeDescription
visitorCodestringA unique visitor identification string, can't exceed 255 characters length.
customDataIndexintAn integer representing the index of the custom data you want to use to target your BigQuery Audiences.
warehouseKeystringA unique key to identify the warehouse data (usually, your internal user ID). This field is optional.
Return value
TypeDescription
Future<CustomData>A CustomData instance confirming that the data has been added to the visitor.
Exceptions thrown
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.
ExceptionException 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 consent 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
NameTypeDescription
consentbooleanA 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
try {
final customData = await kameleoonClient.setLegalConsent(true);
} on PlatformException {
// Generic exception in native plugin integration happened.
} on Exception {
// Any other error (including network issues)
}
Exceptions thrown
TypeDescription
PlatformExceptionException indicating that the native plugin integration works incorrectly.

Data

This section lists the 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.

Shared data

The types of data is available for both types of SDKs: Mobile & Web.

Conversion

Store information about conversion events.

try {
await kameleoonClient.addData([Conversion(32, 10, false)]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
goalIdStringID of the goal. This field is mandatory.
revenuedoubleConversion revenue. This field is optional.
negativeboolDefines if the revenue is positive or negative. This field is optional.
CustomData

Define your own custom data types in the Kameleoon app or the Data API and use them from the SDK.

try {
await kameleoonClient.addData([CustomData(1, "some custom value")]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
idintIndex / ID of the custom data to be stored. This field is mandatory.
valueStringValue of the custom data to be stored. This field is mandatory.
note

The index (ID) of the custom data is available on our Back-Office, 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.

Device

Store information about the user's device.

try {
await kameleoonClient.addData([Device(Devices.phone)]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
deviceDevicesList of devices: phone, table, desktop. This field is mandatory.
Geolocation

Geolocation contains the visitor's geolocation details.

note

Each visitor can only have one Geolocation. Adding a second Geolocation overwrites the first one.

try {
await kameleoonClient.addData([Geolocation("France", region: "Île-de-France", city: "Paris")]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
countrystringThe country of the visitor. This field is required.
regionstringThe region of the visitor. This field is optional.
citystringThe city of the visitor. This field is optional.
postalCodestringThe postal code of the visitor. This field is optional.
latitudefloatThe latitudinal coordinate for the position of the visitor. Coordinate number represents decimal degrees (a double that can be negative). This field is optional.
longitudefloatThe 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.

Web only data

The types of data is available only for Web SDK (it will be ignored on mobile SDKs)

Browser

try {
await kameleoonClient.addData([Browser(Browsers.chrome)]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
browserBrowsersList of browsers: chrome, internerExplorer, firefox, safari, opera, other. This field is mandatory.

PageView

try {
await kameleoonClient.addData([PageView("https://url.com", "title", [3])]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}
NameTypeDescription
urlStringURL of the page viewed. This field is mandatory.
titleStringTitle of the page viewed. This field is mandatory.
referrersList<int>Referrers of viewed pages. This field is optional.
note

The index (ID) of the referrer is available on our Back-Office, in the Acquisition channel configuration page. Be careful: this index starts at 0, so the first acquisition channel you create for a given site would have the ID 0, not 1.

OperatingSystem

OperatingSystem contains information about the operating system on the visitor's device.

note

Each visitor can only have one OperatingSystem. Adding a second OperatingSystem overwrites the first one.

NameTypeDescription
typeOperatingSystemsList of operating systems: windows, mac, ios, linux, android, windowsPhone . This field is required.
try {
await kameleoonClient.addData([OperatingSystem(OperatingSystem.linux)]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}

Cookie contains information about the cookie stored on the visitor's device.

note

Each visitor can only have one Cookie. Adding second Cookie overwrites the first one.

NameTypeDescription
cookiesMap<String, String>A string object map consisting of cookie keys and values. This field is required.
try {
await kameleoonClient.addData([Cookie({
"my_key1": "my_value1",
"my_key2": "my_value2"
})]);
} on PlatformException {
// Generic exception in native plugin integration happened.
}