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.
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.
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()
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
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()
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()
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
Name | Type | Description |
---|---|---|
handler | Function(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.
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
Name | Type | Description |
---|---|---|
data | List<Data> | one or more values conforming to the Data protocol which may be passed separated by a comma. |
Exceptions thrown
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()
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()
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
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. |
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.
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
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.
}
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
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. |
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.
}
Name | Type | Description |
---|---|---|
device | Devices | List of devices: phone , table , desktop . This field is mandatory. |
Geolocation
Geolocation
contains the visitor's geolocation details.
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.
}
Name | Type | Description |
---|---|---|
country | string | The country of the visitor. This field is required. |
region | string | The region of the visitor. This field is optional. |
city | string | The city of the visitor. This field is optional. |
postalCode | string | The postal code of the visitor. This field is optional. |
latitude | float | The latitudinal coordinate for the position of the visitor. Coordinate number represents decimal degrees (a double that can be negative). This field is optional. |
longitude | float | The longitudinal coordinate for the position of the visitor. Provide the coordinate number in decimal degrees (a double that can be negative). This field is optional. |
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.
}
Name | Type | Description |
---|---|---|
browser | Browsers | List 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.
}
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. |
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.
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.
}
Cookie
Cookie
contains information about the cookie stored on the visitor's device.
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.
}