Skip to main content

NodeJS SDK

Introduction

Welcome to the developer documentation for the Kameleoon NodeJS SDK! Our SDK gives you the possibility of running feature experiments and activating feature flags on your server application. Integrating our SDK into your server is easy, and its footprint (in terms of memory and network usage) is low.

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.


Changelog

Latest version description of NodeJS SDK can be found here.


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-event-source": "@kameleoon/nodejs-event-source@^1.0"
"@kameleoon/deno-visitor-code-manager": ":@kameleoon/deno-visitor-code-manager@^1.0",
}
}

Contents

To configure your NodeJS server and start running feature experiments and deploying new features to your users, please follow the instructions provided in the Main usage section. This section contains all the main steps for proper Kameleoon NodeJS SDK configuration as well as main tools for development.

  1. Initializing the Kameleoon Client
  2. Getting access to feature flags and variations
  3. Using Kameleoon Client methods

We highly recommend that you take a look at the Methods section, which includes useful information on every method that is introduced in NodeJS SDK.

Explore additional sections with some useful information on Kameleoon:


Main Usage

Here is a step-by-step guide for configuring NodeJS SDK for your application.

1. Initializing the Kameleoon Client

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,
domain: '.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) => {});

For the start 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.

Arguments
NameTypeDescription
siteCode (required)stringclient's site code defined on Kameleoon platform
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
integrations (optional)IntegrationTypecompute edge integrations, see Integration with Edge providers

Throws

TypeDescription
KameleoonException.CredentialsClient credentials were not provided or are empty
note

configuration consists of following 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)number or undefinedinterval in minutes for cleaning up targeting data, minimum value is 1 minute30
domain (optional)string or undefineddomain which cookie belongs to, Read More about Domainundefined
requestTimeout (optional)number or undefinedtimeout in milliseconds for all SDK network requests, if timeout is exceeded request will fail immediately10_000 (10 seconds)

2. Getting access to feature flags and variations

note

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

After the SDK has been initialized, you can obtain a feature flag configuration. Subsequently, all methods will require you to specify the User ID or visitor code associated with the request.

note

If you are using Kameleoon in Hybrid mode with mixed front-end and back-end environments, you can call the getVisitorCode method to obtain the Kameleoon visitorCode for the current visitor. Alternatively, if you provide your own user ID, you must ensure its uniqueness on your end.

3. Using Kameleoon Client methods

Now your setup is done! You can use KameleoonClient methods to run feature experiments.

To associate various data points with the current user, you can use the addData method. This method requires the visitorCode as the first parameter and accepts several additional parameters. These additional parameters represent the various Data Types allowed in Kameleoon.

import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: {
domain: '.example.com',
},
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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 user data
const customDataIndex = 0;
client.addData(visitorCode, new CustomData(customDataIndex, 'my_data'));

// -- Check if the feature is active for visitor
const isMyFeatureActive = client.isFeatureFlagActive(
visitorCode,
'my_feature_key',
);

// -- Track conversion
client.trackConversion({ visitorCode, revenue: 20000, goalId: 123 });
}

init();

Feature flags can be very useful for implementing ON/OFF switches with optional but advanced user targeting rules. However, you can also use feature flags to run feature experiments with several variations of your feature flag. Check out our documentation on creating feature experiments for more information.

note

See Methods section for detailed guide for each KameleoonClient method available.


Methods

Get Visitor Code / Use Own Visitor ID

KameleoonClient getVisitorCode

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { IncomingMessage, ServerResponse } from 'http';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Method getVisitorCode obtains a visitor code from the request headers cookie. If the visitor code doesn't exist yet, the method generates a random visitor code (or uses the defaultVisitorCode value if you provided one) and sets the new visitor code in a response headers cookie.

note

getVisitorCode utilizes native NodeJS types for request and response, which are IncomingMessage and ServerResponse imported from http module. However if you are using Express framework, Deno or NextJS SSR methods like getServerProps the types of request and response will not match. This could be easily overcome using type cast as in example, it will produce identical result.

note

When using getVisitorCode with Deno, NextJS SSR, Node, or Express, make sure that the correct external dependencies have been implemented.

Parameters

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 in case there is no visitor code in 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 when there 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 cookies
  • Type GetCustomVisitorCodeParametersType (for custom VisitorCodeManager implementation) containing the following fields:
NameTypeDescription
input (required)unknownarbitrary input object that you want to read the visitor code from
output (required)unknownarbitrary output object that you want to write the visitor code to
defaultVisitorCode (optional)stringvisitor code to be used in case there is no visitor code in cookies
  • Type
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.

Returns

string - result visitor code

Throws

TypeDescription
KameleoonException.InitializationMethod was executed before the kameleoonClient completed it's initialize call
KameleoonException.VisitorCodeMaxLengthThe visitor code length was exceeded
KameleoonException.VisitorCodeEmptyThe visitor code is empty

Get Kameleoon Client Configuration URL

KameleoonUtils getClientConfigurationUrl

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

// -- Get Kameleoon Client Configuration URL
const uri = KameleoonUtils.getClientConfigurationUrl(
'my_site_code',
Environment.Development,
);

The static method getClientConfigurationUrl called on KameleoonUtils obtains the Kameleoon Client Configuration URL. Use this URL to retrieve a JSON representation of your feature flags. The JSON data contains all the information you need to activate your feature flags.

Parameters

NameTypeDescription
siteCode (required)stringclient's siteCode defined on Kameleoon platform
environment (optional)EnvironmentThe feature flag environment for which you want to retrieve the client configuration URL. Before using the configuration URL, make sure the environment is turned on in the Rollout Planner in the Kameleoon app. The default environment is Environment.Production

Returns

string - Kameleoon Client Configuration URL


Initialize Kameleoon Client

initialize

import {
KameleoonError,
KameleoonClient,
KameleoonException,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

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.

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

Add associated client data

addData

import {
KameleoonClient,
BrowserType,
CustomData,
Browser,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

The addData() method adds targeting data to storage so other methods can use the data to decide whether or not to target the current visitor.

The addData() method does not return any value and does not interact with Kameleoon back-end servers on its own. Instead, all the declared data is saved for future transmission using the flush method. This approach reduces the number of server calls made, as the data is typically grouped into a single server call that is triggered the flush.

The trackConversion method also sends out any previously associated data, just like the flush. The same holds true for getFeatureFlagVariationKey and getFeatureFlagVariable methods if 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. Visitors can have one instance of associated CustomData per customDataIndex.

note

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

Parameters

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters 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 variadic argument it can be passed as one or several arguments (see the example)

note

The index or ID of the custom data can be found in your Kameleoon account. It is important to note that this index starts at 0, which means that the first custom data you create for a given site will be assigned 0 as its ID, not 1.

Throws

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 it's initialize call
note

Check Data Types reference for more details of how to manage different data types


Track Conversion

trackConversion

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

// -- Track conversion with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.trackConversion({
visitorCode: internalUserId,
revenue: 20000,
goalId: 123,
isUniqueIdentifier: true,
});
}

init();

trackConversion() creates and adds Conversion data to the visitor with the specified parameters and executes the flush method.

note

This helper method is useful for simple conversion tracking. However, you can also create your own Conversion data and flush (add) it manually. Using the data type allows for more flexible Conversion tracking, including use of the negativeparameter.

If you specify a visitorCode and set isUniqueIdentifier to true, the trackConversion() method uses it as the unique visitor identifier, which is useful for Cross-device experimentation because the SDK links the flushed data with the visitor that is associated with the specified identifier.

note

The isUniqueIdentifier can also be useful in other edge-case scenarios, such as when you don’t have the context you need to reuse the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

Parameters

Parameters object consisting of:

NameTypeDescriptionDefault
visitorCode (required)stringUnique visitor identifier string. Can't exceed 255 characters length.-
goalId (required)numberGoal to be sent in tracking request-
revenue (optional)numberRevenue to be sent in tracking request-
isUniqueIdentifier (optional)booleanOptional parameter that specifies whether the visitorCode is a unique identifierfalse

Throws

TypeDescription
KameleoonException.VisitorCodeMaxLengthThe visitor code exceeded the maximum length (255 characters)
KameleoonException.VisitorCodeEmptyThe visitor code is empty
KameleoonException.StorageWriteCouldn't update storage data

Flush tracking data

flush

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

// -- Flush data with unique visitor identifier flag
const internalUserId = 'my_user_id';
client.flush(internalUserId, true);
}

init();

flush() takes the Kameleoon data associated with the visitor and sends the data tracking request along with all of the data that's been added previously using the addData method.

If you don't specify a visitorCode, the SDK flushes all of its stored data to the remote Kameleoon servers. If any previously failed tracking requests were stored locally during offline mode, the SDK attempts to send the stored requests before executing the latest request.

If you specify a visitorCode and set isUniqueIdentifier to true, the flush() method uses it as the unique visitor identifier, which is useful for Cross-device experimentation because the SDK links the flushed data with the visitor that is associated with the specified identifier.

note

The isUniqueIdentifier parameter can also be useful in other edge-case scenarios, such as when you can't access the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

Parameters

NameTypeDescriptionDefault
visitorCode (optional)stringunique visitor identification string, can't exceed 255 characters length, if not passed all the data will be flushed (sent to the remote Kameleoon servers)-
isUniqueIdentifier (optional)booleanan optional parameter for specifying if the visitorCode is a unique identifierfalse

Throws

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 it's initialize call

Get list of all feature flags

getFeatureFlags

🚫 Doesn't send Tracking Data to Kameleoon

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

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

init();

Method getFeatureFlags() returns a list of feature flags stored in the client configuration

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

Get list of feature flags for a certain visitor

getVisitorFeatureFlags

  • 🚫 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';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Method getVisitorFeatureFlags() returns a list of feature flags that the visitor with visitorCode that is targeted by and that are active for the visitor (visitor will have one of the variations allocated).

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 experiment
// it only returns feature flags, where visitor didn't get `off` variation
client.getVisitorFeatureFlags('my_visitor').forEach(({ key }) => {
// -- `getFeatureFlagVariationKey` triggers a feature experiment,
// as `off` is already filtered out - we will never see
// visitor taking part in experiment, where `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

Get list of feature flags for a certain visitor with variation details and variables

getActiveFeatureFlags

  • 🚫 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';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Method getActiveFeatureFlags() returns a Map, where key is feature key and value is detailed information about the visitor's variation and it's variables

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

Check if the feature is active for visitor

isFeatureFlagActive

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

init();

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.

note

Visitor must be targeted to has feature flag active

Parameters

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag

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.

Get variation key for a certain feature flag

getFeatureFlagVariationKey

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation
import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Method getFeatureFlagVariationKey() returns variation key for the visitor under visitorCode in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request.

note

If the user has never been associated with the feature flag, the SDK returns a variation key randomly, following the feature flag rules. If the user is already registered with the feature flag, the SDK detects the previous variation key value. If the user doesn't match any of the 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 be a variation key, but a boolean value or another data type, depending on the feature flag configuration.

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

Get a variable of a certain feature flag

getFeatureFlagVariable

  • 📨 Sends Tracking Data to Kameleoon
  • 🎯 Events: EventType.Evaluation
import {
KameleoonClient,
VariableType,
JSONType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
}
});

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 variable by it's `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:
const myStr: string = result.value;
break;
default:
break;
}
}

init();

Method getFeatureFlagVariable() returns a variable for the visitor under visitorCode in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request.

Parameters

Parameters object of type GetFeatureFlagVariableParamsType containing the following fields:

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for feature flag
variableKey (required)stringkey of the variable to be found for a feature flag with provided featureKey, can be found on Kameleoon Platform

Returns

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

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
KameleoonException.JSONParseCouldn't parse JSON value
KameleoonException.NumberParseCouldn't parse Number value

Get all variables of a certain feature flag

getFeatureFlagVariables

  • 📨 Sends 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';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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 found feature flag
const variables = client.getFeatureFlagVariables(
visitorCode,
'my_feature_key',
);
}

init();

Method getFeatureFlagVariables() returns a list of variable values for the specified visitor and feature flag. This method checks whether the user is targeted, finds the visitor's assigned variation, saves it to storage, and sends the tracking request.

Parameters

NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
featureKey (required)stringa unique key for the feature flag

Returns

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

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

Obtain data from Kameleoon remote source

getRemoteData

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

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

const data = JSON.parse(jsonData);
}

init();

Method getRemoteData() returns a data which is stored for specified site code on a remote Kameleoon server

For example, you can use this method to retrieve user preferences, historical data, or any other data relevant to your application's logic. By storing this data on our highly scalable servers using our Data API, you can efficiently manage massive amounts of data and retrieve it for each of your visitors or users.

Parameters

NameTypeDescription
key (required)stringunique key that the data you try to get is associated with

Returns

JSONType - promise with data retrieved for specific key

Throws

TypeDescription
KameleoonException.RemoteDataCouldn't retrieve data from Kameleoon server

Define an action for real time configuration update

onConfigurationUpdate

danger

This method is deprecated and will be removed in the future. Use the onEvent method with EventType.ConfigurationUpdate instead.

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

// -- Define logic to be executed on client configuration update
client.onConfigurationUpdate(() => {
// -- My Logic
});
}

init();

Method onConfigurationUpdate() fires a callback on client configuration update.

note

This method only works for server sent events of real time update

Parameters

NameTypeDescription
callback (required)() => voidcallback function with no parameters that will be called upon configuration update

Throws

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

Define an action for a specific event

onEvent

import {
KameleoonClient,
EventType,
EvaluationEventDataType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

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

init();

Method onEvent() fires a callback when a specific event is triggered. The callback function can access 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.

Events

Events are defined in the EventType enum. Depending on the event type, the eventData parameter will have a different 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)

Parameters

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

Throws

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

Obtain Kameleoon Visits Data from Kameleoon Data API

getRemoteVisitorData

import {
KameleoonClient,
KameleoonDataType,
VisitorDataFiltersType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

getRemoteVisitorData() is an asynchronous method for retrieving Kameleoon Visits Data for the visitorCode from the Kameleoon Data API. The method adds the data to storage for other methods to use when making targeting decisions.

Data obtained by getRemoteVisitorData plays important role when you are woking with conditions that use asynchronously pre-loaded data. Make sure to use this when working with these conditions.

note

By default, getRemoteVisitorData automatically attaches the latest custom data entry with scope=Visitor to the visitor without calling addData. You can use this data for Synchronizing custom data across devices.

note

The isUniqueIdentifier parameter can be useful in edge-case scenarios, such as when you can't access the anonymous visitorCode that was originally assigned to the visitor, but you do have access to an internal ID that is connected to the anonymous visitor using session merging capabilities.

Parameters

An object with the type RemoteVisitorDataParamsType containing:

NameTypeDescriptionDefault Value
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters 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
isUniqueIdentifier (optional)booleanoptional parameter that, when true, specifies the visitorCode is a unique identifierfalse

Here is the list of available VisitorDataFiltersType filters:

NameTypeDescriptionDefault
previousVisitAmount (optional)numberNumber of previous visits to retrieve data from. 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 data will be retrieved.false

Returns

KameleoonDataType[] - promise with list of Kameleoon Data retrieved

Throws

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 it's initialize call

Retrieve warehouse audience data

getVisitorWarehouseAudience

import {
KameleoonClient,
KameleoonDataType,
CustomData,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

getVisitorWarehouseAudience is an asynchronous method that retrieves all audience data associated with the visitor in your data warehouse using the specified visitorCode and warehouseKey. The warehouseKey is typically your internal user ID. The customDataIndex parameter corresponds to the Kameleoon custom data that Kameleoon uses to target your visitors. Refer to the warehouse targeting documentation for additional details.

Parameters

Parameters object consisting of:

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

Returns

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

Throws

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

Sending exposure events to external tools

Kameleoon offers built-in integrations with various analytics and CDP solutions, such as Mixpanel, Google Analytics 4, and Segment. To ensure that you can track and analyze your feature experiments, Kameleoon provides a method getEngineTrackingCode() that returns the JavasScript code to be inserted in your page to automatically send the exposure events to the analytics solution you are using. The SDK builds a tracking code for your active analytics solution based on the experiments that the visitor has triggered in the last 5 seconds.

note

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

getEngineTrackingCode

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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]);
// window.kameleoonQueue.push(['Experiments.trigger', 100, true]);
// `
}

init();

Method getEngineTrackingCode() returns Kameleoon tracking code for the current visitor. Tracking code is built based the experiments that were triggered during the last 5 seconds.

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]);
window.kameleoonQueue.push(['Experiments.trigger', 100, true]);
`;
const script = document.createElement('script');

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

Parameters

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

Returns

string containing engine tracking code

Throws

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

setLegalConsent

import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { ServerResponse } from 'http';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
configuration: { domain: '.example.com' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

const visitorCode = client.getVisitorCode({
request: req,
response: res,
});

// -- Set consent using native NodeJS `response`
client.setLegalConsent({ visitorCode, consent: true, response: res });

// -- Set consent using `Express`/`Deno`/`NextJS SSR methods`
client.setLegalConsent({
visitorCode,
consent: true,
response: res,
});

// -- Set consent using `NextJS` server side actions
// (`cookie` imported from "next/headers")
client.setLegalConsent({ visitorCode, consent: true, cookie });

// -- Set consent using custom `VisitorCodeManager` implementation
// `myInput` and `myOutput` are custom objects of arbitrary type
// according types should be defined in custom `VisitorCodeManager` implementation
client.setLegalConsent({ visitorCode, input: myInput, output: myOutput });
}

init();

Method setLegalConsent specifies whether the visitor has given legal consent to use personal data. Setting the legalConsent parameter to false limits the types of data that you can include in tracking requests. This helps you adhere to legal and regulatory requirements while responsibly managing visitor data. You can find more information on personal data in the Consent management policy.

note

setLegalConsent uses the NodeJS native type ServerResponse for a response imported from the http module. However if you are using the Express framework, Deno, or NextJS SSR methods, such as getServerProps, the type response will not match. A simple type cast as shown in the example resolves this and produces an identical result.

note

Note that for setLegalConsent with Deno, NextJS SSR, Node, or Express, make sure that you have implemented the correct external dependencies.

Parameters

The parameters object is overloaded with two types:

  • Type SetLegalConsentParametersType (for NodeJS, Express, or NextJS SSR methods) containing the following fields:
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 has withdrawn, legal consent
response (required)ServerResponseresponse object to write the updated cookie to
  • Type SetNextJSLegalConsentParametersType (for NextJS SSR server actions) containing the following fields:
NameTypeDescription
visitorCode (required)stringunique visitor identification string, can't exceed 255 characters length
consent (required)booleanboolean value representing the legal consent status. true indicates the visitor has given legal consent, false indicates the visitor has never provided, or has withdrawn, legal consent
cookies (required)typeof 'next/headers' cookieNextJS server actions headers cookie
  • Type SetDenoLegalConsentParametersType (for Deno) containing the following fields:
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 has withdrawn, legal consent
response (required)DenoMessageresponse object to write the updated cookie to
  • Type SetCustomLegalConsentParametersType (for custom VisitorCodeManager implementation) containing the following fields:
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 has withdrawn, legal consent
output (required)unknownarbitrary output object, to which the updated consent should be written

Throws

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

Data Types

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

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

note

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

Browser

import { KameleoonClient, BrowserType, Browser } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Browser contains browser information.

note

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

Parameters

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

Conversion

import {
KameleoonClient,
ConversionParametersType,
Conversion,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

// -- Defined conversion parameters
const conversionParameters: ConversionParametersType = {
goalId: 123,
revenue: 10000,
negative: true,
};

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

init();

Conversion contains information about your conversion.

note

Each visitor can only have one CustomData per unique index, adding another CustomData with the same index will overwrite the existing one

note

goalId can be found on Kameleoon Platform

Parameters

ConversionParametersType conversionParameters - an object with conversion parameters described below

NameTypeDescriptionDefault Value
goalId (required)numberan id of a goal to track-
revenue (optional)numberan optional parameter for revenue0
negative (optional)booleanan optional parameter identifying whether the conversion should be removedfalse

import { KameleoonClient, CookieType, Cookie } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

Cookie data information about the cookie on the visitor's device.

NodeJS SDK doesn't require a request or response to implicitly 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.

Parameters

NameTypeDescription
cookie (required)CookieType[]A list of CookieType objects consisting of cookie keys and values

Methods

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

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

import {
KameleoonClient,
GeolocationData,
GeolocationInfoType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

GeolocationData contains the visitor's geolocation details.

note

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

Parameters

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

NameTypeDescription
country (required)stringThe country of the visitor
region (optional)stringThe region of the visitor
city (optional)stringThe city of the visitor
postalCode (optional)stringThe postal code of the visitor
coordinates (optional)[number, number]Coordinates array tuple of two location values (longitude and latitude). Coordinate number represents decimal degrees

CustomData

import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

CustomData is usually used with a custom data targeting condition on the Kameleoon platform to determine whether the visitor is targeted or not.

To persist the custom data across future visits, the SDK sends CustomData with Visitor scope with the next tracking request. You can set the scope in the data configuration on the Custom Data Dashboard.

note

The index or ID of the custom data can be found in your Kameleoon account. It is important to note that this index starts at 0, which means that the first custom data you create for a given site will be assigned 0 as its ID, not 1.

note

To prevent the SDK from flushing the data with the selected index to the Kameleoon servers, check the Only save this data in Local Storage on the user's device, not on a server option when creating a new custom data entry on the Custom Data dashboard.

It's a useful option if you only want to utilize your private custom data for targeting.

Parameters

NameTypeDescription
index (required)numberan index of custom data to be stored under in a state, an index of custom data can be specified in Advanced Tools section of Kameleoon Application
value (optional)string[]custom value to store under the specified id, value can be anything but has to be stringified to match the string type. Note value is variadic parameter and can be used as follows

Device

import { KameleoonClient, DeviceType, Device } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});

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

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

init();

Device contains information about your device.

note

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

Parameters

NameTypeDescription
deviceType (required)DeviceTypepossible variants for device type (PHONE, TABLET, DESKTOP)

OperatingSystem

import {
KameleoonClient,
OperatingSystem,
OperatingSystemType,
} from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';

const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(