Skip to main content

React SDK

With the Kameleoon React SDK, you can run feature experiments and activate feature flags on your front-end web and mobile application. Integrating our SDK into your web and mobile application is easy, and its footprint (memory and network usage) is low.

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

Changelog: Details on the latest version of the React SDK can be found in the changelog.

Requirements: React SDK requires React 16.8.0+

Reference​

This is the full reference documentation for the React SDK.

Initialization​

This section provides the methods you use to create and initialize the Kameleoon Client in your application.

initialize()​

An asynchronous initialize function, collected with useInitialize hook, that's used for KameleoonClient initialization by fetching Kameleoon SDK related data from server or by retrieving data from local source if data is up-to-date or update interval has not been reached.

note

If the SDK configuration could not be retrieved but there is an older configuration available in SDK storage, the SDK uses the older configuration as a fallback and the initialize does not throw an error.

note

Client initialization has an optional offline mode. It is activated by setting optional useCache parameter to true.

In offline mode if tracking requests from any of the following methods fail due to internet connectivity issues, the SDK automatically resends the request as soon as it detects that the internet connection has been re-established:

import { useEffect, useCallback } from 'react';
import { useInitialize } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();

  const init = useCallback(async (): Promise<void> => {
    await initialize();
  }, [initialize]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescriptionDefault Value
useCache (optional)boolean or undefinedparameter for activating SDK offline mode, if true is passed failed polls will not return error and will use cached data if such data is availablefalse
Returns​

Promise<boolean> - a promise resolved to a boolean indicating a successful sdk initialization. Generally initialize will throw an error if the something that can not be handled will happen, so the boolean value will almost always be true and won't give as much useful information.

Throws​
TypeDescription
KameleoonException.StorageWriteCouldn't update storage data
KameleoonException.ClientConfigurationCouldn't retrieve client configuration from Kameleoon API
KameleoonException.MaximumRetriesReachedMaximum retries reached, request failed

isInitialized()​

The isInitialized function, collected with the useInitialize hook, is a small utility method that checks if the SDK initialization has completed. For example, this can be useful when dealing with a deeply nested component tree, because it allows you to quickly check the SDK readiness without having to manage a global state, or pass the initialization result using component props.

import { useEffect, useCallback } from 'react';
import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();

  const init = useCallback(async (): Promise<void> => {
    await initialize();
  }, [initialize]);

  useEffect(() => {
    init();
  }, [init]);
}

function DeeplyNestedComponent(): JSX.Element {
  const { isInitialized } = useInitialize();
  const { getFeatureFlagVariationKey } = useFeatureFlag();

  if (isInitialized()) {
    const variation = getFeatureFlagVariationKey('my_feature_key');
  }
}
Returns​

A boolean value. Returns true if SDK was successfully initialized, otherwise returns false.

createClient()​

To get started, you need to create an entry point for React SDK by creating a Kameleoon Client at the top level of your application using the createClient() function imported from kameleoon package.

An instance of KameleoonClient is created using createClient() function.

import {
  createClient,
  Environment,
  SDKConfigurationType,
} from '@kameleoon/react-sdk';

// -- Optional configuration
const configuration: Partial<SDKConfigurationType> = {
  updateInterval: 60,
  environment: Environment.Production,
  domain: '.example.com',
};

const client = createClient({ siteCode: 'my_site_code', configuration });
Parameters​

An object of type SDKParameters containing:

NameTypeDescription
siteCode (required)stringclient's siteCode defined on Kameleoon platform
configuration (optional)Partial<SDKConfigurationType>client's configuration
externals (optional)ExternalsTypeexternal implementation of SDK dependencies (External dependencies)
Configuration Parameters​
NameTypeDescriptionDefault Value
updateInterval (optional)numberupdate interval in minutes for sdk configuration; minimum value is 1 minute60
environment (optional)Environmentfeature flag environmentEnvironment.Production
targetingDataCleanupInterval (optional)numberinterval in minutes for cleaning up targeting data; minimum value is 1 minuteundefined (no cleanup will be performed)
domain (optional)stringdomain that the cookie belongs to. Deprecated, use cookieDomain insteadundefined
cookieDomain (optional)stringdomain that the cookie belongs to.undefined
networkDomain (optional)stringcustom domain the SDKs uses for all outgoing network requests, commonly used for proxying. The format is second_level_domain.top_level_domain (for example, example.com). If an invalid format is specified, the SDK uses the default Kameleoon valueundefined
requestTimeout (optional)numbertimeout in milliseconds for all SDK network requests, if timeout is exceeded request will fail immediately10_000 (10 seconds)
note

The domain parameter is deprecated and will be removed in a future release. Use cookieDomain instead.

Returns​

KameleoonClient - an instance of KameleoonClient.

note

Make sure not to use several client instances in one application as it is not fully supported yet and may overwrite the local storage configuration and cause unintended behavior (bugs).

Feature flags and variations​

This section provides the methods you use to retrieve and manage the feature flags and variations assigned to the visitor.

isFeatureFlagActive()​

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation

Method isFeatureFlagActive() collected with useFeatureFlag hook indicates whether the visitor with visitorCode has featureKey active. The method checks for targeting, finds the variation for the visitor and saves it to storage. The hook also sends the tracking request.

note

Visitor must be targeted to has feature flag active

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  useFeatureFlag,
  useVisitorCode,
  CustomData,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();
  const { isFeatureFlagActive } = useFeatureFlag();
  const { getVisitorCode } = useVisitorCode();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code using `getVisitorCode` function
    const visitorCode = getVisitorCode();

    const featureKey = 'my_feature_key';

    // -- Add CustomData with index `0` containing visitor id to check the targeting
    addData(visitorCode, new CustomData(0, 'visitor_id'));

    // -- Get the status of feature flag
    const isActive = isFeatureFlagActive(visitorCode, featureKey);
  }, [initialize, visitorCode, isFeatureFlagActive, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
Returns​

boolean - indicator of whether the feature flag with featureKey is active for visitor with visitorCode.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.FeatureFlagConfigurationNotFoundNo feature flag was found for the specified featureKey
KameleoonException.DataInconsistencyAllocated variation was found but there is no feature flag with according featureKey

getFeatureFlagVariationKey()​

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation

Method getFeatureFlagVariationKey() collected with useFeatureFlag hook returns variation key for the visitor under visitorCode in the found feature flag, this includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request.

note

If the user has never been associated with the feature flag, the SDK returns a variation key randomly, following the feature flag rules. If the user is already registered with the feature flag, the SDK detects the previous variation key value. If the user doesn't match any of the rules, the default value defined in Kameleoon's feature flag delivery rules will be returned. It's important to note that the default value may not be a variation key, but a boolean value or another data type, depending on the feature flag configuration.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useFeatureFlag,
  useVisitorCode,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getFeatureFlagVariationKey } = useFeatureFlag();
  const { getVisitorCode } = useVisitorCode();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code using `getVisitorCode` function
    const visitorCode = getVisitorCode();

    const featureKey = 'my_feature_key';

    // -- Get the variationKey for the visitor under `visitorCode` in the found feature flag
    const variationKey = getFeatureFlagVariationKey(visitorCode, featureKey);
  }, [initialize, visitorCode, getFeatureFlagVariationKey, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
Returns​

string - a string containing variable key for the allocated feature flag variation for the provided visitor.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before initialize was done for kameleoonClient
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.FeatureFlagConfigurationNotFoundNo feature flag was found for the specified featureKey
KameleoonException.FeatureFlagEnvironmentDisabledFeature flag is disabled for the current environment

getFeatureFlags()​

🚫 Doesn't send Tracking Data to Kameleoon

Method getFeatureFlags collected with useFeatureFlag hook returns a list of feature flags stored in the client configuration.

import { useEffect, useCallback } from 'react';
import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getFeatureFlags } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get list of all feature flags
    const featureFlags = getFeatureFlags();
  }, [initialize, getFeatureFlags]);

  useEffect(() => {
    init();
  }, [init]);
}
Returns​

FeatureFlagType[] - list of feature flags, each feature flag item contains id and key.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call

getVisitorFeatureFlags()​

  • 🚫 Doesn't send Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation (for each feature flag)

Method getVisitorFeatureFlags, collected with the useFeatureFlag hook, returns a list of active feature flags that the visitor associated with the visitorCode is being targeted by (the visitor must have one of the variations allocated).

caution

This method only collects the visitor's active feature flags. This means the result excludes all the feature flags for which the visitor is assigned to the off (default or control) variation. When you need all of the visitor's feature flags, use getFeatureFlags instead.

For example:

// -- `getVisitorFeatureFlags` doesn't trigger feature experiment
//    it only returns feature flags, where visitor didn't get `off` variation
getVisitorFeatureFlags('my_visitor').forEach(({ key }) => {
  // -- `getFeatureFlagVariationKey` triggers feature experiment,
  //    as `off` is already filtered out - I will never see
  //    visitor taking part in experiment, where `off` variation was allocated
  getFeatureFlagVariationKey('my_visitor', key);
});

For cases where you need all of the visitor's feature flags, use getFeatureFlags instead:

// -- Both `off` and other variations are processed as expected
getFeatureFlags('my_visitor').forEach(({ key }) => {
  getFeatureFlagVariationKey('my_visitor', key);
});
import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useFeatureFlag,
  useVisitorCode,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { getVisitorFeatureFlags } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Get active feature flags for visitor
    const featureFlags = getVisitorFeatureFlags(visitorCode);
  }, [initialize, visitorCode, getVisitorFeatureFlags, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
Returns​

FeatureFlagType[] - list of feature flags, each feature flag item contains id and key.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.StorageReadError while reading storage data

getActiveFeatureFlags()​

  • 🚫 Doesn't send Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation (for each feature flag)

Method getActiveFeatureFlags, collected with the useFeatureFlag hook, returns a Map, where key is feature key and value is detailed information about the visitor's variation and it's variables

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useFeatureFlag,
  useVisitorCode,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { getActiveFeatureFlags } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Get active feature flags for visitor
    //    with detailed variation and variables data
    const activeFeatures = getActiveFeatureFlags(visitorCode);

    // -- Result example:
    // Map {
    //   'feature-key-one' => {
    //     id: 100,
    //     key: 'variation-key-one',
    //     experimentId: 200,
    //     variables: [
    //      { key: 'variable_bool', type: VariableType.Boolean, value: true },
    //     ]
    //   },
    //   'feature-key-two' => {
    //     id: null, // -> `null` because it is default variation
    //     key: 'default-variation-key',
    //     experimentId: null, // -> `null` because it is default variation
    //     variables: []
    //   }
    // }
  }, [initialize, visitorCode, getVisitorFeatureFlags, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}

init();
caution

This method only collects the visitor's active feature flags. This means the result excludes all the feature flags for which the visitor is assigned to the off (default or control) variation. When you need all of the visitor's feature flags to iterate over, use getFeatureFlags instead.

See the getVisitorFeatureFlags CAUTION section method for more details.

Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
Returns​

Map<string, KameleoonVariationType> - a map of feature flags, where key is feature key and value is detailed information about the visitor's variation and it's variables

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length of 255 characters
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.StorageReadError while reading storage data
KameleoonException.NumberParseCouldn't parse Number value
KameleoonException.JSONParseCouldn't parse JSON value

Variables​

This section provides the methods you use to retrieve and manage the variables assigned to the visitor.

getFeatureFlagVariable()​

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation

Method getFeatureFlagVariable collected with useFeatureFlag hook returns a variable for the visitor under visitorCode in the found feature flag, this includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useVisitorCode,
  useFeatureFlag,
  VariableType,
  JSONType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { getFeatureFlagVariable } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Get feature variable
    const result = getFeatureFlagVariable({
      visitorCode,
      featureKey: 'my_feature_key',
      variableKey: 'my_variable_key',
    });

    // -- Infer the type of variable by it's `type`
    switch (result.type) {
      case VariableType.BOOLEAN:
        const myBool: boolean = result.value;
        break;
      case VariableType.NUMBER:
        const myNum: number = result.value;
        break;
      case VariableType.JSON:
        const myJson: JSONType = result.value;
        break;
      case VariableType.STRING:
        const myStr: string = result.value;
        break;
      default:
        break;
    }
  }, [initialize, getFeatureFlagVariable, visitorCode, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​

Parameters object of type GetFeatureFlagVariableParamsType containing the following fields:

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
variableKey (required)stringkey of the variable to be found for a feature flag with the specified featureKey, can be found on Kameleoon Platform
Returns​

FeatureFlagVariableType - a variable object containing type and value fields. You can check the type field against VariableType enum. For example, if the type is VariableType.BOOLEAN then value will be a boolean type.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before initialize was done for kameleoonClient
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.FeatureFlagConfigurationNotFoundNo feature flag was found for the specified featureKey
KameleoonException.FeatureFlagVariableNotFoundNo feature variable was found for the specified visitorCode and variableKey
KameleoonException.FeatureFlagEnvironmentDisabledFeature flag is disabled for the current environment
KameleoonException.JSONParseCouldn't parse JSON value
KameleoonException.NumberParseCouldn't parse Number value

getFeatureFlagVariables()​

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation (for each feature flag)

Method getFeatureFlagVariables collected with useFeatureFlag hook returns a list of variables for the visitor under visitorCode in the found feature flag, this includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useFeatureFlag,
  useVisitorCode,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { getFeatureFlagVariables } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Get a list of variables for the visitor under `visitorCode` in the found feature flag
    const variables = getFeatureFlagVariables(visitorCode, 'my_feature_key');
  }, [initialize, getFeatureFlagVariables, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
Returns​

FeatureVariableResultType[] - a list of variable objects containing key, type and value fields. You can check the type field against VariableType enum. For example, if the type is VariableType.BOOLEAN then value will be a boolean type.

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.FeatureFlagConfigurationNotFoundNo feature flag was found for the specified featureKey
KameleoonException.FeatureFlagVariationNotFoundNo feature variation was found for the specified visitorCode and variableKey
KameleoonException.FeatureFlagEnvironmentDisabledFeature flag is disabled for the current environment
KameleoonException.JSONParseCouldn't parse JSON value
KameleoonException.NumberParseCouldn't parse Number value

Visitor data​

This section provides the methods you use to manage visitor data.

getVisitorCode()​

getVisitorCode method collected from useVisitorCode hook obtains a visitor code from the browser cookie. If the visitor code doesn't exist yet, the function generates a random visitor code (or uses the defaultVisitorCode value if you provided one) and sets the new visitor code in a cookie.

import { useEffect, useCallback } from 'react';
import { useInitialize, useVisitorCode } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Pass default visitorCode, save and retrieve it
    const visitorCode = getVisitorCode('default_visitor_code');
  }, [initialize, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
defaultVisitorCode (optional)stringvisitor code to be used in case there is no visitor code in cookies
note

If you don't provide a defaultVisitorCode and there is no visitor code stored in a cookie, the visitor code will be randomly generated.

Returns​

string - result visitor code.

Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code length was exceeded
KameleoonException.VisitorCodeEmptyThe visitor code is empty

addData()​

addData function collected with useData hook adds targeting data to the storage so that other hooks could decide whether the current visitor is targeted or not.

note

The addData() function 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 via the flush method .This approach helps reduce the number of server calls made, as the data is typically grouped into a single server call triggered by the execution of flush.

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

note

userAgent data will not be stored in storage like other data, and it will be sent with every tracking request for bot filtration.

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.

note

Check the list of supported conditions to know what data types can be used for targeting

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useVisitorCode,
  useData,
  CustomData,
  Browser,
  BrowserType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Create Kameleoon Data Types
    const customData = new CustomData(0, 'my_data');
    const browserData = new Browser(BrowserType.Chrome);

    // -- Add one Data item to Storage
    addData(visitorCode, browserData);

    // -- Add Data to Storage using variadic style
    addData(visitorCode, browserData, customData);

    // -- Add Data to Storage in array
    addData(visitorCode, ...[browserData, customData]);
  }, [initialize, visitorCode, addData, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
kameleoonData (optional)KameleoonDataType[]number of instances of any type of KameleoonData, can be added solely in array or as sequential arguments
note

kameleoonData is variadic argument it can be passed as one or several arguments (see the example)

note

The index or ID of the custom data can be found in your Kameleoon account. It is important to note that this index starts at 0, which means that the first custom data you create for a given site will be assigned 0 as its ID, not 1.

Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.StorageWriteCouldn't update storage data
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
note

See the Data types reference for more details of how to manage different data types.

flush()​

Method flush collected with useData takes the Kameleoon data associated with the visitor and sends the data tracking request along with all of the data that's been added previously using the addData.

If you don't specify a visitorCode, the SDK flushes all of its stored data to the remote Kameleoon servers. If any previously failed tracking requests were stored locally during offline mode, the SDK attempts to send the stored requests before executing the latest request.

If you specify a visitorCode and set isUniqueIdentifier to true, the flush() method uses it as the unique visitor identifier, which is useful for Cross-device experimentation because the SDK links the flushed data with the visitor that is associated with the specified identifier.

note

The isUniqueIdentifier can also be useful in other edge-case scenarios, such as when you can't access the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useVisitorCode,
  useData,
  CustomData,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { addData, flush } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Create instance of CustomData
    const customData = new CustomData(0, 'my_data');
    addData(visitorCode, customData);

    // -- Flush added custom data for visitor
    flush(visitorCode);

    // -- Flush data for all the visitors
    flush();

    // -- Flush data with unique visitor identifier flag
    const internalUserId = 'my_user_id';
    flush(internalUserId, true);
  }, [initialize, visitorCode, addData, flush, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescriptionDefault
visitorCode (optional)stringunique visitor identification string, can't exceed 255 characters length, if not passed all the data will be flushed (sent to the remote Kameleoon servers)-
isUniqueIdentifier (optional)booleanan optional parameter for specifying if the visitorCode is a unique identifierfalse
Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call

getRemoteData()​

Asynchronous method getRemoteData, collected with the useData hook, returns a data stored for specified site code on a remote Kameleoon server.

For example, you can use this function to retrieve user preferences, historical data, or any other data relevant to your application's logic. By storing this data on our highly scalable servers using our [Data API], you can efficiently manage massive amounts of data and retrieve it for each of your visitors or users.

import { useEffect, useCallback } from 'react';
import { useData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { getRemoteData } = useData();

  const getData = useCallback(async (): Promise<void> => {
    // -- Get remote data
    const jsonData = await getRemoteData('my_data_key');

    const data = JSON.parse(jsonData);
  }, [getRemoteData]);

  useEffect(() => {
    getData();
  }, [getData]);
}
Parameters​
NameTypeDescription
key (required)stringunique key that the data you try to get is associated with
Returns​

JSONType - promise with data retrieved for specific key.

Throws​
TypeDescription
KameleoonException.RemoteDataCouldn't retrieve data from Kameleoon server

getRemoteVisitorData()​

Asynchronous method getRemoteVisitorData collected with useData hook retrieves Kameleoon Visits Data for the visitorCode from the Kameleoon Data API. The method adds the data to storage so that other methods can use it when making decisions about whether the current visitor is targeted or not.

Data obtained by getRemoteVisitorData plays important role when working with conditions that use asynchronously pre-loaded data, Make sure to use this data when working with these conditions.

note

By default, getRemoteVisitorData automatically attaches the latest custom data entry with scope=Visitor to the visitor without calling addData. You can use this data for Synchronizing custom data across devices.

note

The isUniqueIdentifier parameter can be useful in edge-case scenarios, such as when you can't access the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

import { useEffect, useCallback } from 'react';
import {
  useData,
  KameleoonDataType,
  VisitorDataFiltersType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { getRemoteVisitorData } = useData();

  const getData = useCallback(async (): Promise<void> => {
    // -- Get remote visitor data and add it to storage
    const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({
      visitorCode: 'my_visitor_code',
    });

    // -- Get remote visitor data without adding it to storage
    const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({
      visitorCode: 'my_visitor_code',
      shouldAddData: false,
    });

    // -- Get remote visitor data without adding it to storage
    //    and customizing filters for retrieving visits data
    const filters: VisitorDataFiltersType = {
      currentVisit: true,
      previousVisitAmount: 10,
      customData: true,
      geolocation: true,
      conversions: true,
    };

    const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({
      visitorCode: 'my_visitor_code',
      shouldAddData: false,
      filters,
    });
  }, [getRemoteVisitorData]);

  useEffect(() => {
    getData();
  }, [getData]);
}
Parameters​

An object with the type RemoteVisitorDataParamsType containing:

NameTypeDescriptionDefault Value
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length-
shouldAddData (optional)booleanboolean flag identifying whether the retrieved custom data should be set to the storage like addData method doestrue
filters (optional)VisitorDataFiltersTypefilters for specifying what data should be retrieved from visits, by default only customData is retrieved from the current and latest previous visit{ previousVisitAmount: 1, currentVisit: true customData: true }, other filters parameters are set to false
isUniqueIdentifier (optional)booleanoptional parameter that, when true, specifies that the visitorCode is a unique identifierfalse

Here is the list of available VisitorDataFiltersType filters:

NameTypeDescriptionDefault
previousVisitAmount (optional)numberNumber of previous visits to retrieve data from. Number between 1 and 251
currentVisit (optional)booleanIf true, current visit data will be retrievedtrue
customData (optional)booleanIf true, custom data will be retrieved.true
pageViews (optional)booleanIf true, page data will be retrieved.false
geolocation (optional)booleanIf true, geolocation data will be retrieved.false
device (optional)booleanIf true, device data will be retrieved.false
browser (optional)booleanIf true, browser data will be retrieved.false
operatingSystem (optional)booleanIf true, operating system 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
kcs (optional)booleanIf true, Kameleoon Conversion Score data will be retrieved.false
Returns​

KameleoonDataType[] - promise with list of Kameleoon Data retrieved

Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.RemoteDataCouldn't retrieve data from Kameleoon server
KameleoonException.VisitAmountVisit amount must be a number between 1 and 25
KameleoonException.InitializationMethod was executed before initialize was done for kameleoonClient

getVisitorWarehouseData()​

Asynchronous method getVisitorWarehouseAudience collected with useData hook retrieves all audience data associated with the visitor in your data warehouse using the specified visitorCode and warehouseKey. The warehouseKey is typically your internal user ID. The customDataIndex parameter corresponds to the Kameleoon custom data that Kameleoon uses to target your visitors. Refer to the warehouse targeting documentation for additional details.

import { useEffect, useCallback } from 'react';
import { useData, CustomData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { getVisitorWarehouseAudience } = useData();

  const getData = useCallback(async (): Promise<void> => {
    // -- Get visitor warehouse audience data using `warehouseKey`
    //    and add it to storage
    const customData: CustomData = await getVisitorWarehouseAudience({
      visitorCode: 'my_visitor',
      customDataIndex: 10,
      warehouseKey: 'my_key',
    });

    // -- Get visitor warehouse audience data using `visitorCode`
    //    and add it to storage
    const customData: CustomData = await getVisitorWarehouseAudience({
      visitorCode: 'my_visitor',
      customDataIndex: 10,
    });
  }, [getRemoteData]);

  useEffect(() => {
    getData();
  }, [getData]);
}
Parameters​

Parameters object consisting of:

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
customDataIndex (required)numbernumber representing the index of the custom data you want to use to target your Warehouse Audiences
warehouseKey (optional)stringunique key to identify the warehouse data (usually, your internal user ID)
Returns​

Promise<CustomData | null> - promise containing CustomData with the associated warehouse data or null if there was no data

Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.RemoteDataCouldn't retrieve data from Kameleoon server

setLegalConsent()​

Method setLegalConsent, collected with useVisitorCode hook, specifies whether the visitor has given legal consent to use personal data. Setting the legalConsent parameter to false limits the types of data that you can include in tracking requests. This helps you adhere to legal and regulatory requirements while responsibly managing visitor data. You can find more information on personal data in the consent management policy.

note

When handling legal consent, it's important to use getVisitorCode method. Additionally, getVisitorCode does not accept domain as an argument. Instead, pass it to the createClient function.

import { useEffect, useCallback } from 'react';
import { useInitialize, useVisitorCode } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode, setLegalConsent } = useVisitorCode();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    setLegalConsent(visitorCode, true);
  }, [initialize, getVisitorCode, setLegalConsent]);

  useEffect(() => {
    init();
  }, [init]);
}
Callback Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
consent (required)booleana 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
Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code length exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty

Goals and third-party analytics​

This section provides the methods you use to track when a visitor action achieve one of you goals (a conversion).

trackConversion()​

Method trackConversion collected with useData hook creates and adds conversion data to the visitor with specified parameters and executes flush.

note

This helper method is useful for simple conversion tracking. However, you can also create your own conversion data and flush (add) it manually. Using the data type allows for more flexible Conversion tracking, including use of the negativeparameter.

If you specify a visitorCode and set isUniqueIdentifier to true, the trackconversion() method uses it as the unique visitor identifier, which is useful for cross-device experimentation because the SDK links the flushed data with the visitor that is associated with the specified identifier.

note

The isUniqueIdentifier can also be useful in other edge-case scenarios, such as when you can't access the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

import { useEffect, useCallback } from 'react';
import { useInitialize, useVisitorCode, useData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { trackConversion } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Track conversion
    trackConversion({ visitorCode, revenue: 2000, goalId: 123 });

    // -- Track conversion with unique visitor identifier flag
    const internalUserId = 'my_user_id';
    trackConversion({
      visitorCode: internalUserId,
      revenue: 20000,
      goalId: 123,
      isUniqueIdentifier: true,
    });
  }, [initialize, trackConversion, visitorCode, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}

trackConversion() creates and adds conversion data to the visitor with the specified parameters and executes the flush method.

Parameters​

Parameters object consisting of:

NameTypeDescriptionDefault
visitorCode (required)stringUnique visitor identifier string. Can't exceed 255 characters length.-
goalId (required)numberGoal to be sent in tracking request-
revenue (optional)numberRevenue to be sent in tracking request-
isUniqueIdentifier (optional)booleanOptional parameter that specifies whether the visitorCode is a unique identifierfalse
Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.StorageWriteCouldn't update storage data

getEngineTrackingCode()​

Method getEngineTrackingCode() collected with useFeatureFlag hook obtains Kameleoon tracking code for the current visitor. Tracking code is built based the feature experiments that were triggered during the last 5 seconds

import { useEffect, useCallback } from 'react';
import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getEngineTrackingCode, getFeatureFlagVariationKey } =
    useFeatureFlag();

  const [engineCode, setEngineCode] = useState<string>('');

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Trigger feature experiment
    // -- E.g. result `variationKey` id is `200` and implicit experiment id is `100`
    getFeatureFlagVariationKey('visitor_code', 'my_feature_key');

    // -- Get tracking code and set it to state
    setEngineCode(getEngineTrackingCode('visitor_code'));

    // -- Result engine code will look like this
    // `
    // window.kameleoonQueue = window.kameleoonQueue || [];
    // window.kameleoonQueue.push(['Experiments.assignVariation', 100, 200, true]);
    // window.kameleoonQueue.push(['Experiments.trigger', 100, true]);
    // `
  }, [initialize, getFeatureFlagVariationKey, getEngineTrackingCode]);

  useEffect(() => {
    init();

    // -- Insert tracking code into the page
    if (engineCode) {
      const script = document.createElement('script');
      script.textContent = engineCode;

      document.body.appendChild(script);

      // -- Remove script from the page
      return () => {
        document.body.removeChild(script);
      };
    }
  }, [init]);
}
note

Result tracking code can be inserted directly into html <script> tag

For example:

<!DOCTYPE html>
<html lang="en">
  <body>
    <script>
      const engineTrackingCode = `
        window.kameleoonQueue = window.kameleoonQueue || [];
        window.kameleoonQueue.push(['Experiments.assignVariation', 100, 200, true]);
        window.kameleoonQueue.push(['Experiments.trigger', 100, true]);
      `;
      const script = document.createElement('script');

      script.textContent = engineTrackingCode;
      document.body.appendChild(script);
    </script>
  </body>
</html>
Callback Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
Callback Returns​

string containing engine tracking code

Throws​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty

Events​

This section provides the methods you use to handle events.

onConfigurationUpdate()​

danger

This method is deprecated and will be removed in the future. Use the onEvent method with EventType.ConfigurationUpdate instead.

Method onConfigurationUpdate collected with useInitialize hook fires a callback on client configuration update.

note

This hook only works for server sent events of real time update

import { useEffect, useCallback } from 'react';
import { useInitialize } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize, onConfigurationUpdate } = useInitialize();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Define logic to be executed on client configuration update
    onConfigurationUpdate(() => {
      // -- My Logic
    });
  }, [initialize, onConfigurationUpdate]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
callback (required)() => voidcallback function with no parameters that will be called upon configuration update
Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call

onEvent()​

Method onEvent, collected with the useInitialize hook, fires a callback when a specific event is triggered. The callback function has access to the data associated with the event. The SDK methods in this documentation note which event types they can trigger, if any.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  EventType,
  EvaluationEventDataType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize, onEvent } = useInitialize();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Define logic to be executed on SDK event
    onEvent(EventType.Evaluation, (eventData: EventDataType) => {
      // -- My Logic
    });
  }, [initialize, onEvent]);

  useEffect(() => {
    init();
  }, [init]);
}
note

You can only assign one callback to each EventType.

Events​

Events are defined in the EventType enum. Depending on the event type, the eventData parameter will have a different type.

TypeeventData typeDescription
EventType.EvaluationEvaluationEventDataTypeTriggered when the SDK evaluates any variation for a feature flag. It is triggered regardless of the result variation
EventType.ConfigurationUpdateConfigurationUpdateEventDataTypeTriggered when the SDK receives a configuration update from the server (when using real-time streaming)
Parameters​
NameTypeDescription
event (required)EventTypea variant of the event to associate the callback action with
callback (required)(eventData: EventDataType<EventType>) => voida callback function with the eventData parameter that will be called when a configuration update occurs
Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
Sending exposure events to external tools​

Kameleoon offers built-in integrations with various analytics and CDP solutions, such as Mixpanel, Google Analytics 4, Segment.... To ensure that you can track and analyze your server-side experiments, Kameleoon provides a method getEngineTrackingCode() that returns the JavasScript code to be inserted in your page to automatically send the exposure events to the analytics solution you are using. The SDK builds a tracking code for your active analytics solution based on the experiments that the visitor has triggered in the last 5 seconds. For more information about hybrid experimentation, please refer to this documentation.

note

To benefit from this feature, you will need to implement both the React SDK and our Kameleoon JavaScript tag. We recommend you implement the [Kameleoon asynchronous tag], which you can install before your closing <body> tag in your HTML page, as it will be only used for tracking purposes.

Data types​

Kameleoon Data types are helper classes used for storing data in storage in predefined forms. During the flush execution, the SDK collects all the data and sends it along with the tracking request.

Data available in the SDK is not available for targeting and reporting in the Kameleoon app until you add the data. For example, by using the addData() method. See use visit history to target users for more information.

note

If you are using hybrid mode, you can call getRemoteVisitorData() to automatically fill all data that Kameleoon has collected previously.

Browser​

Browser contains browser information.

note

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

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  Browser,
  BrowserType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add new browser data to client
    const browser = new Browser(BrowserType.Chrome, 86.1);
    addData('my_visitor_code', browser);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
browser (required)BrowserTypepredefined browser type (Chrome, InternetExplorer, Firefox, Safari, Opera, Other)
version (optional)numberversion of the browser, floating point number represents major and minor version of the browser

Conversion​

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  Conversion,
  ConversionParametersType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Defined conversion parameters
    const conversionParameters: ConversionParametersType = {
      goalId: 123,
      revenue: 10000,
      negative: true,
    };

    // -- Add new conversion data to client
    const conversion = new Conversion(conversionParameters);
    addData('my_visitor_code', conversion);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}

Conversion contains information about your conversion.

note

Each visitor can have multiple Conversions

note

goalId can be found on Kameleoon Platform

Parameters​

ConversionParametersType conversionParameters - an object with conversion parameters described below

NameTypeDescriptionDefault Value
goalId (required)numberan id of a goal to track-
revenue (optional)numberan optional parameter for revenue0
negative (optional)booleanan optional parameter identifying whether the conversion should be removedfalse

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

note

Generally, the React SDK will attempt to use a localStorage cookie for the conditions. If not possible, SDK can use Cookie data as an alternative.

note

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

import {
  KameleoonClient,
  CookieType,
  Cookie,
  useInitialize,
  useData,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add new cookie data to client
    const cookieData: CookieType[] = [
      { key: 'key_1', value: 'value_1' },
      { key: 'key_2', value: 'value_2' },
    ];
    const cookie = new Cookie(cookieData);
    addData('my_visitor_code', cookie);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
cookie (required)CookieType[]A list of CookieType objects consisting of cookie keys and values
Methods​

Cookie data has a static utility method fromString that you can use to create a cookie instantly by parsing a string that contains valid cookie data. The method accepts string as parameter and returns an initialized Cookie instance.

import { Cookie } from '@kameleoon/react-sdk';

const cookieString = 'key_1=value_1; key_2=value_2';
const cookie: Cookie = Cookie.fromString(cookieString);

// -- The result cookie will contain the following cookie array
// [
//    { key: 'key_1', value: 'value_1' },
//    { key: 'key_2', value: 'value_2' },
// ]

GeolocationData​

GeolocationData contains the visitor's geolocation details

note

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

import {
  KameleoonClient,
  GeolocationData,
  GeolocationInfoType,
  useData,
  useInitialize,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add geolocation data
    const geolocationInfo: GeolocationInfoType = {
      country: 'France',
      region: 'Île-de-France',
      city: 'Paris',
      postalCode: '75008',
      coordinates: [48.8738, 2.295],
    };
    const geolocationData = new GeolocationData(geolocationInfo);
    addData('my_visitor_code', geolocationData);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​

An object parameter with the type GeolocationInfoType containing the following fields:

NameTypeDescription
country (required)stringThe country of the visitor
region (optional)stringThe region of the visitor
city (optional)stringThe city of the visitor
postalCode (optional)stringThe postal code of the visitor
coordinates (optional)[number, number]Coordinates array tuple of two position values (longitude and latitude). Coordinate number represents decimal degrees

CustomData​

CustomData is usually used with a custom data targeting condition on the Kameleoon platform to determine whether the visitor is targeted or not.

To persist the custom data across future visits, the SDK sends CustomData with Visitor scope with the next tracking request. You can set the scope in the data configuration on the custom data dashboard.

note

Each visitor can only have one CustomData per unique index. Adding a CustomData with the same index as an existing one, overwrites the existing one.

note

The index or ID of the custom data can be found in your Kameleoon account. It is important to note that this index starts at 0, which means that the first custom data you create for a given site will be assigned 0 as its ID, not 1.

note

To prevent the SDK from flushing the data with the selected index to the Kameleoon servers, check the Only save this data in Local Storage on the user's device, not on a server option when creating a new custom data entry on the custom data dashboard.

It's a useful option if you only want to utilize your private custom data for targeting.

import { useEffect, useCallback } from 'react';
import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Defined conversion parameters
    const dataItemOne = 'abc';
    const dataItemTwo = JSON.stringify(100);
    const dataItemThree = JSON.stringify({ a: 200, b: 300 });

    const customDataIndex = 0;

    // -- Create custom data using single parameter
    const customData = new CustomData(customDataIndex, dataItemOne);

    // -- Create custom data using variadic number of parameters
    const customData = new CustomData(
      customDataIndex,
      dataItemOne,
      dataItemTwo,
    );

    // -- Create custom data using an array of values
    const dataList = [dataItemOne, dataItemTwo, dataItemThree];
    const customData = new CustomData(customDataIndex, ...dataList);

    // -- Add new custom data to client
    addData('my_visitor_code', customData);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
index (required)numberan index of custom data to be stored under in a state, an index of custom data can be specified in Advanced Tools section of Kameleoon Application
value (optional)string[]custom value to store under the specified id, value can be anything but has to be stringified to match the string type. Note value is variadic parameter and can be used as follows

Device​

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  Device,
  DeviceType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add new device data to client
    const device = new Device(DeviceType.Desktop);
    addData('my_visitor_code', device);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}

Device contains information about your device.

note

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

Parameters​
NameTypeDescription
deviceType (required)DeviceTypepossible variants for device type (PHONE, TABLET, DESKTOP)

OperatingSystem​

OperatingSystem contains the visitor's operating system information.

note

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

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  OperatingSystem,
  OperatingSystemType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add operating system data
    const operatingSystem = new OperatingSystem(OperatingSystemType.Windows);
    addData('my_visitor_code', operatingSystem);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
operatingSystem (required)OperatingSystemTypepossible variants for device type: WINDOWS_PHONE, WINDOWS, ANDROID, LINUX, MAC, IOS

PageView​

PageView contains information about your web page.

note

Each visitor can have one PageView per unique URL. Adding a PageView with the same URL as an existing one will notify SDK that the visitor revisited page

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  PageView,
  PageViewParametersType,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Define page view parameters
    const pageViewParameters: PageViewParametersType = {
      urlAddress: 'www.example.com',
      title: 'my example',
      referrers: [123, 456],
    };

    // -- Add new page view data to client
    const pageView = new PageView(pageViewParameters);
    addData('my_visitor_code', pageView);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​

PageViewParametersType pageViewParameters - an object with page view parameters described below

NameTypeDescription
urlAddress (required)stringurl address of the page to track
title (required)stringtitle of the web page
referrer (optional)number[]an optional parameter containing a list of referrers Indices, has no default value

UserAgent​

Store information on the user-agent of the visitor. Server-side experiments are more vulnerable to bot traffic than client-side experiments. To address this, Kameleoon uses the IAB/ABC International Spiders and Bots List to identify known bots and spiders. Kameleoon also uses the UserAgent field to filter out bots and other unwanted traffic that could otherwise skew your conversion metrics. For more details, see the help article on bot filtering.

If you use internal bots, we suggest that you pass the value curl/8.0 of the userAgent to exclude them from our analytics.

note

A visitor can only have one UserAgent. Adding a second UserAgent overwrites the first one.

import { useEffect, useCallback } from 'react';
import { useInitialize, useData, UserAgent } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add new user agent data to client
    const userAgent = new UserAgent('my_unique_value');
    addData('my_visitor_code', userAgent);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}

Parameters​

NameTypeDescription
value (required)stringvalue used for comparison
caution

Server-side experiments are more vulnerable to bot traffic than client-side experiments. To address this, Kameleoon uses the IAB/ABC International Spiders and Bots List to identify known bots and spiders. We recommend that you pass the user agent to be filtered by Kameleoon when running server-side experiments for each visitor browsing your website, to avoid counting bots in your analytics.

If you use internal bots, we suggest that you pass the value curl/8.0 of the userAgent to exclude them from our analytics.

ApplicationVersion​

ApplicationVersion contains the semantic version number of your mobile app built with React Native or Ionic.

note

A visitor can only have one ApplicationVersion. Adding a second ApplicationVersion overwrites the first one.

note

This data type is only available for React Native apps or Ionic mobile apps.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  ApplicationVersion,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Add new application version data to client
    const applicationVersion = new ApplicationVersion('1.2');
    addData('my_visitor_code', applicationVersion);
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Parameters​
NameTypeDescription
version (required)stringVersion of mobile application. This field follows only semantic versioning. Acceptable formats are major, major.minor, or major.minor.patch

Developer guide​

Follow this section to integrate the SDK into your application and learn more about using the SDK.

Getting started​

This section walks you through installing and configurating the SDK for the first time.

Installation​

The Kameleoon SDK Installation tool is the preferred way to install the SDK. This SDK Installer helps you to install the SDK of your choice, generate a basic code sample, and configure external dependencies if needed.

To start the SDK Installation tool, install and run it globally:

npm install --global @kameleoon/sdk-installer
kameleoon-sdk

Or run it directly with npx:

npx @kameleoon/sdk-installer

Create the Kameleoon Client​

To get started to create an entry point for React SDK by creating Kameleoon Client on the top level of your application. Create an instance of KameleoonClient using the createClient() function, imported from the kameleoon package.

import {
  createClient,
  Environment,
  SDKConfigurationType,
} from '@kameleoon/react-sdk';

// -- Optional configuration
const configuration: Partial<SDKConfigurationType> = {
  updateInterval: 60,
  environment: Environment.Production,
  domain: '.example.com',
};

const client = createClient({ siteCode: 'my_site_code', configuration });

Wrap the application in the Kameleoon Provider​

The second step is connecting the previously created Kameleoon Client to KameleoonProvider by passing the configured client to KameleoonProvider:

import {
  createClient,
  Environment,
  KameleoonProvider,
} from '@kameleoon/react-sdk';

const client = createClient({
  siteCode: 'my_site_code',
  configuration: {
    updateInterval: 60,
    environment: Environment.Production,
  },
});

function AppWrapper(): JSX.Element {
  return (
    <KameleoonProvider client={client}>
      <App />
    </KameleoonProvider>
  );
}
KameleoonProvider​

Use this provider on root level by wrapping your app to gain an access to KameleoonClient. This ensures your app does not flicker due to flag changes at startup time.

Props​
NameTypeDescription
children (required)ReactNodechild elements of the provider
client (required)KameleoonClientKameleoonClient instance created by createClient()

Await for the client initialization​

KameleoonClient initialization is done asynchronously in order to make sure that Kameleoon API call was successful for that hook useInitialize is used. You can use async/await, Promise.then() or any other method to handle asynchronous client initialization.

import { useEffect, useCallback } from 'react';
import { useInitialize } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();

  // -- Waiting for the client initialization using `async/await`

  const init = useCallback(async (): Promise<void> => {
    await initialize();
  }, [initialize]);

  useEffect(() => {
    init();
  }, [init]);
}

Getting access to feature flags and variations​

note

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

After the SDK has been initialized, you can obtain a feature flag configuration. Subsequently, all hooks will require you to specify the User ID or visitor code associated with the request.

note

If you are using Kameleoon in hybrid mode with mixed front-end and back-end environments, you can call the getVisitorCode method to obtain the Kameleoon visitorCode for the current visitor. Alternatively, if you provide your own User ID, you must ensure its uniqueness on your end.

Using Kameleoon Client methods​

Now that KameleoonClient is created, configured and added to a KameleoonProvider it is possible to communicate with your feature flag and experiments from the inside of React Components.

To associate various data points with the current user, you can use the addData method, which is collected with the useData hook. addData function requires the visitorCode as the first parameter and accepts several additional parameters. These additional parameters represent the various data types allowed in Kameleoon.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useData,
  useVisitorCode,
  useFeatureFlag,
  CustomData,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData, trackConversion } = useData();
  const { getVisitorCode } = useVisitorCode();
  const { isFeatureFlagActive } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Get visitor code
    const visitorCode = getVisitorCode();

    // -- Add user data
    const customDataIndex = 0;
    addData(visitorCode, new CustomData(customDataIndex, 'my_data'));

    // -- Check if the feature is active for visitor
    const isMyFeatureActive = isFeatureFlagActive(
      visitorCode,
      'my_feature_key',
    );

    // -- Track conversion
    trackConversion({ visitorCode, revenue: 20000, goalId: 123 });
  }, [
    initialize,
    visitorCode,
    isFeatureFlagActive,
    trackConversion,
    getVisitorCode,
  ]);

  useEffect(() => {
    init();
  }, [init]);
}

Feature flags can be very useful for implementing ON/OFF switches with optional but advanced user targeting rules. However, you can also use feature flags to run feature experiments with several variations of your feature flag. Check out our documentation on creating feature experiments for more information.

React Native considerations​

note

React Native on android platform doesn't support Real Time Update feature.

While React SDK works the same way in both React Native and React contexts, it's important to note that setup steps differ. Due to the lack of browser API in React Native, React SDK has to have different external dependency implementations to work correctly. For that, Kameleoon provides several dedicated npm packages that you can install and set up manually or install using Kameleoon SDK Installation Tool (recommended).

The packages include:

  • @kameleoon/react-native-storage - built using react-native-mmkv library
  • @kameleoon/react-native-event-source - built using react-native-event-source-ts library
  • @kameleoon/react-native-visitor-code-manager - built on top of react-native-mmkv library
  • optional @kameleoon/react-native-secure-prng - built using react-native-get-random-values library

If you don't want to use the listed packages, you can provide your own implementation following the external dependencies guide.

Example React SDK setup for React Native application:

import { createClient } from '@kameleoon/react-sdk';
import { KameleoonEventSource } from '@kameleoon/react-native-event-source';
import { KameleoonStorage } from '@kameleoon/react-native-storage';
import { KameleoonVisitorCodeManager } from '@kameleoon/react-native-visitor-code-manager';
import { KameleoonSecurePRNG } from '@kameleoon/react-native-secure-prng';

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    storage: new KameleoonStorage(),
    eventSource: new KameleoonEventSource(),
    visitorCodeManager: new KameleoonVisitorCodeManager(),
    // -- Optional --
    prng: new KameleoonSecurePRNG(),
  },
});

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.

Domain information​

You provide a domain as the domain in KameleoonClient [configuration], which is used for storing Kameleoon visitor code in cookies. This is important when working with the getVisitorCode and setLegalConsent methods. The domain you provide is stored in the cookie as the Domain= key.

Setting the domain​

The domain you provide indicates the URL address can use the cookie. For example, if your domain is www.example.com. the cookie is only available from a www.example.com URL. That means that pages with the app.example.com domain can't use the cookie.

To be more flexible around subdomains, you can prefix a domain with .. For example, the domain .example.com allows the cookie to function on both app.example.com and login.example.com.

note

You can't use regular expressions, special symbols, protocol, or port numbers in the domain. Additionally, a specific list of subdomains are not allowed to be used with the prefix ..

Here's a small domain cheat sheet:

DomainAllowed URLsDisallowed URLs
www.example.com✅www.example.com❌ app.example.com
✅ example.com❌ .com
.example.com = example.com✅ example.com❌ otherexample.com
✅ www.example.com
✅ app.example.com
✅ login.example.com
https://www.example.com⛔ bad domain⛔ bad domain
www.example.com:4408⛔ bad domain⛔ bad domain
.localhost.com = localhost⛔ bad domain⛔ bad domain

Developing on localhost​

localhost is always considered a bad domain, making it hard to test the domain when developing on localhost.

There are two ways to avoid this issue:

  • Don't specify the domain field in the SDK client while testing. This prevents localhost issues (the cookie will be set on any domain).
  • Create a local domain for localhost. For example:
    • Navigate to /etc/hosts on Linux or to c:\Windows\System32\Drivers\etc\hosts on Windows
    • Open hosts with file super user or administrator rights
    • Add a domain to the localhost port, for example: 127.0.0.1 app.com
    • Now you can run your app locally on app.com:{my_port} and specify .app.com as your domain

External dependencies​

SDK external dependencies use the dependency injection pattern to give you the ability to provide your own implementations for certain parts of an SDK.

note

In the React SDK, all external dependencies have default implementations, which use a native browser API so there's no need to provide them unless another API is required for specific use cases.

Here's the list of available external dependencies:

DependencyInterfaceRequired/OptionalAPI UsedDescription
storageIExternalStorageOptionalBrowser localStorageUsed for storing all the existing and collected SDK data
requesterIExternalRequesterOptionalBrowser fetchUsed for performing all the network requests
eventSourceIExternalEventSourceOptionalBrowser EventSourceUsed for receiving Server Sent Events for Real Time Update capabilities
visitorCodeManagerIExternalVisitorCodeManagerOptionalBrowser cookieUsed for storing and synchronizing visitor code
prngIExternalPRNGOptionalMath.random or Browser crypto.getRandomValuesUsed to generate unique IDs for tracking events

The following example implements external dependencies. To import an interface from an SDK, create a class that implements it and pass the instantiated class to the SDK.

Storage​

import { IExternalStorage } from '@kameleoon/react-sdk';

// --- External Storage implementation ---
// - JavaScript `Map` is used as an example storage
const storage = new Map();

class MyStorage<T> implements IExternalStorage<T> {
  public read(key: string): T | null {
    // - Read data using `key`
    const data = storage.get(key);

    // - Return `null` if there's no data
    if (!data) {
      return null;
    }

    // - Return obtained data
    return data;
  }

  public write(key: string, data: T): void {
    // - Write data using `key`
    storage.set(key, data);
  }
}

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    storage: new MyStorage(),
  },
});

EventSource​

import {
  IExternalEventSource,
  EventSourceOpenParametersType,
} from '@kameleoon/react-sdk';

// --- External EventSource implementation ---
// - Example uses native browser `EventSource`
class MyEventSource implements IExternalEventSource {
  private eventSource?: EventSource;

  public open({
    eventType,
    onEvent,
    url,
  }: EventSourceOpenParametersType): void {
    // - Initialize `EventSource`
    const eventSource = new EventSource(url);

    this.eventSource = eventSource;
    // - Add event listener with provided event type and event callback
    this.eventSource.addEventListener(eventType, onEvent);
  }

  public close(): void {
    // - Cleanup open event source
    if (this.eventSource) {
      this.eventSource.close();
    }
  }
}

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    eventSource: new MyEventSource(),
  },
});

VisitorCodeManager​

import {
  IExternalVisitorCodeManager,
  SetDataParametersType,
  KameleoonUtils,
} from '@kameleoon/react-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses browser `document.cookie` API
class MyVisitorCodeManager implements IExternalVisitorCodeManager {
  public getData(key: string): string | null {
    const cookieString = document.cookie;

    // - Return `null` if no cookie was found
    if (!cookieString) {
      return null;
    }

    // - Parse cookie finding it by provided `key`
    return KameleoonUtils.getCookieValue(cookieString, key);
  }

  public setData({
    visitorCode,
    domain,
    maxAge,
    key,
    path,
  }: SetDataParametersType): void {
    // - Set cookie with provided parameters
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    document.cookie = resultCookie;
  }
}

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

Requester​

import {
  RequestType,
  IExternalRequester,
  KameleoonResponseType,
  SendRequestParametersType,
} from '@kameleoon/react-sdk';

// --- External Requester Implementation
export class MyRequester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    // - Using native browser `fetch`
    return await fetch(url, parameters);
  }
}

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    requester: new MyRequester(),
  },
});

Pseudo Random Number Generator​

Pseudo Random Number Generator (PRNG) is a dependency that generates random floating point number between 0 and 1 (similar to Math.random).

Default Kameleoon implementation relies on Browser's crypto or Math.random function if crypto is not available. Those API are very secure and reliable, however in some edge cases (especially in some React Native engines) you might want to provide your own implementation or use a dedicated Kameleoon package for React Native - @kameleoon/react-native-secure-prng

import { IExternalPRNG } from '@kameleoon/react-sdk';

// --- External Pseudo Random Number Generator (PRNG) implementation ---
class MyPRNG implements IExternalPRNG {
  public getRandomNumber(): number {
    // Return a random floating point number between `0` and `1` like `Math.random()` does
    return Math.random();
  }
}

// --- Create KameleoonClient ---
const client = createClient({
  siteCode: 'my_site_code',
  externals: {
    prng: new MyPRNG(),
  },
});

Error Handling​

Almost every React SDK callback which is returned by hooks may throw an error at some point, these errors are not just caveats but rather deliberately predefined KameleoonErrors that extend native JavaScript Error class providing useful messages and special type field with a type KameleoonException.

KameleoonException is an enum containing all possible error variants.

To know exactly what variant of KameleoonException the callbacks may throw, you can check Throws section of the hooks description on this page or just hover over the callback in your IDE to see jsdocs description.

Overall handling the errors considered a good practice to make your application more stable and avoid technical issues.

import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useVisitorCode,
  useData,
  CustomData,
  KameleoonError,
  KameleoonException,
} from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getVisitorCode } = useVisitorCode();
  const { addData } = useData();

  const init = useCallback(async (): Promise<void> => {
    try {
      await initialize();

      // -- Get visitor code
      const visitorCode = getVisitorCode();

      const customData = new CustomData(0, 'my_data');
      addData(visitorCode, customData);
    } catch (error) {
      // -- Type guard for inferring error type as native JavaScript `catch`
      //    only infers `unknown`
      if (error instanceof KameleoonError) {
        switch (error.type) {
          case KameleoonException.VisitorCodeMaxLength:
            // -- Handle an error
            break;
          case KameleoonException.StorageWrite:
            // -- Handle an error
            break;
          case KameleoonException.Initialization:
            // -- Handle an error
            break;
          default:
            break;
        }
      }
    }
  }, [initialize, addData, visitorCode, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}

Cross-device experimentation​

To support visitors who access your app from multiple devices cross-device experimentation, Kameleoon allows you to synchronize your custom data across each of the visitor's devices and reconcile their visit history across each device.

Synchronizing custom data across devices​

If you want to synchronize your Custom Data across multiple devices, Kameleoon provides a custom data synchronization mechanism.

To use this feature, in the custom data dashboard, edit the custom data and set the Scope value to Visitor. The custom data will now be permanently associated with a specific visitor as long as getRemoteVisitorData is called before any other actions with the visitor-associated data.

After the custom data is set up, calling getRemoteVisitorData makes the latest data accessible on any device.

See the following example of data synchronization between two devices:

Device One
import { useEffect, useCallback } from 'react';
import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { addData, flush } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Custom Data with index `0` was set to `Visitor` scope
    //    on Kameleoon Platform
    const customDataIndex = 0;
    const customData = new CustomData(customDataIndex, 'my_data');

    addData('my_visitor', customData);
    flush();
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}
Device Two
import { useEffect, useCallback } from 'react';
import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

function MyComponent(): JSX.Element {
  const { initialize } = useInitialize();
  const { getRemoteVisitorData } = useData();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    // -- Before working with data, make `getRemoteVisitorData` call
    await getRemoteVisitorData({ visitorCode: 'my_visitor_code' });

    // -- The further SDK code will have an access to CustomData with `Visitor` scope
    //    defined on Device One.
    //    So "my_data" is now available for targeting and tracking for "my_visitor"
  }, [initialize, addData]);

  useEffect(() => {
    init();
  }, [init]);
}

Using custom data for session merging​

Cross-device experimentation allows you to combine a visitor's history across each of their devices (history reconciliation). One of the powerful features that history reconciliation provides is the ability to merge different visitors sessions into one. To reconcile visit history, you can use CustomData to provide a unique identifier for the visitor.

Follow the activating cross-device history reconciliation guide to set up your custom data on the Kameleoon platform

When your custom data is set up, you can use it in your code to merge a visitor's session. Sessions with the same identifier will always see the same experiment variation and will be displayed as a single visitor in the Visitor view of your experiment's result pages.

The configuration SDK ensures that associated sessions always see the same variation of the experiment.

Afterwards, you can use the SDK normally. The following methods might be helpful in the context of session merging:

  • Use getRemoteVisitorData with isUniqueIdentifier=true to retrieve data for all linked visitors
  • Use trackConversion or flush with isUniqueIdentifier=true to track some data for specific visitor that is associated with another visitor
tip

As the custom data you use as the identifier must be set to Visitor scope, you need to use cross-device custom data synchronization to retrieve the identifier with the getRemoteVisitorData method on each device.

Here's an example of how to use custom data for session merging. In this example, we have an application with a login page. Since we don't know the user ID at the moment of login, we use an anonymous visitor identifier generated by the getVisitorCode method. After the user logs in, we can associate the anonymous visitor with the user ID and use it as a unique identifier for the visitor.

Login Page
import { useEffect, useCallback } from 'react';
import {
  useInitialize,
  useFeatureFlag,
  useVisitorCode,
  CustomData,
} from '@kameleoon/react-sdk';

function LoginPage(): JSX.Element {
  const [visitorCode, setVisitorCode] = useState<string | null>(null);

  const { initialize } = useInitialize();
  const { getFeatureFlagVariationKey } = useFeatureFlag();
  const { getVisitorCode } = useVisitorCode();

  const init = useCallback(async (): Promise<void> => {
    await initialize();

    const anonymousVisitor = getVisitorCode();
    // -- Saving `visitorCode` in the state to later re-use it
    setVisitorCode(anonymousVisitor);

    // -- Getting some variation, assume it's variation `A`
    const variation = getFeatureFlagVariationKey(
      anonymousVisitor,
      'my_feature_key',
    );
  }, [initialize, getFeatureFlagVariationKey, getVisitorCode]);

  useEffect(() => {
    init();
  }, [init]);
}
Application Page
import { useEffect, useCallback } from 'react';
import {
  useData,
  useFeatureFlag,
  useVisitorCode,
  CustomData,
} from '@kameleoon/react-sdk';

type Props = {
  anonymousVisitor: string;
};

function ApplicationPage(props: Props): JSX.Element {
  const { addData, trackConversion, getRemoteVisitorData } = useData();
  const { getFeatureFlagVariationKey } = useFeatureFlag();

  const init = useCallback(async (): Promise<void> => {
    // -- At this point anonymous visitor has logged in
    //    and we have user ID to use as a visitor identifier
    // -- Associating both visitors with identifier Custom Data,
    //    where index `1` is the index of the Custom Data configured
    //    as a unique identifier on Kameleoon Platform
    const userIdentifierData = new CustomData(1, 'my_user_id');
    // -- Let's assume that anonymous visitor identifier
    //    was passed as a prop
    addData(props.anonymousVisitor, userIdentifierData);

    // -- Getting the variation for user ID will
    //    result in the same variation as for anonymous visitor
    //    variation will be `A`
    const variation = getFeatureFlagVariationKey(
      'my_user_id',
      'my_feature_key',
    );

    // -- `my_user_id` and `anonymousVisitor` are now linked
    //    They can be tracked as a single visitor
    trackConversion({
      visitorCode: 'my_user_id',
      goalId: 123,
      revenue: 100,
      // -- Letting SDK know that the visitor is unique identifier
      isUniqueIdentifier: true,
    });

    // -- Moreover linked visitors share previously
    //    collected remote data
    const data = await getRemoteVisitorData({
      visitorCode: 'my_user_id',
      // -- Letting SDK know that the visitor is unique identifier
      isUniqueIdentifier: true,
    });
  }, [
    getRemoteVisitorData,
    trackConversion,
    addData,
    getFeatureFlagVariationKey,
  ]);

  useEffect(() => {
    init();
  }, [init]);
}

Utilities​

SDK has a set of utility methods that can be used to simplify the development process. All the methods are represented as static members of KameleoonUtils class.

simulateSuccessRequest​

Method simulateSuccessRequest is used to simulate a successful request to the Kameleoon server. It can be useful for custom Requester implementations when developer needs to simulate a successful request, for example disabling tracking.

import {
  KameleoonUtils,
  IExternalRequester,
  SendRequestParametersType,
  RequestType,
  KameleoonResponseType,
} from '@kameleoon/react-sdk';

// - Example of `Requester` with disabled tracking
class Requester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
    requestType,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    if (requestType === RequestType.Tracking) {
      return KameleoonUtils.simulateSuccessRequest<RequestType.Tracking>(
        requestType,
        null,
      );
    }

    return await fetch(url, parameters);
  }
}
Parameters​
NameTypeDescription
requestType (required)RequestTypeA type of request
data (required)SimulateRequestDataType[RequestType]A type of request data, which is different depending on RequestType

Data type SimulateRequestDataType is defined as follows:

  • RequestType.Tracking - null
  • RequestType.ClientConfiguration - ClientConfigurationDataType
  • RequestType.RemoteData - JSONType
Returns​

Promise<KameleoonResponseType> - returns a promise with the response of the request

getCookieValue​

Method getCookieValue is used to parse a common cookie string (key_1=value_1; key_2=value_2; ...) and get the value of a specific cookie key. It's useful when working with a custom implementation of VisitorCodeManager.

import { KameleoonUtils } from '@kameleoon/react-sdk';

const cookies = 'key_1=value_1; key_2=value_2';
const key = 'key_1';

const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1`
Parameters​
NameTypeDescription
cookie (required)stringCookie string in a form key_1=value_1; key_2=value_2
key (required)stringString representation of a key to find a value by
Returns​

string | null - returns a string with a cookie value or null if the key was not found