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.
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
:
{
"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.
- Initializing the Kameleoon Client
- Getting access to feature flags and variations
- 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.
- KameleoonClient getVisitorCode - Obtain Visitor Code / Use own User ID using KameleoonClient (recommended)
- KameleoonUtils getClientConfigurationUrl - Obtain Kameleoon Client Configuration URL
- initialize - Initialize Kameleoon Client
- addData - Add associated client data
- trackConversion - Track Conversion
- flush - Flush tracking data
- getRemoteData - Obtain data from Kameleoon remote source
- getRemoteVisitorData - Obtain Kameleoon Visits Data from Kameleoon Data API
- getVisitorWarehouseAudience - Retrieve warehouse audience data
- isFeatureFlagActive - Check if the feature is active for visitor
- getFeatureFlags - Get list of all feature flags
- getVisitorFeatureFlags - Get list of feature flags for a certain visitor
- getFeatureFlagVariationKey - Get variation key for a certain feature flag
- getFeatureFlagVariable - Get a variable of a certain feature flag
- getFeatureFlagVariables - Get a list of variables of a certain feature flag
- onConfigurationUpdate - Define an action for real time configuration update
- getEngineTrackingCode - Sending exposure events to external tools
- setLegalConsent - Set legal consent for visitor
Explore additional sections with some useful information on Kameleoon:
- Data types
- Targeting Conditions
- Integration with Edge providers
- Synchronizing custom data across devices
- Using custom data for session merging
- Domain information
- External dependencies
- Error handling.
Main Usage
Here is a step-by-step guide for configuring NodeJS SDK for your application.
1. Initializing the Kameleoon Client
- Typescript
- Javascript
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) => {});
import { Environment, KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
// -- Mandatory credentials
const credentials = {
clientId: 'my_client_id',
clientSecret: 'my_client_secret',
};
// -- Optional configuration
const configuration = {
updateInterval: 20,
environment: Environment.Production,
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() {
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.
In order to add NodeJS SDK to an Edge environment please refer to Integration with Edge providers.
Arguments
Name | Type | Description |
---|---|---|
siteCode (required) | string | client's site code defined on Kameleoon platform |
credentials (required) | CredentialsType | client API credentials, see Credentials Flow for more information |
externals (required) | ExternalsType | external implementation of SDK dependencies (External dependencies) |
configuration (optional) | Partial<SDKConfigurationType> | client's configuration |
integrations (optional) | IntegrationType | compute edge integrations, see Integration with Edge providers |
Throws
Type | Description |
---|---|
KameleoonException.Credentials | Client credentials were not provided or are empty |
configuration
consists of following parameters:
Name | Type | Description | Default Value |
---|---|---|---|
updateInterval (optional) | number | update interval in minutes for sdk configuration, minimum value is 1 minute | 60 |
environment (optional) | Environment | feature flag environment | Environment.Production |
targetingDataCleanupInterval (optional) | number or undefined | interval in minutes for cleaning up targeting data, minimum value is 1 minute | 30 |
domain (optional) | string or undefined | domain which cookie belongs to, Read More about Domain | undefined |
requestTimeout (optional) | number or undefined | timeout in milliseconds for all SDK network requests, if timeout is exceeded request will fail immediately | 10_000 (10 seconds) |
2. Getting access to feature flags and variations
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.
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.
- Typescript
- Javascript
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();
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() {
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.
See Methods section for detailed guide for each KameleoonClient
method available.
Methods
Get Visitor Code / Use Own Visitor ID
KameleoonClient getVisitorCode
- Typescript
- Javascript
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 as IncomingMessage,
response: res as ServerResponse,
defaultVisitorCode: 'my_default_visitor_code',
});
// -- Get visitor code using `NextJS` server side actions
// (`cookie` imported from "next/headers")
const visitorCode = client.getVisitorCode({
cookie,
});
}
init();
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() {
await client.initialize();
// -- Get visitor code using native `NodeJS` `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Get visitor code using `Express`/`Deno`/`NextJS SSR methods` and optionally providing
// default visitor code
const visitorCode = client.getVisitorCode({
request: req,
response: res,
defaultVisitorCode: 'my_default_visitor_code',
});
// -- Get visitor code using `NextJS` server side actions
// (`cookie` imported from "next/headers")
const visitorCode = client.getVisitorCode({
cookie,
});
}
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.
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.
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
(forNodeJS
/Express
/Deno
/NextJS SSR methods
) containing the following fields:
Name | Type | Description |
---|---|---|
request (required) | IncomingMessage | server request |
response (required) | ServerResponse | server response |
defaultVisitorCode (optional) | string | visitor code to be used in case there is no visitor code in cookies |
- Type
GetNextJSVisitorCodeParametersType
(forNextJS SSR server actions
) containing the following fields:
Name | Type | Description |
---|---|---|
cookies (required) | typeof 'next/headers' cookie | NextJS server actions headers cookie |
defaultVisitorCode (optional) | string | visitor code to be used when there is no visitor code available in the cookies |
If you don't provide a defaultVisitorCode
and there is no visitor code stored in a cookie, the visitor code will be randomly generated.
Returns
string
- result visitor code
Throws
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
KameleoonException.VisitorCodeMaxLength | The visitor code length was exceeded |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
Get Kameleoon Client Configuration URL
KameleoonUtils getClientConfigurationUrl
- Typescript / JavaScript
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
Name | Type | Description |
---|---|---|
siteCode (required) | string | client's siteCode defined on Kameleoon platform |
environment (optional) | Environment | The 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
- Typescript
- Javascript
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();
import { 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() {
try {
await client.initialize();
} catch (err) {
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
Type | Description |
---|---|
KameleoonException.StorageWrite | Couldn't update storage data |
KameleoonException.ClientConfiguration | Couldn't retrieve client configuration from Kameleoon API |
KameleoonException.MaximumRetriesReached | Maximum retries reached, request failed |
Add associated client data
addData
- Typescript
- Javascript
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();
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() {
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.
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
.
Check the list of supported conditions to see the data types you can use for targeting
Parameters
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique 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 |
kameleoonData
is variadic argument it can be passed as one or several arguments (see the example)
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
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.StorageWrite | Couldn't update storage data |
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
Check Data Types reference for more details of how to manage different data types
Track Conversion
trackConversion
- Typescript
- Javascript
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();
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() {
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.
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 negative
parameter.
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.
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:
Name | Type | Description | Default |
---|---|---|---|
visitorCode (required) | string | Unique visitor identifier string. Can't exceed 255 characters length. | - |
goalId (required) | number | Goal to be sent in tracking request | - |
revenue (optional) | number | Revenue to be sent in tracking request | - |
isUniqueIdentifier (optional) | boolean | Optional parameter that specifies whether the visitorCode is a unique identifier | false |
Throws
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.StorageWrite | Couldn't update storage data |
Flush tracking data
flush
- Typescript
- Javascript
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();
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() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = KameleoonUtils.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.
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
Name | Type | Description | Default |
---|---|---|---|
visitorCode (optional) | string | unique 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) | boolean | an optional parameter for specifying if the visitorCode is a unique identifier | false |
Throws
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
Get list of all feature flags
getFeatureFlags
- Typescript
- Javascript
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();
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() {
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
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
Get list of feature flags for a certain visitor
getVisitorFeatureFlags
- Typescript
- Javascript
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();
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() {
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).
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
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
Returns
FeatureFlagType[]
- list of feature flags, each feature flag item contains id
and key
Throws
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.NotTargeted | Current visitor is not targeted |
KameleoonException.StorageRead | Error while reading storage data |
Check if the feature is active for visitor
isFeatureFlagActive
- Typescript
- Javascript
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();
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() {
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.
Visitor must be targeted to has feature flag active
Parameters
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
featureKey (required) | string | a unique key for feature flag |
Returns
boolean
- a boolean indicator of whether the feature flag with featureKey
is active for visitor with visitorCode
Throws
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.NotTargeted | Current visitor is not targeted |
KameleoonException.FeatureFlagConfigurationNotFound | No feature flag was found for provided featureKey |
KameleoonException.FeatureFlagVariableNotFound | No feature variable was found for provided visitorCode and variableKey |
KameleoonException.DataInconsistency | Allocated variation was found, but there is no feature flag with according featureKey . |
Get variation key for a certain feature flag
getFeatureFlagVariationKey
- Typescript
- Javascript
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();
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() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = KameleoonUtils.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.
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
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
featureKey (required) | string | a unique key for feature flag |
Returns
string
a string containing variable key for the allocated feature flag variation for the provided visitor
Throws
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before initialize was done for kameleoonClient |
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.NotTargeted | Current visitor is not targeted |
KameleoonException.FeatureFlagConfigurationNotFound | No feature flag was found for the specified featureKey |
KameleoonException.FeatureFlagEnvironmentDisabled | Feature flag is disabled for the current environment |
Get a variable of a certain feature flag
getFeatureFlagVariable
- Typescript
- Javascript
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();
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() {
await client.initialize();
// -- Get visitor code using server `request` and `response`
const visitorCode = client.getVisitorCode({
request: req,
response: res,
});
// -- Get feature variable
const variableResult = client.getFeatureFlagVariable({
visitorCode,
featureKey: 'my_feature_key'
variableKey: 'my_variable_key'
});
const { type, value } = variableResult;
}
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:
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
featureKey (required) | string | a unique key for feature flag |
variableKey (required) | string | key 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
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before initialize was done for kameleoonClient |
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.NotTargeted | Current visitor is not targeted |
KameleoonException.FeatureFlagConfigurationNotFound | No feature flag was found for the specified featureKey |
KameleoonException.FeatureFlagEnvironmentDisabled | Feature flag is disabled for the current environment |
KameleoonException.JSONParse | Couldn't parse JSON value |
KameleoonException.NumberParse | Couldn't parse Number value |
Get all variables of a certain feature flag
getFeatureFlagVariables
- TypeScript
- JavaScript
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();
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() {
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
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
featureKey (required) | string | a 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
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.NotTargeted | Current visitor is not targeted |
KameleoonException.FeatureFlagConfigurationNotFound | No feature flag was found for the specified featureKey |
KameleoonException.FeatureFlagVariationNotFound | No feature variation was found for the specified visitorCode and variationKey |
KameleoonException.FeatureFlagEnvironmentDisabled | Feature flag is disabled for the current environment |
KameleoonException.JSONParse | Couldn't parse JSON value |
KameleoonException.NumberParse | Couldn't parse Number value |
Obtain data from Kameleoon remote source
getRemoteData
- Typescript
- Javascript
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();
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() {
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
Name | Type | Description |
---|---|---|
key (required) | string | unique key that the data you try to get is associated with |
Returns
JSONType
- promise with data retrieved for specific key
Throws
Type | Description |
---|---|
KameleoonException.RemoteData | Couldn't retrieve data from Kameleoon server |
Define an action for real time configuration update
onConfigurationUpdate
- Typescript
- Javascript
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();
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() {
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.
This method only works for server sent events of real time update
Parameters
Name | Type | Description |
---|---|---|
callback (required) | () => void | callback function with no parameters that will be called upon configuration update |
Throws
Type | Description |
---|---|
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
Obtain Kameleoon Visits Data from Kameleoon Data API
getRemoteVisitorData
- Typescript
- Javascript
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();
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() {
await client.initialize();
// -- Get remote visitor data and add it to storage
const kameleoonDataList = await getRemoteVisitorData({
visitorCode: 'my_visitor_code',
});
// -- Get remote visitor data without adding it to storage
const kameleoonDataList = await getRemoteVisitorData({
visitorCode: 'my_visitor_code',
shouldAddData: false,
});
// -- Get remote visitor data without adding it to storage
// and customizing filters for retrieving visits data
const filters = {
currentVisit: true,
previousVisitAmount: 10,
customData: true,
geolocation: true,
conversions: true,
};
const kameleoonDataList = await getRemoteVisitorData({
visitorCode: 'my_visitor_code',
shouldAddData: false,
filters,
});
}
init();
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.
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.
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:
Name | Type | Description | Default Value |
---|---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length | - |
shouldAddData (optional) | boolean | boolean flag identifying whether the retrieved custom data should be added to storage automatically (without calling addData afterwards) | true |
filters (optional) | VisitorDataFiltersType | filters for specifying what data should be retrieved from visits, by default only customData is retrieved from the current and latest previous visit | { previousVisitAmount: 1, currentVisit: true customData: true } , other filters parameters are set to false |
isUniqueIdentifier (optional) | boolean | optional parameter that, when true , specifies the visitorCode is a unique identifier | false |
Here is the list of available VisitorDataFiltersType
filters:
Name | Type | Description | Default |
---|---|---|---|
previousVisitAmount (optional) | number | Number of previous visits to retrieve data from. Number between 1 and 25 | 1 |
currentVisit (optional) | boolean | If true, current visit data will be retrieved | true |
customData (optional) | boolean | If true, custom data will be retrieved. | true |
pageViews (optional) | boolean | If true, page data will be retrieved. | false |
geolocation (optional) | boolean | If true, geolocation data will be retrieved. | false |
device (optional) | boolean | If true, device data will be retrieved. | false |
browser (optional) | boolean | If true, browser data will be retrieved. | false |
operatingSystem (optional) | boolean | If true, operating system data will be retrieved. | false |
conversions (optional) | boolean | If true, conversion data will be retrieved. | false |
experiments (optional) | boolean | If true, experiment data will be retrieved. | false |
kcs (optional) | boolean | If true, Kameleoon Conversion Score data will be retrieved. | false |
Returns
KameleoonDataType[]
- promise with list of Kameleoon Data retrieved
Throws
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.RemoteData | Couldn't retrieve data from Kameleoon server |
KameleoonException.VisitAmount | Visit amount must be a number between 1 and 25 |
KameleoonException.Initialization | Method was executed before the kameleoonClient completed it's initialize call |
Retrieve warehouse audience data
getVisitorWarehouseAudience
- TypeScript
- JavaScript
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();
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() {
await client.initialize();
// -- Get visitor warehouse audience data using `warehouseKey`
// and add it to storage
const customData = await getVisitorWarehouseAudience({
visitorCode: 'my_visitor',
customDataIndex: 10,
warehouseKey: 'my_key',
});
// -- Get visitor warehouse audience data using `visitorCode`
// and add it to storage
const customData = await getVisitorWarehouseAudience({
visitorCode: 'my_visitor',
customDataIndex: 10,
});
}
init();
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:
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
customDataIndex (required) | number | number representing the index of the custom data you want to use to target your Warehouse Audiences |
warehouseKey (optional) | string | unique 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
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
KameleoonException.RemoteData | Couldn't retrieve data from Kameleoon server |
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.
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
- Typescript
- Javascript
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();
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() {
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.
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
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
Returns
string
containing engine tracking code
Throws
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The visitor code is empty |
Set legal consent for visitor
setLegalConsent
- TypeScript
- JavaScript
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 as ServerResponse,
});
// -- Set consent using `NextJS` server side actions
// (`cookie` imported from "next/headers")
client.setLegalConsent({ visitorCode, consent: true, cookie });
}
init();
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() {
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 });
}
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.
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 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
(forNodeJS
,Express
,Deno
, orNextJS SSR methods
) containing the following fields:
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
consent (required) | boolean | a boolean value representing the legal consent status. true indicates the visitor has given legal consent, false indicates the visitor has never provided, or has withdrawn, legal consent |
response (required) | ServerResponse | response object to write the updated cookie to |
- Type
SetNextJSLegalConsentParametersType
(forNextJS SSR server actions
) containing the following fields:
Name | Type | Description |
---|---|---|
visitorCode (required) | string | unique visitor identification string, can't exceed 255 characters length |
consent (required) | boolean | 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 |
cookies (required) | typeof 'next/headers' cookie | NextJS server actions headers cookie |
Throws
Type | Description |
---|---|
KameleoonException.VisitorCodeMaxLength | The visitor code length exceeded the maximum length (255 characters) |
KameleoonException.VisitorCodeEmpty | The 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.
If you are using hybrid mode, you can call getRemoteVisitorData()
to automatically fill all data that Kameleoon has collected previously.
Browser
- Typescript
- Javascript
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();
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() {
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.
Each visitor can only have one Browser
. Adding a second Browser
overwrites the first one.
Parameters
Name | Type | Description |
---|---|---|
browser (required) | BrowserType | predefined browser type (Chrome , InternetExplorer , Firefox , Safari , Opera , Other ) |
version (optional) | number | version of the browser, floating point number represents major and minor version of the browser |
Conversion
- Typescript
- Javascript
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();
import { KameleoonClient, 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() {
await client.initialize();
// -- Defined conversion parameters
const conversionParameters = {
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.
Each visitor can only have one CustomData
per unique index
, adding another CustomData
with the same index
will overwrite the existing one
goalId
can be found on Kameleoon Platform
Parameters
ConversionParametersType
conversionParameters - an object with conversion parameters described below
Name | Type | Description | Default Value |
---|---|---|---|
goalId (required) | number | an id of a goal to track | - |
revenue (optional) | number | an optional parameter for revenue | 0 |
negative (optional) | boolean | an optional parameter identifying whether the conversion should be removed | false |
Cookie
- TypeScript
- JavaScript
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();
import { KameleoonClient, 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() {
await client.initialize();
// -- Add new cookie data to client
const cookieData = [
{ 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.
Each visitor can only have one Cookie
. Adding a second Cookie
overwrites the first one.
Parameters
Name | Type | Description |
---|---|---|
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.
- TypeScript
- JavaScript
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' },
// ]
import { Cookie } from '@kameleoon/nodejs-sdk';
const cookieString = 'key_1=value_1; key_2=value_2';
const 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
- TypeScript
- JavaScript
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();
import { KameleoonClient, GeolocationData } 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() {
await client.initialize();
// -- Add geolocation data
const geolocationInfo = {
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.
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:
Name | Type | Description |
---|---|---|
country (required) | string | The country of the visitor |
region (optional) | string | The region of the visitor |
city (optional) | string | The city of the visitor |
postalCode (optional) | string | The postal code of the visitor |
coordinates (optional) | [number, number] | Coordinates array tuple of two values (longitude and latitude). Coordinate number represents decimal degrees (double that can be negative) |
CustomData
- Typescript
- Javascript
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();
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() {
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.
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.
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
Name | Type | Description |
---|---|---|
index (required) | number | an 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
- Typescript
- Javascript
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();
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() {
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.
Each visitor can only have one Device
. Adding a second Device
overwrites the first one.
Parameters
Name | Type | Description |
---|---|---|
deviceType (required) | DeviceType | possible variants for device type (PHONE , TABLET , DESKTOP ) |
OperatingSystem
- TypeScript
- JavaScript
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(),
eventSource: new KameleoonEventSource(),
},
});
async function init(): Promise<void> {
await client.initialize();
// -- Add operating system data
const operatingSystem = new OperatingSystem(OperatingSystemType.Windows);
client.addData('my_visitor_code', operatingSystem);
}
init();
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(),
eventSource: new KameleoonEventSource(),
},
});
async function init() {
await client.initialize();
// -- Add operating system data
const operatingSystem = new OperatingSystem(OperatingSystemType.Windows);
client.addData('my_visitor_code', operatingSystem);
}
init();
OperatingSystem
contains information about the visitor's operating system.
Each visitor can only have one OperatingSystem
. Adding a second OperatingSystem
overwrites the first one.
Parameters
Name | Type | Description |
---|---|---|
operatingSystem (required) | OperatingSystemType | possible variants for device type: WINDOWS_PHONE , WINDOWS , ANDROID , LINUX , MAC , IOS |
PageView
- Typescript
- Javascript
import {
KameleoonClient,
PageViewParametersType,
PageView,
} 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 page view parameters
const pageViewParameters: PageViewParametersType = {
urlAddress: 'www.example.com',
title: 'my example',
referrers: [123, 456],
};
// -- Add page view data
const pageView = new PageView(pageViewParameters);
client.addData('my_visitor_code', pageView);
}
init();
import { KameleoonClient, PageView } 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() {
await client.initialize();
// -- Define page view parameters
const pageViewParameters = {
urlAddress: 'www.example.com',
title: 'my example',
referrers: [123, 456],
};
// -- Add page view data
const pageView = new PageView(pageViewParameters);
client.addData('my_visitor_code', pageView);
}
init();
PageView contains information about your web page.
Each visitor can have one PageView
per unique URL. Adding PageView
with the same URL again will notify the SDK that the visitor revisited page.
Parameters
PageViewParametersType
pageViewParameters - an object with page view parameters described below
Name | Type | Description |
---|---|---|
urlAddress (required) | string | url address of the page to track |
title (required) | string | title of the web page |
referrer (optional) | number[] | an optional parameter containing a list of referrers Indices, has no default value |
The index or ID of the referrer can be found in your Kameleoon account. It is important to note that this index starts at 0, which means that the first acquisition channel you create for a given site will be assigned 0 as its ID, not 1.
UserAgent
- Typescript
- Javascript
import { KameleoonClient, UserAgent } 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 user agent data
const userAgent = new UserAgent('my_unique_value');
client.addData('my_visitor_code', userAgent);
}
init();
import { KameleoonClient, UserAgent } 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() {
await client.initialize();
// -- Add user agent data
const userAgent = new UserAgent('my_unique_value');
client.addData('my_visitor_code', userAgent);
}
init();
Store information on the user-agent of the visitor. Server-side experiments are more vulnerable to bot traffic than client-side experiments. To address this, Kameleoon uses the IAB/ABC International Spiders and Bots List to identify known bots and spiders. Kameleoon also uses the UserAgent
field to filter out bots and other unwanted traffic that could otherwise skew your conversion metrics. For more details, see the help article on Bot filtering.
If you use internal bots, we suggest that you pass the value curl/8.0 of the userAgent to exclude them from our analytics.
A visitor can only have one UserAgent
. Adding a second UserAgent
overwrites the first one.
Parameters
Name | Type | Description |
---|---|---|
value (required) | string | value used for comparison |
Server-side experiments are more vulnerable to bot traffic than client-side experiments. To address this, Kameleoon uses the IAB/ABC International Spiders and Bots List to identify known bots and spiders. We recommend that you pass the user agent to be filtered by Kameleoon when running server-side experiments for each visitor browsing your website, to avoid counting bots in your analytics.
If you use internal bots, we suggest that you pass the value curl/8.0 of the userAgent to exclude them from our analytics.
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.
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
.
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:
Domain | Allowed URLs | Disallowed URLs |
---|---|---|
www.example.com | ✅www.example.com | ❌ app.example.com |
✅ example.com | ❌ .com | |
.example.com = example.com | ✅ example.com | ❌ otherexample.com |
✅ www.example.com | ||
✅ app.example.com | ||
✅ login.example.com | ||
https://www.example.com | ⛔ bad domain | ⛔ bad domain |
www.example.com:4408 | ⛔ bad domain | ⛔ bad domain |
.localhost.com = localhost | ⛔ bad domain | ⛔ bad domain |
Developing on localhost
localhost
is always considered a bad domain, making it hard to test the domain when developing on localhost.
There are two ways to avoid this issue:
- Don't specify the
domain
field in the SDK client while testing. This preventslocalhost
issues (the cookie will be set on any domain). - Create a local domain for
localhost
. For example:- Navigate to
/etc/hosts
on Linux or toc:\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
- Navigate to
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.
In the JavaScript SDK, all external dependencies have default implementations, which use a native browser API so there's no need to provide them unless another API is required for specific use cases.
Here's the list of available external dependencies:
Dependency | Interface | Required/Optional | API Used | Description |
---|---|---|---|---|
storage | IExternalStorage | Optional | Server memory | Used for storing all the existing and collected SDK data |
eventSource | IExternalEventSource | Required | - | Used for receiving Server Sent Events for Real Time Update capabilities |
visitorCodeManager | IExternalVisitorCodeManager | Required | - | Used for storing and synchronizing visitor code |
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 oneventsource
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 SSRheaders
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
- TypeScript
- JavaScript
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(),
},
});
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Storage implementation ---
// - JavaScript `Map` is used as an example storage
const storage = new Map();
class MyStorage {
read(key) {
// - Read data using `key`
const data = storage.get(key);
// - Return `null` if there's no data
if (!data) {
return null;
}
// - Return obtained data
return data;
}
write(key, data) {
// - Write data using `key`
storage.set(key, data);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
storage: new MyStorage(),
},
});
EventSource
- TypeScript
- JavaScript
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 {
// - Cleanup open event source
if (this.eventSource) {
this.eventSource.close();
}
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
eventSource: new MyEventSource(),
},
});
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External EventSource implementation ---
// - Example uses dummy `EventSource` class
class MyEventSource {
eventSource;
open({ eventType, onEvent, url }) {
// - Initialize `EventSource` (use any event source of your choice here)
const eventSource = new EventSource(url);
this.eventSource = eventSource;
// - Add event listener with provided event type and event callback
this.eventSource.addEventListener(eventType, onEvent);
}
close() {
// - Cleanup open event source
if (this.eventSource) {
this.eventSource.close();
}
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
eventSource: new MyEventSource(),
},
});
VisitorCodeManager
- TypeScript
- JavaScript
import {
IExternalVisitorCodeManager,
SetDataParametersType,
GetDataParametersType,
KameleoonClient,
} 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;
if (!cookieString) {
return null;
}
// - Parse cookie finding it by provided `key`
const cookieEntry = cookieString.split(' ;').find((keyValue) => {
const [cookieKey, cookieValue] = keyValue.split('=');
return cookieKey === key && cookieValue !== '';
});
if (cookieEntry) {
const [_, value] = cookieEntry.split('=');
return value;
}
// - Return `null` if no cookie was found
return null;
}
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(),
},
});
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
// --- External Visitor Code Manager implementation ---
// - Example uses server `request` and `response`
class MyVisitorCodeManager {
getData({ request, key }) {
// - Get cookie from server request
const cookieString = request.headers.cookie;
if (!cookieString) {
return null;
}
// - Parse cookie finding it by provided `key`
const cookieEntry = cookieString.split(' ;').find((keyValue) => {
const [cookieKey, cookieValue] = keyValue.split('=');
return cookieKey === key && cookieValue !== '';
});
if (cookieEntry) {
const [_, value] = cookieEntry.split('=');
return value;
}
// - Return `null` if no cookie was found
return null;
}
setData({ visitorCode, response, domain, maxAge, key, path }) {
// - Set cookie to request using provided parameters
let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;
if (domain) {
resultCookie += `; Domain=${domain}`;
}
response.setHeader('Set-Cookie', resultCookie);
}
}
// --- Create KameleoonClient ---
const client = new KameleoonClient({
siteCode: 'my_site_code',
externals: {
visitorCodeManager: new MyVisitorCodeManager(),
},
});
Error Handling
- Typescript
- Javascript
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();
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();
import { 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() {
try {
await client.initialize();
const customData = new CustomData(0, 'my_data');
client.addData(visitorCode, customData);
} catch (error) {
switch (error.type) {
case KameleoonException.VisitorCodeMaxLength:
// -- Handle an error
break;
case KameleoonException.StorageWrite:
// -- Handle an error
break;
case KameleoonException.Initialization:
// -- Handle an error
break;
default:
break;
}
}
}
init();
Almost every KameleoonClient
method may throw an error at some point, these errors are not just caveats but rather deliberately predefined KameleoonError
s
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.
Integration with Edge providers
Kameleoon provides the following starter packs to automate your integration with specific edge providers:
Provider | Starter pack |
---|---|
Fastly Compute@Edge | https://github.com/Kameleoon/fastly-compute-starter-kit |
Cloudfare Workers | https://github.com/Kameleoon/cloudflare-worker-starter-kit |
AWS Lambda@Edge Function | https://github.com/Kameleoon/aws-lambda-edge-starter-kit |
For the other edge providers, you can initialize the Kameleoon Client yourself using externalClientConfiguration
. Passing externalClientConfiguration
causes the SDK to rely solely on the provided configuration data, instead of making a call to the Kameleoon servers. This gives you greater control and flexibility over the configuration data used in your application. For example:
- Typescript / Javascript
import rp from 'request-promise';
import { KameleoonClient, KameleoonUtils } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
async function init() {
// -- Get Kameleoon Client Configuration URL
const uri = KameleoonUtils.getClientConfigurationUrl('my_site_code');
const clientConfiguration = await rp({
uri,
json: true,
});
const client = new KameleoonClient({
siteCode: 'my_site_code',
credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
integrations: {
externalClientConfiguration: clientConfiguration,
},
externals: {
visitorCodeManager: new KameleoonVisitorCodeManager(),
eventSource: new KameleoonEventSource(),
},
});
}
init();
To update the configuration, obtain a fresh copy of the configuration data and re-initialize the client with the updated file.
Cross-device experimentation
To support visitors who access your app from multiple devices (cross-device experimentation), Kameleoon allows you to synchronize your custom data across each of the visitor's devices and reconcile their visit history across each device.
Synchronizing custom data across devices
If you want to synchronize your Custom Data across multiple devices, Kameleoon provides a Custom Data synchronization mechanism.
To use this feature, in the Custom Data Dashboard, edit the custom data and set the Scope
value to Visitor
. The custom data will now be permanently associated with a specific visitor as long as getRemoteVisitorData
is called before any other actions with the visitor-associated data.
After the custom data is set up, calling getRemoteVisitorData makes the latest data accessible on any device.
See the following example of data synchronization between two devices:
- TypeScript
- JavaScript
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();
// -- Custom Data with index `0` was set to `Visitor` scope
// on Kameleoon Platform
const customDataIndex = 0;
const customData = new CustomData(customDataIndex, 'my_data');
client.addData('my_visitor', customData);
client.flush();
}
init();
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();
// -- Before working with data, make `getRemoteVisitorData` call
await getRemoteVisitorData({ visitorCode: 'my_visitor_code' });
// -- The further SDK code will have an access to CustomData with `Visitor` scope
// defined on Device One.
// So "my_data" is now available for targeting and tracking for "my_visitor"
}
init();
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() {
await client.initialize();
// -- Custom Data with index `0` was set to `Visitor` scope
// on Kameleoon Platform
const customDataIndex = 0;
const customData = new CustomData(customDataIndex, 'my_data');
client.addData('my_visitor', customData);
client.flush();
}
init();
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() {
await client.initialize();
// -- Before working with data, make `getRemoteVisitorData` call
await getRemoteVisitorData({ visitorCode: 'my_visitor_code' });
// -- The further SDK code will have an access to CustomData with `Visitor` scope
// defined on Device One.
// So "my_data" is now available for targeting and tracking for "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 the associated sessions always see the same variation of the experiment.
Afterwards, you can use the SDK normally. The following methods might be helpful in the context of session merging:
- Use
getRemoteVisitorData
withisUniqueIdentifier=true
to retrieve data for all linked visitors - Use
trackConversion
orflush
withisUniqueIdentifier=true
to track data for specific visitor that is associated with another visitor
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.
- TypeScript
- JavaScript
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();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to later re-use it
global.anonymousVisitor = anonymousVisitor;
// -- Getting some variation, assume it's variation `A`
const variation = client.getFeatureFlagVariationKey(
anonymousVisitor,
'my_feature_key',
);
}
init();
import { CustomData } from '@kameleoon/nodejs-sdk';
async function init(): Promise<void> {
// -- At this point anonymous visitor has logged in
// and we have user ID to use as a visitor identifier
// -- Associating both visitors with identifier Custom Data,
// where index `1` is the index of the Custom Data configured
// as a unique identifier on Kameleoon Platform
const userIdentifierData = new CustomData(1, 'my_user_id');
// -- Taking `visitorCode` from `global` object
client.addData(global.anonymousVisitor, userIdentifierData);
// -- Getting the variation for user ID will
// result in the same variation as for anonymous visitor
// variation will be `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,
// -- Letting SDK know that the visitor is unique identifier
isUniqueIdentifier: true,
});
// -- Moreover linked visitors share previously
// collected remote data
const data = await client.getRemoteVisitorData({
visitorCode: 'my_user_id',
// -- Letting SDK know that the visitor is unique identifier
isUniqueIdentifier: true,
});
}
init();
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() {
await client.initialize();
const anonymousVisitor = getVisitorCode();
// -- Saving `visitorCode` in `global` to later re-use it
global.anonymousVisitor = anonymousVisitor;
// -- Getting some variation, assume it's variation `A`
const variation = client.getFeatureFlagVariationKey(
anonymousVisitor,
'my_feature_key',
);
}
init();
import { CustomData } from '@kameleoon/nodejs-sdk';
async function init() {
// -- At this point anonymous visitor has logged in
// and we have user ID to use as a visitor identifier
// -- Associating both visitors with identifier Custom Data,
// where index `1` is the index of the Custom Data configured
// as a unique identifier on Kameleoon Platform
const userIdentifierData = new CustomData(1, 'my_user_id');
// -- Taking `visitorCode` from `global` object
client.addData(global.anonymousVisitor, userIdentifierData);
// -- Getting the variation for user ID will
// result in the same variation as for anonymous visitor
// variation will be `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,
// -- Letting SDK know that the visitor is unique identifier
isUniqueIdentifier: true,
});
// -- Moreover linked visitors share previously
// collected remote data
const data = await client.getRemoteVisitorData({
visitorCode: 'my_user_id',
// -- Letting SDK know that the visitor is unique identifier
isUniqueIdentifier: true,
});
}
init();