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

    @override
    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

Name	Type	Description
siteCode	String	This is a unique key of the Kameleoon project you are using with the SDK. This field is mandatory.
visitorCode	String	Unique identifier of the user. This field is optional.
config	KameleoonClientConfig	Configuration SDK object. This field is optional.

Exceptions thrown

Type	Description
SiteCodeIsEmpty	Exception indicating that the provided siteCode is empty.
VisitorCodeInvalid	Exception 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

Name	Type	Description
ready	bool	Boolean 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

Name	Type	Description
callback	Function(bool ready)	Callback object with `ready` flag . This field is mandatory.
timeout	int	Timeout (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

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
`Future<bool>`	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).
PlatformException	Exception 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

Name	Type	Description
featureKey	String	Key of the feature you want to expose to a user. This field is mandatory.

Return value

Type	Description
`Future<String>`	Variation key of the feature flag 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).
PlatformException	Exception 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

Type	Description
`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

Type	Description
`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

Name	Type	Description
featureKey	String	Key of the feature you want to expose to a user. This field is mandatory.
variableKey	String	Name of the variable you want to get a value. This field is mandatory.

Return value

Type	Description
`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

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).
FeatureEnvironmentDisabled	Exception indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development).
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.
PlatformException	Exception 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

Name	Type	Description
featureKey	String	Identificator key of the feature you need to obtain. This field is mandatory.
variationKey	String	The key of the variation you want to obtain. This field is mandatory.

Return value

Type	Description
`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

Type	Description
FeatureNotFound	Exception 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.
FeatureEnvironmentDisabled	Exception indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development).
FeatureVariationNotFound	Exception 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.
PlatformException	Exception 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

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

note

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

The onUpdateConfiguration() method allows you to handle the event when configuration has updated data. It takes one input parameter, handler. 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

Name	Type	Description
handler	`Function(int)?`	The handler that will be called when the configuration is updated using a real-time configuration event.

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

The trackConversion() method also sends out any previously associated data, just like the flush(). The same holds true for getVariation() and getVariations() methods if an experimentation rule is triggered.

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

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

Name	Type	Description
data (required)	`List<Data>`	Collection of Kameleoon data types.

Exceptions

Type	Description
`PlatformException`	Exception 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

Type	Description
PlatformException	Exception 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

Name	Type	Description
key	String	The key that the data you try to get is associated with. This field is optional.

Return value

Type	Description
`Future<dynamic>`	Future with retrieving data for specific `key` (or `visitorCode` if `key` is omitted).

Type	Description
PlatformException	Exception indicating that the native plugin integration works incorrectly.
Exception	Exception indicating that the request timed out or any other reason of failure.

getRemoteVisitorData()

getRemoteVisitorData() is an asynchronous method for retrieving Kameleoon Visits Data for the visitorCode from the Kameleoon Data API. The method adds the data to storage for other methods to use when making targeting decisions.

Data obtained using this method plays an important role when you want to:

use data collected from other devices.
access a user's history, such as custom data collected during previous visits.

Read this article for a better understanding of possible use cases.

caution

By default, getRemoteVisitorData() automatically retrieves the latest stored custom data with scope=Visitor and attaches them to the visitor without the need to call the method addData(). It is particularly useful for synchronizing custom data between multiple 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)
}

Using parameters in getRemoteVisitorData()

The getRemoteVisitorData() method offers flexibility by allowing you to define various parameters when retrieving data on visitors. Whether you're targeting based on goals, experiments, or variations, the same approach applies across all data types.

For example, let's say you want to retrieve data on visitors who completed a goal "Order transaction". You can specify parameters within the getRemoteVisitorData() method to refine your targeting. For instance, if you want to target only users who converted on the goal in their last five visits, you can set the previousVisitAmount parameter to 5 and conversions to true.

The flexibility shown in this example is not limited to goal data. You can use parameters within the getRemoteVisitorData() method to retrieve data on a variety of visitor behaviors.

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()`). All other filters parameters default to `false`. This field is optional.
addData	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.

note

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`
pageViews (optional, web only)	`boolean`	If true, page data will be retrieved.	`false`
device (optional, web only)	`boolean`	If true, device data will be retrieved.	`false`
browser (optional, web only)	`boolean`	If true, browser data will be retrieved.	`false`
operatingSystem (optional, web only)	`boolean`	If true, operating system data will be retrieved.	`false`

Exceptions thrown

Type	Description
PlatformException	Exception indicating that the native plugin integration works incorrectly.
Exception	Exception 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

Name	Type	Description
visitorCode	string	A unique visitor identification string, can't exceed 255 characters length.
customDataIndex	int	An integer representing the index of the custom data you want to use to target your BigQuery Audiences.
warehouseKey	string	A unique key to identify the warehouse data (usually, your internal user ID). This field is optional.

Return value

Type	Description
`Future<CustomData>`	A `CustomData` instance confirming that the data has been added to the visitor.

Exceptions thrown

Type	Description
PlatformException	Exception indicating that the native plugin integration works incorrectly.
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 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

Name	Type	Description
consent	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

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

Type	Description
PlatformException	Exception indicating that the native plugin integration works incorrectly.

Data types

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.

Conversion

note

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

Store information about conversion events.

try {
    await kameleoonClient.addData([Conversion(32, 10, false)]);
}  on PlatformException {
    // Generic exception in native plugin integration happened.
}

Name	Type	Description
goalId	String	ID of the goal. This field is mandatory.
revenue	double	Conversion revenue. This field is optional.
negative	bool	Defines if the revenue is positive or negative. This field is optional.

CustomData

note

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

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

Name	Type	Description
id	int	Index / ID of the custom data to be stored. This field is mandatory.
value	String	Value 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

note

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

Store information about the user's device.

try {
    await kameleoonClient.addData([Device(Devices.phone)]);
}  on PlatformException {
    // Generic exception in native plugin integration happened.
}

Name	Type	Description
device	Devices	List of devices: `phone`, `table`, `desktop`. This field is mandatory.

Geolocation

note

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

Geolocation contains the visitor's geolocation details.

tip

Each visitor can have only 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.
}

Name	Type	Description
country (required)	`String`	The country of the visitor.
region (optional)	`String?`	The region of the visitor.
city (optional)	`String?`	The city of the visitor.
postalCode (optional)	`String?`	The postal code of the visitor.
latitude (optional)	`double?`	The latitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees.
longitude (optional)	`double?`	The longitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees.

Browser

note

The data type is available only for Web SDK

The Browser data set stored here can be used to filter experiment and personalization reports by any value associated with it.

try {
    await kameleoonClient.addData([Browser(Browsers.chrome)]);

    await kameleoonClient.addData([Browser(Browsers.chrome, 10.0)]);
}  on PlatformException {
    // Generic exception in native plugin integration happened.
}

Name	Type	Description
browser (required)	`Browsers`	List of browsers: `chrome`, `internetExplorer`, `firefox`, `safari`, `opera`, `other`.
version (optional)	`double?`	Version of the browser, floating point number represents major and minor version of the browser

PageView

note

The data type is available only for Web SDK

try {
    await kameleoonClient.addData([PageView("https://url.com", "title", [3])]);
}  on PlatformException {
    // Generic exception in native plugin integration happened.
}

Name	Type	Description
url	String	URL of the page viewed. This field is mandatory.
title	String	Title of the page viewed. This field is mandatory.
referrers	`List<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

note

The data type is available only for Web SDK

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

tip

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

Name	Type	Description
type	`OperatingSystems`	List 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.
}

note

The data type is available only for Web SDK

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

tip

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

Name	Type	Description
cookies	`Map<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.
}

Flutter SDK

Developer guide​

Getting started​

Install the Flutter client​

Initialize the Kameleoon client​

Activating a feature flag​

Retrieving a flag configuration​

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

Tracking flag exposition and goal conversions​

Targeting conditions​

Error Handling​

Reference​

Initialization​

create()​

Arguments​

Exceptions thrown​

isReady()​

Return value​

runWhenReady()​

Arguments​

Feature flags and variations​

isFeatureActive()​

Arguments​

Return value​

Exceptions thrown​

getFeatureVariationKey()​

Arguments​

Return value​

Exceptions thrown​

getFeatureList()​

Return value​

getActiveFeatures()​

Return value​

Feature variables​

getFeatureVariable()​

Arguments​

Return value​

Exceptions thrown​

getFeatureVariationVariables()​

Arguments​

Return value​

Exceptions thrown​

Goals​

trackConversion()​

Arguments​

Events​

onUpdateConfiguration()​

Arguments​

Visitor data​

addData()​

Arguments​

Exceptions​

flush()​

Exceptions thrown​

getRemoteData()​

Arguments​

Return value​

getRemoteVisitorData()​

Using parameters in getRemoteVisitorData()​

Arguments​

Exceptions thrown​

getVisitorWarehouseAudience()​

Arguments​

Return value​

Exceptions thrown​

setLegalConsent()​

Arguments​

Example code​

Exceptions thrown​

Data types​

Conversion​

CustomData​

Device​

Geolocation​

Browser​

PageView​

OperatingSystem​

Cookie​

Developer guide

Getting started

Install the Flutter client

Initialize the Kameleoon client

Activating a feature flag

Retrieving a flag configuration

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

Tracking flag exposition and goal conversions

Targeting conditions

Error Handling

Reference

Initialization

create()

Arguments

Exceptions thrown

isReady()

Return value

runWhenReady()

Arguments

Feature flags and variations

isFeatureActive()

Arguments

Return value

Exceptions thrown

getFeatureVariationKey()

Arguments

Return value

Exceptions thrown

getFeatureList()

Return value

getActiveFeatures()

Return value

Feature variables

getFeatureVariable()

Arguments

Return value

Exceptions thrown

getFeatureVariationVariables()

Arguments

Return value

Exceptions thrown

Goals

trackConversion()

Arguments

Events

onUpdateConfiguration()

Arguments

Visitor data

addData()

Arguments

Exceptions

flush()

Exceptions thrown

getRemoteData()

Arguments

Return value

getRemoteVisitorData()

Using parameters in getRemoteVisitorData()

Arguments

Exceptions thrown

getVisitorWarehouseAudience()

Arguments

Return value

Exceptions thrown

setLegalConsent()

Arguments

Example code

Exceptions thrown

Data types

Conversion

CustomData

Device

Geolocation

Browser

PageView

OperatingSystem

Cookie