Skip to main content

NodeJS SDK

With the NodeJS SDK, you can run experiments and activate feature flags. 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.1.1 Changelog.

note

Before you begin installing our NodeJS SDK, we recommend that you read our technical considerations article to gain an understanding of the fundamental technological concepts behind our SDKs. This will help you to better understand the SDK and ensure a successful integration.

Developer Guide​

Follow this section to install and configure the SDK as well as learn about advanced features.

Get started​

Installation​

The Kameleoon SDK Installation tool is the preferred way to install the SDK quickly. 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:

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​

To begin, developers will need to create an entry point for 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 initialization is done asynchronously in order to make sure that Kameleoon API call was successful for that method initialize() is used. You can use async/await, Promise.then() or any other method to handle asynchronous client initialization.

note

In order to add NodeJS SDK to an Edge environment please refer to integration with Edge providers.

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 a 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)Compatibilitycompatibility mode for the SDK, see Compatibility Mode
integrations (optional)IntegrationTypecompute edge integrations, see Integration with Edge providers
Throws​
TypeDescription
KameleoonException.CredentialsClient credentials were not provided or are empty
Configuration Parameters​
NameTypeDescriptionDefault Value
updateInterval (optional)numberupdate interval in minutes for sdk configuration, minimum value is 1 minute60
environment (optional)Environmentfeature flag environmentEnvironment.Production
targetingDataCleanupInterval (optional)numberinterval in minutes for cleaning up targeting data, minimum value is 1 minute30
cookieDomain (optional)stringdomain that the cookie belongs to.undefined
networkDomain (optional)stringcustom 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). If the format is invalid, the SDK uses the default Kameleoon valueundefined
requestTimeout (optional)numbertimeout in milliseconds for all SDK network requests, if timeout is exceeded request will fail immediately10_000 (10 seconds)
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, which is performed once per interval. The minimum value is 100 ms and the maximum value is 1_000 ms1_000 (1 second)
Compatibility Mode​

The SDK parameter compatibility allows to disable some of the SDK feature to improve compatibility with older NodeJS versions. Compatibility is an enum representing all possible compatibility modes:

  • Compatibility.Node16 - default mode, all features are enabled. It will be used if no compatibility mode isn't provided. Supports Node version 16 and higher.
  • Compatibility.Node14 - compatibility with this version will make 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 for Node14 compatibility mode, moreover, it will not allow to provide "@kameleoon/nodejs-requester" as a requester implementation as it uses "node-fetch" library not supporting Node.js 12.x.x version. In that case a developer must provide a custom requester implementation of their own choice, such as older "node-fetch" version or other HTTP based implementation.

Activating a feature flag​

Assigning a unique ID to a user​

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

If you are using Kameleoon in Hybrid mode, calling the getVisitorCode() method ensures that the unique ID (visitorCode) is shared between the application file (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.

To determine if a feature flag is active for a specific user, you need to retrieve its configuration. Use the getFeatureFlagVariationKey() or isFeatureFlagActive() method to retrieve the configuration based on the featureKey.

The isFeatureFlagActive() method can be used if you want to retrieve the configuration of a simple feature flag that has only an ON or OFF state, as opposed to more complex feature flags with multiple variations or targeting options.

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. To retrieve these variables, use the getFeatureFlagVariables() method. This method checks whether the user is targeted, finds the visitor’s assigned variation, saves it to storage, and sends a tracking request.

note

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

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 past data points about a user (which would have been collected client-side if you are using Kameleoon in Hybrid mode), use the getRemoteVisitorData() method. This method asynchronously fetches data from our servers. However, it is important you 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, allowing you to filter and break down your results by factors like device and browser. Kameleoon Hybrid mode automatically collects a variety of data points on the client-side, making it easy to break down your results based on these pre-collected data points. See the complete list here.

If you need to track additional data points beyond what's automatically collected, you can use Kameleoon's Custom Data feature. Custom Data allows you to capture and analyze specific information relevant to your experiments. To ensure your results are accurate, it's recommended to filter out bots by using the userAgent data type. You can learn more about this 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 as soon as 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. To track conversions, you must use the trackConversion() method, and provide the visitorCode and goalId parameters.

Sending events to analytics solutions​

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

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

Error Handling​

Almost every KameleoonClient method may throw an error at some point, these errors are not just caveats but rather deliberately predefined KameleoonErrors that extend native JavaScript Error class providing useful messages and special type field with a type KameleoonException.

KameleoonException is an enum containing all possible error variants.

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

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

import {
  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 the other edge providers, you can utilize a power of External Dependencies to control any moving part of 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 now available to target and track "my_visitor".
}

init();

Using custom data for session merging​

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

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

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

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

Before using other methods make sure to let SDK know that the visitor is a unique identifier by adding UniqueIdentifier data to a visitor

tip

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

Here's an example of how to use custom data for session merging.

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

Login Page
import { 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);

  // -- 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. This is important when working with the getVisitorCode and setLegalConsent methods. The domain you provide is stored in the cookie as the Domain= key.

Setting the domain​

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

To be more flexible around subdomains you can specify domain starting with the ., 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 are not allowed to be used with the prefix ..

Here's a small domain cheat sheet:

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

Developing on localhost​

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

There are two ways to avoid this issue:

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

External dependencies​

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

note

In the NodeJS SDK, some external dependencies have default implementations while others must be provided by the user, whether using dedicated Kameleoon implementations or custom ones.

Here's the list of available external dependencies:

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

You can also implement visitorCodeManager using the IExternalNextJSVisitorCodeManager, IExternalDenoVisitorCodeManager, IExternalCustomVisitorCodeManager interfaces for NextJS, Deno, or custom visitor code manager implementations, respectively.

External dependencies grant developer a flexibility to adapt and use NodeJS SDK in any environment, moreover there is a number of packages provided by Kameleoon for some frequently used environments in form of dedicated npm packages. You can install them manually or using SDK installation tool (recommended). 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

Optionally you can 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​

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

simulateSuccessRequest​

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

import {
  KameleoonUtils,
  IExternalRequester,
  SendRequestParametersType,
  RequestType,
  KameleoonResponseType,
} from '@kameleoon/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);
  }
}
Parameters​
NameTypeDescription
requestType (required)RequestTypeA type of request
data (required)SimulateRequestDataType[RequestType]A type of request data, which is different depending on RequestType

Data type SimulateRequestDataType is defined as follows:

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

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

getCookieValue​

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

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

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

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

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

Reference​

This is the full reference documentation for the Kameleoon JavaScript SDK.

Initialization​

initialize()​

An asynchronous method for KameleoonClient initialization by fetching Kameleoon SDK related data from server or by retrieving data from local source if data is up-to-date or update interval has not been reached.

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

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

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

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

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

Method isFeatureFlagActive() returns a boolean indicating whether the visitor with visitorCode has featureKey active for that visitor. This method checks for targeting, finds the variation for the visitor, and saves it to storage. THe method also sends the tracking request.

There is an additional overload for this method that allows you to pass a track parameter, which disables the tracking of feature evaluation.

note

Visitor must be targeted to has feature flag active

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

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 length-
featureKey (required)stringa unique key for feature flag-
track (optional)booleana boolean indicator of whether to track the feature evaluationtrue
Returns​

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

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

getFeatureFlagVariationKey()​

caution

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

The method getFeatureFlagVariationKey() returns the variation key for the visitor under visitorCode in the found 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 previously been associated with the feature flag, the SDK will randomly return a variation key in accordance with the feature flag's rules. If the user is already linked to the feature flag, the SDK will recognize the 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. It’s important to note that the default value may not always be a variation key; it could also be a boolean value or another data type, depending on how the feature flag is configured.

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();
Parameters​
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
Returns​

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

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

getFeatureFlags()​

🚫 Doesn't send Tracking Data to Kameleoon

caution

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

The method getFeatureFlags() 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();
Returns​

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

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

getVisitorFeatureFlags()​

caution

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

Method getVisitorFeatureFlags() 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. This means the result excludes all the feature flags for which the visitor is assigned to the off (default or control) variation. When you need all of the visitor's feature flags, use getFeatureFlags instead.

For example:

// -- `getVisitorFeatureFlags` doesn't trigger feature 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);
});

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

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

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

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

getActiveFeatureFlags()​

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

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

Method getActiveFeatureFlags() 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 retrieves only the active feature flags for the visitor. This means that any feature flags assigned to the off (default or control) variation will be excluded from the results. If you need to access all of the visitor’s feature flags, use getFeatureFlags instead.

See CAUTION section of the the getVisitorFeatureFlags method for more details.

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

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

Throws​
TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length 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();
Parameters​

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
Throws​
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 also handle general language errors by including Error.

Variables​

getFeatureFlagVariable()​

caution

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

The method getFeatureFlagVariable() retrieves a variable for the visitor based on 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.