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

# Target users with native segmentation criteria

> Trigger feature flags based on specific criteria and manage visitor data across SDK environments.

Kameleoon targeting conditions trigger feature flags based on specific criteria. To use these conditions effectively, set their values with the `addData()` method. In some scenarios, call `getRemoteVisitorData()` to retrieve historical visitor data. This combination creates highly targeted and personalized experiences.

## Manage data in Kameleoon SDKs

Accurate data ensures consistent targeting and experimentation. The following sections explain how client-side and server-side SDKs manage targeting conditions and specify when to use `getRemoteVisitorData()` to fetch data from the server.

### Key terminology

* **Targeting condition**: The specific user or session attribute used for targeting, such as conversion, browser, or custom data.
* **Client-side**: Data handling for standard SDKs operating in a web browser or mobile app.
* **Client-side (Cross-device)**: Data handling for client-side implementations that maintain a consistent visitor profile across multiple devices.
* **Server-side**: Data handling when the SDK runs on a backend server. Unlike client-side SDKs, server-side SDKs typically delete visitor information after a session ends.
* **web only**: A targeting condition based on data that only a browser generates, such as the page URL or page title. Web SDKs collect this data automatically. The Android, iOS, and Flutter SDKs don't support these conditions because no browser generates the data. The React Native SDK has experimental support for them. Server-side SDKs do support these conditions: they receive the data through `addData()` or retrieve it from a prior web session with `getRemoteVisitorData()`.

## Data collection requirements

The SDK requires specific visitor data to evaluate targeting conditions. The table below identifies which criteria the SDK handles automatically and which require an explicit method call.

> [!NOTE]
>
> "web only" labels the origin of the data, not which SDKs can use it. web only conditions come from browser data, so most mobile SDKs don't support them, but server-side SDKs do, through `addData()` or `getRemoteVisitorData()`. The [React Native SDK](https://docs.kameleoon.com/developer-docs/sdks/mobile-sdks/react-native-sdk.md) is the exception among mobile SDKs: it has experimental support for these conditions.

| Targeting condition | Actions (Web) | Actions (Mobile) | Actions (Server-side) |
| :- | :- | :- | :- |
| **Exclusive feature flag** | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` |
| **Exclusive experiment** | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` |
| **Target feature flag** | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` |
| **Target experiment** | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` |
| **Target personalization** | `getRemoteVisitorData()` | `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **Browser (web only)** | Auto-added / `addData()` | Not supported\* | `addData()` / `getRemoteVisitorData()` |
| **Device** | Auto-added / `addData()` | Auto-added / `addData()` | `addData()` / `getRemoteVisitorData()` |
| **Operating system** | Auto-added / `addData()` | Auto-added | `addData()` / `getRemoteVisitorData()` |
| **Conversion goal** | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` |
| **Custom data** | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` |
| **Page URL (web only)** | Auto-added\* / `addData()` | Not supported\*\* | `addData()` / `getRemoteVisitorData()` |
| **Page title (web only)** | Auto-added\* / `addData()` | Not supported\*\* | `addData()` / `getRemoteVisitorData()` |
| **Previous page (web only)** | Auto-added\* / `addData()` / `getRemoteVisitorData()` | Not supported\*\* | `addData()` / `getRemoteVisitorData()` |
| **Page view count (web only)** | Auto-added\* / `addData()` / `getRemoteVisitorData()` | Not supported\*\* | `addData()` / `getRemoteVisitorData()` |
| **IP geolocation** | `addData()` | `addData()` | `addData()` / `getRemoteVisitorData()` |
| **SDK type** | Auto-added | Auto-added | Auto-added |
| **Time elapsed since first visit** | Auto-added / `getRemoteVisitorData()` | Auto-added / `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **Time elapsed since last visit** | Auto-added / `getRemoteVisitorData()` | Auto-added / `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **Visit number today** | Auto-added / `getRemoteVisitorData()` | Auto-added / `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **Visit number total** | Auto-added / `getRemoteVisitorData()` | Auto-added / `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **New or returning visitor** | Auto-added / `getRemoteVisitorData()` | Auto-added / `getRemoteVisitorData()` | `getRemoteVisitorData()` |
| **Visitor code** | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` | `KameleoonClientFactory.create()` | `isFeatureFlagActive()` / `getVariations` / `getRemoteVisitorData()` |
| **Segment** | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` | `addData()` / `getRemoteVisitorData()` |
| **Browser cookie** | `addData()` | Not supported\*\* | `addData()` |
| **Application version** | `addData()` | Auto-added | `addData()` |
| **Likelihood to convert** | `getRemoteVisitorData()` | `getRemoteVisitorData()` | `getRemoteVisitorData()` |

> [!NOTE]
>
> * \* Automatic data collection does not work in single-page applications (SPAs). In an SPA, you must call the `addData()` method manually.
> * \*\* Not supported in the mobile SDKs (Android, iOS, or Flutter). The React Native SDK has experimental support via `addData()`.

## Use getRemoteVisitorData() for historical data

The following table outlines when a remote call to `getRemoteVisitorData()` is required to retrieve historical data for targeting decisions.

| Targeting condition | Client-side | Client-side (Cross-device) | Server-side |
| :- | :- | :- | :- |
| **Exclusive feature flag** | No | Yes | Yes |
| **Exclusive experiment** | No | Yes | Yes |
| **Target feature flag** | No | Yes | Yes |
| **Target experiment** | No | Yes | Yes |
| **Target personalization** | Yes | Yes | Yes |
| **Browser (web only)** | No | No | No |
| **Device** | No | No | No |
| **Operating system** | No | No | No |
| **Conversion goal** | No | Yes | Yes |
| **Custom data** | No | Yes | Yes |
| **Page URL (web only)** | No (Automatic) | No (Automatic) | No/Yes |
| **Page title (web only)** | No (Automatic) | No (Automatic) | No/Yes |
| **Previous page (web only)** | No (Automatic) | Yes | No/Yes |
| **Page view count (web only)** | No (Automatic) | Yes | Yes |
| **IP geolocation** | No | No | No/Yes |
| **SDK type** | No (Automatic) | No (Automatic) | No (Automatic) |
| **Time elapse since first visit** | No (Automatic) | Yes | Yes |
| **Time elapse since last visit** | No (Automatic) | Yes | Yes |
| **Visit number today** | No (Automatic) | Yes | Yes |
| **Visit number total** | No (Automatic) | Yes | Yes |
| **New or returning visitor** | No (Automatic) | Yes | Yes |
| **Visitor code** | No | No | No |
| **Segment** | No (Automatic) | Yes | Yes |
| **Browser cookie** | No | No | No |
| **Application version** | No | No | No |
| **Likelihood to convert** | Yes | Yes | Yes |

### Data handling definitions

#### Client-side SDKs

* **No (Automatic)**: The SDK collects this data automatically. It requires no remote requests or explicit `addData()` calls.
* **No**: The SDK does not collect this data automatically. You must use `addData()`, `trackConversion()`, or evaluation methods like `getVariation()` to add this data. It does not require a remote request.
* **Yes**: You must call `getRemoteVisitorData()`. This requirement applies to data generated on the server (like "Likelihood to convert") or when unifying sessions across multiple devices to retrieve actions from a previous device.

#### Server-side SDKs

* **No (Automatic)**: Applies only to "SDK Type." The SDK collects this automatically.
* **No**: Use `addData()` or `trackConversion()` to provide this data. It does not require a remote request.
* **No/Yes**: You can provide data directly on the server or obtain it via a remote request. This scenario occurs if a client-side SDK has already collected information during the current visit.
* **Yes**: You must call `getRemoteVisitorData()`. Because server-side SDKs have [limited data storage](https://docs.kameleoon.com/developer-docs/feature-experimentation/technical-reference/technical-considerations.md#data-storage), they require a remote call to identify historical actions, such as previous visits or exclusivity for an experiment.

### Benefits of remote data retrieval

Calling `getRemoteVisitorData()` provides the following advantages:

* **Up-to-date information**: Decisions use real-time data from the Data API.
* **Cross-device consistency**: Accesses data collected from other devices or sessions.
* **Historical access**: Retrieves previous user behavior, such as past URL visits, even if the local SDK state has cleared.

> [!NOTE]
>
> Use the `VisitorDataFiltersType` parameter to specify the number of past visits to retrieve or to apply specific criteria filters.

## Edge targeting constraints

Feature flags and experiments evaluated at the edge only have access to the visitor data your integration makes available to the edge worker. An edge request behaves like a server-side SDK evaluation for a brand-new visitor session: the edge worker has no guaranteed memory of any previous request from that visitor, so most targeting conditions have no data to evaluate unless you supply it explicitly.

Getting visitor data into the edge worker so it can evaluate targeting conditions is covered below. Sending the resulting flag and variation decisions back to your origin server is a separate concern, not handled by the `addData()` and cookie mechanism described here. Edge frameworks expose different mechanisms for this; check your own framework's documentation.

### Where visitor data comes from at the edge

Depending on your edge framework, some browser and device data, such as user agent and geolocation, is available directly from the incoming request through the platform's own request-context APIs. Check your framework's documentation for what it exposes. Every other targeting condition, including custom data and visitor history, has no path into the worker unless your integration explicitly supplies it.

Whichever source the data comes from, your integration is responsible for reading it and calling `addData()` with it before evaluating a feature flag or experiment. Kameleoon doesn't collect any of this on your behalf at the edge, including data a framework exposes on the request itself.

### getRemoteVisitorData() at the edge

`getRemoteVisitorData()` works at the edge the same way it does in any server-side evaluation, but it isn't practical for most edge use cases:

* **Latency**: A call to `getRemoteVisitorData()` typically takes 100-200 ms to fetch historical visitor data from the Data API. Flag and variation evaluation itself normally completes in milliseconds, so adding a remote data fetch to every request pushes latency well outside what most edge use cases target.
* **No durable shared memory**: An edge platform can destroy and recreate a worker instance at any time, so caching a `getRemoteVisitorData()` result across requests isn't reliable unless your framework offers durable, cross-request memory to store it in.

See [Use getRemoteVisitorData() for historical data](#use-getremotevisitordata-for-historical-data) for how this method works outside the edge. For most edge use cases, supply the visitor data your targeting conditions need through `addData()` instead, using the approach below.

### Pass visitor data into the edge worker

Because the edge SDK can neither fetch nor retain visitor data on its own, your integration is responsible for making that data available at request time:

1. Collect the visitor attributes upstream, for example during an earlier page load or client-side SDK call.
2. Pass the attributes into the edge request, typically as cookies, since an edge worker can read cookies from the incoming request without making an external call.
3. In the edge worker, read the attributes and call `addData()` with them before evaluating any feature flag or experiment.

```js theme={null}
import { CustomData } from '@kameleoon/nodejs-sdk';

// Inside the edge worker, before evaluating any feature flag
const visitorCode = getCookie(request, 'kameleoonVisitorCode');
const plan = getCookie(request, 'customerPlan');

const customData = new CustomData(1, plan);
client.addData(visitorCode, customData);

const variation = client.getVariation({ visitorCode, featureKey: 'my_feature_key' });
```

Cookies have a practical size limit of approximately 4 KB. Reserve that budget for the visitor attributes your targeting conditions actually need.

### Constraints vary by edge framework and plan

Edge framework capabilities change over time and can depend on your specific plan with a provider, not just which provider you use. External request support, cross-request shared memory, and compute billing all vary between frameworks, and can change between plan tiers or as a provider updates its offering. Check your framework's current documentation and your account's plan details before relying on a specific capability such as an external call or cross-request caching. See [Serverless edge compute starter kits](https://docs.kameleoon.com/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits.md) for the frameworks Kameleoon currently supports.

## Hybrid Experimentation mode

Hybrid Experimentation combines the SDK with the Kameleoon JavaScript snippet to enable advanced targeting. For more details, see the [Hybrid Experimentation](https://docs.kameleoon.com/developer-docs/feature-experimentation/get-started/hybrid-experimentation.md) guide.

**Benefits:**

* Streamlines the implementation process.
* Accesses engine-collected client-side data, such as datalayer variables and front-end goals, directly at the SDK level.

**Requirement:**

* Implement both the SDK and the Kameleoon JavaScript tag.

Calling `getRemoteVisitorData()` in this mode provides access to all data points automatically collected by the Kameleoon engine on the webpage.

## FAQ

> [accordion] When I use addData(), is the data available for targeting right away?
>
> Yes, data is immediately available for targeting. Data is available during the visitor session for server-based SDKs and during the set lifetime for client-based SDKs (mobile and web).

> [accordion] How do I use previously collected data for targeting?
>
> If you have a server-based SDK, it stores data during a visitor's session. You don't need to load the data on every request if the user's session hasn't expired. In mobile SDKs, data persists indefinitely (or according to your settings).
>
> If the user session is no longer active or if the visitor is moving between devices in the client SDK, call the `getRemoteVisitorData` method with the appropriate parameters to get data sent to the Data API. After loading, the SDK includes the data in visitor targeting.

> [accordion] Why doesn't my targeting work when I run feature flags at the edge?
>
> An edge worker has no guaranteed memory of a visitor's previous requests, so it behaves like a server-side SDK evaluating a brand-new visitor session every time. Most targeting conditions have no data to evaluate unless your integration supplies that data explicitly, typically by reading it from a cookie and calling `addData()` before evaluating the feature flag.
>
> `getRemoteVisitorData()` works at the edge, but its latency (typically 100-200 ms) and the lack of durable, cross-request memory in most edge platforms make it impractical for most edge use cases.
>
> See [Edge targeting constraints](#edge-targeting-constraints) for the full explanation and a code example, and [Serverless edge compute starter kits](https://docs.kameleoon.com/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits.md) for the frameworks Kameleoon supports.
