Kameleoon OpenFeature provider for web-side

The Kameleoon OpenFeature provider for web-side js allows you to connect your OpenFeature client implementation to Kameleoon without needing to install the Kameleoon SDK JavaScript.

[!WARNING] This is a beta version. Breaking changes may be introduced before general release.

Get started

This section explains how to install, configure, and customize the Kameleoon OpenFeature provider.

Install

npm install @kameleoon/openfeature-web

Usage

The following example shows how to use the Kameleoon provider with the OpenFeature SDK.

let provider: KameleoonProvider;
const userId = "userId";
const featureKey = "featureKey";
const CLIENT_ID = 'clientId';
const CLIENT_SECRET = 'clientSecret';
const SITE_CODE = 'tndueuutdq';

try {
  provider = new KameleoonProvider({
    siteCode: SITE_CODE,
    visitorCode: VISITOR_CODE,
  });
} catch (e) {
  throw new Error();
}

OpenFeature.setProvider(provider);

// Or use OpenFeature.setProviderAndWait for wait for the provider to be ready
try {
  await OpenFeature.setProviderAndWait(provider);
} catch (e) {
  throw new Error();
}

const client = OpenFeature.getClient();

let evalContext: EvaluationContext = {
  [DataType.VARIABLE_KEY]: 'variableKey',
};
await OpenFeature.setContext(evalContext);

let numberOfRecommendedProducts = await client.getNumberValue(
  FEATURE_KEY,
  5,
  evalContext,
);
showRecommendedProducts(numberOfRecommendedProducts);

let provider;
try {
  provider = new KameleoonProvider({
    siteCode: SITE_CODE,
    visitorCode: VISITOR_CODE,
  });
} catch (e) {
  throw new Error(e.message);
}

OpenFeature.setProvider(provider);

// Or use OpenFeature.setProviderAndWait to wait for the provider to be ready
try {
  await OpenFeature.setProviderAndWait(provider);
} catch (e) {
  throw new Error(e.message);
}

const client = OpenFeature.getClient();

const evalContext = {
  [DataType.VARIABLE_KEY]: 'variableKey',
};
await OpenFeature.setContext(evalContext);

const numberOfRecommendedProducts = await client.getNumberValue(
  FEATURE_KEY,
  5,
  evalContext,
);
showRecommendedProducts(numberOfRecommendedProducts);

Customize the Kameleoon provider

You can customize the Kameleoon provider by changing the KameleoonClientConfig object that you passed to the constructor above. For example:

const configuration: Partial<SDKConfigurationType> = {
  updateInterval: 20,
  environment: Environment.Production,
  domain: '.example.com',
};

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

const configuration = {
  updateInterval: 20,
  environment: Environment.Production,
  domain: '.example.com',
};

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

[!NOTE] For additional configuration options, see the Kameleoon documentation.

EvaluationContext and Kameleoon Data

Kameleoon uses the concept of associating Data to users, while the OpenFeature SDK uses the concept of an EvaluationContext, which is a dictionary of string keys and values. The Kameleoon provider maps the EvaluationContext to the Kameleoon Data.

The Kameleoon provider provides a few predefined parameters that you can use to target a visitor from a specific audience and track each conversion. These are:

| Parameter | Description | |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | DataType.CUSTOM_DATA | The parameter is used to set CustomData for a visitor. | | DataType.CONVERSION | The parameter is used to track a Conversion for a visitor. | | DataType.VARIABLE_KEY | The parameter is used to set key of the variable you want to get a value. |

DataType.VARIABLE_KEY

The DataType.VARIABLE_KEY field has the following parameter:

| Type | Description | |----------|-----------------------------------------------------------------------------------| | string | Value of the key of the variable you want to get a value This field is mandatory. |

Example

const evalContext: EvaluationContext = {
  [DataType.VARIABLE_KEY]: 'variableKey',
};

const evalContext = {
  [DataType.VARIABLE_KEY]: 'variableKey',
};

DataType.CUSTOM_DATA

Use DataType.CUSTOM_DATA to set CustomData for a visitor. For creation use DataType.makeCustomData method with the following parameters:

| Parameter | Type | Description | |-----------|------------|-------------------------------------------------------------------| | id | number | Index or ID of the custom data to store. This field is mandatory. | | values | string[] | Value(s) of the custom data to store. This field is optional. |

Example

const customDataDictionary = {
  [DataType.CUSTOM_DATA]: DataType.makeCustomData(1, '10'),
};

const evalContext: EvaluationContext = {
  ...customDataDictionary,
};

const customDataDictionary = {
  [DataType.CUSTOM_DATA]: DataType.makeCustomData(1, '10'),
};

const evalContext = {
  targetingKey: VISITOR_CODE,
  ...customDataDictionary,
};

DataType.CONVERSION

Use DataType.CONVERSION to track a Conversion for a visitor. For creation use DataType.makeConversion method with the following parameters:

| Parameter | Type | Description | |-----------|----------|-----------------------------------------------------------------| | goalId | number | Identifier of the goal. This field is mandatory. | | revenue | number | Revenue associated with the conversion. This field is optional. |

Example

const conversionDictionary = {
  [DataType.CONVERSION]: DataType.makeConversion(1, 200),
};

const evalContext: EvaluationContext = {
  targetingKey: VISITOR_CODE,
  ...conversionDictionary,
};

const conversionDictionary = {
  [DataType.CONVERSION]: DataType.makeConversion(1, 200),
};

const evalContext = {
  targetingKey: VISITOR_CODE,
  ...conversionDictionary,
};

Use multiple Kameleoon Data types

You can provide many different kinds of Kameleoon data within a single EvaluationContext instance.

For example, the following code provides one DataType.CONVERSION instance and two DataType.CUSTOM_DATA instances.

const dataDictionary = {
  [DataType.CONVERSION]: DataType.makeConversion(1, 200),
  [DataType.CUSTOM_DATA]: [
    DataType.makeCustomData(1, "10", "30"),
    DataType.makeCustomData(2, "20"),
  ],
};

const evalContext: EvaluationContext = {
  ...dataDictionary,
};

const dataDictionary = {
  [DataType.CONVERSION]: DataType.makeConversion(1, 200),
  [DataType.CUSTOM_DATA]: [
    DataType.makeCustomData(1, "10", "30"),
    DataType.makeCustomData(2, "20"),
  ],
};

const evalContext = {
  ...dataDictionary,
};