> ## 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.
# NodeJS SDK
> Integrate the Kameleoon Node.js SDK to run experiments and activate feature flags in Node.js server applications.
You can run experiments and activate feature flags with the NodeJS SDK. Integrating our SDK into your server is easy, and its footprint (memory and network usage) is low. Our Node SDK supports Node version 16+ with the option to downgrade it to version 14 and 12 using [compatibility mode](#compatibility-mode).
**Getting started**: For help getting started, see the [developer guide](#developer-guide).
**SDK methods**: For the full reference documentation of the NodeJS SDK, see the [reference](#reference) section.
**Changelog**: Latest version of the NodeJS SDK: 5.26.1 [Changelog](https://github.com/Kameleoon/client-nodejs/blob/main/CHANGELOG.md).
Before you begin installing our NodeJS SDK, we recommend reading our [technical considerations article](/developer-docs/feature-experimentation/technical-reference/technical-considerations) to understand the technological concepts behind our SDKs. This article will help ensure a successful integration.
## Developer Guide
Follow this section to install and configure the SDK and to learn about advanced features.
### Get started
#### Installation
Use the Kameleoon SDK Installation tool to install the SDK. The **SDK Installer** helps you install the SDK of your choice, generate a basic code sample, and configure [external dependencies](#external-dependencies) if needed.
To use 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
```
When using **Deno**, provide dependencies manually in `deno.json`:
```json title=deno.json theme={null}
{
"imports": {
"@kameleoon/nodejs-sdk": "npm:@kameleoon/nodejs-sdk@^4.0",
// -- Optional dependencies, can be implemented manually
"@kameleoon/nodejs-requester": "npm:@kameleoon/nodejs-requester@^1.0",
"@kameleoon/nodejs-event-source": "npm:@kameleoon/nodejs-event-source@^1.0",
"@kameleoon/deno-visitor-code-manager": "npm:@kameleoon/deno-visitor-code-manager@^1.0",
}
}
```
#### Initializing the Kameleoon Client
Developers must create an entry point for the NodeJS SDK by instantiating a new `KameleoonClient`.
It is recommended to treat `KameleoonClient` as a **singleton**, creating a single shared instance and reusing it throughout the server instance to ensure consistency and avoid unnecessary reinitialization.
Use `KameleoonClient` to run feature experiments and retrieve the status of feature flags and their variations.
`KameleoonClient` initializes asynchronously to ensure that communication with the Kameleoon API is successful, using the [`initialize()`](#initialize) method. You can use `async/await`, `Promise.then()`, or any other asynchronous pattern to handle client initialization.
To add NodeJS SDK to an Edge environment, please refer to [this section](#integration-with-edge-providers).
```ts theme={null}
import {
Environment,
KameleoonClient,
SDKConfigurationType,
CredentialsType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
// -- Mandatory credentials
const credentials: CredentialsType = {
clientId: 'my_client_id',
clientSecret: 'my_client_secret',
};
// -- Optional configuration
const configuration: Partial = {
updateInterval: 20,
environment: Environment.Production,
cookieDomain: '.example.com',
};
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials,
configuration,
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
// -- Waiting for the client initialization using `async/await`
async function init(): Promise {
await client.initialize();
}
init();
// -- Waiting for the client initialization using `Promise.then()`
client
.initialize()
.then(() => {})
.catch((error) => {});
```
```js theme={null}
import { Environment, KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
// -- Mandatory credentials
const credentials = {
clientId: 'my_client_id',
clientSecret: 'my_client_secret',
};
// -- Optional configuration
const configuration = {
updateInterval: 20,
environment: Environment.Production,
cookieDomain: '.example.com',
};
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials,
configuration,
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
// -- Waiting for the client initialization using `async/await`
async function init() {
await client.initialize();
}
init();
// -- Waiting for the client initialization using `Promise.then()`
client
.initialize()
.then(() => {})
.catch((error) => {});
```
##### Parameters
| Name | Type | Description |
| ------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| siteCode required | `string` | This is the [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. |
| credentials required | `CredentialsType` | client [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials), see [credentials flow](/developer-docs/apis/automation-api-rest/get-started/get-started#client-credentials-flow) for more information |
| externals required | `ExternalsType` | external implementation of SDK dependencies ([External dependencies](#external-dependencies)) |
| configuration optional | `Partial` | client's configuration |
| compatibility optional | `Compatibility` | SDK's compatibility mode, see [Compatibility Mode](#compatibility-mode) |
| integrations optional | `IntegrationType` | compute edge integrations, see [Integration with Edge providers](#integration-with-edge-providers) |
##### Exceptions thrown
| Type | Description |
| -------------------------------- | ------------------------------------------------- |
| `KameleoonException.Credentials` | Client credentials were not provided or are empty |
##### Configuration Parameters
| Name | Type | Description | Default Value |
| ---------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| updateInterval optional | `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 optional | `Environment` | feature flag environment | `Environment.Production` |
| targetingDataCleanupInterval optional | `number` | interval in *minutes* for cleaning up targeting data, minimum value is 1 minute | `30` |
| domain optional | `string` | [domain](#domain-information) to which the cookie belongs. Deprecated, use `cookieDomain` instead | `undefined` |
| cookieDomain optional | `string` | [domain](#domain-information) to which the cookie belongs. | `undefined` |
| networkDomain optional | `string` | custom domain the SDK uses in all outgoing network requests, commonly used for proxying. The format is `second_level_domain.top_level_domain` (for example, `example.com`). The SDK uses the default Kameleoon value if the format is invalid. | `undefined` |
| requestTimeout optional | `number` | timeout in *milliseconds* for all SDK network requests, if timeout is exceeded request will fail | `10_000` (10 seconds) |
| trackingInterval optional | `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. The tracking request is performed once per interval. The minimum value is `100` ms and the maximum value is `1_000` ms | `1_000` (1 second) |
The `domain` parameter is deprecated and will be removed in the future. Use `cookieDomain` instead.
| Name | Type | Description | Default Value |
| ---------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| updateInterval optional | `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 optional | `Environment \| string` | feature flag environment | `Environment.Production` |
| targetingDataCleanupInterval optional | `number` | interval in *minutes* for cleaning up targeting data, minimum value is 1 minute | `30` |
| cookieDomain optional | `string` | [domain](#domain-information) that the cookie belongs to. | `undefined` |
| networkDomain optional | `string` | The custom domain the SDK uses in all outgoing network requests, commonly used for proxying. The format is `second_level_domain.top_level_domain` (for example, `example.com`). The SDK uses the default Kameleoon value if the format is invalid. | `undefined` |
| requestTimeout optional | `number` | timeout in *milliseconds* for all SDK network requests, if timeout is exceeded request will fail immediately | `10_000` (10 seconds) |
| trackingInterval optional | `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. The tracking request is performed once per interval. The minimum value is `1_000` ms and the maximum value is `5_000` ms | `1_000` (1 second) |
| defaultDataFile optional | `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/` 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` |
**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}`
};
```
##### Compatibility Mode
Use the SDK parameter `compatibility` to disable some of the SDK's features to improve compatibility with older NodeJS versions.
`Compatibility` is an enum representing all possible compatibility modes:
* `Compatibility.Node16` - default mode, all features are enabled. This mode will be used if no compatibility mode is provided. Supports Node version 16 and higher.
* `Compatibility.Node14` - compatibility with this version will make the `requestTimeout` parameter in `SDKConfigurationType` unavailable and prevent the SDK from using `AbortController` for request cancellation, even within default `10_000` ms timeout. Supports Node version 14 and higher.
* `Compatibility.Node12` - compatibility with this version implies the same limitations as the `Node14` compatibility mode. Additionally, you cannot provide "@kameleoon/nodejs-requester" as a requester implementation in this compatibility mode, as it uses the "node-fetch" library, which doesn't support the Node.js 12.x.x version. A developer must provide a custom requester implementation of their choice, such as an older "node-fetch" version or other HTTP based implementation.
#### 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.
To ensure your results are accurate, it's recommended to filter out bots by using the [`UserAgent`](#useragent) data type.
##### 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.
### Error Handling
Almost every `KameleoonClient` method may throw an error at some point. These errors are deliberately predefined `KameleoonError`s
that extend the native JavaScript `Error` class, providing useful messages and a special `type` field with a type `KameleoonException`.
`KameleoonException` is an enum containing all possible error types.
To know exactly what type of `KameleoonException` the method may throw, check the method description's `Throws` section, or hover over the method in your IDE to see the jsdocs description.
Handling errors is considered a good practice to make your application more stable and avoid technical issues.
```ts theme={null}
import {
KameleoonError,
KameleoonClient,
KameleoonException,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
try {
await client.initialize();
const customData = new CustomData(0, 'my_data');
client.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;
}
}
}
}
init();
```
```js theme={null}
import { KameleoonClient, KameleoonException } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
try {
await client.initialize();
const customData = new CustomData(0, 'my_data');
client.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;
}
}
}
init();
```
### Integration with Edge providers
Kameleoon provides the following starter packs to automate your integration with specific edge providers:
| Provider | Starter pack |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Fastly Compute\@Edge | [https://github.com/Kameleoon/fastly-compute-starter-kit](https://github.com/Kameleoon/fastly-compute-starter-kit) |
| Cloudfare Workers | [https://github.com/Kameleoon/cloudflare-worker-starter-kit](https://github.com/Kameleoon/cloudflare-worker-starter-kit) |
| AWS Lambda\@Edge Function | [https://github.com/Kameleoon/aws-lambda-edge-starter-kit](https://github.com/Kameleoon/aws-lambda-edge-starter-kit) |
For the other edge providers, you can initialize the Kameleoon Client yourself using `externalClientConfiguration`. Passing `externalClientConfiguration` causes the SDK to rely solely on the provided configuration data instead of making a call to the Kameleoon servers. `externalClientConfiguration` gives you greater control and flexibility over the configuration data used in your application. For example:
```ts theme={null}
import rp from 'request-promise';
import { KameleoonClient, KameleoonUtils } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
async function init() {
// -- Get Kameleoon Client Configuration URL
const uri = KameleoonUtils.getClientConfigurationUrl('my_site_code');
const clientConfiguration = await rp({
uri,
json: true,
});
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
integrations: {
externalClientConfiguration: clientConfiguration,
},
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
}
init();
```
Kameleoon provides the following starter packs to automate your integration with specific edge providers:
| Provider | Starter pack |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Fastly Compute\@Edge | [https://github.com/Kameleoon/fastly-compute-starter-kit](https://github.com/Kameleoon/fastly-compute-starter-kit) |
| Cloudfare Workers | [https://github.com/Kameleoon/cloudflare-worker-starter-kit](https://github.com/Kameleoon/cloudflare-worker-starter-kit) |
| AWS Lambda\@Edge Function | [https://github.com/Kameleoon/aws-lambda-edge-starter-kit](https://github.com/Kameleoon/aws-lambda-edge-starter-kit) |
For other edge providers, use [External Dependencies](#external-dependencies) for greater control over the SDK.
### 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.
If you want to sync collected data in real time, you need to choose the scope **Visitor** for your custom data.
```ts title="Device One" theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Custom Data with index `0` was set to `Visitor` scope
// in Kameleoon.
const customDataIndex = 0;
const customData = new CustomData(customDataIndex, 'my_data');
client.addData('my_visitor', customData);
client.flush();
}
init();
```
```ts title="Device Two" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.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 available to target and track "my_visitor".
}
init();
```
```ts title="Device One" theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Custom Data with index `0` was set to `Visitor` scope
// in Kameleoon.
const customDataIndex = 0;
const customData = new CustomData(customDataIndex, 'my_data');
client.addData('my_visitor', customData);
client.flush();
}
init();
```
```ts title="Device Two" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.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".
}
init();
```
#### Using custom data for session merging
Cross-device experimentation lets you combine a visitor's history across each of their devices (history reconciliation). You can merge multiple visitor sessions into one with history reconciliation. Use [`CustomData`](#customdata) and provide a unique identifier for the visitor to reconcile visit history.
Follow the [activating cross-device history reconciliation](#cross-device-experimentation) guide to set up your custom data in Kameleoon.
You can use custom data 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 page.
The SDK configuration ensures that associated sessions always see the same variation of the experiment.
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 data for specific visitor that is associated with another visitor.
Since the custom data you use as the identifier must be set to the `Visitor` scope, you must 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.
In the following example, we have an application with a login page. Since we don't know the user ID at the time 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.
```ts title="Login Page" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to re-use it later
global.anonymousVisitor = anonymousVisitor;
// -- Getting a variation, assume it's variation `A`
const variation = client.getVariation({
visitorCode: anonymousVisitor,
featureKey: 'my_feature_key',
});
}
init();
```
```ts title="Application Page" theme={null}
import { CustomData } from '@kameleoon/nodejs-sdk';
async function init(): Promise {
// -- 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');
// -- Taking `visitorCode` from `global` object
client.addData(global.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 = 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
client.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 client.getRemoteVisitorData({
visitorCode: 'my_user_id',
// -- Informing the SDK that the visitor is a unique identifier.
isUniqueIdentifier: true,
});
}
init();
```
```js title="Login Page" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to re-use it later.
global.anonymousVisitor = anonymousVisitor;
// -- Getting a variation, assume it's variation `A`.
const variation = client.getVariation({
visitorCode: anonymousVisitor,
featureKey: 'my_feature_key',
});
}
init();
```
```js title="Application Page" theme={null}
import { CustomData } from '@kameleoon/nodejs-sdk';
async function init() {
// -- 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');
// -- Taking `visitorCode` from `global` object
client.addData(global.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 = 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.
client.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 client.getRemoteVisitorData({
visitorCode: 'my_user_id',
// -- Informing the SDK that the visitor is a unique identifier.
isUniqueIdentifier: true,
});
}
init();
```
Cross-device experimentation lets you combine a visitor's history across each of their devices (history reconciliation). You can merge multiple visitor sessions into one with history reconciliation. Use [`CustomData`](#customdata) and provide a unique identifier for the visitor to reconcile visit history.
Follow the [activating cross-device history reconciliation](#cross-device-experimentation) guide to set up your custom data in Kameleoon.
You can use custom data 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 page.
The SDK configuration ensures that associated sessions always see the same variation of the experiment.
Before using other methods, inform the SDK that the visitor is a unique identifier by adding [`UniqueIdentifier`](#uniqueidentifier) data to a visitor.
Since the custom data you use as the identifier must be set to the `Visitor` scope, you must 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.
In the following example, we have an application with a login page. Since we don't know the user ID at the time 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.
```ts title="Login Page" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to re-use it later.
global.anonymousVisitor = anonymousVisitor;
// -- Getting a variation, assume it's variation `A`.
const variation = client.getVariation({
visitorCode: anonymousVisitor,
featureKey: 'my_feature_key',
});
}
init();
```
```ts title="Application Page" theme={null}
import { CustomData, UniqueIdentifier } from '@kameleoon/nodejs-sdk';
async function init(): Promise {
// -- 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');
// -- Taking `visitorCode` from `global` object
client.addData(global.anonymousVisitor, userIdentifierData);
// -- Flushing data for the anonymous `visitorCode`
client.flush(global.anonymousVisitor);
// -- Informing the SDK that the visitor is a unique identifier.
client.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.
client.trackConversion({
visitorCode: 'my_user_id',
goalId: 123,
revenue: 100,
});
// -- Additionally, linked visitors share previously
// collected remote data.
const data = await client.getRemoteVisitorData({
visitorCode: 'my_user_id',
});
}
init();
```
```js title="Login Page" theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to re-use it later.
global.anonymousVisitor = anonymousVisitor;
// -- Getting a variation, assume it's variation `A`.
const variation = client.getVariation({
visitorCode: anonymousVisitor,
featureKey: 'my_feature_key',
});
}
init();
```
```js title="Application Page" theme={null}
import { CustomData, UniqueIdentifier } from '@kameleoon/nodejs-sdk';
async function init() {
// -- 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');
// -- Taking `visitorCode` from `global` object
client.addData(global.anonymousVisitor, userIdentifierData);
// -- Flushing data for the anonymous `visitorCode`
client.flush(global.anonymousVisitor);
// -- Informing the SDK that the visitor is a unique identifier.
client.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.
client.trackConversion({
visitorCode: 'my_user_id',
goalId: 123,
revenue: 100,
});
// -- Additionally, linked visitors share previously
// collected remote data.
const data = await client.getRemoteVisitorData({
visitorCode: 'my_user_id',
});
}
init();
```
### 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:
```js theme={null}
client.addData(visitorCode, new CustomData(index, 'newVisitorCode'));
```
[More information in addData()](#adddata)
* **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`).
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).
* **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.
```ts theme={null}
import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({ siteCode: 'my_site_code', configuration });
// The `NONE` log level does not allow logging.
client.setLogLevel(LogLevel.NONE);
// Or use directly 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 directly 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);
// 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);
```
```js theme={null}
import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({ 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);
// 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);
```
#### Custom handling of logs
The SDK writes its logs to the console output by default. This behaviour can be overridden.
Logging limiting by a log level is performed apart from the log handling logic.
```ts theme={null}
import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/nodejs-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 = new KameleoonClient({
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);
```
```js theme={null}
import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/nodejs-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 = new KameleoonClient({
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);
```
### Domain information
You provide a domain as the `domain` in `KameleoonClient` [configuration](#initializing-the-kameleoon-client), which is used for storing Kameleoon visitor code in cookies. Providing a domain 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 lets the URL address use the cookie. For example, if your domain is `www.example.com`, the cookie is only available from a `www.example.com` URL. Pages with the `app.example.com` domain can't use the cookie.
For more flexibility with subdomains, you can specify a domain starting with a `.`. For instance, domain `.example.com` allows the cookie to function on both `app.example.com` and `login.example.com`.
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) cannot be used with the prefix `.`.
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
The SDK's external dependencies use the *dependency injection* pattern, letting you provide your own implementations for certain parts of an SDK.
In the NodeJS SDK, some external dependencies have default implementations, while others must be provided by the user, whether using dedicated Kameleoon implementations or custom implementations.
Here's the list of available external dependencies:
| Dependency | Interface | Required/Optional | API Used | Description |
| -------------------- | ----------------------------- | ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `storage` | `IExternalStorage` | *Optional* | Server memory | Used for storing all of the existing and collected SDK data |
| `eventSource` | `IExternalEventSource` | *Required* | - | Used for receiving Server Sent Events for [Real Time Updates](/developer-docs/feature-experimentation/technical-reference/technical-considerations#streaming-premium-option) capabilities |
| `requester` | `IExternalRequester` | *Required* | - | Used for performing all network requests |
| `visitorCodeManager` | `IExternalVisitorCodeManager` | *Required* | - | Used for storing and synchronizing visitor code |
| `logger` | `ILogger` | *Optional* | Custom implementation | Used for custom handling of logs from the SDK. Lets users define how logs are processed and where they output. |
You can also implement `visitorCodeManager` using the `IExternalNextJSVisitorCodeManager`, `IExternalDenoVisitorCodeManager`, or `IExternalCustomVisitorCodeManager` interfaces for NextJS, Deno, or custom visitor code manager implementations, respectively.
External dependencies provide developers flexibility to adapt and use the NodeJS SDK in any environment. There are a number of npm packages Kameleoon provides for frequently used environments. You can install the packages manually, or by using the [SDK installation tool](#installation) (recommended).
These are the Kameleoon-provided external dependencies for NodeJS SDK:
* `@kameleoon/nodejs-event-source` - based on `eventsource` library (can be used for NodeJS/Deno/NextJS SSR)
* `@kameleoon/nodejs-requester` - based on `node-fetch` library (can be used for NodeJS/Deno/NextJS SSR)
* `@kameleoon/nodejs-visitor-code-manager` - implemented with server memory storage
* `@kameleoon/deno-visitor-code-manager` - implemented using Deno request/response cookies
* `@kameleoon/nextjs-visitor-code-manager` - implemented using NextJS SSR `headers` cookie or NextJS SSR request/response
You can optionally implement external dependencies on your own.
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
```ts theme={null}
import { IExternalStorage, KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Storage implementation ---
// - JavaScript `Map` is used as an example storage
const storage = new Map();
class MyStorage implements IExternalStorage {
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 = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
storage: new MyStorage(),
},
});
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-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 = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
storage: new MyStorage(),
},
});
```
#### EventSource
```ts theme={null}
import {
IExternalEventSource,
KameleoonClient,
EventSourceOpenParametersType,
} from '@kameleoon/nodejs-sdk';
// --- External EventSource implementation ---
// - Example uses dummy `EventSource` class
class MyEventSource implements IExternalEventSource {
private eventSource?: EventSource;
public open({
eventType,
onEvent,
url,
}: EventSourceOpenParametersType): void {
// - Initialize `EventSource` (use any event source of your choice here)
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 {
// - Clean up 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 = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
eventSource: new MyEventSource(),
},
});
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External EventSource implementation ---
// - Example uses dummy `EventSource` class
class MyEventSource {
eventSource;
open({ eventType, onEvent, url }) {
// - Initialize `EventSource` (use any event source of your choice here)
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 = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
eventSource: new MyEventSource(),
},
});
```
#### VisitorCodeManager
`visitorCodeManager` implementation for `NodeJS`/`NextJS SSR`:
```ts theme={null}
import {
IExternalVisitorCodeManager,
SetDataParametersType,
GetDataParametersType,
KameleoonClient,
KameleoonUtils,
} from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager implements IExternalVisitorCodeManager {
public getData({ request, key }: GetDataParametersType): string | null {
// - Get cookie from server request
const cookieString = request.headers.cookie;
// - Return `null` if no cookie was found
if (!cookieString) {
return null;
}
// - Parse cookie using the provided `key`
return KameleoonUtils.getCookieValue(cookieString, key);
}
public setData({
visitorCode,
response,
domain,
maxAge,
key,
path,
}: SetDataParametersType): void {
// - Set cookie to request using provided parameters
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
response.setHeader('Set-Cookie', resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
```js theme={null}
import { KameleoonClient, KameleoonUtils } from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager {
getData({ request, key }) {
// - Get cookie from server request
const cookieString = request.headers.cookie;
if (!cookieString) {
return null;
}
// - Return `null` if no cookie was found
if (!cookieString) {
return null;
}
// - Parse cookie using the provided `key`
return KameleoonUtils.getCookieValue(cookieString, key);
}
setData({ visitorCode, response, domain, maxAge, key, path }) {
// - Set cookie to request using provided parameters
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
response.setHeader('Set-Cookie', resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
`visitorCodeManager` implementation for `Deno`:
```ts theme={null}
import {
IExternalDenoVisitorCodeManager,
SetDenoDataParametersType,
GetDenoDataParametersType,
KameleoonClient,
KameleoonUtils,
} from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager implements IExternalDenoVisitorCodeManager {
public getData({ request, key }: GetDenoDataParametersType): string | null {
// - Get cookie from server request
const cookieString = request.headers.get('cookie');
// - Return `null` if no cookie was found
if (!cookieString) {
return null;
}
// - Parse cookie using the provided `key`
return KameleoonUtils.getCookieValue(cookieString, key);
}
public setData({
visitorCode,
response,
domain,
maxAge,
key,
path,
}: SetDenoDataParametersType): void {
// - Set cookie to request using provided parameters
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
response.headers.set('Set-Cookie', resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
```js theme={null}
import { KameleoonClient, KameleoonUtils } from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager {
getData({ request, key }) {
// - Get cookie from server request
const cookieString = request.headers.get('cookie');
// - Return `null` if no cookie was found
if (!cookieString) {
return null;
}
// - Parse cookie finding it by provided `key`
return KameleoonUtils.getCookieValue(cookieString, key);
}
setData({ visitorCode, response, domain, maxAge, key, path }) {
// - Set cookie to request using provided parameters
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
response.headers.set('Set-Cookie', resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
`visitorCodeManager` implementation for `NextJS` Server Actions:
```ts theme={null}
import {
IExternalNextJSVisitorCodeManager,
SetNextJSDataParametersType,
GetNextJSDataParametersType,
KameleoonClient,
} from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `cookies` object imported from "next/headers"
class MyVisitorCodeManager implements IExternalNextJSVisitorCodeManager {
public getData({ cookies, key }: GetNextJSDataParametersType): string | null {
// - Get cookie from server request by provided `key`
const cookie = cookies().get(key);
if (cookie) {
return cookie.value;
}
// - Return `null` if no cookie was found
return null;
}
public setData({
visitorCode,
cookie,
domain,
maxAge,
key,
path,
}: SetNextJSDataParametersType): void {
// - Set cookie to request using provided parameters
cookies().set(key, visitorCode, {
path,
domain,
maxAge,
});
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `cookies` object imported from "next/headers"
class MyVisitorCodeManager {
public getData({ cookies, key }) {
// - Get cookie from server request by provided `key`
const cookie = cookies().get(key);
if (cookie) {
return cookie.value;
}
// - Return `null` if no cookie was found
return null;
}
public setData({
visitorCode,
cookie,
domain,
maxAge,
key,
path,
}){
// - Set cookie to request using provided parameters
cookies().set(key, visitorCode, {
path,
domain,
maxAge,
});
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
Custom `visitorCodeManager` implementation with arbitrary parameters:
```ts theme={null}
import {
IExternalCustomVisitorCodeManager,
SetDataCustomParametersType,
GetDataCustomParametersType,
KameleoonClient,
} from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses custom arbitrary `input` and `output` objects
class MyVisitorCodeManager implements IExternalCustomVisitorCodeManager {
public getData({ input, key }: GetDataCustomParametersType): string | null {
// - Get visitor code from `input` object
// `input` is of type `unknown`, so you can provide any structure.
// In Example, we assume `input` is a `Map` object.
const visitorCode = input.get(key);
if (visitorCode) {
return visitorCode;
}
// - Return `null` if no visitor code was found
return null;
}
public setData({
visitorCode,
output,
domain,
maxAge,
key,
path,
}: SetDataCustomParametersType): void {
// - Set visitor code as a cookie to `output` object using provided parameters.
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
// - `output` is of type `unknown`, so you can provide any structure.
// In Example, we assume `output` is a `Map` object.
output.set(key, resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses custom arbitrary `input` and `output` objects.
class MyVisitorCodeManager {
public getData({ input, key }) {
// - Get visitor code from `input` object
// `input` is of type `unknown`, so you can provide any structure
// In Example, we assume `input` is a `Map` object.
const visitorCode = input.get(key);
if (visitorCode) {
return visitorCode;
}
// - Return `null` if no visitor code was found
return null;
}
public setData({
visitorCode,
output,
domain,
maxAge,
key,
path,
}) {
// - Set visitor code as a cookie to `output` object using provided parameters.
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
// - `output` is of type `unknown`, so you can provide any structure.
// In Example, we assume `output` is a `Map` object.
output.set(key, resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
```
#### Requester
```ts theme={null}
import {
RequestType,
IExternalRequester,
KameleoonResponseType,
SendRequestParametersType,
KameleoonClient,
} from '@kameleoon/nodejs-sdk';
// --- External Requester Implementation
export class MyRequester implements IExternalRequester {
public async sendRequest({
url,
parameters,
}: SendRequestParametersType): Promise {
// - Using native NodeJS `fetch` (for v18+)
return await fetch(url, parameters);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
requester: new MyRequester(),
},
});
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Requester Implementation
export class MyRequester {
async sendRequest({ url, parameters }) {
// - Using native NodeJS `fetch` (for v18+)
return await fetch(url, parameters);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
requester: new MyRequester(),
},
});
```
[Return mocked result](#simulatesuccessrequest)
### Utilities
The SDK has a set of utility methods that you can use to simplify development. All methods are represented as static members of the `KameleoonUtils` class.
#### getClientConfigurationUrl
Use the `getClientConfigurationUrl` method to get the URL for fetching the client configuration. This method is useful for handling edge cases when working with [Edge computing integrations](#integration-with-edge-providers).
This method will soon be deprecated and replaced by custom [`Requester`](#requester) implementation.
```ts theme={null}
import { KameleoonUtils, Environment } from '@kameleoon/nodejs-sdk';
const url = KameleoonUtils.getClientConfigurationUrl(
'my_site_code',
Environment.Production,
'example.com',
);
```
```js theme={null}
import { KameleoonUtils, Environment } from '@kameleoon/nodejs-sdk';
const url = KameleoonUtils.getClientConfigurationUrl(
'my_site_code',
Environment.Production,
'example.com',
);
```
##### Parameters
| Name | Type | Description | Default |
| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------ |
| siteCode required | `string` | site code | - |
| environment optional | `Environment` | an optional parameter specifying the SDK environment | `Environment.Production` |
| networkDomain optional | `string` | an optional parameter specifying the domain for instances using custom domains. Must be in form `example.com` | `kameleoon.com` |
##### Return value
| Type | Description |
| -------- | ----------------------------------------------------- |
| `string` | returns the URL for fetching the client configuration |
#### simulateSuccessRequest
Use the `simulateSuccessRequest` method to simulate a successful request to the Kameleoon server. This method can be useful for custom [Requester](#requester) implementations when a developer needs to simulate a successful request.
```ts theme={null}
import {
KameleoonUtils,
IExternalRequester,
SendRequestParametersType,
RequestType,
KameleoonResponseType,
} from '@kameleoon/nodejs-sdk';
// - Example of `Requester` with disabled tracking
class Requester implements IExternalRequester {
public async sendRequest({
url,
parameters,
requestType,
}: SendRequestParametersType): Promise {
if (requestType === RequestType.Tracking) {
return KameleoonUtils.simulateSuccessRequest(
requestType,
null,
);
}
return await fetch(url, parameters);
}
}
```
```js theme={null}
import { KameleoonUtils } from '@kameleoon/nodejs-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);
}
}
```
##### Parameters
| Name | Type | Description |
| --------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| requestType required | `RequestType` | A type of request |
| data required | `SimulateRequestDataType[RequestType]` | A type of request data, which is different depending on `RequestType` |
The `SimulateRequestDataType` data type is defined as follows:
* `RequestType.Tracking` - `null`
* `RequestType.ClientConfiguration` - `ClientConfigurationDataType`
* `RequestType.RemoteData` - `JSONType`
##### Return value
| Type | Description |
| -------------------------------- | --------------------------------------------- |
| `Promise` | returns a promise with the request's response |
#### getCookieValue
Use the `getCookieValue` method to parse a common cookie string (`key_1=value_1; key_2=value_2; ...`), and get the value of a specific cookie key. This method is useful when working with a custom implementation of [`VisitorCodeManager`](#visitorcodemanager).
```ts theme={null}
import { KameleoonUtils } from '@kameleoon/nodejs-sdk';
const cookies = 'key_1=value_1; key_2=value_2';
const key = 'key_1';
const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1`
```
```js theme={null}
import { KameleoonUtils } from '@kameleoon/nodejs-sdk';
const cookies = 'key_1=value_1; key_2=value_2';
const key = 'key_1';
const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1`
```
##### Parameters
| Name | Type | Description |
| ---------------------------------------------------- | -------- | ---------------------------------------------------- |
| cookie required | `string` | Cookie string in form `key_1=value_1; key_2=value_2` |
| key required | `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 Kameleoon JavaScript SDK.
### Initialization
#### initialize()
An asynchronous method for initializing `KameleoonClient` that retrieves Kameleoon SDK data either from the server or a local source if the data is still up-to-date or the update interval has not yet elapsed.
```ts theme={null}
import {
KameleoonError,
KameleoonClient,
KameleoonException,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
try {
await client.initialize();
} catch (err) {
if (err instanceof KameleoonError) {
switch (err.type) {
case KameleoonException.StorageWrite:
// -- Handle error case
case KameleoonException.ClientConfiguration:
// -- Handle error case
default:
break;
}
}
}
}
init();
```
```js theme={null}
import { KameleoonClient, KameleoonException } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
try {
await client.initialize();
} catch (err) {
switch (err.type) {
case KameleoonException.StorageWrite:
// -- Handle error case
case KameleoonException.ClientConfiguration:
// -- Handle error case
default:
break;
}
}
}
init();
```
##### Return value
| Type | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Promise` | A promise resolved to a boolean indicating the SDK's successful initialization. Generally, initialize() will throw an error if an unhandled issue occurs, so the `boolean` value will almost always be `true` and may not provide 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 |
***
### Feature flags and variations
#### 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.
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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Get variation with tracking
const variation = client.getVariation({
visitorCode,
featureKey: 'my_feature_key',
});
// -- Get variation without tracking
const variation = client.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,
// }
// },
// }
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Get variation with tracking
const variation = client.getVariation({
visitorCode,
featureKey: 'my_feature_key',
});
// -- Get variation without tracking
const variation = client.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,
// }
// },
// }
}
init();
```
##### Parameters
An object of type `GetVariationParamsType` with the following properties:
| Name | Type | Description | Default |
| ----------------------------------------------------------- | --------- | ------------------------------------------------------------------------------ | ------- |
| `visitorCode` required | `string` | Unique identifier of the visitor. | |
| `featureKey` required | `string` | Key of the feature you want to expose to a visitor. | |
| `track` optional | `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)
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.
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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Get all feature flag variations with tracking
const variations = client.getVariations({
visitorCode,
});
// -- Get active feature flag variations with tracking
const variations = client.getVariations({
visitorCode,
onlyActive: true,
});
// -- Get active feature flag variations without tracking
const variations = client.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,
// }
// },
// }
// }
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Get all feature flag variations with tracking
const variations = client.getVariations({
visitorCode,
});
// -- Get active feature flag variations with tracking
const variations = client.getVariations({
visitorCode,
onlyActive: true,
});
// -- Get active feature flag variations without tracking
const variations = client.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,
// }
// },
// }
// }
}
init();
```
##### Parameters
An object of type `GetVariationsParamsType` with the following properties:
| Name | Type | Description | Default |
| ------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- | ------- |
| `visitorCode` required | `string` | Unique identifier of the visitor. | |
| `onlyActive` optional | `boolean` | An optional parameter indicating whether to return variations for active (`true`) or all (`false`) feature flags. | `false` |
| `track` optional | `boolean` | An optional parameter to enable or disable tracking of the feature evaluation. | `true` |
##### Return value
| Type | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Map` | 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`](#events-1)
The `isFeatureFlagActive()` method returns a boolean indicating whether the visitor with `visitorCode` has an active `featureKey`. This method checks for targeting, finds the variation for the visitor, and saves it to storage. The method also sends a tracking request.
This method has an additional overload that lets you pass a `track` parameter, which disables the tracking of feature evaluation.
A visitor must be targeted for feature flags to activate.
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.
```ts theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Add CustomData with index `0` containing visitor id to check the targeting
client.addData(visitorCode, new CustomData(0, 'visitor_id'));
// -- Check if the feature flag is active for visitor
const isActive = client.isFeatureFlagActive(visitorCode, 'my_feature_key');
// -- Check if the feature flag is active for visitor without tracking
const isActive = client.isFeatureFlagActive({ visitorCode, featureKey: 'my_feature_key', track: false});
}
init();
```
```js theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Add CustomData with index `0` containing visitor id to check the targeting
client.addData(visitorCode, new CustomData(0, 'visitor_id'));
// -- Check if the feature flag is active for visitor
const isActive = client.isFeatureFlagActive(visitorCode, 'my_feature_key');
// -- Check if the feature flag is active for visitor without tracking
const isActive = client.isFeatureFlagActive({ visitorCode, featureKey: 'my_feature_key', track: false});
}
init();
```
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**.
##### Parameters
There are two overloads available for this method:
1. Two parameters overload:
This overload is deprecated and will be removed in the next major version. Please use the new overload with an object parameter.
| Name | Type | Description |
| --------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters length |
| featureKey required | `string` | a unique key for feature flag |
2. Object parameter overload of type `IsFeatureFlagActiveParamsType`:
| Name | Type | Description | Default |
| --------------------------------------------------------- | --------- | --------------------------------------------------------------------------- | ------- |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters in length | - |
| featureKey required | `string` | a unique key for a feature flag | - |
| track optional | `boolean` | a boolean indicator of whether to track the feature evaluation | `true` |
##### Return value
| Type | Description |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `boolean` | a boolean indicator of whether the feature flag with `featureKey` is active for the visitor with `visitorCode` |
##### Exceptions thrown
| Type | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `KameleoonException.Initialization` | Method was executed before the `kameleoonClient` completed its `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 provided `featureKey` |
| `KameleoonException.FeatureFlagVariableNotFound` | No feature variable were found for provided `visitorCode` and `variableKey` |
| `KameleoonException.DataInconsistency` | Allocated variation was found, but there is no feature flag with the 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.
**Simulated** variations always take precedence in the execution order. If a **simulated** variation calculation is triggered, it will be fully processed and completed first.
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.
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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Forcing the variation "on" for the "featureKey1" feature flag for the visitor.
client.setForcedVariation({
visitorCode: visitorCode,
experimentId: 9516,
variationKey: 'on',
forceTargeting: false,
});
// -- Resetting the forced variation for the "featureKey1" feature flag for the visitor.
client.setForcedVariation({
visitorCode: visitorCode,
experimentId: 9516,
variationKey: null,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
// -- Forcing the variation "on" for the "featureKey1" feature flag for the visitor.
client.setForcedVariation({
visitorCode: visitorCode,
experimentId: 9516,
variationKey: 'on',
forceTargeting: false,
});
// -- Resetting the forced variation for the "featureKey1" feature flag for the visitor.
client.setForcedVariation({
visitorCode: visitorCode,
experimentId: 9516,
variationKey: null,
});
}
init();
```
##### Parameters
An object of type `SetForcedVariationParametersType` with the following properties:
| Name | Type | Description | Default | |
| ---------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| `visitorCode` required | `string` | Unique identifier of the visitor. | | |
| `experimentId` required | `number` | **Experiment Id** that will be targeted and selected during the evaluation process. | | |
| `variationKey` required | \`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` optional | `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. |
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`.
#### 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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
client.evaluateAudiences(visitorCode);
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code
const visitorCode = client.getVisitorCode();
client.evaluateAudiences(visitorCode);
}
init();
```
##### Parameters
| Name | Type | Description |
| ----------------------------------------------------------- | -------- | --------------------------------- |
| `visitorCode` required | `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). |
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`.
#### getDataFile()
To evaluate all feature flags, use [`getVariations()`](#getvariations). This method is more efficient than calling `DataFile` and iterating through flags with [`getVariation()`](#getvariation).
Returns the current SDK configuration as a [`DataFile`](#datafile) object.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
const dataFile = client.getDataFile();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
const dataFile = client.getDataFile();
```
##### Return value
| Type | Description |
| ---------- | ------------------------------------------------------------ |
| `DataFile` | The [`DataFile`](#datafile) containing the SDK configuration |
### Visitor data
#### getVisitorCode()
The `getVisitorCode` method retrieves a visitor code from the request's cookie in the headers. If the visitor code does not exist, the method generates a new random visitor code, or uses a provided `defaultVisitorCode` value. It then sets the new visitor code in a cookie in the response headers.
This method utilizes Node.js's native types for `request` and `response`, specifically `IncomingMessage` and `ServerResponse`, imported from the `http` module. However, if you're using the Express framework, Deno, or Next.js super server-rendering methods, like `getServerProps`, the types for `request` and `response` will differ. You can resolve this issue using type casting, which will yield identical results.
When using `getVisitorCode()` with Deno, `Next.js SSR`, `Node`, or `Express`, ensure that you've implemented the correct external dependencies.
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).
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using native `NodeJS/NextJS/Deno` `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Get visitor code using `Express`/`Deno`/`NextJS` SSR methods' `request`, `response`, and optionally providing
// default visitor code
const visitorCode = client.getVisitorCode({
request: req,
response: res,
defaultVisitorCode: 'my_default_visitor_code',
});
// -- Get visitor code using `NextJS` server side actions
// (`cookies` imported from "next/headers")
const visitorCode = client.getVisitorCode({
cookies,
});
// -- Get visitor code using custom `VisitorCodeManager` implementation
// `myInput` and `myOutput` are custom input and output parameters with arbitrary types.
// According types should be defined in `VisitorCodeManager` implementation.
const visitorCode = client.getVisitorCode({
input: myInput,
output: myOutput,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using native `NodeJS` `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Get visitor code using `Express`/`Deno`/`NextJS SSR methods`, and optionally providing
// default visitor code
const visitorCode = client.getVisitorCode({
request: req,
response: res,
defaultVisitorCode: 'my_default_visitor_code',
});
// -- Get visitor code using `NextJS` server side actions
// (`cookies` imported from "next/headers")
const visitorCode = client.getVisitorCode({
cookies,
});
// -- Get visitor code using custom `VisitorCodeManager` implementation
// `myInput` and `myOutput` are custom input and output parameters with arbitrary types.
// According types should be defined in `VisitorCodeManager` implementation.
const visitorCode = client.getVisitorCode({
input: myInput,
output: myOutput,
});
}
init();
```
##### Parameters
The parameters object is overloaded with two types:
* Type `GetVisitorCodeParametersType` (for `NodeJS`/`Express`/`NextJS SSR methods`), containing the following fields:
| Name | Type | Description |
| ------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------ |
| request required | `IncomingMessage` | server request |
| response required | `ServerResponse` | server response |
| defaultVisitorCode optional | `string` | visitor code to be used if is no visitor code in the cookies |
* Type `GetNextJSVisitorCodeParametersType` (for `NextJS SSR server actions`), containing the following fields:
| Name | Type | Description |
| ------------------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------- |
| cookies required | `typeof 'next/headers' cookies` | NextJS server actions headers cookie |
| defaultVisitorCode optional | `string` | visitor code to be used if is no visitor code available in the cookies |
* Type `GetDenoVisitorCodeParametersType` (for `Deno`), containing the following fields:
| Name | Type | Description |
| ------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------- |
| request required | `DenoMessage` | server request |
| response required | `DenoMessage` | server response |
| defaultVisitorCode optional | `string` | default visitor code that the SDK uses when there is no visitor code in the cookies |
* Type `GetCustomVisitorCodeParametersType` (for custom `VisitorCodeManager` implementation), containing the following fields:
| Name | Type | Description |
| ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------- |
| input required | `unknown` | arbitrary input object from which you want to read the visitor code |
| output required | `unknown` | arbitrary output object to which you want to write the visitor code |
| defaultVisitorCode optional | `string` | visitor code to be used in case there is no visitor code in the cookies |
If you don't provide a `defaultVisitorCode` and there is no visitor code stored in a cookie, the visitor code will be randomly generated.
##### Return value
| Type | Description |
| -------- | ------------------- |
| `string` | result visitor code |
##### Exceptions thrown
| Type | Description |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| `KameleoonException.Initialization` | Method was executed before the `kameleoonClient` completed its `initialize` call |
| `KameleoonException.VisitorCodeMaxLength` | The maximum visitor code length was exceeded (255 characters) |
| `KameleoonException.VisitorCodeEmpty` | The visitor code is empty |
***
#### addData()
Use the `addData()` method to add targeting data to storage so other methods can utilize this information to determine whether to target the current visitor.
The `addData()` method does not return any value, and does not directly interact with the Kameleoon back-end servers. Instead, all data the method collects is saved for future transmission using the [`flush()`](#flush) method. This approach minimizes the number of server calls, as data is generally grouped into a single server call that is activated by the `flush()` method.
Additionally, the [`trackConversion()`](#trackconversion) method transmits any previously associated data. The [`getFeatureFlagVariationKey()`](#getfeatureflagvariationkey) and [`getFeatureFlagVariable()`](#getfeatureflagvariable) methods transmit data when an experimentation rule is triggered.
Each visitor can only have one instance of associated data for most data types; however, `CustomData` is an exception, as visitors can have one instance of associated `CustomData` for each `customDataIndex`.
Check the [list of supported conditions](#targeting-conditions) to see the data types you can use for targeting.
```ts theme={null}
import {
KameleoonClient,
BrowserType,
CustomData,
Browser,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Create Kameleoon Data Types
const browserData = new Browser(BrowserType.Chrome);
const customData = new CustomData(0, 'my_data');
// -- Add a single data item (tracked by default)
client.addData('my_visitor_code', browserData);
// -- Add multiple data items (tracked by default)
client.addData('my_visitor_code', browserData, customData);
// -- Add multiple data items from array (tracked by default)
const dataArr = [browserData, customData];
client.addData('my_visitor_code', ...dataArr);
// -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
client.addData({visitorCode: 'my_visitor_code', track: false, data: dataArr});
}
init();
```
```js theme={null}
import {
KameleoonClient,
BrowserType,
CustomData,
Browser,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Create Kameleoon Data Types
const browserData = new Browser(BrowserType.Chrome);
const customData = new CustomData(0, 'my_data');
// -- Add a single data item (tracked by default)
client.addData('my_visitor_code', browserData);
// -- Add multiple data items (tracked by default)
client.addData('my_visitor_code', browserData, customData);
// -- Add multiple data items from array (tracked by default)
const dataArr = [browserData, customData];
client.addData('my_visitor_code', ...dataArr);
// -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
client.addData({visitorCode: 'my_visitor_code', track: false, data: dataArr});
}
init();
```
##### Parameters
| Name | Type | Description | Default value |
| ------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters. | |
| track optional | `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 optional | `KameleoonDataType[]` | number of instances of any type of `KameleoonData`, can be added solely in array or as sequential arguments | |
* `kameleoonData` is a variadic argument: it can be passed as one or several arguments (see the example).
* The [custom data's](/user-manual/assets/custom-data/create-custom-data) index or ID can be found in your Kameleoon account. Note that this index starts at `0`, meaning the first custom data you create for a given site will be assigned `0` as its ID, rather than `1`.
##### 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 its `initialize` call |
Check the [data types](#data-types) reference for more details on how to manage different data types.
***
#### flush()
The `flush()` method takes the Kameleoon data associated with a visitor and sends a data tracking request along with all previously added data using the [`addData()`](#adddata) method.
The SDK will send all of its stored data to the remote Kameleoon servers if you don't specify a `visitorCode`. Additionally, if there were any tracking requests that previously failed and were stored locally in [offline mode](#initialize), the SDK will attempt to send those stored requests before processing the latest request.
The `isUniqueIdentifier` parameter can be beneficial in certain edge cases. For example, if you can't access the anonymous `visitorCode` initially assigned to a visitor but have an internal ID linked through session merging, this parameter is useful.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
const customData = new CustomData(0, 'my_data');
client.addData(visitorCode, customData);
// -- Flush added custom data for visitor
client.flush(visitorCode);
// -- Flush data for all the visitors
client.flush();
// -- Flush data with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.flush(internalUserId, true);
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
const customData = new CustomData(0, 'my_data');
client.addData(visitorCode, customData);
// -- Flush added custom data for visitor
client.flush(visitorCode);
// -- Flush data for all the visitors
client.flush();
// -- Flush data with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.flush(internalUserId, true);
}
init();
```
##### Parameters
| Name | Type | Description | Default |
| ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitorCode optional | `string` | unique visitor identification string, can't exceed 255 characters in length, if not passed, all data will be flushed (sent to the remote Kameleoon servers) | - |
| isUniqueIdentifier optional | `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 its `initialize` call |
`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 in the SDK Configuration's [`trackingInterval`](#configuration-parameters) parameter. You can add visitor data using the [`addData()`](#adddata) and [`getRemoteVisitorData()`](#getremotevisitordata) methods.
The SDK will send all of its stored data to the remote Kameleoon servers if you don't specify a `visitorCode`. Additionally, if there were any tracking requests that previously failed and were stored locally in [offline mode](#initialize), the SDK will attempt to send those stored requests before processing the latest request.
If you need to send tracking requests immediately, use `flushInstant()` — the asynchronous version of `flush` that returns `Promise`. You can `await` it when you need delivery guarantees (for example, before ending a request/response cycle), or call it without `await` as a fire-and-forget request:
* `await client.flushInstant(visitorCode)` sends tracking requests immediately for a specific visitor and waits for completion
* `await client.flushInstant()` sends tracking requests immediately for all visitors and waits for completion
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
const customData = new CustomData(0, 'my_data');
client.addData(visitorCode, customData);
// -- Flush added custom data for visitor
client.flush(visitorCode);
// -- Instantly flush added custom data for visitor
client.flush({ visitorCode, instant: true });
// -- Flush data for all the visitors
client.flush();
// -- Instantly flush data for all the visitors
client.flush({ instant: true });
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
const customData = new CustomData(0, 'my_data');
client.addData(visitorCode, customData);
// -- Flush added custom data for visitor
client.flush(visitorCode);
// -- Instantly flush added custom data for visitor (fire-and-forget)
client.flushInstant(visitorCode);
// -- Instantly flush added custom data for visitor and wait for completion
await client.flushInstant(visitorCode);
// -- Flush data for all the visitors
client.flush();
// -- Instantly flush data for all the visitors (fire-and-forget)
client.flushInstant();
// -- Instantly flush data for all the visitors and wait for completion
await client.flushInstant();
}
init();
```
##### Parameters
| Name | Type | Description | Default |
| ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitorCode optional | `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 optional | `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 optional | `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 its `initialize` call |
***
#### getRemoteData()
The `getRemoteData()` method retrieves data that is stored on a remote Kameleoon server for a specified site code.
For instance, you can use this method to access user preferences, historical data, or any other information pertinent to your application's logic. By storing this data on our highly scalable servers using our [Data API](/developer-docs/apis/data-api-rest/overview), you can efficiently manage large volumes of data and retrieve it for each of your visitors or users.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get remote data
const jsonData = await getRemoteData('my_data_key');
const data = JSON.parse(jsonData);
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get remote data
const jsonData = await getRemoteData('my_data_key');
const data = JSON.parse(jsonData);
}
init();
```
##### Parameters
| Name | Type | Description |
| ------------------------------------------------- | -------- | ---------------------------------------------------------- |
| key required | `string` | the unique key with which the retrieved data is associated |
##### 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()
`getRemoteVisitorData()` is an asynchronous method that retrieves Kameleoon Visits Data for a specific `visitorCode` from the Kameleoon Data API. This method stores the data for use by other methods when making targeting decisions.
The data obtained using this method is essential for certain scenarios, including:
* Utilizing data collected from multiple devices.
* Accessing a user's history, including visited pages during prior visits.
* Using client-side data, such as datalayer variables and goals that only convert on the front end.
For a clearer understanding of the potential use cases, read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
By default, `getRemoteVisitorData()` retrieves the latest stored custom data with `scope=Visitor` and attaches it to the visitor, eliminating the need to call the method `addData()`. This feature is especially useful for [synchronizing custom data between multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
The `isUniqueIdentifier` parameter can be beneficial in certain edge cases. For example, if you can't access the anonymous `visitorCode` initially assigned to a visitor but have an internal ID linked through session merging, this parameter is useful.
```ts theme={null}
import {
KameleoonClient,
KameleoonDataType,
VisitorDataFiltersType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- 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,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- 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,
});
}
init();
```
##### Parameters
An object with the type `RemoteVisitorDataParamsType` containing:
| Name | Type | Description | Default Value |
| ------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters in length | - |
| shouldAddData optional | `boolean` | boolean flag identifying whether the retrieved data should be added to storage automatically (without calling `addData()` afterwards). | `true` |
| filters optional | `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 optional | `boolean` | optional parameter that, when `true`, specifies the `visitorCode` as 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 the `kameleoonClient` completed its `initialize` call |
##### Using parameters in getRemoteVisitorData()
The `getRemoteVisitorData()` method provides flexibility by letting you define various parameters when retrieving visitor data. This method can target data based on goals, experiments, or variations, and the same approach applies to all data types.
For example, if you want to retrieve data on visitors who completed the goal "Order transaction," you can specify parameters in the `getRemoteVisitorData()` method to refine your targeting. If you're interested in users who converted on the goal during 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.
Here is the list of available `VisitorDataFiltersType` filters:
| Name | Type | Description | Default |
| ------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previousVisitAmount optional | `number` | Number of previous visits from which to retrieve data. Number between `1` and `25` | `1` |
| currentVisit optional | `boolean` | If true, current visit data will be retrieved | `true` |
| customData optional | `boolean` | If true, custom data will be retrieved. | `true` |
| pageViews optional | `boolean` | If true, page data will be retrieved. | `false` |
| geolocation optional | `boolean` | If true, geolocation data will be retrieved. | `false` |
| device optional | `boolean` | If true, device data will be retrieved. | `false` |
| browser optional | `boolean` | If true, browser data will be retrieved. | `false` |
| operatingSystem optional | `boolean` | If true, operating system data will be retrieved. | `false` |
| conversions optional | `boolean` | If true, conversion data will be retrieved. | `false` |
| experiments optional | `boolean` | If true, experiment data will be retrieved. | `false` |
| kcs optional | `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` |
The `getRemoteVisitorData()` method is an asynchronous function that retrieves Kameleoon Visits Data for a specific `visitorCode` from the Kameleoon Data API. This method stores the data so that it can be accessed when making targeting decisions.
The data obtained through this method is crucial when you want to:
* Access data collected from multiple devices.
* Review a user's history, including pages visited during previous sessions.
* Utilize client-side data, such as data layer variables and goals that are only applicable on the front end.
For a better understanding of potential use cases, please read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
By default, `getRemoteVisitorData()` retrieves the latest stored custom data with `scope=Visitor` and attaches it to the visitor without the need to call the method `addData()`. This feature is particularly useful for [synchronizing custom data across multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
```ts theme={null}
import {
KameleoonClient,
KameleoonDataType,
VisitorDataFiltersType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- 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,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- 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,
});
}
init();
```
##### Parameters
An object with the type `RemoteVisitorDataParamsType`, containing:
| Name | Type | Description | Default Value |
| ------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters in length | - |
| shouldAddData optional | `boolean` | boolean flag identifying whether the retrieved custom data should be added to storage automatically (without calling `addData` afterwards) | `true` |
| filters optional | `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 the `kameleoonClient` completed its `initialize` call |
##### Using parameters in getRemoteVisitorData()
The `getRemoteVisitorData()` method provides flexibility by letting you define various parameters when retrieving visitor data. This method can target data based on goals, experiments, or variations, and the same approach applies to all data types.
For example, if you want to retrieve data on visitors who completed the goal "Order transaction," you can specify parameters in the `getRemoteVisitorData()` method to refine your targeting. If you're interested in users who converted on the goal during 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.
Here is the list of available `VisitorDataFiltersType` filters:
| Name | Type | Description | Default |
| ------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previousVisitAmount optional | `number` | Number of previous visits from which to retrieve data. Number between `1` and `25` | `1` |
| currentVisit optional | `boolean` | If true, current visit data will be retrieved | `true` |
| customData optional | `boolean` | If true, custom data will be retrieved. | `true` |
| pageViews optional | `boolean` | If true, page data will be retrieved. | `false` |
| geolocation optional | `boolean` | If true, geolocation data will be retrieved. | `false` |
| device optional | `boolean` | If true, device data will be retrieved. | `false` |
| browser optional | `boolean` | If true, browser data will be retrieved. | `false` |
| operatingSystem optional | `boolean` | If true, operating system data will be retrieved. | `false` |
| conversions optional | `boolean` | If true, conversion data will be retrieved. | `false` |
| experiments optional | `boolean` | If true, experiment data will be retrieved. | `false` |
| kcs optional | `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 optional | `boolean` | If true, Kameleoon will retrieve the `visitorCode` from the most recent visit and use it for the current visit. This retrieval 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 optional | `boolean` | If true, personalization data will be retrieved. This is required for the personalization condition | `false` |
| cbs optional | `boolean` | If true, Contextual Bandit score data will be retrieved. | `false` |
***
#### getVisitorWarehouseAudience()
The `getVisitorWarehouseAudience` method is asynchronous and retrieves all audience data related to a visitor from your data warehouse. To use this method, you’ll need to provide a `visitorCode` and a `warehouseKey`, which typically correspond to your internal user ID. The `customDataIndex` parameter refers to the custom data Kameleoon uses to target your visitors. For more details, refer to the [warehouse targeting documentation](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting).
```ts theme={null}
import {
KameleoonClient,
KameleoonDataType,
CustomData,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- 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,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- 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,
});
}
init();
```
##### Parameters
Parameters object consisting of:
| Name | Type | Description |
| ------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string, can't exceed 255 characters in length |
| customDataIndex required | `number` | number representing the custom data's index you want to use to target your Warehouse Audiences |
| warehouseKey optional | `string` | unique key identifying the warehouse data (usually your internal user ID) |
##### Return value
| Type | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| `Promise` | 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()
When handling legal consent, it’s important you use the [`getVisitorCode`](#getvisitorcode) method from the `KameleoonClient` class, rather than the deprecated method from `KameleoonUtils`. Note that this method does not require the `domain` as an argument. Instead, you should pass the `domain` to the `KameleoonClient` constructor. Refer to the example above for clarification.
The method `setLegalConsent` determines whether a visitor has provided legal consent for their personal data's use. If you set the `legalConsent` parameter to `false`, it restricts the types of data you can include in tracking requests. This measure ensures that you comply with legal and regulatory requirements while responsibly managing visitor data. For more information on personal data, refer to the [consent management policy](/user-manual/project-management/consent-management-policy).
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
});
async function init(): Promise {
await client.initialize();
const visitorCode = client.getVisitorCode();
client.setLegalConsent({
visitorCode,
consent: true,
response, // or cookies or output, depending on the environment
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
const client = new KameleoonClient({
siteCode: 'my_site_code',
});
async function init() {
await client.initialize();
const visitorCode = client.getVisitorCode();
client.setLegalConsent({
visitorCode,
consent: true,
response, // or cookies or output, depending on the environment
});
}
init();
```
##### Parameters
The parameters object is overloaded with the following types:
* Type `SetLegalConsentParametersType` (for `NodeJS`/`Express`/`NextJS SSR methods`), containing the following fields:
| Name | Type | Description |
| --------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string. Can't exceed 255 characters in length |
| consent required | `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 withdrawn legal consent |
| response required | `ServerResponse` | server response |
* Type `SetNextJSLegalConsentParametersType` (for `NextJS SSR server actions`), containing the following fields:
| Name | Type | Description |
| --------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string. Can't exceed 255 characters in length |
| consent required | `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 withdrawn legal consent |
| cookies required | `typeof 'next/headers' cookies` | NextJS server actions headers cookie |
* Type `SetDenoLegalConsentParametersType` (for `Deno`), containing the following fields:
| Name | Type | Description |
| --------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string. Can't exceed 255 characters in length |
| consent required | `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 withdrawn legal consent |
| response required | `DenoMessage` | server response |
* Type `SetCustomLegalConsentParametersType` (for custom `VisitorCodeManager` implementation), containing the following fields:
| Name | Type | Description |
| --------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode required | `string` | unique visitor identification string. Can't exceed 255 characters in length |
| consent required | `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 withdrawn legal consent |
| output required | `unknown` | arbitrary output object to which you want to write the visitor code |
##### 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
#### trackConversion()
* 📨 *Sends Tracking Data to Kameleoon*
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.
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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Track conversion
client.trackConversion({ visitorCode, revenue: 20000, goalId: 123 });
// -- Track conversion with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.trackConversion({
visitorCode: internalUserId,
revenue: 20000,
goalId: 123,
isUniqueIdentifier: true,
});
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Track conversion
client.trackConversion({ visitorCode, revenue: 20000, goalId: 123 });
// -- Track conversion with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.trackConversion({
visitorCode: internalUserId,
revenue: 20000,
goalId: 123,
isUniqueIdentifier: true,
});
}
init();
```
##### Parameters
Parameters object consisting of:
| Name | Type | Description | Default |
| -------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | ------- |
| `visitorCode` required | `string` | Unique identifier of the visitor. | |
| `goalId` required | `number` | ID of the goal. | |
| `revenue` optional | `number` | Revenue of the conversion. | `0` |
| `isUniqueIdentifier` optional | `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. |
* 📨 *Sends Tracking Data to Kameleoon*
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.
```ts theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Track conversion
client.trackConversion({
visitorCode,
revenue: 20000,
goalId: 123,
metadata: [new CustomData(0, 'value')],
negative: true,
});
}
init();
```
```js theme={null}
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Track conversion
client.trackConversion({
visitorCode,
revenue: 20000,
goalId: 123,
metadata: [new CustomData(0, 'value')],
negative: true,
});
}
init();
```
##### Parameters
Parameters object consisting of:
| Name | Type | Description | Default |
| ----------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `visitorCode` required | `string` | Unique identifier of the visitor. | |
| `goalId` required | `number` | ID of the goal. | |
| `revenue` optional | `number` | Revenue of the conversion. | `0` |
| `negative` optional | `boolean` | Defines if the revenue is positive or negative. | `false` |
| `metadata` optional | `CustomData[]` | Metadata of the conversion. [Must be defined beforehand in the Kameleoon App](/user-manual/assets/goals/create-a-goal#metadata). | `undefined` |
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').
```ts theme={null}
kameleoonClient.addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery'));
kameleoonClient.trackConversion({
visitorCode,
goalId: 1000,
metadata: [new CustomData(5, 'Amex Credit Card')]
});
```
```js theme={null}
kameleoonClient.addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery'));
kameleoonClient.trackConversion({
visitorCode,
goalId: 1000,
metadata: [new CustomData(5, 'Amex Credit Card')]
});
```
##### 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. |
***
#### 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.
```ts theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init(): Promise {
await client.initialize();
// -- Trigger feature experiment
// -- E.g., result `variationKey` id is `200`, and implicit experiment id is `100`
client.getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' });
// -- Get tracking code
const engineCode = client.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]);
// `
}
init();
```
```js theme={null}
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
requester: new KameleoonRequester(),
},
});
async function init() {
await client.initialize();
// -- Trigger feature experiment
// -- E.g., result `variationKey` id is `200`, and implicit experiment id is `100`
client.getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' });
// -- Get tracking code
const engineCode = client.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]);
// `
}
init();
```
* To use this feature, implement both the NodeJS 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 `` tag.
* You can insert the returned tracking code directly into an HTML `