@kameleoon/javascript-sdk-core 5.14.5 → 5.16.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Change Log
 
+## 5.16.0 (2025-10-22)
+
+### Minor Changes
+
+- Introduced a new [`getDataFile`](getDataFile) method. This method returns the current SDK configuration (also known as the **data file**) used for evaluation and targeting. It is **not** intended for production use to fetch variations for every feature flag in the returned list, as it is not optimized for performance. For that purpose, use [`getVariations`](getVariations) instead. `getDataFile` is mainly useful for debugging or QA, for example to let internal users manually select a variant for a specific feature flag in production.
+
+### Patch Changes
+
+- Addressed an issue where tracking data was sent for visitors who had not provided [consent](setLegalConsent).
+
+[setLegalConsent]: https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/js-sdk#setLegalConsent
+[getDataFile]: https://developers.kameleoon.com/feature-management-and-experimentation/web-sdks/js-sdk#getdatafile
+
+## 5.15.0 (2025-09-01)
+
+> [!WARNING]
+> If you're upgrading from a version earlier than 5.14.0 and run into any unexpected build or SDK-related issues, please reach out to the Kameleoon Support Team. We're here to ensure your transition is smooth and will promptly address any concerns.
+
+### Features
+
+- Added an `overwrite` flag to [`CustomData`](CustomData), used as the `overwrite` parameter during tracking.
+- [`CustomData`](CustomData) can now be created using a `name`, in addition to the existing method of using an `index`.
+
 ## 5.14.5 (2025-08-20)
 
 > [!WARNING]

package/dist/browser.d.ts

@@ -23,3 +23,4 @@ export { MappingIdentifierType } from './storage/types';
 export { CustomDataConfigurationType, CustomDataScope, } from './clientConfiguration';
 export { ListUtilities, Utilities } from './utilities';
 export { BrowserDataType, CustomDataType, DataFilterType, DataManagerParametersType, DeviceDataType, GeolocationDataType, KameleoonVisitorDataType, MutUpdateTargetingDataParametersType, OperatingSystemDataType, PageViewDataType, ProcessCustomDataManagerParametersType, VisitDataType, VisitorsDataType, } from './kameleoonData/types';
+export { FeatureFlag, Rule, DataFile, Variable, Variation } from './types';

package/dist/clientConfiguration/types.d.ts

@@ -70,6 +70,7 @@ export type ExperimentType = {
     variationByExposition: VariationByExpositionType[];
 };
 export type FeatureVariationType = {
+    name?: string;
     key: string;
     variables: FeatureVariableType[];
 };
@@ -119,6 +120,7 @@ export type ClientConfigurationDataType = Omit<ConfigurationDataType, 'featureFl
 export type CustomDataConfigurationType = {
     id?: number;
     index: number;
+    name?: string;
     localOnly: boolean;
     isMappingIdentifier: boolean;
     scope: CustomDataScope;

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { MappingIdentifierType } from './storage/types';
 export { CustomDataConfigurationType, CustomDataScope, } from './clientConfiguration';
 export { ListUtilities, Utilities } from './utilities';
 export { BrowserDataType, CustomDataType, DataFilterType, DataManagerParametersType, DeviceDataType, GeolocationDataType, KameleoonVisitorDataType, MutUpdateTargetingDataParametersType, OperatingSystemDataType, PageViewDataType, ProcessCustomDataManagerParametersType, VisitDataType, VisitorsDataType, } from './kameleoonData/types';
+export { FeatureFlag, Rule, DataFile, Variable, Variation } from './types';

package/dist/javascript-sdk-core-browser.cjs.js

@@ -2296,25 +2296,22 @@ class PageView {
  * CustomData - a class for creating an instance for user's custom data
  * */
 let CustomData$1 = class CustomData {
-    /**
-     * @param {number} index - 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
-     * @param {string[]} value - 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
-     * @example
-     * ```ts
-     * // - Single value
-     * const customData = new CustomData(0, 'value_1');
-     * // - Variadic number of values
-     * const customData = new CustomData(0, 'value_1', 'value_2', 'value_3');
-     * // - Array of values
-     * const values = ['value_1', 'value_2', 'value_3'];
-     * const customData = new CustomData(0, ...values);
-     * ```
-     * */
-    constructor(index, ...value) {
-        this.index = index;
-        this.value = value;
+    constructor(first, second, ...rest) {
         this._status = exports.TrackingStatus.Unsent;
         this.isIdentifier = false;
+        const isNumber = typeof first === 'number';
+        const isBoolean = typeof second === 'boolean';
+        if (isNumber) {
+            this.index = first;
+        }
+        else {
+            this.name = first;
+            this.index = -1;
+        }
+        this.overwrite = isBoolean ? second : true;
+        this.value = isBoolean
+            ? rest
+            : [second, ...rest].filter((v) => v != null);
     }
     get url() {
         // --- Note ---
@@ -2341,17 +2338,11 @@ let CustomData$1 = class CustomData {
             UrlParameter.ValuesCountMap +
             encodeURIComponent(JSON.stringify(resultValue)) +
             UrlParameter.Overwrite +
-            String(true) +
+            String(this.overwrite) +
             identifierParameter);
     }
     get data() {
-        return {
-            index: this.index,
-            value: this.value,
-            type: exports.KameleoonData.CustomData,
-            isIdentifier: this.isIdentifier,
-            status: this.status,
-        };
+        return Object.assign(Object.assign({ index: this.index }, (this.name !== undefined ? { name: this.name } : {})), { value: this.value, type: exports.KameleoonData.CustomData, isIdentifier: this.isIdentifier, status: this.status, overwrite: this.overwrite });
     }
     get status() {
         if (this._isMappingIdentifier) {
@@ -2366,8 +2357,15 @@ let CustomData$1 = class CustomData {
      * @return {CustomData} a CustomData instance
      * */
     static _fromRaw(data) {
-        const { index, value, status, isIdentifier } = data;
-        const customData = new CustomData(index, ...value);
+        const { index, value, status, isIdentifier, name, overwrite } = data;
+        let customData;
+        if (name) {
+            customData = new CustomData(name, overwrite !== null && overwrite !== void 0 ? overwrite : true, ...value);
+            customData._index = index;
+        }
+        else {
+            customData = new CustomData(index, overwrite !== null && overwrite !== void 0 ? overwrite : true, ...value);
+        }
         customData.status = status;
         customData._isMappingIdentifier = isIdentifier;
         return customData;
@@ -2398,6 +2396,14 @@ let CustomData$1 = class CustomData {
             }
         }
     }
+    /**
+     * @private
+     * @method _index - an internal setter for setting index of custom data
+     * @param {number} value - an index value
+     * */
+    set _index(value) {
+        this.index = value;
+    }
 };
 
 /**
@@ -5143,7 +5149,7 @@ class ConditionFactory {
             case TargetingType.HEAT_SLICE:
                 return buildExports.Ok(new ConversionLikelihood(data));
             default:
-                KameleoonLogger.error `Unsupported targeted condition type found: ${targetingType}`;
+                KameleoonLogger.info `Unsupported targeted condition type found: ${targetingType}`;
                 return buildExports.Err(new KameleoonError(exports.KameleoonException.TargetingCondition, targetingType));
         }
     }
@@ -5532,6 +5538,7 @@ class DataManager {
         this.mappingIdentifierCustomDataIndex = null;
         this.persistentCustomDataIndexes = new Set();
         this.localCustomDataIndexes = new Set();
+        this.customDataIndexByName = new Map();
         this.cleanupIntervalId = null;
         KameleoonLogger.debug `CALL: new DataManager(dataStorage, infoStorage, cleanupInterval: ${cleanupInterval})`;
         this.dataStorage = dataStorage;
@@ -5866,12 +5873,15 @@ class DataManager {
     mutUpdateTargetingData({ infoData, visitorCode, kameleoonData, targetingData, }) {
         for (const dataItem of kameleoonData) {
             if (dataItem.data.type === exports.KameleoonData.CustomData) {
-                this.processCustomData({
+                const customDataIsValid = this.processCustomData({
                     infoData,
                     customData: dataItem,
                     mutData: targetingData,
                     visitorCode,
                 });
+                if (!customDataIsValid) {
+                    continue;
+                }
             }
             const expirationTime = this.dataProcessor.mutUpdateData({
                 infoData,
@@ -5912,6 +5922,14 @@ class DataManager {
         var _a;
         const { data } = customData;
         const isDataValid = Boolean(data.value.length && data.value[0].length);
+        if (data.name) {
+            const cdIndex = this.customDataIndexByName.get(data.name);
+            if (cdIndex === undefined) {
+                return false;
+            }
+            data.index = cdIndex;
+            customData._index = cdIndex;
+        }
         if (this.mappingIdentifierCustomDataIndex === data.index && isDataValid) {
             customData._isMappingIdentifier = true;
             const userId = data.value[0];
@@ -5935,6 +5953,7 @@ class DataManager {
         if (this.localCustomDataIndexes.has(data.index)) {
             customData.status = exports.TrackingStatus.Sent;
         }
+        return true;
     }
     get unsentDataVisitors() {
         const infoResult = this.infoStorage.read();
@@ -5967,6 +5986,7 @@ class DataManager {
     set customDataIndexes(customData) {
         var _a;
         const [customDataLocalOnlyIndexes, persistentCustomDataIndexes] = [[], []];
+        const customDataIndexByName = new Map();
         customData.forEach((customData) => {
             if (customData.localOnly) {
                 customDataLocalOnlyIndexes.push(customData.index);
@@ -5974,12 +5994,19 @@ class DataManager {
             if (customData.scope === exports.CustomDataScope.Visitor) {
                 persistentCustomDataIndexes.push(customData.index);
             }
+            if (customData.name) {
+                customDataIndexByName.set(customData.name, customData.index);
+            }
         });
         this.mappingIdentifierCustomDataIndex =
             ((_a = customData.find((customData) => customData.isMappingIdentifier)) === null || _a === void 0 ? void 0 : _a.index) ||
                 null;
         this.localCustomDataIndexes = new Set(customDataLocalOnlyIndexes);
         this.persistentCustomDataIndexes = new Set(persistentCustomDataIndexes);
+        this.customDataIndexByName = customDataIndexByName;
+    }
+    getCustomDataIndexByName(name) {
+        return this.customDataIndexByName.get(name);
     }
 }
 
@@ -7780,7 +7807,7 @@ class BodyProvider {
         const identifier = isMappingIdentifier
             ? UrlParameter.MappingValue
             : UrlParameter.VisitorCode;
-        return identifier + visitorCode;
+        return identifier + encodeURIComponent(visitorCode);
     }
 }
 
@@ -8364,6 +8391,7 @@ class KameleoonClient {
             }
             const resultVariables = variables.map((variable) => Parser.parseFeatureVariable(variable).throw());
             resultFeatureList.set(variation.featureKey, {
+                name: '',
                 key: variationKey,
                 id: variationId,
                 experimentId,
@@ -8584,6 +8612,62 @@ class KameleoonClient {
         this.flush(visitorCode);
         KameleoonLogger.info `RETURN: KameleoonClient.evaluateAudiences(visitorCode: ${visitorCode})`;
     }
+    getDataFile() {
+        const dataFile = {
+            featureFlags: new Map(),
+        };
+        if (this.stubMode) {
+            return dataFile;
+        }
+        KameleoonLogger.debug `CALL: KameleoonClient.getDataFile()`;
+        this.clientConfiguration.featureFlags.forEach((featureFlag, key) => {
+            const variationsMap = new Map();
+            featureFlag.variations.forEach((sourceVariation) => {
+                var _a;
+                const variablesMap = new Map();
+                sourceVariation.variables.forEach((variable) => {
+                    try {
+                        const parsedVariable = Parser.parseFeatureVariable(variable).throw();
+                        variablesMap.set(variable.key, parsedVariable);
+                    }
+                    catch (err) {
+                        KameleoonLogger.error `Error parsing variable ${variable.key} of feature flag ${featureFlag.featureKey}: ${err}`;
+                    }
+                });
+                variationsMap.set(sourceVariation.key, {
+                    name: (_a = sourceVariation.name) !== null && _a !== void 0 ? _a : '',
+                    key: sourceVariation.key,
+                    id: null,
+                    experimentId: null,
+                    variables: variablesMap,
+                });
+            });
+            const rules = featureFlag.rules.map((rule) => {
+                const ruleVariations = new Map();
+                rule.variationByExposition.forEach((varByExp) => {
+                    const baseVariation = variationsMap.get(varByExp.variationKey);
+                    if (!baseVariation)
+                        return;
+                    ruleVariations.set(baseVariation.key, {
+                        name: baseVariation.name,
+                        key: baseVariation.key,
+                        id: varByExp.variationId,
+                        experimentId: rule.experimentId,
+                        variables: baseVariation.variables,
+                    });
+                });
+                return { variations: ruleVariations };
+            });
+            dataFile.featureFlags.set(key, {
+                variations: variationsMap,
+                environmentEnabled: featureFlag.environmentEnabled,
+                rules,
+                defaultVariationKey: featureFlag.defaultVariationKey,
+            });
+        });
+        KameleoonLogger.debug `RETURN: KameleoonClient.getDataFile() -> (dataFile: ${dataFile})`;
+        return dataFile;
+    }
     setUserConsent({ visitorCode, consent, setData, }) {
         if (this.stubMode) {
             return;
@@ -8770,6 +8854,7 @@ class KameleoonClient {
         return selected;
     }
     _getFeatureVariation({ visitorCode, featureKey, track, }) {
+        var _a, _b;
         KameleoonLogger.debug `CALL: KameleoonClient._getFeatureVariation(visitorCode: ${visitorCode}, featureKey: ${featureKey}, track: ${track})`;
         if (!this.initialized) {
             return buildExports.Err(new KameleoonError(exports.KameleoonException.Initialization));
@@ -8820,7 +8905,9 @@ class KameleoonClient {
         if (track && !isSimulated) {
             this.tracker.scheduleVisitor(visitorCode, this._isConsentProvided(visitorCode));
         }
+        const variationName = (_b = (_a = featureFlag.variations.find((item) => item.key === variationKey)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : '';
         const resultData = {
+            name: variationName,
             key: variationKey,
             id: variationId,
             experimentId,