> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React SDK

> Integrate the Kameleoon React SDK to run experiments and activate feature flags in React applications using hooks and components.

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](#developer-guide)

**Changelog**: Details on the latest version of the React SDK can be found in the [changelog](https://github.com/Kameleoon/client-react/blob/main/CHANGELOG.md).

**SDK methods**: For the full reference documentation of the React SDK, see the [reference](#reference) section.

**Requirements**: React SDK requires `React 16.8.0+`

## 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](#external-dependencies) if needed.

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

```bash theme={null}
npm install --global @kameleoon/sdk-installer
kameleoon-sdk
```

Or run it directly with `npx`:

```bash theme={null}
npx @kameleoon/sdk-installer
```

#### Create the Kameleoon Client

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.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import {
      createClient,
      Environment,
      SDKConfigurationType,
    } from '@kameleoon/react-sdk';

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

    const client = createClient({ siteCode: 'my_site_code', configuration });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { createClient, Environment } from '@kameleoon/react-sdk';

    // -- Optional configuration
    const configuration = {
      updateInterval: 60,
      environment: Environment.Production,
      cookieDomain: '.example.com',
    };

    const client = createClient({ siteCode: 'my_site_code', configuration });
    ```
  </Tab>
</Tabs>

#### 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`:

<Tabs defaultTabIndex={0}>
  <Tab title="TS">
    ```tsx theme={null}
    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>
      );
    }
    ```
  </Tab>

  <Tab title="JS">
    ```jsx theme={null}
    import {
      createClient,
      Environment,
      KameleoonProvider,
    } from '@kameleoon/react-sdk';

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

    function AppWrapper() {
      return (
        <KameleoonProvider client={client}>
          <App />
        </KameleoonProvider>
      );
    }
    ```
  </Tab>

  <Tab title="NextJS (TS)">
    <Warning>
      If you are using **Next.js** for server-side rendering (SSR), you **have to** use `KameleoonProviderSSR` or `KameleoonProvider` with `stubMode=true`.
      This prevents the SDK client from being initialized on the server and ensures that the React SDK runs exclusively on the client side.
    </Warning>

    ```tsx theme={null}
    import {
      createClient,
      Environment,
      KameleoonProviderSSR,
    } from '@kameleoon/react-sdk';

    function AppWrapper(): JSX.Element {
      return (
        <KameleoonProviderSSR sdkParameters={{
          siteCode: 'my_site_code',
          configuration: {
            updateInterval: 60,
            environment: Environment.Production,
          }
        }}>
          <App />
        </KameleoonProviderSSR>
      );
    }
    ```
  </Tab>

  <Tab title="NextJS (JS)">
    <Warning>
      If you are using **Next.js** for server-side rendering (SSR), you **have to** use `KameleoonProviderSSR` or `KameleoonProvider` with `stubMode=true`.
      This prevents the SDK client from being initialized on the server and ensures that the React SDK runs exclusively on the client side.
    </Warning>

    ```jsx theme={null}
    import {
      createClient,
      Environment,
      KameleoonProviderSSR,
    } from '@kameleoon/react-sdk';

    function AppWrapper() {
      return (
        <KameleoonProviderSSR sdkParameters={{
          siteCode: 'my_site_code',
          configuration: {
            updateInterval: 60,
            environment: Environment.Production,
          }
        }}>
          <App />
        </KameleoonProviderSSR>
      );
    }
    ```
  </Tab>

  <Tab title="NextJS with externals(TS)">
    <Warning>
      If you are using **Next.js** for server-side rendering (SSR), you **have to** use `KameleoonProviderSSR` or `KameleoonProvider` with `stubMode=true`.
      This prevents the SDK client from being initialized on the server and ensures that the React SDK runs exclusively on the client side.
    </Warning>

    ```tsx theme={null}
    import {
      createClient,
      Environment,
      KameleoonProvider,
    } from '@kameleoon/react-sdk';

    // Checks if the code is running on the server (Node.js) and not in the browser.
    // This can be replaced with any other mechanism you use to detect server-side execution.
    const isServer = typeof window === 'undefined';

    const client = createClient({
      siteCode: 'my_site_code',
      configuration: {
        updateInterval: 60,
        environment: Environment.Production,
      },
      externals: {
        // Add your external dependencies here, e.g. storage, eventSource, visitorCodeManager, etc.
      },
      stubMode: isServer,
    });

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

  <Tab title="NextJS with externals(JS)">
    <Warning>
      If you are using **Next.js** for server-side rendering (SSR), you **have to** use `KameleoonProviderSSR` or `KameleoonProvider` with `stubMode=true`.
      This prevents the SDK client from being initialized on the server and ensures that the React SDK runs exclusively on the client side.
    </Warning>

    ```jsx theme={null}
    import {
      createClient,
      Environment,
      KameleoonProvider,
    } from '@kameleoon/react-sdk';

    // Checks if the code is running on the server (Node.js) and not in the browser.
    // This can be replaced with any other mechanism you use to detect server-side execution.
    const isServer = typeof window === 'undefined';

    const client = createClient({
      siteCode: 'my_site_code',
      configuration: {
        updateInterval: 60,
        environment: Environment.Production,
      },
      externals: {
        // Add your external dependencies here, e.g. storage, eventSource, visitorCodeManager, etc.
      },
      stubMode: isServer,
    });

    function AppWrapper() {
      return (
        <KameleoonProvider client={client}>
          <App />
        </KameleoonProvider>
      );
    }
    ```
  </Tab>
</Tabs>

##### 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

| Name                                                   | Type              | Description                                            |
| ------------------------------------------------------ | ----------------- | ------------------------------------------------------ |
| children <Badge color="red" size="sm">required</Badge> | `ReactNode`       | child elements of the provider                         |
| client <Badge color="red" size="sm">required</Badge>   | `KameleoonClient` | `KameleoonClient` instance created by `createClient()` |

##### KameleoonProviderSSR

Use this provider on root level by wrapping your app to gain an access to `KameleoonClient`.
`KameleoonProviderSSR` differs from `KameleoonProvider` in that it creates a `KameleoonClient` instance inside the context on the first client request. This prevents the risk of creating the client on the server side. It is recommended for use in SSR-based systems, such as Next.js with SSR.

###### Props

| Name                                                        | Type            | Description                                                            |
| ----------------------------------------------------------- | --------------- | ---------------------------------------------------------------------- |
| children <Badge color="red" size="sm">required</Badge>      | `ReactNode`     | child elements of the provider                                         |
| sdkParameters <Badge color="red" size="sm">required</Badge> | `SDKParameters` | `SDKParameters` settings for creating an instance of `KameleoonClient` |

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();

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

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

#### Activating a feature flag

##### Assigning a unique ID to a user

To assign a unique ID to a user, you can use the [`getVisitorCode()`](#getvisitorcode) method. If a **visitor code** doesn’t exist (from the request headers cookie), the method generates a random unique ID or uses a `defaultVisitorCode` that you would have generated. The ID is then set in a response headers cookie.

If you are using Kameleoon in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation), calling the `getVisitorCode()` method ensures that the unique ID (**visitor code**) is shared between the application file `engine.js` (previously named, `kameleoon.js`) and the SDK.

##### Retrieving a flag configuration

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

To determine the status or variation of a feature flag for a specific user, you should use the [`getVariation()`](#getvariation) or [`isFeatureFlagActive()`](#isfeatureflagactive) method to retrieve the configuration based on the `featureKey`.

The `getVariation()` method handles both simple feature flags with ON/OFF states and more complex flags with multiple variations. The method retrieves the appropriate variation for the user by checking the feature rules, assigning the variation, and returning it based on the `featureKey` and `visitorCode`.

The `isFeatureFlagActive()` 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.

If your feature flag has associated variables (such as specific behaviors tied to each variation) `getVariation()` also enables you to access the [`Variation`](#variation) object, which provides details about the assigned variation and its associated experiment. This method checks whether the user is targeted, finds the visitor’s assigned variation, and saves it to storage. When `track=true`, the SDK will send the exposure event to the specified experiment on the next tracking request, which is automatically triggered based on the SDK’s [`tracking_interval_millisecond`](#configuration-parameters). By default, this interval is set to 1000 milliseconds (1 second).

The `getVariation()` method allows you to control whether tracking is done. If `track=false`, no exposure events will be sent by the SDK. This is useful if you prefer not to track data through the SDK and instead rely on client-side tracking managed by the Kameleoon engine, for example. Additionally, setting `track=false` is helpful when using the `getVariations()` method, where you might only need the variations for all flags without triggering any tracking events. If you want to know more about how tracking works, view [this article](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)

##### 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()`](#adddata) method to add these data points to the user's profile.

To retrieve data points collected on other devices or to access past user data (collected client-side when using Kameleoon in Hybrid mode), use the [`getRemoteVisitorData()`](#getremotevisitordata) method. This method asynchronously fetches data from the servers. It is important to 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.

To learn more about available targeting conditions, see the [detailed article on the subject](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).

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. Kameleoon Hybrid mode automatically collects a variety of data points on the client-side, making it easy to break down your results based on these pre-collected data points. See the complete list [here](/user-manual/experiment-analytics/analyze-results/results-page-settings#breakdown-audience).

If you need to track additional data points beyond what's automatically collected, you can use Kameleoon's [Custom Data feature](#customdata). Custom Data allows you to capture and analyze specific information relevant to your experiments. Don't forget to call the [`flush()`](#flush) method to send the collected data to Kameleoon servers for analysis.

<Note>
  To ensure your results are accurate, it's recommended to filter out bots by using the [`UserAgent`](#useragent) data type.
</Note>

##### Tracking goal conversions

When a user completes a desired action (such as making a purchase), it is recorded as a conversion. To track conversions, use the [`trackConversion()`](#trackconversion) method and provide the required `visitorCode` and `goalId` parameters.

The conversion tracking request will be sent along with the next scheduled tracking request, which the SDK sends at regular intervals (defined by [`tracking_interval_millisecond`](#configuration-parameters)). If you prefer to send the request immediately, use the [`flush()`](#flush) method with the parameter `instant=true`.

##### Sending events to analytics solutions

To track conversions and send exposure events to your customer analytics solution, you must first implement Kameleoon in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/). Then, use the [`getEngineTrackingCode()`](#getenginetrackingcode) method.

The `getEngineTrackingCode()` method retrieves the unique tracking code required to send exposure events to your analytics solution. Using this method allows you to record events and send them to your desired analytics platform.

### React Native considerations

<Note>
  React Native on `android` platform doesn't support `Real Time Update` feature.
</Note>

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](#external-dependencies) 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](#installation) (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
* `@kameleoon/react-native-platform-analyzer` - built using `react-native` 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](#external-dependencies).

Example React SDK setup for React Native application:

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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';
    import { KameleoonPlatformAnalyzer } from '@kameleoon/react-native-platform-analyzer';

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

  <Tab title="JavaScript">
    ```js theme={null}
    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';
    import { KameleoonPlatformAnalyzer } from '@kameleoon/react-native-platform-analyzer';

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

### Using a custom bucketing key

By default, Kameleoon uses a unique, anonymous visitor ID (`visitorCode`) to assign users to feature flag variations. This ID is typically generated and stored on the user's device (in a browser cookie for client-side and server-side SDKs—in persistent storage for mobile SDKs). However, in certain scenarios you may need to ensure all users of the same organization see the same variant of a feature flag.

The **Custom Bucketing Key** option allows you to override this default behavior by providing your own custom identifier for bucketing. This override ensures that Kameleoon's assignment logic uses your specified key instead of the default `visitorCode`.

#### Use cases

Using a custom bucketing key is essential for maintaining consistency and accuracy in your feature flag assignments, particularly in these situations:

* **Account-level or organizational experiments:** For B2B products or scenarios where you want to assign all users from the same organization to the same variation, you can use an identifier like an `accountId`. Custom bucketing keys are crucial for A/B testing features that impact an entire team or company.

By implementing a custom bucketing key, you ensure greater consistency and accuracy in your experiments, leading to more reliable results and a better user experience.

#### Technical details

When you configure a custom bucketing key for a feature flag, you provide Kameleoon with a specific identifier from your application's data:

```jsx theme={null}
addData(visitorCode, new CustomData(index, 'newVisitorCode'));
```

<Tip>
  [More information in addData()](#adddata)
</Tip>

* **Providing the custom key:** You provide your custom identifier to the Kameleoon SDK using the [`addData()`](#adddata) method. In this method, you will pass your chosen custom bucketing key as a [`CustomData`](#customdata) object. Here, `newVisitorCode` refers to the identifier you wish to use for your bucketing (for example, the new `userId` or `accountId`).

<Warning>
  For the custom bucketing key to function correctly, it must also be defined and configured for the feature flag during the flag creation or editing process. Without this corresponding configuration, the SDK's bucketing will not apply your custom key. For detailed instructions on how to set this up in Kameleoon, refer to this [article](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
</Warning>

* **Bucketing logic:** Once a custom bucketing key is provided through the `addData()` method, all hash calculations for assigning users to variations will use this `newVisitorCode` (your custom key) instead of the default `visitorCode`. Using the `newVisitorCode` means that the bucketing decision is tied to your custom identifier, ensuring consistent assignments across various contexts where that identifier is present.
* **Data tracking and analytics:** It's crucial to note that while the `newVisitorCode` (your custom key) is used for bucketing decisions, **all subsequent data (tracking events and conversions, for example) is sent and associated with the *original* `visitorCode`.** This separation ensures that your analytics accurately reflect individual user journeys and interactions within your experiment's broader context, even when bucketing is performed at a higher level (like an account) or across multiple devices/sessions. Your original visitor data remains intact for comprehensive reporting.

#### Technical requirements

To effectively use a custom bucketing key:

* The key must be a `string`.
* It must be unique for the entity you intend to bucket (for example, if using a `userId`, each user's ID should be unique).
* The key must be available to the SDK at the exact moment the feature flag decision is evaluated for that user or request.

### 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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).

You can also use your own [external data to target users](/developer-docs/feature-experimentation/targeting-and-segmentation\use-external-data-to-target-users).

### Logging

The SDK generates logs to reflect various internal processes and issues.

#### Log levels

The SDK supports configuring limiting logging by a log level.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/react-sdk';

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

    // The `NONE` log level does not allow logging.
    client.setLogLevel(LogLevel.NONE);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.NONE);


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

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

    ```ts theme={null}
    import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/react-sdk/full’;

    // The `INFO` log level allows logging general information on the SDK’s internal processes.
    // It extends the `WARNING` log level.
    client.setLogLevel(LogLevel.INFO);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.INFO);

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

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/react-sdk’;

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

    // The `NONE` log level allows no logging.
    client.setLogLevel(LogLevel.NONE);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.NONE);


    // The `ERROR` log level only allows logging issues that may affect the SDK’s main behaviour.
    client.setLogLevel(LogLevel.ERROR);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.ERROR);

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

    ```js theme={null}
    import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/react-sdk/full’;

    // The `INFO` log level allows logging general information on the SDK’s internal processes.
    // It extends the `WARNING` log level.
    client.setLogLevel(LogLevel.INFO);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.INFO);

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

#### Custom handling of logs

The SDK writes its logs to the console output by default. This behaviour can be overridden.

<Note>
  Logging limiting by a log level is performed apart from the log handling logic.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/react-sdk';

    export class CustomLogger implements IExternalLogger {
      // `log` method accepts logs from the SDK
      public log(level: LogLevel, message: string): void {
        // Custom log handling logic here. For example:
        switch (level) {
          case LogLevel.DEBUG:
            console.debug(message);
            break;
          case LogLevel.INFO:
            console.info(message);
            break;
          case LogLevel.WARNING:
            console.warn(message);
            break;
          case LogLevel.ERROR:
            console.error(message);
            break;
        }
      }
    }

    const client = createClient({
      siteCode: 'my_site_code',
      externals: {
        logger: new CustomLogger(),
      },
    });

    // Log level filtering is applied separately from log handling logic.
    // The custom logger will only accept logs that meet or exceed the specified log level.
    // Ensure the log level is set correctly.
    client.setLogLevel(LogLevel.DEBUG);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.DEBUG);
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/react-sdk';

    export class CustomLogger {
      // `log` method accepts logs from the SDK
      log(level, message) {
        // Custom log handling logic here. For example:
        switch (level) {
          case 'DEBUG':
            console.debug(message);
            break;
          case 'INFO':
            console.info(message);
            break;
          case 'WARNING':
            console.warn(message);
            break;
          case 'ERROR':
            console.error(message);
            break;
        }
      }
    }

    const client = createClient({
      siteCode: 'my_site_code',
      externals: {
        logger: new CustomLogger(),
      },
    });

    // Log level filtering is applied separately from log handling logic.
    // The custom logger will only accept logs that meet or exceed the specified log level.
    // Ensure the log level is set correctly.
    client.setLogLevel(LogLevel.DEBUG);
    // Or use KameleoonLogger
    KameleoonLogger.setLogLevel(LogLevel.DEBUG);
    ```
  </Tab>
</Tabs>

### 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`](#getvisitorcode) and [`setLegalConsent`](#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](https://publicsuffix.org/list/public_suffix_list.dat) are not allowed to be used with the prefix `.`.
</Note>

Here's a small domain cheat sheet:

| Domain                         | Allowed URLs          | Disallowed 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.
</Note>

Here's the list of available external dependencies:

| Dependency                                                           | Interface                     | API Used                                          | Description                                                                                                                                                                              |
| -------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `storage` <Badge color="green" size="sm">optional</Badge>            | `IExternalStorage`            | Browser `localStorage`                            | Used for storing all the existing and collected SDK data                                                                                                                                 |
| `requester` <Badge color="green" size="sm">optional</Badge>          | `IExternalRequester`          | Browser `fetch`                                   | Used for performing all the network requests                                                                                                                                             |
| `eventSource` <Badge color="green" size="sm">optional</Badge>        | `IExternalEventSource`        | Browser `EventSource`                             | Used for receiving Server Sent Events for [Real Time Update](/developer-docs/feature-experimentation/technical-reference/technical-considerations#streaming-premium-option) capabilities |
| `visitorCodeManager` <Badge color="green" size="sm">optional</Badge> | `IExternalVisitorCodeManager` | Browser cookie                                    | Used for storing and synchronizing visitor code                                                                                                                                          |
| `prng` <Badge color="green" size="sm">optional</Badge>               | `IExternalPRNG`               | `Math.random` or Browser `crypto.getRandomValues` | Used to generate unique IDs for tracking events                                                                                                                                          |
| `logger` <Badge color="green" size="sm">optional</Badge>             | `ILogger`                     | Custom implementation                             | Used for custom handling of logs from the SDK. Allows to define how logs are processed and where they are output.                                                                        |
| `platformAnalyzer` <Badge color="green" size="sm">optional</Badge>   | `IPlatformAnalyzer`           | React Native API                                  | Automatically detects the platform and attaches this information to the visitor data. Designed specifically for React Native.                                                            |

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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(),
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonClient } from '@kameleoon/react-sdk';

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

    class MyStorage {
      read(key) {
        // - 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;
      }

      write(key, data) {
        // - Write data using `key`
        storage.set(key, data);
      }
    }

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

#### EventSource

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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();
        }
      }

      public onError(callback: (error: Event) => void): void {
        // - Set error callback
        if (this.eventSource) {
          this.eventSource.onerror = callback;
        }
      }
    }

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

  <Tab title="JavaScript">
    ```js theme={null}
    // --- External EventSource implementation ---
    // - Example uses native browser `EventSource`
    class MyEventSource {
      eventSource;

      open({ eventType, onEvent, url }) {
        // - 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);
      }

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

      public onError(callback) {
        // - Set error callback
        if (this.eventSource) {
          this.eventSource.onerror = callback;
        }
      }
    }

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

#### VisitorCodeManager

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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 using 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(),
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonUtils } from '@kameleoon/react-sdk';

    // --- External Visitor Code Manager implementation ---
    // - Example uses browser `document.cookie` API
    class MyVisitorCodeManager {
      getData(key) {
        const cookieString = document.cookie;

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

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

      setData({ visitorCode, domain, maxAge, key, path }) {
        // - 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(),
      },
    });
    ```
  </Tab>
</Tabs>

#### Requester

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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(),
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonClient } from '@kameleoon/react-sdk';

    // --- External Requester Implementation
    export class MyRequester {
      async sendRequest({ url, parameters }) {
        // - Using native browser `fetch`
        return await fetch(url, parameters);
      }
    }

    // --- Create KameleoonClient ---
    const client = new KameleoonClient({
      siteCode: 'my_site_code',
      externals: {
        requester: new MyRequester(),
      },
    });
    ```
  </Tab>
</Tabs>

<Tip>
  [Return mocked result](#simulatesuccessrequest)
</Tip>

#### 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`

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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(),
      },
    });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // --- External Pseudo Random Number Generator (PRNG) implementation ---
    class MyPRNG {
      getRandomNumber() {
        // 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(),
      },
    });
    ```
  </Tab>
</Tabs>

### 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 `KameleoonError`s
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 types.

To know exactly what type 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.

***

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useVisitorCode,
      useData,
      CustomData,
      KameleoonException,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { addData } = useData();

      const init = useCallback(async () => {
        try {
          await initialize();

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

          const customData = new CustomData(0, 'my_data');
          addData(visitorCode, customData);
        } catch (error) {
          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]);
    }
    ```
  </Tab>
</Tabs>

### Cross-device experimentation

To support visitors who access an app from multiple devices, Kameleoon allows the synchronization of previously collected visitor data across each of the visitor's devices and reconciliation of their visit history across devices through cross-device experimentation. Case studies and detailed information on how Kameleoon handles data across devices are available in the [article on cross-device experimentation](/developer-docs/cross-device-experimentation).

#### Synchronizing custom data across devices

Although custom mapping synchronization is used to align visitor data across devices, it is not always necessary. Below are two scenarios where custom mapping sync is not required:

**Same user ID across devices**
If the same user ID is used consistently across all devices, synchronization is handled automatically without a custom mapping sync. It is enough to call the `getRemoteVisitorData()` method when you want to sync the data collected between multiple devices.

**Multi-server instances with consistent IDs**
In complex setups involving multiple servers (for example, distributed server instances), where the same user ID is available across servers, synchronization between servers (with `getRemoteVisitorData()`) is sufficient without additional custom mapping sync.

Customers who need additional data can refer to the [`getRemoteVisitorData()`](#getremotevisitordata) method description for further guidance. In the below code, it is assumed that the same unique identifier (in this case, the `visitorCode`, which can also be referred to as `userId`) is used consistently between the two devices for accurate data retrieval.

<Note>
  If you want to sync collected data in real time, you need to choose the scope **Visitor** for your custom data.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx title="Device One" theme={null}
    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
        //    in Kameleoon.
        const customDataIndex = 0;
        const customData = new CustomData(customDataIndex, 'my_data');

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

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

    ```tsx title="Device Two" theme={null}
    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, call `getRemoteVisitorData`.
        await getRemoteVisitorData({ visitorCode: 'my_visitor_code' });

        // -- New SDK code will have access to CustomData with `Visitor` scope
        //    defined on Device One.
        //    So, "my_data" is now available to target and track "my_visitor".
      }, [initialize, addData]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx title="Device One" theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData, flush } = useData();

      const init = useCallback(async () => {
        await initialize();

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

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

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

    ```jsx title="Device Two" theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getRemoteVisitorData } = useData();

      const init = useCallback(async () => {
        await initialize();

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

        // -- New SDK code will have access to CustomData with `Visitor` scope
        //    defined on Device One.
        //    So, "my_data" is now available to target and track "my_visitor".
      }, [initialize, addData]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

#### Using custom data for session merging

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    [Cross-device experimentation](/developer-docs/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`](#customdata) to provide a unique identifier for the visitor.

    Follow the [activating cross-device history reconciliation](/developer-docs/cross-device-experimentation#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`](#getremotevisitordata) with `isUniqueIdentifier=true` to retrieve data for all linked visitors
    * Use [`trackConversion`](#trackconversion) or [`flush`](#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](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices) to retrieve the identifier with the [`getRemoteVisitorData`](#getremotevisitordata) method on each device.
    </Tip>

    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`](#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.

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx title="Login Page" theme={null}
        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 { getVariation } = useFeatureFlag();
          const { getVisitorCode } = useVisitorCode();

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

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

            // -- Getting a variation, assume it's variation `A`
            const variation = getVariation({
              visitorCode: anonymousVisitor,
              featureKey: 'my_feature_key',
            });
          }, [initialize, getVariation, getVisitorCode]);

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

        ```tsx title="Application Page" theme={null}
        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 { getVariation } = useFeatureFlag();

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

            // -- Retrieving the variation for the user ID ensures
            //    consistency with the anonymous visitor's variation.
            //    Both the anonymous visitor and the user ID will be
            //    assigned variation `A`.
            const variation = getVariation({
              visitorCode: 'my_user_id',
              featureKey: '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,
              // -- Informing the SDK that the visitor is a unique identifier
              isUniqueIdentifier: true,
            });

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx title="Login Page" theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useInitialize,
          useFeatureFlag,
          useVisitorCode,
          CustomData,
        } from '@kameleoon/react-sdk';

        function LoginPage() {
          const [visitorCode, setVisitorCode] = useState(null);

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

          const init = useCallback(async () => {
            await initialize();

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

            // -- Getting a variation, assume it's variation `A`
            const variation = getVariation({
              visitorCode: anonymousVisitor,
              featureKey: 'my_feature_key',
            });
          }, [initialize, getVariation, getVisitorCode]);

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

        ```jsx title="Application Page" theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useData,
          useFeatureFlag,
          useVisitorCode,
          CustomData,
        } from '@kameleoon/react-sdk';

        function ApplicationPage(props) {
          const { addData, trackConversion, getRemoteVisitorData } = useData();
          const { getVariation } = useFeatureFlag();

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

            // -- Retrieving the variation for the user ID ensures
            //    consistency with the anonymous visitor's variation.
            //    Both the anonymous visitor and the user ID will be
            //    assigned variation `A`.
            const variation = getVariation({
              visitorCode: 'my_user_id',
              featureKey: '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,
              // -- Informing the SDK that the visitor is a unique identifier.
              isUniqueIdentifier: true,
            });

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="SDK Version 10">
    [Cross-device experimentation](/developer-docs/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`](#customdata) to provide a unique identifier for the visitor.

    Follow the [activating cross-device history reconciliation](/developer-docs/cross-device-experimentation#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 SDK configuration ensures that associated sessions always see the same variation of the experiment.

    Before using other methods make sure to let SDK know that the visitor is a unique identifier by adding [`UniqueIdentifier`](#uniqueidentifier) data to a 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](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices) to retrieve the identifier with the [`getRemoteVisitorData`](#getremotevisitordata) method on each device.
    </Tip>

    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`](#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.

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx title="Login Page" theme={null}
        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 { getVariation } = useFeatureFlag();
          const { getVisitorCode } = useVisitorCode();

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

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

            // -- Getting a variation, assume it's variation `A`
            const variation = getVariation({
              visitorCode: anonymousVisitor,
              featureKey: 'my_feature_key',
            });
          }, [initialize, getVariation, getVisitorCode]);

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

        ```tsx title="Application Page" theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useData,
          useFeatureFlag,
          useVisitorCode,
          CustomData,
          UniqueIdentifier,
        } from '@kameleoon/react-sdk';

        type Props = {
          anonymousVisitor: string;
        };

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

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

            // -- Informing the SDK that the visitor is unique identifier.
            addData('my_user_id', new UniqueIdentifier(true));

            // -- Retrieving the variation for the user ID ensures
            //    consistency with the anonymous visitor's variation.
            //    Both the anonymous visitor and the user ID will be
            //    assigned variation `A`.
            const variation = getVariation({
              visitorCode: 'my_user_id',
              featureKey: '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,
            });

            // -- Additionally, linked visitors share previously
            //    collected remote data.
            const data = await getRemoteVisitorData({
              visitorCode: 'my_user_id',
            });
          }, [
            getRemoteVisitorData,
            trackConversion,
            addData,
            getVariation,
          ]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx title="Login Page" theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useInitialize,
          useFeatureFlag,
          useVisitorCode,
          CustomData,
        } from '@kameleoon/react-sdk';

        function LoginPage() {
          const [visitorCode, setVisitorCode] = useState(null);

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

          const init = useCallback(async () => {
            await initialize();

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

            // -- Getting a variation, assume it's variation `A`
            const variation = getVariation({
              visitorCode: anonymousVisitor,
              featureKey: 'my_feature_key',
            });
          }, [initialize, getVariation, getVisitorCode]);

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

        ```jsx title="Application Page" theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useData,
          useFeatureFlag,
          useVisitorCode,
          CustomData,
          UniqueIdentifier,
        } from '@kameleoon/react-sdk';

        function ApplicationPage(props) {
          const { addData, trackConversion, getRemoteVisitorData, flush } = useData();
          const { getVariation } = useFeatureFlag();

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

            // -- Informing the SDK that the visitor is a unique identifier.
            addData('my_user_id', new UniqueIdentifier(true));

            // -- Retrieving the variation for the user ID ensures
            //    consistency with the anonymous visitor's variation.
            //    Both the anonymous visitor and the user ID will be
            //    assigned variation `A`.
            const variation = client.getVariation({
              visitorCode: 'my_user_id',
              featureKey: '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,
            });

            // -- Additionally, linked visitors share previously
            //    collected remote data.
            const data = await getRemoteVisitorData({
              visitorCode: 'my_user_id',
            });
          }, [
            getRemoteVisitorData,
            trackConversion,
            addData,
            getVariation,
          ]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### 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](#requester) implementations when developer needs to simulate a successful request, for example disabling tracking.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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);
      }
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { KameleoonUtils } from '@kameleoon/react-sdk';

    // - Example of `Requester` with disabled tracking
    class Requester {
      async sendRequest({ url, parameters, requestType }) {
        if (requestType === RequestType.Tracking) {
          return KameleoonUtils.simulateSuccessRequest(requestType, null);
        }

        return await fetch(url, parameters);
      }
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                      | Type                                   | Description                                                           |
| --------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| requestType <Badge color="red" size="sm">required</Badge> | `RequestType`                          | A type of request                                                     |
| data <Badge color="red" size="sm">required</Badge>        | `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`

##### Return value

| Type                             | Description                                        |
| -------------------------------- | -------------------------------------------------- |
| `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`](#visitorcodemanager).

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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`
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    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`
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                 | Type     | Description                                            |
| ---------------------------------------------------- | -------- | ------------------------------------------------------ |
| cookie <Badge color="red" size="sm">required</Badge> | `string` | Cookie string in a form `key_1=value_1; key_2=value_2` |
| key <Badge color="red" size="sm">required</Badge>    | `string` | String representation of a key to find a value by      |

##### Return value

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

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

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    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.

      * 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:

      * [flush](#flush)
      * [trackConversion](#trackconversion)
      * [getFeatureFlagVariationKey](#getfeatureflagvariationkey)
      * [getFeatureVariable](#getfeatureflagvariable)
      * [sFeatureFlagActive](#isfeatureflagactive)
    </Note>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useInitialize } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { initialize } = useInitialize();

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    | Name                                                     | Type                     | Description                                                                                                                                          | Default Value |
    | -------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
    | useCache <Badge color="green" size="sm">optional</Badge> | `boolean` or `undefined` | parameter for activating SDK offline mode, if `true` is passed failed polls will not return error and will use cached data if such data is available | `false`       |

    ##### Return value

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

    ##### Exceptions thrown

    | Type                                       | Description                                               |
    | ------------------------------------------ | --------------------------------------------------------- |
    | `KameleoonException.StorageWrite`          | Couldn't update storage data                              |
    | `KameleoonException.ClientConfiguration`   | Couldn't retrieve client configuration from Kameleoon API |
    | `KameleoonException.MaximumRetriesReached` | Maximum retries reached, request failed                   |
  </Tab>

  <Tab title="SDK Version 10">
    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.

      * SDK supports an *offline mode*.

      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:

      * [flush](#flush)
      * [trackConversion](#trackconversion)
      * [getFeatureFlagVariationKey](#getfeatureflagvariationkey)
      * [getFeatureVariable](#getfeatureflagvariable)
      * [sFeatureFlagActive](#isfeatureflagactive)
    </Note>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useInitialize } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { initialize } = useInitialize();

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Return value

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

    ##### Exceptions thrown

    | Type                                       | Description                                               |
    | ------------------------------------------ | --------------------------------------------------------- |
    | `KameleoonException.StorageWrite`          | Couldn't update storage data                              |
    | `KameleoonException.ClientConfiguration`   | Couldn't retrieve client configuration from Kameleoon API |
    | `KameleoonException.MaximumRetriesReached` | Maximum retries reached, request failed                   |
  </Tab>
</Tabs>

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 { getVariation } = useFeatureFlag();

      if (isInitialized()) {
        const variation = getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' });
      }
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();

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

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

    function DeeplyNestedComponent() {
      const { isInitialized } = useInitialize();
      const { getVariation } = useFeatureFlag();

      if (isInitialize()) {
        const variation = getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' });
      }
    }
    ```
  </Tab>
</Tabs>

##### Return value

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.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import {
      createClient,
      Environment,
      SDKConfigurationType,
    } from '@kameleoon/react-sdk';

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

    const client = createClient({ siteCode: 'my_site_code', configuration });
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { createClient, Environment } from '@kameleoon/react-sdk';

    // -- Optional configuration
    const configuration = {
      updateInterval: 60,
      environment: Environment.Production,
      cookieDomain: '.example.com',
    };

    const client = createClient({ siteCode: 'my_site_code', configuration });
    ```
  </Tab>
</Tabs>

##### Parameters

An object of type `SDKParameters` containing:

| Name                                                          | Type                            | Description                                                                                                                                      |
| ------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| siteCode <Badge color="red" size="sm">required</Badge>        | `string`                        | This is a [unique key](/user-manual/faq#how-do-i-find-my-sitecode) of the Kameleoon project you are using with the SDK. This field is mandatory. |
| configuration <Badge color="green" size="sm">optional</Badge> | `Partial<SDKConfigurationType>` | client's configuration                                                                                                                           |
| externals <Badge color="green" size="sm">optional</Badge>     | `ExternalsType`                 | external implementation of SDK dependencies ([External dependencies](#external-dependencies))                                                    |

##### Configuration Parameters

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    | Name                                                                         | Type          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default Value                              |
    | ---------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
    | updateInterval <Badge color="green" size="sm">optional</Badge>               | `number`      | Specifies the refresh interval, in minutes, that the SDK fetches the configuration for the active experiments and feature flags. The value determines the maximum time it takes to propagate changes, such as activating or deactivating feature flags or launching experiments, to your production servers. If left unspecified, the default interval is set to 60 minutes. Additionally, we offer a [streaming mode](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) that uses server-sent events (SSE) to push new configurations to the SDK automatically and apply new configurations in real-time, without any delays. | `60`                                       |
    | environment <Badge color="green" size="sm">optional</Badge>                  | `Environment` | feature flag environment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `Environment.Production`                   |
    | targetingDataCleanupInterval <Badge color="green" size="sm">optional</Badge> | `number`      | interval in *minutes* for cleaning up targeting data; minimum value is 1 minute                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` (no cleanup will be performed) |
    | domain <Badge color="green" size="sm">optional</Badge>                       | `string`      | [domain](#domain-information) that the cookie belongs to. Deprecated, use `cookieDomain` instead                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined`                                |
    | cookieDomain <Badge color="green" size="sm">optional</Badge>                 | `string`      | [domain](#domain-information) that the cookie belongs to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `undefined`                                |
    | networkDomain <Badge color="green" size="sm">optional</Badge>                | `string`      | custom 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 value                                                                                                                                                                                                                                                                                                                                                                                                                                    | `undefined`                                |
    | requestTimeout <Badge color="green" size="sm">optional</Badge>               | `number`      | timeout in *milliseconds* for all SDK network requests, if timeout is exceeded request will fail immediately                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `10_000` (10 seconds)                      |
    | trackingInterval <Badge color="green" size="sm">optional</Badge>             | `number`      | Specifies the interval for tracking requests, in milliseconds. All visitors who were evaluated for any feature flag or had associated data will be included in this tracking request, which is performed once per interval. The minimum value is `100` ms and the maximum value is `1_000` ms                                                                                                                                                                                                                                                                                                                                                                                                | `1_000` (1 second)                         |

    <Note>
      The `domain` parameter is deprecated and will be removed in a future release. Use `cookieDomain` instead.
    </Note>
  </Tab>

  <Tab title="SDK Version 10">
    | Name                                                                         | Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Default Value                              |
    | ---------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
    | updateInterval <Badge color="green" size="sm">optional</Badge>               | `number`                | Specifies the refresh interval, in minutes, that the SDK fetches the configuration for the active experiments and feature flags. The value determines the maximum time it takes to propagate changes, such as activating or deactivating feature flags or launching experiments, to your production servers. If left unspecified, the default interval is set to 60 minutes. Additionally, we offer a [streaming mode](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) that uses server-sent events (SSE) to push new configurations to the SDK automatically and apply new configurations in real-time, without any delays.              | `60`                                       |
    | environment <Badge color="green" size="sm">optional</Badge>                  | `Environment \| string` | feature flag environment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `Environment.Production`                   |
    | targetingDataCleanupInterval <Badge color="green" size="sm">optional</Badge> | `number`                | interval in *minutes* for cleaning up targeting data; minimum value is 1 minute                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `undefined` (no cleanup will be performed) |
    | cookieDomain <Badge color="green" size="sm">optional</Badge>                 | `string`                | [domain](#domain-information) that the cookie belongs to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `undefined`                                |
    | networkDomain <Badge color="green" size="sm">optional</Badge>                | `string`                | custom 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 value                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `undefined`                                |
    | requestTimeout <Badge color="green" size="sm">optional</Badge>               | `number`                | timeout in *milliseconds* for all SDK network requests, if timeout is exceeded request will fail immediately                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `10_000` (10 seconds)                      |
    | trackingInterval <Badge color="green" size="sm">optional</Badge>             | `number`                | Specifies the interval for tracking requests, in milliseconds. All visitors who were evaluated for any feature flag or had associated data will be included in this tracking request, which is performed once per interval. The minimum value is `1_000` ms and the maximum value is `5_000` ms                                                                                                                                                                                                                                                                                                                                                                                                           | `1_000` (1 second)                         |
    | stubMode <Badge color="green" size="sm">optional</Badge>                     | `boolean`               | When set to true, the client will operate in stub mode and perform no operations. In this mode, all method calls execute no actions, ensuring that no external actions or side effects occur.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                    |
    | defaultDataFile <Badge color="green" size="sm">optional</Badge>              | `string`                | The `defaultDataFile` feature ensures the Kameleoon SDK is always **READY** by providing a fallback configuration when no cached data file exists. Developers can preload a valid configuration by fetching it from `https://sdk-config.kameleoon.eu/v3/<sitecode>` and passing it as `defaultDataFile` during initialization. When a `dateModified` timestamp (in milliseconds) is provided and is newer than the cached version, the SDK will use the default datafile instead of the cached version. **If `dateModified` is omitted, the default datafile is only applied when no cached version exists**. This ensures the SDK always has a valid configuration, whether default, cached, or updated. | `undefined`                                |

    <Tip>
      **Option 1 (Recommended):** Use `JSON.stringify()`

      ```js theme={null}
      const dataFileJson = {"configuration":{"consentType":.....,
          {"key":"show_car","type":"JSON","value":"{\"make\":\"Porsche\",\"model\":\"911\"}"}},
          "dateModified":1752209266000};
      const dataFileString = JSON.stringify(dataFileJson);
      const configuration = {
        updateInterval: 20,
        defaultDataFile: dataFileString
      };
      ```

      **Option 2:** Raw JSON string (escape special characters)

      ```js theme={null}
      const configuration = {
        updateInterval: 20,
        defaultDataFile: `{"configuration":{"consentType":.....,
          {"key":"show_car","type":"JSON","value":"{\\"make\\":\\"Porsche\\",\\"model\\":\\"911\\"}"},
          "dateModified":1752209266000}`
      };
      ```
    </Tip>
  </Tab>
</Tabs>

##### Return value

| Type              | Description                     |
| ----------------- | ------------------------------- |
| `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).
</Note>

### Feature flags and variations

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

#### getVariation()

* 📨 *Sends Tracking Data to Kameleoon (depending on the `track` parameter)*

Retrieves the [`Variation`](#variation) assigned to a given visitor for a specific feature flag.

This method takes `featureKey` as a mandatory argument and `track` as an optional argument. The `track` argument is optional and defaults to `true`.

It returns the assigned `Variation` for the visitor. If the visitor is not associated with any feature flag rules, the method returns the default `Variation` for the given feature flag.

Ensure that proper error handling is implemented in your code to manage potential exceptions.

<Note>
  The default variation refers to the variation assigned to a visitor when they do not match any predefined delivery rules for a feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. It's represented as the variation in the "Then, for everyone else..." section in a management interface.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

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

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

        // -- Get variation with tracking
        const variation = getVariation({
          visitorCode,
          featureKey: 'my_feature_key',
        });

        // -- Get variation without tracking
        const variation = getVariation({
          visitorCode,
          featureKey: 'my_feature_key',
          track: false,
        });

        // -- An Example variation:
        // {
        //  key: 'variation_key',
        //  id: 123,
        //  experimentId: 456,
        //  variables: Map {
        //    'variable_key' => {
        //      key: 'variable_key',
        //      type: VariableType.BOOLEAN,
        //      value: true,
        //    }
        //  },
        // }
      }, [initialize, visitorCode, getVariation, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVariation } = useFeatureFlag();
      const { getVisitorCode } = useVisitorCode();

      const init = useCallback(async () => {
        await initialize();

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

        // -- Get variation with tracking
        const variation = getVariation({
          visitorCode,
          featureKey: 'my_feature_key',
        });

        // -- Get variation without tracking
        const variation = getVariation({
          visitorCode,
          featureKey: 'my_feature_key',
          track: false,
        });

        // -- An Example variation:
        // {
        //  key: 'variation_key',
        //  id: 123,
        //  experimentId: 456,
        //  variables: Map {
        //    'variable_key' => {
        //      key: 'variable_key',
        //      type: VariableType.BOOLEAN,
        //      value: true,
        //    }
        //  },
        // }
      }, [initialize, visitorCode, getVariation, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

An object of type `GetVariationParamsType` with the following properties:

| Name                                                        | Type      | Description                                                                    | Default |
| ----------------------------------------------------------- | --------- | ------------------------------------------------------------------------------ | ------- |
| `visitorCode` <Badge color="red" size="sm">required</Badge> | `string`  | Unique identifier of the visitor.                                              |         |
| `featureKey` <Badge color="red" size="sm">required</Badge>  | `string`  | Key of the feature you want to expose to a visitor.                            |         |
| `track` <Badge color="green" size="sm">optional</Badge>     | `boolean` | An optional parameter to enable or disable tracking of the feature evaluation. | `true`  |

##### Return value

| Type        | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `Variation` | An assigned [`Variation`](#variation) to a given visitor for a specific feature flag. |

##### Exceptions thrown

| Type                                                  | Description                                                                                                                                                                                                                                                           |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`                   | Method was executed before the `kameleoonClient` completed its [`initialize`](#initialize) call.                                                                                                                                                                      |
| `KameleoonException.VisitorCodeEmpty`                 | The visitor code is empty.                                                                                                                                                                                                                                            |
| `KameleoonException.VisitorCodeMaxLength`             | The visitor code exceeded the maximum length (255 characters).                                                                                                                                                                                                        |
| `KameleoonException.FeatureFlagConfigurationNotFound` | Exception indicating that the requested feature key wasn't found in the internal configuration of the SDK. This usually means that the feature flag is not activated in the Kameleoon app (but code implementing the feature is already deployed in the application). |
| `KameleoonException.FeatureFlagEnvironmentDisabled`   | Exception indicating that feature flag is disabled for the visitor's current environment (for example, production, staging, or development).                                                                                                                          |

#### getVariations()

* 📨 *Sends Tracking Data to Kameleoon (depending on the `track` parameter)*
* 🎯 *Events:* [`EventType.Evaluation`](#events-1)

<Info>
  Method is obtained using `useFeatureFlag` hook.
</Info>

Retrieves a map of [`Variation`](#variation) objects assigned to a given visitor across all feature flags.

This method iterates over all available feature flags and returns the assigned `Variation` for each flag associated with the specified visitor. It takes `visitorCode` as a mandatory argument, while `onlyActive` and `track` are optional.

* If `onlyActive` is set to `true`, the method `getVariations()` will return feature flags variations provided the user is not bucketed with the `off` variation.
* The `track` parameter controls whether or not the method will track the variation assignments. By default, it is set to `true`. If set to `false`, the tracking will be disabled.

The returned map consists of feature flag keys as keys and their corresponding `Variation` as values. If no variation is assigned for a feature flag, the method returns the default `Variation` for that flag.

Proper error handling should be implemented to manage potential exceptions.

<Note>
  The default variation refers to the variation assigned to a visitor when they do not match any predefined delivery rules for a feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. It's represented as the variation in the "Then, for everyone else..." section in a management interface.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

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

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

        // -- Get all feature flag variations with tracking
        const variations = getVariations({
          visitorCode,
        });

        // -- Get active feature flag variations with tracking
        const variations = getVariations({
          visitorCode,
          onlyActive: true,
        });

        // -- Get active feature flag variations without tracking
        const variations = getVariations({
          visitorCode,
          onlyActive: true,
          track: false,
        });

        // -- An Example variations:
        // Map {
        // 'feature_key' => {
        //    key: 'variation_key',
        //    id: 123,
        //    experimentId: 456,
        //    variables: Map {
        //      'variable_key' => {
        //        key: 'variable_key',
        //        type: VariableType.BOOLEAN,
        //        value: true,
        //      }
        //    },
        //   }
        // }
      }, [initialize, visitorCode, getVariations, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVariations } = useFeatureFlag();
      const { getVisitorCode } = useVisitorCode();

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

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

        // -- Get all feature flag variations with tracking
        const variations = getVariations({
          visitorCode,
        });

        // -- Get active feature flag variations with tracking
        const variations = getVariations({
          visitorCode,
          onlyActive: true,
        });

        // -- Get active feature flag variations without tracking
        const variations = getVariations({
          visitorCode,
          onlyActive: true,
          track: false,
        });

        // -- An Example variations:
        // Map {
        // 'feature_key' => {
        //    key: 'variation_key',
        //    id: 123,
        //    experimentId: 456,
        //    variables: Map {
        //      'variable_key' => {
        //        key: 'variable_key',
        //        type: VariableType.BOOLEAN,
        //        value: true,
        //      }
        //    },
        //   }
        // }
      }, [initialize, visitorCode, getVariations, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

An object of type `GetVariationsParamsType` with the following properties:

| Name                                                         | Type      | Description                                                                                                       | Default |
| ------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- | ------- |
| `visitorCode` <Badge color="red" size="sm">required</Badge>  | `string`  | Unique identifier of the visitor.                                                                                 |         |
| `onlyActive` <Badge color="green" size="sm">optional</Badge> | `boolean` | An optional parameter indicating whether to return variations for active (`true`) or all (`false`) feature flags. | `false` |
| `track` <Badge color="green" size="sm">optional</Badge>      | `boolean` | An optional parameter to enable or disable tracking of the feature evaluation.                                    | `true`  |

##### Return value

| Type                     | Description                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Map<string, Variation>` | Map that contains the assigned [`Variation`](#variation) objects of the feature flags using the keys of the corresponding features. |

##### Exceptions thrown

| Type                                      | Description                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed its [`initialize`](#initialize) call. |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty.                                                                       |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters).                                   |

#### isFeatureFlagActive()

* 📨 *Sends Tracking Data to Kameleoon (depending on the `track` parameter)*
* 🎯 *Events:* `EventType.Evaluation`

The method `isFeatureFlagActive()`, used with the `useFeatureFlag` hook, determines whether a visitor identified by `visitorCode` has the specified `featureKey` active. This method checks the targeting conditions, identifies the variation for the visitor, and saves this information to storage. Additionally, the hook sends a tracking request.

There is also an overload for this method that includes a `track` parameter, allowing you to disable the tracking of the feature evaluation.

<Note>
  Visitor must be targeted to has feature flag active
</Note>

<Note>
  Kameleoon uses tracking to count sessions and visitors when you call certain methods, such as `isFeatureFlagActive()`, `getVariation()` or `getVariations()`.

  Use the default `true` value for the `track` parameter when you expose visitors to a variation and need to count them. Set the `track` parameter to `false` only if you call these methods before you expose visitors.

  For example, if you call `getVariations()` to retrieve all variations before you expose visitors, set the `track` parameter to `false`. This setting prevents Kameleoon from prematurely counting a session. You can then trigger tracking later when you explicitly expose the visitor.

  Kameleoon sends tracking data every second by default. You can configure this interval up to five seconds using the tracking interval configuration option. Kameleoon groups tracking events into a single session as long as the interval between events is less than 30 minutes. If more than 30 minutes elapse between tracking events, Kameleoon counts the events as separate sessions. A visit appears in your reports 30 minutes after the last recorded event in the session.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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);

        // -- Check if the feature flag is active for visitor without tracking
        const isActive = isFeatureFlagActive({ visitorCode, featureKey: 'my_feature', track: false});
      }, [initialize, visitorCode, isFeatureFlagActive, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      useFeatureFlag,
      useVisitorCode,
      CustomData,
    } from '@kameleoon/react-sdk';

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

      const init = useCallback(async () => {
        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 targeting.
        addData(visitorCode, new CustomData(0, 'visitor_id'));

        // -- Get the feature flag's status.
        const isActive = isFeatureFlagActive(visitorCode, featureKey);

        // -- Check if the feature flag is active for visitors without tracking.
        const isActive = isFeatureFlagActive({ visitorCode, featureKey: 'my_feature', track: false});
      }, [initialize, visitorCode, isFeatureFlagActive, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

<Warning>
  The `isFeatureFlagActive()` method evaluates the served variant, not the master flag state. If you exclude rules, the method uses the **Then, for everyone else serve** default state. If you select **Off** for this default state, the method always returns `false` even when the master feature flag is **On**.
</Warning>

##### Parameters

There are two overloads available for this method:

1. Two parameters overload:

<Warning>
  This overload is deprecated and will be removed in the next major version. Please use the new overload with an object parameter.
</Warning>

| Name                                                      | Type     | Description                                                              |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length |
| featureKey <Badge color="red" size="sm">required</Badge>  | `string` | a unique key for feature flag                                            |

2. Object parameter overload of type `IsFeatureFlagActiveParamsType`:

| Name                                                      | Type      | Description                                                              | Default |
| --------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------- |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string`  | unique visitor identification string, can't exceed 255 characters length | -       |
| featureKey <Badge color="red" size="sm">required</Badge>  | `string`  | a unique key for feature flag                                            | -       |
| track <Badge color="green" size="sm">optional</Badge>     | `boolean` | a boolean indicator of whether to track the feature evaluation           | `true`  |

##### Return value

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

##### Exceptions thrown

| Type                                                  | Description                                                                            |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`                   | Method was executed before the `kameleoonClient` completed it's `initialize` call      |
| `KameleoonException.VisitorCodeMaxLength`             | The visitor code exceeded the maximum length (255 characters)                          |
| `KameleoonException.VisitorCodeEmpty`                 | The visitor code is empty                                                              |
| `KameleoonException.FeatureFlagConfigurationNotFound` | No feature flag was found for the specified `featureKey`                               |
| `KameleoonException.DataInconsistency`                | Allocated variation was found but there is no feature flag with according `featureKey` |

***

#### setForcedVariation()

The method allows you to programmatically assign a specific [`Variation`](#variation) to a user, bypassing the standard evaluation process. This is especially valuable for controlled experiments where the usual evaluation logic is not required or must be skipped. It can also be helpful in scenarios like debugging or custom testing.

When a **forced** variation is set, it overrides Kameleoon's real-time evaluation logic. Processes like segmentation, targeting conditions, and algorithmic calculations are skipped. To preserve segmentation and targeting conditions during an experiment, set `forceTargeting=false` instead.

<Info>
  **Simulated** variations always take precedence in the execution order. If a **simulated** variation calculation is triggered, it will be fully processed and completed first.
</Info>

A forced variation is treated the same as an evaluated variation. It is tracked in analytics and stored in the user context like any standard evaluated variation, ensuring consistency in reporting.

The method may throw exceptions under certain conditions (e.g., invalid parameters, user context, or internal issues). Proper exception handling is essential to ensure that your application remains stable and resilient.

<Warning>
  It’s important to distinguish **forced** variations from **[simulated](#getvisitorcode)** variations:

  * **Forced variations**: Are specific to an individual experiment.
  * **Simulated variations**: Affect the overall **feature flag** result.
</Warning>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

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

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

        // -- Forcing the variation "on" in the feature flag "featureKey1" for the visitor
        setForcedVariation({
          visitorCode: visitorCode,
          experimentId: 9516,
          variationKey: 'on',
          forceTargeting: false,
        });

        // -- Resetting the forced variation for the "featureKey1" feature flag for the visitor
        setForcedVariation({
          visitorCode: visitorCode,
          experimentId: 9516,
          variationKey: null,
        });
      }, [initialize, visitorCode, setForcedVariation, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { setForcedVariation } = useFeatureFlag();

      const init = useCallback(async () => {
        await initialize();

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

        // -- Forcing the variation "on" for the "featureKey1" feature flag for the visitor
        setForcedVariation({
          visitorCode: visitorCode,
          experimentId: 9516,
          variationKey: 'on',
          forceTargeting: false,
        });

        // -- Resetting the forced variation for the "featureKey1" feature flag for the visitor
        setForcedVariation({
          visitorCode: visitorCode,
          experimentId: 9516,
          variationKey: null,
        });
      }, [initialize, visitorCode, setForcedVariation, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

An object of type `SetForcedVariationParametersType` with the following properties:

| Name                                                             | Type      | Description                                                                                                                                      | Default                                                                                                                                                                      |   |
| ---------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| `visitorCode` <Badge color="red" size="sm">required</Badge>      | `string`  | Unique identifier of the visitor.                                                                                                                |                                                                                                                                                                              |   |
| `experimentId` <Badge color="red" size="sm">required</Badge>     | `number`  | **Experiment Id** that will be targeted and selected during the evaluation process.                                                              |                                                                                                                                                                              |   |
| `variationKey` <Badge color="red" size="sm">required</Badge>     | \`string  | null\`                                                                                                                                           | **Variation Key** corresponding to a `Variation` that should be forced as the returned value for the experiment. If the value is `null`, the forced variation will be reset. |   |
| `forceTargeting` <Badge color="green" size="sm">optional</Badge> | `boolean` | Indicates whether targeting for the experiment should be forced and skipped (`true`) or applied as in the standard evaluation process (`false`). | `true`                                                                                                                                                                       |   |

##### Exceptions thrown

| Type                                               | Description                                                                                                                                                                                                                                           |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonException.VisitorCodeEmpty`              | The visitor code is empty.                                                                                                                                                                                                                            |
| `KameleoonException.VisitorCodeMaxLength`          | The visitor code exceeded the maximum length (255 characters).                                                                                                                                                                                        |
| `KameleoonException.Initialization`                | Indicates that the SDK is not yet fully initialized.                                                                                                                                                                                                  |
| `KameleoonException.FeatureFlagExperimentNotFound` | Exception indicating that the requested experiment id has not been found in the SDK's internal configuration. This is usually normal and means that the rule's corresponding experiment has not yet been activated on Kameleoon's side.               |
| `KameleoonException.FeatureFlagVariationNotFound`  | Exception indicating that the requested variation key(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. |
| `KameleoonException.StorageRead`                   | Couldn't read storage data.                                                                                                                                                                                                                           |
| `KameleoonException.StorageWrite`                  | Couldn't update storage data.                                                                                                                                                                                                                         |

<Info>
  In most cases, only the basic error, `KameleoonException`, needs to be handled, as demonstrated in the example. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Error`.
</Info>

#### evaluateAudiences()

* 📨 *Sends Tracking Data to Kameleoon*

This method evaluates visitors against all available Audiences Explorer segments and tracks those who match.

`evaluateAudiences()` should be called **after all relevant visitor data has been set or updated**, and **just before** getting a feature variation or checking a feature flag. This approach ensures that the visitor is evaluated against the most current data available, allowing for accurate audience assignment based on all criteria.

After calling this method, you can perform a detailed analysis of segment performance in Audiences Explorer.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

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

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

        evaluateAudiences(visitorCode);
      }, [initialize, visitorCode, evaluateAudiences, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

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

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

        evaluateAudiences(visitorCode);
      }, [initialize, visitorCode, evaluateAudiences, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                        | Type     | Description                       |
| ----------------------------------------------------------- | -------- | --------------------------------- |
| `visitorCode` <Badge color="red" size="sm">required</Badge> | `string` | Unique identifier of the visitor. |

##### Exceptions thrown

| Type                                      | Description                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed its [`initialize`](#initialize) call. |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty.                                                                       |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters).                                   |

<Info>
  In most cases, only the basic error, `KameleoonException`, needs to be handled, as demonstrated in the example. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Error`.
</Info>

#### getDataFile()

<Tip>
  To evaluate all feature flags, use [`getVariations()`](#getvariations). This method is more efficient than calling `DataFile` and iterating through flags with [`getVariation()`](#getvariation).
</Tip>

Returns the current SDK configuration as a [`DataFile`](#datafile) object.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useFeatureFlag,
    } from '@kameleoon/react-sdk';

    function MyComponent(): JSX.Element {
      const { getDataFile } = useFeatureFlag();

      useEffect(() => {
        const dataFile = getDataFile();
      }, [getDataFile]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useFeatureFlag,
    } from '@kameleoon/react-sdk';

    function MyComponent(): JSX.Element {
      const { getDataFile } = useFeatureFlag();

      useEffect(() => {
        const dataFile = getDataFile();
      }, [getDataFile]);
    }
    ```
  </Tab>
</Tabs>

##### Return value

| Type       | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `DataFile` | The [`DataFile`](#datafile) containing the SDK configuration |

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

<Info>
  The `getVisitorCode()` method allows you to set **simulated** variations for a visitor. When cookies (from a **request** or **document**) contain the key `kameleoonSimulationFFData`, the standard evaluation process is bypassed. Instead, the method directly returns a [`Variation`](#variation) based on the provided data.

  You can apply simulations in two ways:

  * **Automatically (recommended):** If using Kameleoon Web Experimentation or the SDK in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code), the cookie is created automatically when simulating a variant's display using the [Simulation Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode).
  * **Manually:** Set the `kameleoonSimulationFFData` cookie manually.

  It’s important to distinguish **simulated** variations from **[forced](#setforcedvariation)** variations:

  * **Simulated variations**: Affect the overall **feature flag** result.
  * **Forced variations**: Are specific to an individual experiment.

  ⚙️ **Manual setup**

  Please ensure the `kameleoonSimulationFFData` cookie follows this format:

  * `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: Simulates the variation with `varId` of experiment `expId` for the given `featureKey`.
  * `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: Simulates the default variation (defined in the **Then, for everyone else in Production, serve** section) for the given `featureKey`.

  ⚠️ To ensure proper functionality, the cookie value must be encoded as a URI component using a method such as [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
</Info>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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, save, and retrieve the default visitorCode.
        const visitorCode = getVisitorCode('default_visitor_code');
      }, [initialize, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useVisitorCode } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();

      const init = useCallback(async () => {
        await initialize();

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

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                               | Type     | Description                                                         |
| ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------- |
| defaultVisitorCode <Badge color="green" size="sm">optional</Badge> | `string` | visitor 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.
</Note>

##### Return value

| Type     | Description          |
| -------- | -------------------- |
| `string` | result visitor code. |

##### Exceptions thrown

| Type                                      | Description                          |
| ----------------------------------------- | ------------------------------------ |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code length was exceeded |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty            |

***

#### addData()

The `addData` function, used with the `useData` hook, collects targeting data to store for other hooks to determine if the current visitor is targeted.

<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](#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](#flush).

  The [trackConversion](#trackconversion) method also sends out any previously associated data, just like the [flush](#flush). The same holds true for [getFeatureFlagVariationKey](#getfeatureflagvariationkey) and [getFeatureVariable](#getfeatureflagvariable) methods if an experimentation rule is triggered.

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

  * Check the list of [supported conditions](#targeting-conditions) to know what data types can be used for targeting
</Note>

<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`.
</Tip>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 a single data item (tracked by default)
        addData('my_visitor_code', browserData);

        // -- Add multiple data items (tracked by default)
        addData('my_visitor_code', browserData, customData);

        // -- Add multiple data items from array (tracked by default)
        const dataArr = [browserData, customData];
        addData('my_visitor_code', ...dataArr);

        // -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
        addData({visitorCode: 'my_visitor_code', track: false, data: dataArr});
      }, [initialize, visitorCode, addData, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useVisitorCode,
      useData,
      CustomData,
      Browser,
      BrowserType,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { addData } = useData();

      const init = useCallback(async () => {
        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 a single data item (tracked by default)
        addData('my_visitor_code', browserData);

        // -- Add multiple data items (tracked by default)
        addData('my_visitor_code', browserData, customData);

        // -- Add multiple data items from array (tracked by default)
        const dataArr = [browserData, customData];
        addData('my_visitor_code', ...dataArr);

        // -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
        addData({visitorCode: 'my_visitor_code', track: false, data: dataArr});
      }, [initialize, visitorCode, addData, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                          | Type                  | Description                                                                                                                                                                                  | Default value |
| ------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| visitorCode <Badge color="red" size="sm">required</Badge>     | `string`              | unique visitor identification string, can't exceed 255 characters.                                                                                                                           |               |
| track <Badge color="green" size="sm">optional</Badge>         | `boolean`             | Specifies whether the added data is eligible for tracking. When set to `false`, the data is stored locally and used only for targeting evaluation; it is not sent to the Kameleoon Data API. | `true`        |
| kameleoonData <Badge color="green" size="sm">optional</Badge> | `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)

  * The index or ID of the [custom data](/user-manual/assets/custom-data/create-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>

##### Exceptions thrown

| Type                                      | Description                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)                     |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                                         |
| `KameleoonException.StorageWrite`         | Couldn't update storage data                                                      |
| `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed it's `initialize` call |

<Note>
  See the [Data types](#data-types) reference for more details of how to manage different data types.
</Note>

***

#### flush()

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    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](#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](#initialize), the SDK attempts to send the stored requests before executing the latest request.

    <Note>
      The `isUniqueIdentifier` parameter can be useful in some 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.
    </Note>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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);

            // -- Instantly flush added custom data for visitor (fire-and-forget)
            flushInstant(visitorCode);

            // -- Instantly flush added custom data for visitor and wait for completion
            await flushInstant(visitorCode);

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

            // -- Instantly flush data for all the visitors (fire-and-forget)
            flushInstant();

            // -- Instantly flush data for all the visitors and wait for completion
            await flushInstant();

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useInitialize,
          useVisitorCode,
          useData,
          CustomData,
        } from '@kameleoon/react-sdk';

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

          const init = useCallback(async () => {
            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]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    | Name                                                               | Type      | Description                                                                                                                                                 | Default |
    | ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
    | visitorCode <Badge color="green" size="sm">optional</Badge>        | `string`  | unique 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 <Badge color="green" size="sm">optional</Badge> | `boolean` | an optional parameter for specifying if the visitorCode is a unique identifier                                                                              | `false` |

    ##### Exceptions thrown

    | Type                                      | Description                                                                       |
    | ----------------------------------------- | --------------------------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)                     |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                                         |
    | `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed it's `initialize` call |
  </Tab>

  <Tab title="SDK Version 10">
    `flush()` takes the Kameleoon data associated with the visitor and schedules the data to be sent with the next tracking request. The time of the next tracking request is defined by SDK Configuration [`trackingInterval`](#configuration-parameters) parameter. Visitor data can be added using [addData](#adddata) and [getRemoteVisitorData](#getremotevisitordata) methods.

    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](#initialize), the SDK attempts to send the stored requests before executing the latest request.

    <Tip>
      If you need to send tracking requests immediately, use `flushInstant()` — the asynchronous version of `flush` that returns `Promise<void>`. You can `await` it when you need delivery guarantees (for example, before page navigation/unload), or call it without `await` as a fire-and-forget request:

      * `await flushInstant(visitorCode)` sends tracking requests immediately for a specific visitor and waits for completion
      * `await flushInstant()` sends tracking requests immediately for all visitors and waits for completion
    </Tip>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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);

            // -- Instantly flush added custom data for visitor
            flush({ visitorCode, instant: true });

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

            // -- Instantly flush data for all the visitors
            flush({ instant: true });
          }, [initialize, visitorCode, addData, flush, getVisitorCode]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import {
          useInitialize,
          useVisitorCode,
          useData,
          CustomData,
        } from '@kameleoon/react-sdk';

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

          const init = useCallback(async () => {
            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);

            // -- Instantly flush added custom data for visitor
            flush({ visitorCode, instant: true });

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

            // -- Instantly flush data for all the visitors
            flush({ instant: true });
          }, [initialize, visitorCode, addData, flush, getVisitorCode]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    | Name                                                        | Type     | Description                                                                                                                                        | Default |
    | ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
    | visitorCode <Badge color="green" size="sm">optional</Badge> | `string` | unique visitor identification string, can't exceed 255 characters, if not passed, all data will be flushed (sent to the remote Kameleoon servers). | -       |

    Or an object with the type FlushParamsType, containing:

    | Name                                                        | Type      | Description                                                                                                                                        | Default |
    | ----------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
    | visitorCode <Badge color="green" size="sm">optional</Badge> | `string`  | unique visitor identification string, can't exceed 255 characters, if not passed, all data will be flushed (sent to the remote Kameleoon servers). | -       |
    | instant <Badge color="green" size="sm">optional</Badge>     | `boolean` | Boolean flag indicating whether the data should be sent instantly (`true`) or according to the scheduled tracking interval (`false`).              | -       |

    ##### Exceptions thrown

    | Type                                      | Description                                                                       |
    | ----------------------------------------- | --------------------------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)                     |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                                         |
    | `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed it's `initialize` call |
  </Tab>
</Tabs>

***

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { getRemoteData } = useData();

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

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

      useEffect(() => {
        getData();
      }, [getData]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                              | Type     | Description                                                |
| ------------------------------------------------- | -------- | ---------------------------------------------------------- |
| key <Badge color="red" size="sm">required</Badge> | `string` | unique key that the data you try to get is associated with |

##### Return value

| Type       | Description                                   |
| ---------- | --------------------------------------------- |
| `JSONType` | promise with data retrieved for specific key. |

##### Exceptions thrown

| Type                            | Description                                  |
| ------------------------------- | -------------------------------------------- |
| `KameleoonException.RemoteData` | Couldn't retrieve data from Kameleoon server |

***

#### getRemoteVisitorData()

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    `getRemoteVisitorData()` is an asynchronous method for retrieving Kameleoon Visits Data for the `visitorCode` from the Kameleoon Data API. The method adds the data to storage for other methods to use when making targeting decisions.

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

    * use data collected from other devices.
    * access a user's history, such as previously visited pages during past visits.
    * use data that is only accessible on the client-side, like datalayer variables and goals that only convert on the front-end.

    Read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) for a better understanding of possible use cases.

    <Warning>
      By default, `getRemoteVisitorData()` automatically retrieves the latest stored custom data with `scope=Visitor` and attaches them to the visitor without the need to call the method `addData()`. It is particularly useful for [synchronizing custom data between multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
    </Warning>

    <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.
    </Note>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useData } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { getRemoteVisitorData } = useData();

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

            // -- Get remote visitor data without adding it to storage.
            const kameleoonDataList = 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 = {
              currentVisit: true,
              previousVisitAmount: 10,
              customData: true,
              geolocation: true,
              conversions: true,
            };

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

          useEffect(() => {
            getData();
          }, [getData]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    An object with the type `RemoteVisitorDataParamsType` containing:

    | Name                                                               | Type                     | Description                                                                                                                                            | Default Value                                                                                                   |
    | ------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
    | visitorCode <Badge color="red" size="sm">required</Badge>          | `string`                 | unique visitor identification string, can't exceed 255 characters length                                                                               | -                                                                                                               |
    | shouldAddData <Badge color="green" size="sm">optional</Badge>      | `boolean`                | boolean flag identifying whether the retrieved custom data should be set to the storage like `addData` method does                                     | `true`                                                                                                          |
    | filters <Badge color="green" size="sm">optional</Badge>            | `VisitorDataFiltersType` | filters 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 <Badge color="green" size="sm">optional</Badge> | `boolean`                | optional parameter that, when `true`, specifies that the visitorCode is a unique identifier                                                            | `false`                                                                                                         |

    ##### Return value

    | Type                  | Description                                   |
    | --------------------- | --------------------------------------------- |
    | `KameleoonDataType[]` | promise with list of Kameleoon Data retrieved |

    ##### Exceptions thrown

    | Type                                      | Description                                                            |
    | ----------------------------------------- | ---------------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)          |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                              |
    | `KameleoonException.RemoteData`           | Couldn't retrieve data from Kameleoon server                           |
    | `KameleoonException.VisitAmount`          | Visit amount must be a number between 1 and 25                         |
    | `KameleoonException.Initialization`       | Method was executed before `initialize` was done for `kameleoonClient` |

    ##### Using parameters in getRemoteVisitorData()

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

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

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

    <Note>
      Here is the list of available `VisitorDataFiltersType` filters:

      | Name                                                                | Type      | Description                                                                                                                                                                          | Default |
      | ------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
      | previousVisitAmount <Badge color="green" size="sm">optional</Badge> | `number`  | Number of previous visits to retrieve data from. Number between `1` and `25`                                                                                                         | `1`     |
      | currentVisit <Badge color="green" size="sm">optional</Badge>        | `boolean` | If true, current visit data will be retrieved                                                                                                                                        | `true`  |
      | customData <Badge color="green" size="sm">optional</Badge>          | `boolean` | If true, custom data will be retrieved.                                                                                                                                              | `true`  |
      | pageViews <Badge color="green" size="sm">optional</Badge>           | `boolean` | If true, page data will be retrieved.                                                                                                                                                | `false` |
      | geolocation <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, geolocation data will be retrieved.                                                                                                                                         | `false` |
      | device <Badge color="green" size="sm">optional</Badge>              | `boolean` | If true, device data will be retrieved.                                                                                                                                              | `false` |
      | browser <Badge color="green" size="sm">optional</Badge>             | `boolean` | If true, browser data will be retrieved.                                                                                                                                             | `false` |
      | operatingSystem <Badge color="green" size="sm">optional</Badge>     | `boolean` | If true, operating system data will be retrieved.                                                                                                                                    | `false` |
      | conversions <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, conversion data will be retrieved.                                                                                                                                          | `false` |
      | experiments <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, experiment data will be retrieved.                                                                                                                                          | `false` |
      | kcs <Badge color="green" size="sm">optional</Badge>                 | `boolean` | If true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the [AI Predictive Targeting add-on](/user-manual/assets/segments/target-users-based-on-likelihood-to-convert) | `false` |
    </Note>
  </Tab>

  <Tab title="SDK Version 10">
    `getRemoteVisitorData()` is an asynchronous method for retrieving Kameleoon Visits Data for the `visitorCode` from the Kameleoon Data API. The method adds the data to storage for other methods to use when making targeting decisions.

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

    * use data collected from other devices.
    * access a user's history, such as previously visited pages during past visits.
    * use data that is only accessible on the client-side, like datalayer variables and goals that only convert on the front-end.

    Read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) for a better understanding of possible use cases.

    <Warning>
      By default, `getRemoteVisitorData()` automatically retrieves the latest stored custom data with `scope=Visitor` and attaches them to the visitor without the need to call the method `addData()`. It is particularly useful for [synchronizing custom data between multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
    </Warning>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useData } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { getRemoteVisitorData } = useData();

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

            // -- Get remote visitor data without adding it to storage.
            const kameleoonDataList = 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 = {
              currentVisit: true,
              previousVisitAmount: 10,
              customData: true,
              geolocation: true,
              conversions: true,
            };

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

          useEffect(() => {
            getData();
          }, [getData]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    An object with the type `RemoteVisitorDataParamsType` containing:

    | Name                                                          | Type                     | Description                                                                                                                                            | Default Value                                                                                                   |
    | ------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
    | visitorCode <Badge color="red" size="sm">required</Badge>     | `string`                 | unique visitor identification string, can't exceed 255 characters length                                                                               | -                                                                                                               |
    | shouldAddData <Badge color="green" size="sm">optional</Badge> | `boolean`                | boolean flag identifying whether the retrieved custom data should be set to the storage like `addData` method does                                     | `true`                                                                                                          |
    | filters <Badge color="green" size="sm">optional</Badge>       | `VisitorDataFiltersType` | filters 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` |

    ##### Return value

    | Type                  | Description                                   |
    | --------------------- | --------------------------------------------- |
    | `KameleoonDataType[]` | promise with list of Kameleoon Data retrieved |

    ##### Exceptions thrown

    | Type                                      | Description                                                            |
    | ----------------------------------------- | ---------------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)          |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                              |
    | `KameleoonException.RemoteData`           | Couldn't retrieve data from Kameleoon server                           |
    | `KameleoonException.VisitAmount`          | Visit amount must be a number between 1 and 25                         |
    | `KameleoonException.Initialization`       | Method was executed before `initialize` was done for `kameleoonClient` |

    ##### Using parameters in getRemoteVisitorData()

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

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

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

    <Note>
      Here is the list of available `VisitorDataFiltersType` filters:

      | Name                                                                | Type      | Description                                                                                                                                                                                                                                                                                                                                     | Default |
      | ------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
      | previousVisitAmount <Badge color="green" size="sm">optional</Badge> | `number`  | Number of previous visits to retrieve data from. Number between `1` and `25`                                                                                                                                                                                                                                                                    | `1`     |
      | currentVisit <Badge color="green" size="sm">optional</Badge>        | `boolean` | If true, current visit data will be retrieved                                                                                                                                                                                                                                                                                                   | `true`  |
      | customData <Badge color="green" size="sm">optional</Badge>          | `boolean` | If true, custom data will be retrieved.                                                                                                                                                                                                                                                                                                         | `true`  |
      | pageViews <Badge color="green" size="sm">optional</Badge>           | `boolean` | If true, page data will be retrieved.                                                                                                                                                                                                                                                                                                           | `false` |
      | geolocation <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, geolocation data will be retrieved.                                                                                                                                                                                                                                                                                                    | `false` |
      | device <Badge color="green" size="sm">optional</Badge>              | `boolean` | If true, device data will be retrieved.                                                                                                                                                                                                                                                                                                         | `false` |
      | browser <Badge color="green" size="sm">optional</Badge>             | `boolean` | If true, browser data will be retrieved.                                                                                                                                                                                                                                                                                                        | `false` |
      | operatingSystem <Badge color="green" size="sm">optional</Badge>     | `boolean` | If true, operating system data will be retrieved.                                                                                                                                                                                                                                                                                               | `false` |
      | conversions <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, conversion data will be retrieved.                                                                                                                                                                                                                                                                                                     | `false` |
      | experiments <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, experiment data will be retrieved.                                                                                                                                                                                                                                                                                                     | `false` |
      | kcs <Badge color="green" size="sm">optional</Badge>                 | `boolean` | If true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the [AI Predictive Targeting add-on](/user-manual/assets/segments/target-users-based-on-likelihood-to-convert)                                                                                                                                                            | `false` |
      | visitorCode <Badge color="green" size="sm">optional</Badge>         | `boolean` | If true, Kameleoon will retrieve the `visitorCode` from the most recent visit and use it for the current visit. This is necessary if you want to ensure that the visitor, identified by their `visitorCode`, always receives the same variation across visits for [Cross-device experimentation](/developer-docs/cross-device-experimentation). | `true`  |
      | personalization <Badge color="green" size="sm">optional</Badge>     | `boolean` | If true, personalization data will be retrieved. This is required for the personalization condition                                                                                                                                                                                                                                             | `false` |
      | cbs <Badge color="green" size="sm">optional</Badge>                 | `boolean` | If true, Contextual Bandit score data will be retrieved.                                                                                                                                                                                                                                                                                        | `false` |
    </Note>
  </Tab>
</Tabs>

***

#### 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](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) for additional details.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { getVisitorWarehouseAudience } = useData();

      const getData = useCallback(async () => {
        // -- Get visitor warehouse audience data using `warehouseKey`
        //    and add it to storage.
        const 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 = await getVisitorWarehouseAudience({
          visitorCode: 'my_visitor',
          customDataIndex: 10,
        });
      }, [getRemoteData]);

      useEffect(() => {
        getData();
      }, [getData]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

Parameters object consisting of:

| Name                                                          | Type     | Description                                                                                         |
| ------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| visitorCode <Badge color="red" size="sm">required</Badge>     | `string` | unique visitor identification string, can't exceed 255 characters length                            |
| customDataIndex <Badge color="red" size="sm">required</Badge> | `number` | number representing the index of the custom data you want to use to target your Warehouse Audiences |
| warehouseKey <Badge color="green" size="sm">optional</Badge>  | `string` | unique key to identify the warehouse data (usually, your internal user ID)                          |

##### Return value

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

##### Exceptions thrown

| Type                                      | Description                                                   |
| ----------------------------------------- | ------------------------------------------------------------- |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters) |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                     |
| `KameleoonException.RemoteData`           | Couldn'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](/user-manual/project-management/consent-management-policy).

<Note>
  * Consent information is in sync between the Kameleoon Engine (application file engine.js) and the React SDK. This synchronization means that once consent is set on either the Engine or the SDK, it's automatically set for both. This feature eliminates the need for manual consent handling and ensures that SDKs operate in compliance with user preferences.

  If you use Kameleoon in Hybrid mode, we recommend reading the consent section in our [Hybrid experimentation article](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/#managing-consent-in-hybrid-mode)

  * When handling legal consent, it's important to use [`getVisitorCode`](#getvisitorcode) method. Additionally, `getVisitorCode` does not accept `domain` as an argument. Instead, pass it to the [`createClient`](#createclient) function.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useVisitorCode } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode, setLegalConsent } = useVisitorCode();

      const init = useCallback(async () => {
        await initialize();

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

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                      | Type      | Description                                                                                                                                                                                    |
| --------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string`  | unique visitor identification string, can't exceed 255 characters length                                                                                                                       |
| consent <Badge color="red" size="sm">required</Badge>     | `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 |

##### Exceptions thrown

| Type                                      | Description                                                          |
| ----------------------------------------- | -------------------------------------------------------------------- |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code length exceeded the maximum length (255 characters) |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                            |

##### Consent revocation behavior

When you call `setLegalConsent()` with `consent=false`, the SDK does not delete the `kameleoonVisitorCode` cookie. Instead, it stops extending the cookie's expiration date, allowing the cookie to persist until it naturally expires.

If your compliance requirements demand the immediate removal of the cookie file upon opt-out, you must delete it manually using your framework’s native cookie management methods. The SDK will not remove the file automatically.

***

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

<Tabs defaultTabIndex={1}>
  <Tab title="SDK Version 9">
    * 📨 *Sends Tracking Data to Kameleoon*

    The `trackConversion()` function, used with the `useData` hook creates and adds [`Conversion`](#conversion) data to the visitor with specified parameters and executes `flush()`.

    Use this method to track a conversion for a specific [goal](/user-manual/assets/goals/create-a-goal) and user. This method requires `visitorCode` and `goalId`. In addition, this method also accepts an optional `revenue` argument. The `visitorCode` is usually identical to the one that was used when triggering the experiment.

    The `trackConversion()` method doesn't return any value. This method is non-blocking as the server call is made asynchronously.

    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](#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.
    </Note>

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useInitialize, useVisitorCode, useData } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { initialize } = useInitialize();
          const { getVisitorCode } = useVisitorCode();
          const { trackConversion } = useData();

          const init = useCallback(async () => {
            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]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    Parameters object consisting of:

    | Name                                                                 | Type      | Description                                                                     | Default |
    | -------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | ------- |
    | `visitorCode` <Badge color="red" size="sm">required</Badge>          | `string`  | Unique identifier of the visitor.                                               |         |
    | `goalId` <Badge color="red" size="sm">required</Badge>               | `number`  | ID of the goal.                                                                 |         |
    | `revenue` <Badge color="green" size="sm">optional</Badge>            | `number`  | Revenue of the conversion.                                                      | `0`     |
    | `isUniqueIdentifier` <Badge color="green" size="sm">optional</Badge> | `boolean` | An optional parameter for specifying if the visitorCode is a unique identifier. | `false` |

    ##### Exceptions thrown

    | Type                                      | Description                                                    |
    | ----------------------------------------- | -------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters). |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty.                                     |
    | `KameleoonException.StorageWrite`         | Couldn't update storage data.                                  |
  </Tab>

  <Tab title="SDK Version 10">
    * 📨 *Sends Tracking Data to Kameleoon*

    The `trackConversion()` function, used with the `useData` hook creates and adds [`Conversion`](#conversion) data to the visitor with specified parameters and executes `flush()`.

    Use this method to track a conversion for a specific [goal](/user-manual/assets/goals/create-a-goal) and user. This method requires `visitorCode` and `goalId`. In addition, this method also accepts an optional `revenue`, `negative` and `metadata` arguments. The `visitorCode` is usually identical to the one that was used when triggering the experiment.

    The `trackConversion()` method doesn't return any value. This method is non-blocking as the server call is made asynchronously.

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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 { trackConversion } = useData();

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

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

            // -- Track conversion
            trackConversion({
              visitorCode,
              revenue: 2000,
              goalId: 123,
              metadata: [new CustomData(0, 'value')],
              negative: true,
            });
          }, [initialize, trackConversion, visitorCode, getVisitorCode]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useInitialize, useVisitorCode, useData, CustomData } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { initialize } = useInitialize();
          const { getVisitorCode } = useVisitorCode();
          const { trackConversion } = useData();

          const init = useCallback(async () => {
            await initialize();

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

            // -- Track conversion
            trackConversion({
              visitorCode,
              revenue: 2000,
              goalId: 123,
              metadata: [new CustomData(0, 'value')],
              negative: true,
            });
          }, [initialize, trackConversion, visitorCode, getVisitorCode]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>

    ##### Parameters

    Parameters object consisting of:

    | Name                                                        | Type           | Description                                                                                                                      | Default     |
    | ----------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- |
    | `visitorCode` <Badge color="red" size="sm">required</Badge> | `string`       | Unique identifier of the visitor.                                                                                                |             |
    | `goalId` <Badge color="red" size="sm">required</Badge>      | `number`       | ID of the goal.                                                                                                                  |             |
    | `revenue` <Badge color="green" size="sm">optional</Badge>   | `number`       | Revenue of the conversion.                                                                                                       | `0`         |
    | `negative` <Badge color="green" size="sm">optional</Badge>  | `boolean`      | Defines if the revenue is positive or negative.                                                                                  | `false`     |
    | `metadata` <Badge color="green" size="sm">optional</Badge>  | `CustomData[]` | Metadata of the conversion. [Must be defined beforehand in the Kameleoon App](/user-manual/assets/goals/create-a-goal#metadata). | `undefined` |

    <Note>
      metadata values are accessible through [raw data exports](/user-manual/experiment-analytics/analyze-results/results-page-actions#Export) and [the results page](/user-manual/experiment-analytics/analyze-results/goal-metadata).

      If the `metadata` parameter is provided, Kameleoon will use these specified values for the current conversion instead of what was previously collected using the [`addData()`](#adddata) method. If the parameter is omitted, Kameleoon will use the last tracked values for those [`CustomData`](#customdata) prior to the conversion and within the same visit.

      Kameleoon will only consider the metadata values that are explicitly passed as parameters to the `trackConversion()` method.

      In the example below, Kameleoon will associate the conversion only with the custom data value explicitly provided as a parameter (here: index 5 with the value 'Amex Credit Card').

      <Tabs defaultTabIndex={0}>
        <Tab title="TypeScript">
          ```ts theme={null}
          addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery'));
          trackConversion({
              visitorCode,
              goalId: 1000,
              metadata: [new CustomData(5, 'Amex Credit Card')]
          });
          ```
        </Tab>

        <Tab title="JavaScript">
          ```js theme={null}
          addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery'));
          trackConversion({
              visitorCode,
              goalId: 1000,
              metadata: [new CustomData(5, 'Amex Credit Card')]
          });
          ```
        </Tab>
      </Tabs>
    </Note>

    ##### Exceptions thrown

    | Type                                      | Description                                                    |
    | ----------------------------------------- | -------------------------------------------------------------- |
    | `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters). |
    | `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty.                                     |
    | `KameleoonException.StorageWrite`         | Couldn't update storage data.                                  |
  </Tab>
</Tabs>

***

#### getEngineTrackingCode()

Kameleoon integrates with several analytics solutions, including Mixpanel, Google Analytics 4, and Segment. To track server-side experiments correctly, call the `getEngineTrackingCode()` method after the visitor triggers an experiment. The SDK returns JavaScript queue commands for the experiments that the visitor triggered during the previous five seconds. When you insert this code into the page, Engine.js processes the commands and sends the exposure events through the active analytics integration.

Refer to [hybrid experimentation](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) for more information on implementing this method.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

    function MyComponent(): JSX.Element {
      const { initialize } = useInitialize();
      const { getEngineTrackingCode, getVariation } =
        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`
        getVariation({ visitorCode: 'visitor_code', featureKey: '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, getVariation, getEngineTrackingCode]);

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

      useEffect(() => {
        if (!engineCode) {
          return;
        }

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

        document.body.appendChild(script);

        // -- Remove script from the page
        return () => {
          document.body.removeChild(script);
        };
      }, [engineCode]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getEngineTrackingCode, getVariation } =
        useFeatureFlag();

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

      const init = useCallback(async () => {
        await initialize();

        // -- Trigger feature experiment
        // -- E.g., result `variationKey` id is `200` and implicit experiment id is `100`
        getVariation({ visitorCode: 'visitor_code', featureKey: '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, getVariation, getEngineTrackingCode]);

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

      useEffect(() => {
        if (!engineCode) {
          return;
        }

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

        document.body.appendChild(script);

        // -- Remove script from the page
        return () => {
          document.body.removeChild(script);
        };
      }, [engineCode]);
    }
    ```
  </Tab>
</Tabs>

<Note>
  * To use this feature, implement both the React SDK and Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Because Engine.js is used only for tracking in this flow, you can install the asynchronous tag before the closing `</body>` tag.

  * You can insert the returned tracking code directly into an HTML `<script>` tag.

  ```html theme={null}
  <html lang="en">
    <body>
      <script>
        const engineTrackingCode = `
          window.kameleoonQueue = window.kameleoonQueue || [];
          window.kameleoonQueue.push(['Experiments.assignVariation', 123456, 7890, true]);
          window.kameleoonQueue.push(['Experiments.trigger', 123456, true]);
          window.kameleoonQueue.push(['Experiments.assignVariation', 234567, 8901, true]);
          window.kameleoonQueue.push(['Experiments.trigger', 234567, true]);
        `;
        const script = document.createElement('script');

        script.textContent = engineTrackingCode;
        document.body.appendChild(script);
      </script>

    </body>
  </html>
  ```

  In this example, `123456` and `234567` are experiment IDs, and `7890` and `8901` are variation IDs. In your implementation, the SDK generates these values in the returned tracking code.
</Note>

##### Parameters

| Name                                                        | Type     | Description                       |
| ----------------------------------------------------------- | -------- | --------------------------------- |
| `visitorCode` <Badge color="red" size="sm">required</Badge> | `string` | Unique identifier of the visitor. |

##### Return value

| Type     | Description                              |
| -------- | ---------------------------------------- |
| `string` | JavaScript code to insert into the page. |

##### Exceptions thrown

| Type                                      | Description                                                   |
| ----------------------------------------- | ------------------------------------------------------------- |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters) |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                     |

***

### Events

This section provides the methods you use to handle events.

<Tabs defaultTabIndex={0}>
  <Tab title="SDK Version 10">
    #### 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.

    <Tabs defaultTabIndex={0}>
      <Tab title="TypeScript">
        ```tsx theme={null}
        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 execute on SDK event
            onEvent(EventType.Evaluation, (eventData: EventDataType) => {
              // -- My Logic
            });
          }, [initialize, onEvent]);

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```jsx theme={null}
        import { useEffect, useCallback } from 'react';
        import { useInitialize, EventType } from '@kameleoon/react-sdk';

        function MyComponent() {
          const { initialize, onEvent } = useInitialize();

          const init = useCallback(async () => {
            await initialize();

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

          useEffect(() => {
            init();
          }, [init]);
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      You can only assign one callback to each `EventType`.
    </Note>

    ##### Events

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

    | Type                            | `eventData` type                   | Description                                                                                                           |
    | ------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
    | `EventType.Evaluation`          | `EvaluationEventDataType`          | Triggered when the SDK evaluates any variation for a feature flag. It is triggered regardless of the result variation |
    | `EventType.ConfigurationUpdate` | `ConfigurationUpdateEventDataType` | Triggered when the SDK receives a configuration update from the server (when using real-time streaming)               |

    ##### Parameters

    | Name                                                   | Type                                            | Description                                                                                               |
    | ------------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
    | event <Badge color="red" size="sm">required</Badge>    | `EventType`                                     | a type of the event to associate the callback action with                                                 |
    | callback <Badge color="red" size="sm">required</Badge> | `(eventData: EventDataType<EventType>) => void` | a callback function with the `eventData` parameter that will be called when a configuration update occurs |

    ##### Exceptions thrown

    | Type                                | Description                                                                       |
    | ----------------------------------- | --------------------------------------------------------------------------------- |
    | `KameleoonException.Initialization` | Method 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...](/user-manual/integrations/integrations-overview). 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](/developer-docs/feature-experimentation/get-started/hybrid-experimentation).

    <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.
    </Note>
  </Tab>
</Tabs>

### Data types

Kameleoon Data types are helper classes used for storing data in storage in predefined forms.
During the [flush](#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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) for more information.

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

#### Browser

<Note>
  Since React SDK `10.11.0`, `Browser` is automatically detected based on the `User-Agent` string. However, you can still manually override it if needed.
</Note>

Browser contains browser information.

<Note>
  Each visitor can only have one `Browser`. Adding a second `Browser` overwrites the first one.
</Note>

| Name                                                    | Type          | Description                                                                                     |
| ------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| browser <Badge color="red" size="sm">required</Badge>   | `BrowserType` | predefined browser type (`Chrome`, `InternetExplorer`, `Firefox`, `Safari`, `Opera`, `Other`)   |
| version <Badge color="green" size="sm">optional</Badge> | `number`      | version of the browser, floating point number represents major and minor version of the browser |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      Browser,
      BrowserType,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        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]);
    }
    ```
  </Tab>
</Tabs>

***

#### UniqueIdentifier

`UniqueIdentifier` data is used as marker for unique visitor identification.

If you add `UniqueIdentifier` for a visitor, `visitorCode` is used as the unique visitor identifier, which is useful for [Cross-device experimentation](/developer-docs/cross-device-experimentation). Associating a `UniqueIdentifier` with a visitor notify SDK that the visitor is linked to another visitor.

The `UniqueIdentifier` 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.

<Note>
  Each visitor can only have one `UniqueIdentifier`. Adding another `UniqueIdentifier` overwrites the first one.
</Note>

| Name                                                | Type      | Description                                                                                                                                                   |
| --------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value <Badge color="red" size="sm">required</Badge> | `boolean` | value that specifies if the visitor is associated with another visitor, provided `false` will imply that the visitor is not associated with any other visitor |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, UniqueIdentifier } from '@kameleoon/react-sdk';

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

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

        // -- Add new unique identifier to a visitor
        addData('my_visitor_code', new UniqueIdentifier(true));
      }, [initialize, addData]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, UniqueIdentifier } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

        // -- Add new unique identifier to a visitor
        addData('my_visitor_code', new UniqueIdentifier(true));
      }, [initialize, addData]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

***

#### Conversion

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

<Tip>
  * Each visitor can have multiple `Conversion` objects.
  * You can find the `goalId` in the Kameleoon app.
</Tip>

`ConversionParametersType` conversionParameters - an object with conversion parameters described below

| Name                                                       | Type           | Description                                     | Default     |
| ---------------------------------------------------------- | -------------- | ----------------------------------------------- | ----------- |
| `goalId` <Badge color="red" size="sm">required</Badge>     | `number`       | ID of the goal.                                 |             |
| `revenue` <Badge color="green" size="sm">optional</Badge>  | `float`        | Revenue of the conversion                       | `0`         |
| `negative` <Badge color="green" size="sm">optional</Badge> | `boolean`      | Defines if the revenue is positive or negative. | `false`     |
| `metadata` <Badge color="green" size="sm">optional</Badge> | `CustomData[]` | Metadata of the conversion.                     | `undefined` |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      Conversion,
      ConversionParametersType,
      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 conversionParameters: ConversionParametersType = {
          goalId: 123,
          revenue: 10000,
          negative: true,
          metadata: [new CustomData(0, 'value')],
        };

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, Conversion, CustomData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

        // -- Defined conversion parameters
        const conversionParameters = {
          goalId: 123,
          revenue: 10000,
          negative: true,
          metadata: [new CustomData(0, 'value')],
        };

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

#### Cookie

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

  * Each visitor can only have one `Cookie`. Adding a second `Cookie` overwrites the first one.
</Note>

| Name                                                 | Type           | Description                                                         |
| ---------------------------------------------------- | -------------- | ------------------------------------------------------------------- |
| cookie <Badge color="red" size="sm">required</Badge> | `CookieType[]` | A list of `CookieType` objects consisting of cookie keys and values |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import {
      KameleoonClient,
      CookieType,
      Cookie,
      useInitialize,
      useData,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

        // -- Add new cookie data to client
        const cookieData = [
          { 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]);
    }
    ```
  </Tab>
</Tabs>

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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' },
    // ]
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import { Cookie } from '@kameleoon/react-sdk';

    const cookieString = 'key_1=value_1; key_2=value_2';
    const 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' },
    // ]
    ```
  </Tab>
</Tabs>

#### GeolocationData

`GeolocationData` contains the visitor's geolocation details

<Note>
  Each visitor can only have one `GeolocationData`. Adding a second `GeolocationData` overwrites the first one.
</Note>

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

| Name                                                        | Type               | Description                                                                                                           |
| ----------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| country <Badge color="red" size="sm">required</Badge>       | `string`           | The country of the visitor                                                                                            |
| region <Badge color="green" size="sm">optional</Badge>      | `string`           | The region of the visitor                                                                                             |
| city <Badge color="green" size="sm">optional</Badge>        | `string`           | The city of the visitor                                                                                               |
| postalCode <Badge color="green" size="sm">optional</Badge>  | `string`           | The postal code of the visitor                                                                                        |
| coordinates <Badge color="green" size="sm">optional</Badge> | `[number, number]` | Coordinates array tuple of two position values (longitude and latitude). Coordinate number represents decimal degrees |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    import {
      KameleoonClient,
      GeolocationData,
      useData,
      useInitialize,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

        // -- Add geolocation data
        const geolocationInfo = {
          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]);
    }
    ```
  </Tab>
</Tabs>

***

#### CustomData

To retain custom data for future visits, the SDK transmits `CustomData` with a `Visitor` scope during the next tracking request. You can configure the scope in the data settings on the [custom data dashboard](https://app.kameleoon.com/customData/dashboard).

`CustomData` allows you to associate any type of data with each visitor easily. This data can then be used as a targeting condition in [segments](/user-manual/assets/segments/create-a-segment/) or as a filter or breakdown in experiment reports.

For more information about custom data, please refer to this [article](/developer-docs/custom-data).

| Name                                                      | Type              | Description                                                                                                                                                                             | Default |
| --------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| index/name <Badge color="red" size="sm">required</Badge>  | `number`/`string` | Index or Name of the custom data. **Either `index` or `name` must be provided** to identify the data.                                                                                   |         |
| overwrite <Badge color="green" size="sm">optional</Badge> | `boolean`         | Flag to explicitly control how the values are stored and how they appear in reports. [See more](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true`  |
| value <Badge color="red" size="sm">required</Badge>       | `string[]`        | The custom data value. It must be stringified to match the `string` type. *Note:* value is variadic.                                                                                    |         |

<Note>
  * Each visitor is allowed only one `CustomData` for each unique `index`. Adding another `CustomData` with the same `index` will replace the existing one.

  * The custom data ‘index’ can be found in the [Custom Data dashboard](/user-manual/assets/custom-data/manage-custom-data) under the “INDEX” column.

  * To prevent the SDK from sending data with the selected index to Kameleoon servers for privacy reasons, enable the option: **Use this data only locally for targeting purposes** when creating custom data.

  * Adding a `CustomData` instance created with a name when the SDK instance is not initialized or the name is not registered, will result in the data being ignored.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 overwrite flag
        const customData = new CustomData(customDataIndex, false, dataItemOne);

        // -- Create custom data using name instead of index
        const customData = new CustomData('customDataName', 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);

        // -- Create custom data using overwrite flag
        const customData = new CustomData(customDataIndex, false, ...dataList);

        // -- Create custom data using name instead of index
        const customData = new CustomData('customDataName', false, ...dataList);

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, CustomData } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        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 overwrite flag
        const customData = new CustomData(customDataIndex, false, dataItemOne);

        // -- Create custom data using name instead of index
        const customData = new CustomData('customDataName', 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);

        // -- Create custom data using overwrite flag
        const customData = new CustomData(customDataIndex, false, ...dataList);

        // -- Create custom data using name instead of index
        const customData = new CustomData('customDataName', false, ...dataList);

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

***

#### Device

<Note>
  Since React SDK `10.11.0`, `Device` is automatically detected based on the `User-Agent` string. However, you can still manually override it if needed.

  **React Native:** Support for this feature is currently experimental and may require adjustments to work correctly. In React Native, the `Device` is automatically detected based on the `DPI` from `react-native.Dimensions`.
</Note>

Device contains information about your device.

<Note>
  Each visitor can only have one `Device`. Adding a second `Device` overwrites the first one.
</Note>

| Name                                                     | Type         | Description                                                   |
| -------------------------------------------------------- | ------------ | ------------------------------------------------------------- |
| deviceType <Badge color="red" size="sm">required</Badge> | `DeviceType` | possible types for device type (`PHONE`, `TABLET`, `DESKTOP`) |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      Device,
      DeviceType,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

***

#### OperatingSystem

<Note>
  Since React SDK `10.11.0`, `OperatingSystem` is automatically detected based on the `User-Agent` string. However, you can still manually override it if needed.

  **React Native:** Support for this feature is currently experimental and may require adjustments to work correctly. In React Native, the `OperatingSystem` is automatically detected based on the `react-native.Platform`.
</Note>

`OperatingSystem` contains the visitor's operating system information.

<Note>
  Each visitor can only have one `OperatingSystem`. Adding a second `OperatingSystem` overwrites the previous one.
</Note>

| Name                                                          | Type                  | Description                                                                                  |
| ------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------- |
| operatingSystem <Badge color="red" size="sm">required</Badge> | `OperatingSystemType` | possible types for device type: `WINDOWS_PHONE`, `WINDOWS`, `ANDROID`, `LINUX`, `MAC`, `IOS` |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      OperatingSystem,
      OperatingSystemType,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

***

#### PageView

<Note>
  Since React SDK `10.11.0`, `PageView` is automatically detected based on the `window.location?.href` and `document.title`. However, you can still manually override it if needed.

  **React Native:** Support for this feature is currently experimental and may require adjustments to work correctly.
</Note>

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
</Note>

`PageViewParametersType` pageViewParameters - an object with page view parameters described below

| Name                                                     | Type       | Description                                                                        |
| -------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| urlAddress <Badge color="red" size="sm">required</Badge> | `string`   | url address of the page to track                                                   |
| title <Badge color="red" size="sm">required</Badge>      | `string`   | title of the web page                                                              |
| referrer <Badge color="green" size="sm">optional</Badge> | `number[]` | an optional parameter containing a list of referrers Indices, has no default value |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, PageView } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        await initialize();

        // -- Define page view parameters
        const pageViewParameters = {
          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]);
    }
    ```
  </Tab>
</Tabs>

***

#### 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](/user-manual/faq#how-does-kameleoon-filter-bot-traffic-from-my-results).

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.
</Note>

| Name                                                | Type     | Description               |
| --------------------------------------------------- | -------- | ------------------------- |
| value <Badge color="red" size="sm">required</Badge> | `string` | value used for comparison |

<Warning>
  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.
</Warning>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useData, UserAgent } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        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]);
    }
    ```
  </Tab>
</Tabs>

#### ApplicationVersion

`ApplicationVersion` represents the semantic version number of your application.

<Tip>
  A **visitor** can have only one `ApplicationVersion`. Adding a second instance will overwrite the first one.
</Tip>

| Name                                                    | Type     | Description                                                                                                                                      |
| ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| version <Badge color="green" size="sm">optional</Badge> | `string` | The mobile application version. This field must follow semantic versioning. Accepted formats are `major`, `major.minor`, or `major.minor.patch`. |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useData,
      ApplicationVersion,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { addData } = useData();

      const init = useCallback(async () => {
        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]);
    }
    ```
  </Tab>
</Tabs>

***

### Returned Types

#### DataFile

The `DataFile` contains the SDK configuration details.

It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

| Name           | Type                       | Description                                                                       |
| -------------- | -------------------------- | --------------------------------------------------------------------------------- |
| `featureFlags` | `Map<string, FeatureFlag>` | A map of [`FeatureFlag`](#featureflag) objects, keyed by feature flag keys.       |
| `dateModified` | `number`                   | The timestamp (in milliseconds) indicating when the `DataFile` was last modified. |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { FeatureFlag } from '@kameleoon/javascript-sdk';

    // Retrieves the map of feature flags from the DataFile.
    // The map is keyed by feature flag identifiers, with each value being a FeatureFlag object.
    const featureFlags: Map<string, FeatureFlag> = dataFile.featureFlags;

    // Retrieves the last modification timestamp of the DataFile.
    // The value is a number representing milliseconds since the Unix epoch.
    const dateModified: number = dateFile.dateModified;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // Retrieves the map of feature flags from the DataFile.
    // The map is keyed by feature flag identifiers, with each value being a FeatureFlag object.
    const featureFlags = dataFile.featureFlags;

    // Retrieves the last modification timestamp of the DataFile.
    // The value is a number representing milliseconds since the Unix epoch.
    const dateModified = dateFile.dateModified;
    ```
  </Tab>
</Tabs>

#### FeatureFlag

The `FeatureFlag` represents a set of properties that define a feature flag itself — for example, its [`Variations`](#variation), [`Rules`](#rule), environment status, and other related details.

It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

| Name                  | Type                     | Description                                                                |
| --------------------- | ------------------------ | -------------------------------------------------------------------------- |
| `environmentEnabled`  | `boolean`                | Indicating whether the feature flag is enabled in the current environment. |
| `defaultVariationKey` | `string`                 | The key of the default variation associated with the feature flag.         |
| `variations`          | `Map<string, Variation>` | A map of `Variation` objects, keyed by variation keys.                     |
| `rules`               | `Rule[]`                 | A list of `Rule` objects                                                   |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { Variation, Rule } from '@kameleoon/react-sdk';

    // Check whether the feature flag is enabled in the current environment
    const isEnvironmentEnabled: boolean = featureFlag.environmentEnabled;

    // Retrieve the key of the default variation
    const defaultVariationKey: string = featureFlag.defaultVariationKey;

    // Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
    const variations: Map<string, Variation> = featureFlag.variations;

    // Retrieve all targeting rules associated with the feature flag
    const rules: Rule[] = featureFlag.rules;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // Check whether the feature flag is enabled in the current environment
    const isEnvironmentEnabled = featureFlag.environmentEnabled;

    // Retrieve the key of the default variation
    const defaultVariationKey = featureFlag.defaultVariationKey;

    // Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
    const variations = featureFlag.variations;

    // Retrieve all targeting rules associated with the feature flag
    const rules = featureFlag.rules;
    ```
  </Tab>
</Tabs>

#### Rule

The `Rule` represents a set of properties that define a rule itself — for example, its [`Variations`](#variation).

It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

| Name         | Type                     | Description                                            |
| ------------ | ------------------------ | ------------------------------------------------------ |
| `variations` | `Map<string, Variation>` | A map of `Variation` objects, keyed by variation keys. |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    import { Variation } from '@kameleoon/react-sdk';

    // Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
    const variations: Map<string, Variation>  = rule.variations;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
    const variations  = rule.variations;
    ```
  </Tab>
</Tabs>

#### Variation

`Variation` contains information about the assigned variation to the visitor (or the default variation, if no specific assignment exists).

| Name         | Type                    | Description                                                                                         |
| ------------ | ----------------------- | --------------------------------------------------------------------------------------------------- |
| name         | `string`                | name of the variation.                                                                              |
| key          | `string`                | key of the variation.                                                                               |
| id           | `number` or `null`      | id of the variation or `null` if the visitor landed on the default variation.                       |
| experimentId | `number` or `null`      | id of the experiment or `null` if the visitor landed on the default variation.                      |
| variables    | `Map<string, Variable>` | map of variables for the variation, where key is the variable key and value is the variable object. |

<Note>
  * Ensure that your code handles the case where `id` or `experimentId` may be `null`, indicating a default variation.
  * The `variables` map might be empty if no variables are associated with the variation.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    // Retrieving the variation name
    const variationName = variation.name;

    // Retrieving the variation key
    const variationKey = variation.key;

    // Retrieving the variation id
    const variationId = variation.id;

    // Retrieving the experiment id
    const experimentId = variation.experimentId;

    // Retrieving the variables map
    const variables = variation.variables;
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // Retrieving the variation name
    const variationName = variation.name;

    // Retrieving the variation key
    const variationKey = variation.key;

    // Retrieving the variation id
    const variationId = variation.id;

    // Retrieving the experiment id
    const experimentId = variation.experimentId;

    // Retrieving the variables map
    const variables = variation.variables;
    ```
  </Tab>
</Tabs>

#### Variable

`Variable` contains information about a variable associated with the assigned variation.

| Name  | Type     | Description                                                                                                                                |
| ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| key   | `string` | The unique key identifying the variable.                                                                                                   |
| type  | `string` | The type of the variable. Possible values: **BOOLEAN**, **NUMBER**, **STRING**, **JSON**, **JS**, **CSS**.                                 |
| value | `any`    | The value of the variable, which can be of the following types: **boolean**, **number**, **String**, **Record\<string, any>**, **any\[]**. |

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```ts theme={null}
    // Retrieving the variables map
    const variables = variation.variables;

    // Variable type can be retrieved for further processing
    const type = variables.get('isDiscount')?.type || '';

    // Retrieving the variable value by key
    const isDiscount = variables.get('isDiscount')?.value || false;

    // Variable value can be of different types
    const title = variables.get('title')?.value || '';
    ```
  </Tab>

  <Tab title="JavaScript">
    ```js theme={null}
    // Retrieving the variables map
    const variables = variation.variables;

    // Variable type can be retrieved for further processing
    const type = variables.get('isDiscount')?.type || '';

    // Retrieving the variable value by key
    const isDiscount = variables.get('isDiscount')?.value || false;

    // Variable value can be of different types
    const title = variables.get('title')?.value || '';
    ```
  </Tab>
</Tabs>

### Deprecated methods

<Warning>
  These methods are deprecated and will be removed in the next major update.
</Warning>

#### getFeatureFlagVariationKey()

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

<Note>
  Use the [`getVariation`](#getvariation) method.
</Note>

The method `getFeatureFlagVariationKey()`, which is used with the `useFeatureFlag` hook, retrieves the variation key for a visitor identified by their `visitorCode`. This process includes checking the targeting criteria, identifying the appropriate variation assigned to the visitor, storing this information, and sending a tracking request.

<Note>
  If a user has never been associated with a feature flag, the SDK will randomly return a variation key according to the rules of that feature flag. If the user is already linked to the feature flag, the SDK will identify the previously assigned variation key. If the user does not meet any of the specified rules, the SDK will return the default value defined in Kameleoon’s feature flag delivery rules. It’s important to note that the default value may not always be a variation key; it could also be a boolean value or another data type, depending on how the feature flag is configured.
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 feature flag.
        const variationKey = getFeatureFlagVariationKey(visitorCode, featureKey);
      }, [initialize, visitorCode, getFeatureFlagVariationKey, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

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

      const init = useCallback(async () => {
        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]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                      | Type     | Description                                                              |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length |
| featureKey <Badge color="red" size="sm">required</Badge>  | `string` | a unique key for feature flag                                            |

##### Return value

| Type     | Description                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------- |
| `string` | a string containing variable key for the allocated feature flag variation for the provided visitor. |

##### Exceptions thrown

| Type                                                  | Description                                                            |
| ----------------------------------------------------- | ---------------------------------------------------------------------- |
| `KameleoonException.Initialization`                   | Method was executed before `initialize` was done for `kameleoonClient` |
| `KameleoonException.VisitorCodeMaxLength`             | The visitor code exceeded the maximum length (255 characters)          |
| `KameleoonException.VisitorCodeEmpty`                 | The visitor code is empty                                              |
| `KameleoonException.FeatureFlagConfigurationNotFound` | No feature flag was found for the specified `featureKey`               |
| `KameleoonException.FeatureFlagEnvironmentDisabled`   | Feature flag is disabled for the current environment                   |

#### getVisitorFeatureFlags()

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

<Note>
  Use the [`getVariations`](#getvariations) method.
</Note>

The `getVisitorFeatureFlags` method, utilized with the `useFeatureFlag` hook, returns a list of *active* feature flags that target the visitor associated with the `visitorCode` (the visitor must have one of the allocated variations).

<Warning>
  This method only collects the feature flags that are currently active for the visitor. As a result, it does not include any feature flags for which the visitor is assigned to the “off” variation (default or control). If you need to retrieve all of the visitor’s feature flags, use `getFeatureFlags` instead.

  For example:

  ```ts theme={null}
  // -- `getVisitorFeatureFlags` doesn't trigger feature experiments;
  //    it only returns feature flags where visitors didn't get the `off` variation.
  getVisitorFeatureFlags('my_visitor').forEach(({ key }) => {
    // -- `getFeatureFlagVariationKey` triggers a feature experiment,
    //    as `off` is already filtered out - visitors will never take part
    //    in an experiment where the `off` variation was allocated.
    getFeatureFlagVariationKey('my_visitor', key);
  });
  ```

  For cases where you need all of the visitor's feature flags, use [`getFeatureFlags`](#getfeatureflags) instead:

  ```ts theme={null}
  // -- Both `off` and other variations are processed as expected
  getFeatureFlags('my_visitor').forEach(({ key }) => {
    getFeatureFlagVariationKey('my_visitor', key);
  });
  ```
</Warning>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { getVisitorFeatureFlags } = useFeatureFlag();

      const init = useCallback(async () => {
        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]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                      | Type     | Description                                                              |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length |

##### Return value

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

##### Exceptions thrown

| Type                                      | Description                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed it's `initialize` call |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length (255 characters)                     |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                                         |
| `KameleoonException.StorageRead`          | Error while reading storage data                                                  |

***

#### getActiveFeatureFlags()

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

<Note>
  Use the [`getVariations`](#getvariations) method.
</Note>

The `getActiveFeatureFlags` method, 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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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();
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    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();
    ```
  </Tab>
</Tabs>

<Warning>
  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](#getvisitorfeatureflags) *CAUTION* section method for more details.
</Warning>

##### Parameters

| Name                                                      | Type     | Description                                                              |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length |

##### Return value

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

##### Exceptions thrown

| Type                                      | Description                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`       | Method was executed before the `kameleoonClient` completed it's `initialize` call |
| `KameleoonException.VisitorCodeMaxLength` | The visitor code exceeded the maximum length of 255 characters                    |
| `KameleoonException.VisitorCodeEmpty`     | The visitor code is empty                                                         |
| `KameleoonException.StorageRead`          | Error while reading storage data                                                  |
| `KameleoonException.NumberParse`          | Couldn't parse Number value                                                       |
| `KameleoonException.JSONParse`            | Couldn't parse JSON value                                                         |

***

#### getFeatureFlagVariable()

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

<Note>
  Use the [`getVariation`](#getvariation) method.
</Note>

The `getFeatureFlagVariable` method, 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.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 its `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:
          case VariableType.JS:
          case VariableType.CSS:
            const myStr: string = result.value;
            break;
          default:
            break;
        }
      }, [initialize, getFeatureFlagVariable, visitorCode, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useVisitorCode,
      useFeatureFlag,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { getFeatureFlagVariable } = useFeatureFlag();

      const init = useCallback(async () => {
        await initialize();

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

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

        const { type, value } = variableResult;
      }, [initialize, getFeatureFlagVariable, visitorCode, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

Parameters object of type `GetFeatureFlagVariableParamsType` containing the following fields:

| Name                                                      | Type     | Description                                                                                                            |
| --------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length                                               |
| featureKey <Badge color="red" size="sm">required</Badge>  | `string` | a unique key for feature flag                                                                                          |
| variableKey <Badge color="red" size="sm">required</Badge> | `string` | key of the variable to be found for a feature flag with the specified `featureKey`, can be found on Kameleoon Platform |

##### Return value

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

##### Exceptions thrown

| Type                                                  | Description                                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`                   | Method was executed before `initialize` was done for `kameleoonClient`          |
| `KameleoonException.VisitorCodeMaxLength`             | The visitor code exceeded the maximum length (255 characters)                   |
| `KameleoonException.VisitorCodeEmpty`                 | The visitor code is empty                                                       |
| `KameleoonException.FeatureFlagConfigurationNotFound` | No feature flag was found for the specified `featureKey`                        |
| `KameleoonException.FeatureFlagVariableNotFound`      | No feature variable was found for the specified `visitorCode` and `variableKey` |
| `KameleoonException.FeatureFlagEnvironmentDisabled`   | Feature flag is disabled for the current environment                            |
| `KameleoonException.JSONParse`                        | Couldn't parse JSON value                                                       |
| `KameleoonException.NumberParse`                      | Couldn't parse Number value                                                     |

#### getFeatureFlagVariables()

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

<Note>
  Use the [`getVariations`](#getvariations) method.
</Note>

The `getFeatureFlagVariables` method, collected with the `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.

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 feature flag
        const variables = getFeatureFlagVariables(visitorCode, 'my_feature_key');
      }, [initialize, getFeatureFlagVariables, getVisitorCode]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import {
      useInitialize,
      useFeatureFlag,
      useVisitorCode,
    } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getVisitorCode } = useVisitorCode();
      const { getFeatureFlagVariables } = useFeatureFlag();

      const init = useCallback(async () => {
        await initialize();

        // -- Get visitor code
        const visitorCode = getVisitorCode('www.example.com');

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                      | Type     | Description                                                              |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode <Badge color="red" size="sm">required</Badge> | `string` | unique visitor identification string, can't exceed 255 characters length |
| featureKey <Badge color="red" size="sm">required</Badge>  | `string` | a unique key for feature flag                                            |

##### Return value

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

##### Exceptions thrown

| Type                                                  | Description                                                                       |
| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
| `KameleoonException.Initialization`                   | Method was executed before the `kameleoonClient` completed it's `initialize` call |
| `KameleoonException.VisitorCodeMaxLength`             | The visitor code exceeded the maximum length (255 characters)                     |
| `KameleoonException.VisitorCodeEmpty`                 | The visitor code is empty                                                         |
| `KameleoonException.FeatureFlagConfigurationNotFound` | No feature flag was found for the specified `featureKey`                          |
| `KameleoonException.FeatureFlagVariationNotFound`     | No feature variation was found for the specified `visitorCode` and `variableKey`  |
| `KameleoonException.FeatureFlagEnvironmentDisabled`   | Feature flag is disabled for the current environment                              |
| `KameleoonException.JSONParse`                        | Couldn't parse JSON value                                                         |
| `KameleoonException.NumberParse`                      | Couldn't parse Number value                                                       |

***

#### onConfigurationUpdate()

<Note>
  Use the `onEvent` method with `EventType.ConfigurationUpdate` instead.
</Note>

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
</Note>

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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 execute on client configuration update
        onConfigurationUpdate(() => {
          // -- My Logic
        });
      }, [initialize, onConfigurationUpdate]);

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize, onConfigurationUpdate } = useInitialize();

      const init = useCallback(async () => {
        await initialize();

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Parameters

| Name                                                   | Type         | Description                                                                        |
| ------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------- |
| callback <Badge color="red" size="sm">required</Badge> | `() => void` | callback function with no parameters that will be called upon configuration update |

##### Exceptions thrown

| Type                                | Description                                                                      |
| ----------------------------------- | -------------------------------------------------------------------------------- |
| `KameleoonException.Initialization` | Method was executed before the `kameleoonClient` completed its `initialize` call |

***

#### getFeatureFlags()

🚫 *Doesn't send Tracking Data to Kameleoon*

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

<Tabs defaultTabIndex={0}>
  <Tab title="TypeScript">
    ```tsx theme={null}
    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]);
    }
    ```
  </Tab>

  <Tab title="JavaScript">
    ```jsx theme={null}
    import { useEffect, useCallback } from 'react';
    import { useInitialize, useFeatureFlag } from '@kameleoon/react-sdk';

    function MyComponent() {
      const { initialize } = useInitialize();
      const { getFeatureFlags } = useFeatureFlag();

      const init = useCallback(async () => {
        await initialize();

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

      useEffect(() => {
        init();
      }, [init]);
    }
    ```
  </Tab>
</Tabs>

##### Return value

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

##### Exceptions thrown

| Type                                | Description                                                                       |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| `KameleoonException.Initialization` | Method was executed before the `kameleoonClient` completed it's `initialize` call |