Skip to main content

NodeJS SDK

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.

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

SDK methods: For the full reference documentation of the NodeJS SDK, see the reference section.

Changelog: Latest version of the NodeJS SDK: 5.2.3 Changelog.

note

Before you begin installing our NodeJS SDK, we recommend reading our technical considerations article 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 if needed.

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

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

Or run it directly with npx:

npx @kameleoon/sdk-installer

When using Deno, provide dependencies manually in deno.json:

{
  "imports": {
    "@kameleoon/nodejs-sdk": "npm:@kameleoon/nodejs-sdk@^4.0",
    // -- Optional dependencies, can be implemented manually
    "@kameleoon/nodejs-requester": "@kameleoon/nodejs-requester@^1.0"
    "@kameleoon/nodejs-event-source": "@kameleoon/nodejs-event-source@^1.0"
    "@kameleoon/deno-visitor-code-manager": ":@kameleoon/deno-visitor-code-manager@^1.0",
  }
}

Initializing the Kameleoon Client​

Developers must make an entry point for the NodeJS SDK by creating a new instance of Kameleoon Client.

Use KameleoonClient to run feature experiments and retrieve the status of feature flags and their variations.

KameleoonClient initializes asynchronously to confirm the Kameleoon API call is successful, using the initialize() method. Use async/await, Promise.then() or any other method to handle asynchronous client initialization.

note

To add NodeJS SDK to an Edge environment, please refer to this section.

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<SDKConfigurationType> = {
  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(),
  },
});

// -- Waiting for the client initialization using `async/await`
async function init(): Promise<void> {
  await client.initialize();
}

init();

// -- Waiting for the client initialization using `Promise.then()`
client
  .initialize()
  .then(() => {})
  .catch((error) => {});
Arguments​
NameTypeDescription
siteCode (required)stringThis is the unique key of the Kameleoon project you are using with the SDK. This field is mandatory.
credentials (required)CredentialsTypeclient API credentials, see credentials flow for more information
externals (required)ExternalsTypeexternal implementation of SDK dependencies (External dependencies)
configuration (optional)Partial<SDKConfigurationType>client's configuration
compatibility (optional)CompatibilitySDK's compatibility mode, see Compatibility Mode
integrations (optional)IntegrationTypecompute edge integrations, see Integration with Edge providers
Exceptions thrown​
TypeDescription
KameleoonException.CredentialsClient credentials were not provided or are empty
Configuration Parameters​
NameTypeDescriptionDefault Value
updateInterval (optional)numberSpecifies 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 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 | stringfeature flag environmentEnvironment.Production
targetingDataCleanupInterval (optional)numberinterval in minutes for cleaning up targeting data, minimum value is 1 minute30
cookieDomain (optional)stringdomain that the cookie belongs to.undefined
networkDomain (optional)stringThe 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)numbertimeout in milliseconds for all SDK network requests, if timeout is exceeded request will fail immediately10_000 (10 seconds)
trackingInterval (optional)numberSpecifies 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 ms1_000 (1 second)
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​

Use the getVisitorCode() method to assign a unique ID to a user. If a visitor code doesn’t exist (from the request headers cookie), the method generates a random unique ID or uses a defaultVisitorCode. The ID is then set in a response headers cookie.

If you are using Kameleoon in Hybrid mode, calling getVisitorCode() ensures that the unique ID (visitorCode) 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 a feature flag in your Kameleoon account.

You need to retrieve a feature flag's configuration to determine if it's active for a user. Use the getFeatureFlagVariationKey() or isFeatureFlagActive() method to retrieve the configuration based on the featureKey.

Use the isFeatureFlagActive() method if you want to retrieve the configuration of a simple feature flag that has only an ON or OFF state.

The getFeatureFlagVariationKey() method retrieves the configuration of a feature experiment with several feature variations. You can use the method to get a variation key for a given user by providing the visitorCode and featureKey as mandatory arguments.

Feature flags can have associated variables that are used to customize their behavior. Use the getFeatureFlagVariables() method to retrieve these variables. This method checks whether the user is targeted, finds the visitor’s assigned variation, saves it to storage, and sends a tracking request.

note

You only need to use one method to check if a feature flag is active. Choose isFeatureFlagActive if you want to know if a feature flag is on or off. Use getFeatureFlagVariables for more complex scenarios, like dynamically changing the feature's behavior.

Adding data points to target a user or filter / breakdown visits in reports​

To target a user, ensure you’ve added relevant data points to their profile before retrieving the feature variation or checking if the flag is active. Use the addData() method to add these data points to the user’s profile.

To retrieve data points that have been collected on other devices or to access a user's past data points (which would have been collected client-side if you are using Kameleoon in Hybrid mode), use the getRemoteVisitorData() method. This method fetches data asynchronously from our servers. However, 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 of a feature flag.

To learn more about available targeting conditions, read our detailed article on the subject.

Additionally, the data points you add to the visitor profile will be available when analyzing your experiments, letting you filter and break down your results by criteria 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.

Use Kameleoon's Custom Data feature to track additional data points beyond what's collected automatically. Custom Data lets you capture and analyze specific information relevant to your experiments. Filter out bots using the userAgent data type to ensure your results are accurate. You can learn more about userAgent here. Don't forget to call the flush() method to send the collected data to Kameleoon servers for analysis.

Tracking flag exposition and goal conversions​

Kameleoon will automatically track visitors’ exposition to flags when you call one of these methods:

  • getFeatureFlagVariationKey()
  • getFeatureFlagVariable()
  • getFeatureFlagVariables()
  • isFeatureFlagActive()

When a user completes a desired action (for example, making a purchase), it counts as a conversion. You must use to the trackConversion() method to track conversions, and provide the visitorCode and goalId parameters.

Sending events to analytics solutions​

You must implement Kameleoon in Hybrid mode to track conversions and send exposure events to your analytics solution. Then, use the getEngineTrackingCode() method.

The getEngineTrackingCode method retrieves the unique tracking code that is required to send exposure events to your analytics solution. Using this method lets you 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 KameleoonErrors 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 variants.

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

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<void> {
  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();

Integration with Edge providers​

Kameleoon provides the following starter packs to automate your integration with specific edge providers:

ProviderStarter pack
Fastly Compute@Edgehttps://github.com/Kameleoon/fastly-compute-starter-kit
Cloudfare Workershttps://github.com/Kameleoon/cloudflare-worker-starter-kit
AWS Lambda@Edge Functionhttps://github.com/Kameleoon/aws-lambda-edge-starter-kit

For other edge providers, use External Dependencies for greater control over the SDK.

Cross-device experimentation​

To support visitors who access your app from multiple devices, Kameleoon allows you to synchronize previously collected visitor data across each of the visitor's devices and reconcile their visit history across devices through cross-device experimentation. We recommend reading our article on cross-device experimentation for more information on how Kameleoon handles data across devices and detailed use cases.

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() method description for further guidance. In the below code, it is assumed that the same unique identifier (in this case, the visitorCode, which can also be referred to as userId) is used consistently between the two devices for accurate data retrieval.

note

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

Device One
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<void> {
  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();
Device Two
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<void> {
  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();

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 and provide a unique identifier for the visitor to reconcile visit history.

Follow the activating cross-device history reconciliation 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 data to a visitor.

tip

Since the custom data you use as the identifier must be set to the Visitor scope, you must use cross-device custom data synchronization to retrieve the identifier with the 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 method. After the user logs in, we can associate the anonymous visitor with the user ID and use it as a unique identifier for the visitor.

Login Page
import { 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<void> {
  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.getFeatureFlagVariationKey(
    anonymousVisitor,
    'my_feature_key',
  );
}

init();
Application Page
import { CustomData, UniqueIdentifier } from '@kameleoon/nodejs-sdk';

async function init(): Promise<void> {
  // -- At this point anonymous visitor has logged in,
  //    and we have a user ID to use as a visitor identifier
  // -- Associating both visitors with an identifier Custom Data,
  //    where index `1` is the Custom Data's index, configured
  //    as a unique identifier in Kameleoon.
  const userIdentifierData = new CustomData(1, 'my_user_id');
  // -- 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.getFeatureFlagVariationKey(
    'my_user_id',
    '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();

Targeting conditions​

The Kameleoon SDKs support a variety of predefined targeting conditions that you can use to target users in your campaigns. For the list of conditions supported by this SDK, see use visit history to target users.

You can also use your own external data to target users.

Logging​

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

Log levels​

The SDK supports configuring limiting logging by a log level.

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` log level allows logging extra information on the SDK's internal processes.
// It extends the `INFO` log level.
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.

note

Logging limiting by a log level is performed apart from the log handling logic.

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);

Domain information​

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

Setting the domain​

The domain you provide 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.

note

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

Here's a small domain cheat sheet:

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

Developing on localhost​

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

There are two ways to avoid this issue:

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

External dependencies​

The SDK's external dependencies use the dependency injection pattern, letting you provide your own implementations for certain parts of an SDK.

note

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:

DependencyInterfaceRequired/OptionalAPI UsedDescription
storageIExternalStorageOptionalServer memoryUsed for storing all of the existing and collected SDK data
eventSourceIExternalEventSourceRequired-Used for receiving Server Sent Events for Real Time Updates capabilities
requesterIExternalRequesterRequired-Used for performing all network requests
visitorCodeManagerIExternalVisitorCodeManagerRequired-Used for storing and synchronizing visitor code
loggerILoggerOptionalCustom implementationUsed for custom handling of logs from the SDK. Lets users define how logs are processed and where they output.
note

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 (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​

import { IExternalStorage, KameleoonClient } from '@kameleoon/nodejs-sdk';

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

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

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

    // - Return obtained data
    return data;
  }

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

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

EventSource​

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(),
  },
});

VisitorCodeManager​

visitorCodeManager implementation for NodeJS/NextJS SSR:

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(),
  },
});

visitorCodeManager implementation for Deno:

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(),
  },
});

visitorCodeManager implementation for NextJS Server Actions:

import {
  IExternalNextJSVisitorCodeManager,
  SetNextJSDataParametersType,
  GetNextJSDataParametersType,
  KameleoonClient,
} from '@kameleoon/nodejs-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses server `cookie` object imported from "next/headers"
class MyVisitorCodeManager implements IExternalNextJSVisitorCodeManager {
  public getData({ cookie, 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(),
  },
});

Custom visitorCodeManager implementation with arbitrary parameters:

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(),
  },
});

Requester​

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

// --- External Requester Implementation
export class MyRequester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    // - 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(),
  },
});

Logger​

import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/nodejs-sdk';

// --- Custom Logger Implementation
export class CustomLogger implements IExternalLogger {
  public log(level: LogLevel, message: string): void {
    // Custom log handling logic here.
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    logger: new CustomLogger(),
  },
});

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.

simulateSuccessRequest​

Use the simulateSuccessRequest method to simulate a successful request to the Kameleoon server. This method can be useful for custom Requester implementations when a developer needs to simulate a successful request.

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<RequestType>): Promise<KameleoonResponseType> {
    if (requestType === RequestType.Tracking) {
      return KameleoonUtils.simulateSuccessRequest<RequestType.Tracking>(
        requestType,
        null,
      );
    }

    return await fetch(url, parameters);
  }
}
Arguments​
NameTypeDescription
requestType (required)RequestTypeA 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​

Promise<KameleoonResponseType> - 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.

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`
Arguments​
NameTypeDescription
cookie (required)stringCookie string in form key_1=value_1; key_2=value_2
key (required)stringString representation of a key to find a value by
Return value​

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.

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<void> {
  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();
Return value​

Promise<boolean> - 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​
TypeDescription
KameleoonException.StorageWriteCouldn't update storage data
KameleoonException.ClientConfigurationCouldn't retrieve client configuration from Kameleoon API
KameleoonException.MaximumRetriesReachedMaximum retries reached, request failed

Feature flags and variations​

getVariation()​

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

Retrieves the VariationType assigned to a given visitor for a specific feature flag.

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

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

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

note

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

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<void> {
  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();
Arguments​

An object of type GetVariationParamsType with the following properties:

NameTypeDescriptionDefault
visitorCode (required)stringUnique identifier of the user.
featureKey (required)stringKey of the feature you want to expose to a user.
track (optional)booleanAn optional parameter to enable or disable tracking of the feature evaluation.true
Return value​
TypeDescription
VariationAn assigned VariationType to a given visitor for a specific feature flag.
Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call.
KameleoonException.VisitorCodeEmptyThe visitor code is empty.
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters).
KameleoonException.FeatureFlagConfigurationNotFoundException 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 on your application).
KameleoonException.FeatureFlagEnvironmentDisabledException 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

Retrieves a map of VariationType objects assigned to a given visitor across all feature flags.

This method iterates over all available feature flags and returns the assigned VariationType 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 VariationType as values. If no variation is assigned for a feature flag, the method returns the default VariationType for that flag.

Proper error handling should be implemented to manage potential exceptions.

note

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

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<void> {
  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();
Arguments​

An object of type GetVariationsParamsType with the following properties:

NameTypeDescriptionDefault
visitorCode (required)stringUnique identifier of the user.
onlyActive (optional)booleanAn optional parameter indicating whether to return variations for active (true) or all (false) feature flags.false
track (optional)booleanAn optional parameter to enable or disable tracking of the feature evaluation.true
Return value​
TypeDescription
Map<string, VariationType>Map that contains the assigned VariationType objects of the feature flags using the keys of the corresponding features.
Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call.
KameleoonException.VisitorCodeEmptyThe visitor code is empty.
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters).

isFeatureFlagActive()​

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

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.

note

A visitor must be targeted for feature flags to activate.

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<void> {
  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, track: false});
}

init();
Arguments​

There are two overloads available for this method:

  1. Two parameters overload:
danger

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

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
  1. Object parameter overload of type IsFeatureFlagActiveParamsType:
NameTypeDescriptionDefault
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length-
featureKey (required)stringa unique key for a feature flag-
track (optional)booleana boolean indicator of whether to track the feature evaluationtrue
Return value​

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

Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.NotTargetedCurrent visitor is not targeted
KameleoonException.FeatureFlagConfigurationNotFoundNo feature flag was found for provided featureKey
KameleoonException.FeatureFlagVariableNotFoundNo feature variable were found for provided visitorCode and variableKey
KameleoonException.DataInconsistencyAllocated variation was found, but there is no feature flag with the according featureKey.

getFeatureFlagVariationKey()​

caution

This method is deprecated and will be removed in the next major update. Please use the new method getVariation.

The getFeatureFlagVariationKey() method retrieves the variation key for the specified visitorCode in the corresponding feature flag. This method includes a targeting check, finding the appropriate variation exposed to the visitor, saving it to storage, and sending a tracking request.

note

If a user has not been previously assigned a variation key for the feature flag, the SDK will randomly determine a variation based on the feature flag's rules. If the user is already linked to the feature flag, the SDK will return their previously assigned variation key. If the user does not meet any of the specified rules, the default value defined in Kameleoon's feature flag delivery rules will be returned. This default value is not always a variation key—it can also be a boolean or another data type, depending on the feature flag's configuration.

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<void> {
  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(new CustomData(0, 'visitor_id'));

  // -- Get visitor feature flag variation key
  const variationKey = client.getFeatureFlagVariationKey(
    visitorCode,
    'my_feature_key',
  );
}

init();
Arguments​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length
featureKey (required)stringa unique key for a feature flag
Return value​

string — a string containing the variable key for the visitor's allocated feature flag.

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

getFeatureFlags()​

🚫 Doesn't send Tracking Data to Kameleoon

caution

This method is deprecated and will be removed in the next major update. Please use the new getVariations method.

The getFeatureFlags() method retrieves a list of feature flags that are stored in the client configuration.

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<void> {
  await client.initialize();

  // -- Get all feature flags
  const featureFlags = client.getFeatureFlags();
}

init();
Return value​

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

Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call

getVisitorFeatureFlags()​

caution

This method is deprecated and will be removed in the next major update. Please use the new getVariations method

The getVisitorFeatureFlags() method returns a list of feature flags that are active for the visitor with the specified visitorCode, ensuring that the visitor is allocated one of the variations.

  • 🚫 Doesn't send Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation (for each feature flag)
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<void> {
  await client.initialize();

  // -- Get visitor code using server `request` and `response`
  const visitorCode = client.getVisitorCode({
    request: req,
    response: res,
  });

  // -- Get active feature flags for visitor
  const featureFlags = client.getVisitorFeatureFlags(visitorCode);
}

init();
caution

This method only collects the visitor's active feature flags, meaning the result excludes all feature flags for which the visitor is assigned the off (default or control) variation.

For example:

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

Use getFeatureFlags when you need all of the visitor's feature flags:

// -- Both `off` and other variations are processed as expected.
client.getFeatureFlags('my_visitor').forEach(({ key }) => {
  client.getFeatureFlagVariationKey('my_visitor', key);
});
Arguments​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length
Return value​

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

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

getActiveFeatureFlags()​

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

This method is deprecated and will be removed in the next major update. Use the new getVariations method instead.

The getActiveFeatureFlags() method returns a Map, where the key represents the feature key, and the value contains detailed information about the visitor’s variation and its variables.

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<void> {
  await client.initialize();

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

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

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

init();
caution

This method only collects the visitor's active feature flags, meaning the result excludes all feature flags for which the visitor is assigned the off (default or control) variation.

See the getVisitorFeatureFlags method's CAUTION section for more details.

Arguments​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length
Return value​

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

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

setForcedVariation()​

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

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

info

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

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.

caution

It’s important to distinguish forced variations from simulated variations:

  • Forced variations: Are specific to an individual experiment.
  • Simulated variations: Affect the overall feature flag result.
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<void> {
  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();
Arguments​

An object of type SetForcedVariationParametersType with the following properties:

NameTypeDescriptionDefault
visitorCode (required)stringUnique identifier of the user.
experimentId (required)numberExperiment Id that will be targeted and selected during the evaluation process.
variationKey (required)string | nullVariation Key corresponding to a VariationType that should be forced as the returned value for the experiment. If the value is null, the forced variation will be reset.
forceTargeting (optional)booleanIndicates whether targeting for the experiment should be forced and skipped (true) or applied as in the standard evaluation process (false).true
Exceptions thrown​
TypeDescription
KameleoonException.VisitorCodeEmptyThe visitor code is empty.
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters).
KameleoonException.InitializationException indicating that the SDK is not fully initialized yet.
KameleoonException.FeatureFlagExperimentNotFoundException 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.FeatureFlagVariationNotFoundException 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.StorageReadCouldn't read storage data.
KameleoonException.StorageWriteCouldn't update storage data.
info

In most cases, you only need to handle the basic error, KameleoonException, as demonstrated in our example. However, if you need to respond to different types of errors, you can handle each one separately based on your requirements. Additionally, for enhanced reliability, you can (or should) also handle general language errors by including Error.

Variables​

getFeatureFlagVariable()​

caution

This method is deprecated and will be removed in the next major update. Use the new getVariation method instead.

The getFeatureFlagVariable() method retrieves a variable for the visitor based on the visitorCode within the identified feature flag. This method includes a targeting check, determines the appropriate variation for the visitor, saves it to storage, and sends a tracking request.

import {
  KameleoonClient,
  VariableType,
  JSONType,
} 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<void> {
  await client.initialize();

 // -- Get visitor code using server `request` and `response`
  const visitorCode = client.getVisitorCode({
    request: req,
    response: res,
  });


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

  // -- Infer the type of a variable by its `type`
  switch (result.type) {
    case VariableType.BOOLEAN:
      const myBool: boolean = result.value;
      break;
    case VariableType.NUMBER:
      const myNum: number = result.value;
      break;
    case VariableType.JSON:
      const myJson: JSONType = result.value;
      break;
    case VariableType.STRING:
    case VariableType.JS:
    case VariableType.CSS:
      const myStr: string = result.value;
      break;
    default:
      break;
  }
}

init();
Arguments​

Parameters object of type GetFeatureFlagVariableParamsType containing the following fields:

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length
featureKey (required)stringa unique key for a feature flag
variableKey (required)stringvariable's key for a feature flag with provided featureKey, can be found in Kameleoon
Return value​

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

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

getFeatureFlagVariables()​

caution

This method is deprecated and will be removed in the next major update. Use the new getVariation method instead.

The getFeatureFlagVariables() method retrieves a list of variable values for a specified visitor and feature flag. This method checks if the user is targeted, identifies the visitor’s assigned variation, stores it, and sends a tracking request.

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<void> {
  await client.initialize();

  // -- Get visitor code using server `request` and `response`
  const visitorCode = client.getVisitorCode({
    request: req,
    response: res,
  });

  // -- Get a list of variables for the visitor under `visitorCode` in the feature flag
  const variables = client.getFeatureFlagVariables(
    visitorCode,
    'my_feature_key',
  );
}

init();
Arguments​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length
featureKey (required)stringa unique key for the feature flag
Return value​

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

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

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.

note

When using getVisitorCode() with Deno, Next.js SSR, Node, or Express, ensure that you've implemented the correct external dependencies.

info

The getVisitorCode() method allows you to set simulated variations for a visitor. When cookies (from a request or document) contain the key kameleoonSimulationFFData, the standard evaluation process is bypassed. Instead, the method directly returns a VariationType based on the provided data.

View Details

You can apply simulations in two ways:

  • Automatically (recommended): If you use Kameleoon Web Experimentation or our SDK in Hybrid mode, the cookie will be created automatically when simulating a variant's display using our Simulation Panel.
  • Manually: Set the kameleoonSimulationFFData cookie yourself.

It’s important to distinguish simulated variations from forced variations:

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

⚙️ Manual setup

Please ensure that your 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.

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<void> {
  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
  //    (`cookie` imported from "next/headers")
  const visitorCode = client.getVisitorCode({
    cookie,
  });

  // -- 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();
Arguments​

The parameters object is overloaded with two types:

  • Type GetVisitorCodeParametersType (for NodeJS/Express/NextJS SSR methods), containing the following fields:
NameTypeDescription
request (required)IncomingMessageserver request
response (required)ServerResponseserver response
defaultVisitorCode (optional)stringvisitor code to be used if is no visitor code in the cookies
  • Type GetNextJSVisitorCodeParametersType (for NextJS SSR server actions), containing the following fields:
NameTypeDescription
cookies (required)typeof 'next/headers' cookieNextJS server actions headers cookie
defaultVisitorCode (optional)stringvisitor code to be used if is no visitor code available in the cookies
  • Type GetDenoVisitorCodeParametersType (for Deno), containing the following fields:
NameTypeDescription
request (required)DenoMessageserver request
response (required)DenoMessageserver response
defaultVisitorCode (optional)stringdefault 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:
NameTypeDescription
input (required)unknownarbitrary input object from which you want to read the visitor code
output (required)unknownarbitrary output object to which you want to write the visitor code
defaultVisitorCode (optional)stringvisitor code to be used in case there is no visitor code in the cookies
note

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

Return value​

string - result visitor code

Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call
KameleoonException.VisitorCodeMaxLengthThe maximum visitor code length was exceeded (255 characters)
KameleoonException.VisitorCodeEmptyThe 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() 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() method transmits any previously associated data. The getFeatureFlagVariationKey() and getFeatureFlagVariable() methods transmit data when an experimentation rule is triggered.

tip

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.

note

Check the list of supported conditions to see the data types you can use for targeting.

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<void> {
  await client.initialize();

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

  // -- Add one Data item to Storage
  client.addData('my_visitor_code', browserData);

  // -- Add Data to Storage using variadic style
  client.addData('my_visitor_code', browserData, customData);

  // -- Add Data to Storage in array
  const dataArr = [browserData, customData];
  client.addData('my_visitor_code', ...dataArr);
}

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

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

  • The custom data's 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​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.StorageWriteCouldn't update storage data
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call
note

Check the data types reference for more details on how to manage different data types.

flush()​

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 parameter. You can add visitor data using the addData() and 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, the SDK will attempt to send those stored requests before processing the latest request.

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<void> {
  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();
}

init();
Arguments​
NameTypeDescriptionDefault
visitorCode (optional)stringunique visitor identification string, can't exceed 255 characters in length, if not passed, all data will be flushed (sent to the remote Kameleoon servers)-
Exceptions thrown​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.InitializationMethod was executed before the kameleoonClient completed 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, you can efficiently manage large volumes of data and retrieve it for each of your visitors or users.

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<void> {
  await client.initialize();

  // -- Get remote data
  const jsonData = await getRemoteData('my_data_key');

  const data = JSON.parse(jsonData);
}

init();
Arguments​
NameTypeDescription
key (required)stringthe unique key with which the retrieved data is associated
Return value​

JSONType - promise with data retrieved for specific key

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

getRemoteVisitorData()​

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.

caution

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.

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<void> {
  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();
Arguments​

An object with the type RemoteVisitorDataParamsType, containing:

NameTypeDescriptionDefault Value
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters in length-
shouldAddData (optional)booleanboolean flag identifying whether the retrieved custom data should be added to storage automatically (without calling addData afterwards)true
filters (optional)VisitorDataFiltersTypefilters for specifying what data should be retrieved from visits, by default, only customData is retrieved from the current and latest previous visit{ previousVisitAmount: 1, currentVisit: true customData: true }, other filters parameters are set to false
Return value​

KameleoonDataType[] - promise with list of Kameleoon Data retrieved

Exceptions thrown​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.RemoteDataCouldn't retrieve data from Kameleoon server
KameleoonException.VisitAmountVisit amount must be a number between 1 and 25
KameleoonException.InitializationMethod was executed before 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.

note

Here is the list of available VisitorDataFiltersType filters:

NameTypeDescriptionDefault
previousVisitAmount (optional)numberNumber of previous visits from which to retrieve data. Number between 1 and 251
currentVisit (optional)booleanIf true, current visit data will be retrievedtrue
customData (optional)booleanIf true, custom data will be retrieved.true
pageViews (optional)booleanIf true, page data will be retrieved.false
geolocation (optional)booleanIf true, geolocation data will be retrieved.false
device (optional)booleanIf true, device data will be retrieved.false
browser (optional)booleanIf true, browser data will be retrieved.false
operatingSystem (optional)booleanIf true, operating system data will be retrieved.false
conversions (optional)booleanIf true, conversion data will be retrieved.false
experiments (optional)booleanIf true, experiment data will be retrieved.false
kcs (optional)booleanIf true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the AI Predictive Targeting add-on.false
visitorCode (optional)booleanIf 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 variant across visits for Cross-device experimentation.true
personalization (optional)booleanIf true, personalization data will be retrieved. This is required for the personalization conditionfalse
cbs (optional)booleanIf 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.

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<void> {
  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();
Arguments​

Parameters object consisting of:

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

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

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

setLegalConsent()​

note

When handling legal consent, it’s important you use the 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.

import { KameleoonClient } from '@kameleoon/javascript-sdk';

const client = new KameleoonClient({
  siteCode: 'my_site_code',
});

async function init(): Promise<void> {
  await client.initialize();

  const visitorCode = client.getVisitorCode();
  client.setLegalConsent(visitorCode, true);
}

init();
Arguments​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
consent (required)booleana boolean value representing the legal consent status. true indicates the visitor has given legal consent, false indicates the visitor has never provided or withdrawn legal consent
Exceptions thrown​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code length exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty

Goals and third-party analytics​

trackConversion()​

  • 📨 Sends Tracking Data to Kameleoon

Use this method to track a conversion for a specific 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.

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<void> {
  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();
Arguments​

Parameters object consisting of:

NameTypeDescriptionDefault
visitorCode (required)stringUnique identifier of the user.
goalId (required)numberID of the goal.
negative (optional)booleanDefines if the revenue is positive or negative.false
revenue (optional)numberRevenue of the conversion.0
metadata (optional)CustomData[]Metadata of the conversion.undefined
note

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() method. If the parameter is omitted, Kameleoon will use the last tracked values for those 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').

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​
TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters).
KameleoonException.VisitorCodeEmptyThe visitor code is empty.
KameleoonException.StorageWriteCouldn't update storage data.

getEngineTrackingCode()​

Kameleoon offers built-in integrations with various analytics and CDP solutions, such as Mixpanel, Google Analytics 4, and Segment. To help you track and analyze feature experiments, Kameleoon offers the getEngineTrackingCode() method, which returns JavaScript code to insert into your page to automatically send exposure events to your analytics solution.

The SDK builds a tracking code for your active analytics solution based on the experiments that the visitor has triggered in the last five seconds.

note

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

The getEngineTrackingCode() method returns the Kameleoon tracking code for the current visitor. The tracking code is based on the experiments that were triggered during the last five seconds.

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<void> {
  await client.initialize();

  // -- Trigger feature experiment
  // -- E.g., result `variationKey` id is `200`, and implicit experiment id is `100`
  client.getFeatureFlagVariationKey('visitor_code', '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();
note

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

For example:

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

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

string containing engine tracking code

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

Events​

onEvent()​

The onEvent() method fires a callback when a specific event is triggered. The callback function accesses the data associated with the event. The SDK methods in this documentation note which event types they trigger, if any.

note

You can only assign one callback to each EventType.

import {
  KameleoonClient,
  EventType,
  EvaluationEventDataType,
} 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<void> {
  await client.initialize();

  // -- Define logic that will execute on SDK event
  client.onEvent(EventType.Evaluation, (eventData: EventDataType) => {
    // -- My Logic
  });
}

init();
Events​

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

TypeeventData typeDescription
EventType.EvaluationEvaluationEventDataTypeTriggered when the SDK evaluates any variation for a feature flag. The event is triggered regardless of the result variation
EventType.ConfigurationUpdateConfigurationUpdateEventDataTypeTriggered when the SDK receives a configuration update from the server (when using real-time streaming)
Arguments​
NameTypeDescription
event (required)EventTypea variant of the event to associate the callback action with
callback (required)(eventData: EventDataType<EventType>) => voida callback function with the eventData parameter that is called when a configuration update occurs
Exceptions thrown​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed its initialize call

Data types​

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

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

note

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

Browser​

Browser contains browser information.

note

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

NameTypeDescription
browser (required)BrowserTypepredefined browser type (Chrome, InternetExplorer, Firefox, Safari, Opera, Other)
version (optional)numberversion of the browser, floating point number represents major and minor version of the browser
import { KameleoonClient, BrowserType, 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<void> {
  await client.initialize();

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

init();

UniqueIdentifier​

UniqueIdentifier data is used for unique visitor identification.

If you add UniqueIdentifier for a visitor, visitorCode is used as the unique visitor identifier, which is useful for Cross-device experimentation. Linking a UniqueIdentifier to a visitor informs the SDK that this visitor is associated with another visitor.

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

note

Each visitor can only have one UniqueIdentifier. Adding another UniqueIdentifier overwrites the first one.

NameTypeDescription
value (required)booleanvalue that specifies if the visitor is associated with another visitor, provided false will imply that the visitor is not associated with any other visitor
import { KameleoonClient, UniqueIdentifier } 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<void> {
  await client.initialize();

  // -- Add a unique identifier to a visitor
  client.addData('my_visitor_code', new UniqueIdentifier(true));
}

init();

Conversion​

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

tip
  • Each visitor can have multiple Conversion objects.
  • You can find the goalId in the Kameleoon app.

ConversionParametersType conversionParameters - an object with conversion parameters described below

NameTypeDescriptionDefault
goalId (required)numberID of the goal.
revenue (optional)floatRevenue of the conversion0
negative (optional)booleanDefines if the revenue is positive or negative.false
metadata (optional)CustomData[]Metadata of the conversion.undefined
import {
  KameleoonClient,
  ConversionParametersType,
  Conversion,
  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<void> {
  await client.initialize();

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

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

init();

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

The NodeJS SDK doesn't require a request or response to extract the cookie. Instead, add the cookie manually using Cookie data.

note

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

NameTypeDescription
cookie (required)CookieType[]A list of CookieType objects consisting of cookie keys and values
import { KameleoonClient, CookieType, Cookie } 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<void> {
  await client.initialize();

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

init();
Methods​

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

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

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

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

GeolocationData​

GeolocationData contains the visitor's geolocation details.

note

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

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

NameTypeDescription
country (required)stringThe visitor's country
region (optional)stringThe visitor's region
city (optional)stringThe visitor's city
postalCode (optional)stringThe visitor's postal code
coordinates (optional)[number, number]Coordinates array tuple of two location values (longitude and latitude). Coordinate number represents decimal degrees
import {
  KameleoonClient,
  GeolocationData,
  GeolocationInfoType,
} 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<void> {
  await client.initialize();

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

init();

CustomData​

CustomData allows any type of data to be easily associated with each visitor. It can then be used as a targeting condition in segments or as a filter/breakdown in experiment reports. To learn more about custom data, please refer to this article.

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

NameTypeDescription
index (required)numberThe unique index of the custom data.
value (required)string[]The custom data value. It must be stringifed to match the string type. Note value is variadic.
note

  • Each visitor is allowed only one CustomData for each unique index. Adding another CustomData with the same index will replace the existing one.

  • The custom data ‘index’ can be found in the Custom Data dashboard under the “INDEX” column.

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

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<void> {
  await client.initialize();

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

  const customDataIndex = 0;

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

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

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

  // -- Add custom data
  client.addData('my_visitor_code', customData);
}

init();

Device​

Device contains information about your device.

note

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

NameTypeDescription
deviceType (required)DeviceTypepossible variants for device type (PHONE, TABLET, DESKTOP)
import { KameleoonClient, DeviceType, Device } 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<void> {
  await client.initialize();

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

init();

OperatingSystem​

OperatingSystem contains information about the visitor's operating system.

note

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

NameTypeDescription
operatingSystem (required)OperatingSystemTypepossible variants for device type: WINDOWS_PHONE, WINDOWS, ANDROID, LINUX, MAC, IOS
import {
  KameleoonClient,
  OperatingSystem,
  OperatingSystemType,
} 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<void> {
  await client.initialize();

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

init();

PageView​

PageView contains information about your web page.

note

Each visitor can have one PageView per unique URL. Adding a PageView with the same URL notifies the SDK that the visitor revisited the page.

PageViewParametersType pageViewParameters - an object with page view parameters described below

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

You can find the referrer's index or ID in your Kameleoon account. Note that this index starts at 0, meaning the first acquisition channel you create for a given site will be assigned 0 as its ID, not 1.

import {
  KameleoonClient,
  PageViewParametersType,
  PageView,
} 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<void> {
  await client.initialize();

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

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

init();

UserAgent​

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

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

note

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

NameTypeDescription
value (required)stringvalue used for comparison
caution

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

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

import { KameleoonClient, UserAgent } 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<void> {
  await client.initialize();

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

init();

Returned Types​

VariationType​

VariationType contains information about the visitor''s assigned variation (or the default variation, if no specific assignment exists).

NameTypeDescription
keystringkey of the variation
idnumber or nullid of the variation or null if the visitor hit default variation
experimentIdnumber or nullid of the experiment or null if the visitor hit default variation
variablesMap<string, KameleoonVariableType>map of variables for the variation, where key is the variable key and value is the variable object
note
  • Ensure that your code handles the case where id or experimentId may be null, indicating a default variation.
  • The variables map might be empty if no variables are associated with the variation.
// -- Get all feature flag variations with tracking
const variations = client.getVariations({
  visitorCode,
});

// -- 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,
//      }
//    },
//   }
// }