@kameleoon/javascript-sdk-core/dist/kameleoonClientInterface.d.ts

Kameleoon JS SDK Core

import { JSONType } from './clientConfiguration';
import { EventCallbackType, EventType } from './eventManager';
import { CustomData, KameleoonDataType } from './kameleoonData';
import { DataFile, FeatureFlagType, FeatureFlagVariableType, GetFeatureFlagVariableParamsType, GetVariationParamsType, GetVariationsParamsType, GetVisitorWarehouseAudienceParamsType, IsFeatureFlagActiveParamsType, KameleoonVariationType, RemoteVisitorDataParamsType, SetForcedVariationParametersType, TrackConversionParamsType, Variable, Variation } from './types';
import { LogLevel } from './logging';
/**
 * @interface an interface of KameleoonClient instance
 */
export interface IKameleoonClient {
    /**
     * @method initialize - an asynchronous method for KameleoonClient initialization by fetching Kameleoon SDK related data from server or by retrieving data from local source if data is up-to-date or update interval has not been reached
     *
     * Triggered Events: `EventType.ConfigurationUpdate` (On each successful configuration update while using Real Time Update)
     *
     * @returns {Promise<boolean>} Promise resolved into boolean field indicating success or fail
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.StorageWrite` Couldn't update storage data
     * - `KameleoonException.ClientConfiguration` Couldn't retrieve client configuration from Kameleoon Api
     * - `KameleoonException.MaximumRetriesReached` Maximum retries reached, request failed
     */
    initialize(): Promise<boolean>;
    /**
     * @method addData - method for adding targeting data to the storage so that other methods could decide whether the current visitor is targeted or not. Note: userAgent data will not be stored in storage like other data, and it will be sent with every tracking request for bot filtration.
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @param {KameleoonDataType[]} kameleoonData - number of instances of any type of `KameleoonData`, can be added solely in array or as a sequential arguments
     * @returns {void}
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
     * - `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
     */
    addData: (visitorCode: string, ...data: KameleoonDataType[]) => void;
    /**
     * @method getRemoteVisitorData - an asynchronous method for retrieving KameleoonData from Data API and optionally adding it to the storage so that other methods could decide whether the current visitor is targeted or not.
     * @param {RemoteVisitorDataParamsType} remoteVisitorDataParameters - `visitorCode`, `shouldAddData` and `filters` parameters
     * @returns {KameleoonDataType[]} promise resolved to an array of `KameleoonData` instances, only includes custom data
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
     * - `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
     */
    getRemoteVisitorData: ({ visitorCode, shouldAddData, filters, }: RemoteVisitorDataParamsType) => Promise<KameleoonDataType[]>;
    /**
     * @method trackConversion - creates and adds `Conversion` data to the visitor with specified parameters and executes `flush`. Note: it's a helper method for the quick and convenient conversion tracking, however creating and adding `Conversion` manually allows more flexible `Conversion` with `negative` parameter
     * @param {TrackConversionParamsType} conversionParameters - `visitorCode`, `goalId`, `revenue`, `negative` and `metadata` parameters for data tracking
     * @returns {void}
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.StorageWrite` Couldn't update storage data
     */
    trackConversion: ({ visitorCode, goalId, revenue, negative, metadata, }: TrackConversionParamsType) => void;
    /**
     * @method flush - takes visitor associated kameleoon data and sends the data tracking request with collected data,
     * sent data is removed from `KameleoonClient` instance but not from the storage for correct targeting checks. If no visitor is passed,
     * then data for all visitors is sent and removed from `KameleoonClient` instance. Moreover, regardless of visitor code input
     * the method first attempts to send all previously failed tracking requests which were stored locally during the offline mode.
     *
     * @param {string | FlushParamsType | undefined} params - either a unique visitor identifier (cannot exceed 255 characters in length) or an object with parameters:
     * - `visitorCode` - unique visitor identification string.
     * - `instant` - optional flag indicating whether the data should be sent instantly.
     * @returns {void}
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     */
    flush: (visitorCode?: string) => void;
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariations` instead.
     * @method getFeatureFlags - returns a list of feature flags stored in the client configuration
     *
     * Note: This method **doesn't send** tracking data
     *
     * @returns {FeatureFlagType[]} a list of all feature flags items with `id` and `key` fields
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     */
    getFeatureFlags: () => FeatureFlagType[];
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariations` instead.
     * @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).
     *
     * Note: This method **doesn't send** tracking data
     * Triggered Events: `EventType.Evaluation` (For each feature flag evaluated)
     *
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @returns {FeatureFlagType[]} a list of all feature flags items with `id` and `key` fields
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
     * - `KameleoonException.StorageRead` - Couldn't read storage data
     */
    getVisitorFeatureFlags: (visitorCode: string) => FeatureFlagType[];
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariations` instead.
     * @method getActiveFeatureFlags - method collecting all active feature flags information including it's variation and variables for the visitor
     *
     * Note: This method **doesn't send** tracking data
     * Triggered Events: `EventType.Evaluation` (For each feature flag evaluated)
     *
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @returns {Map<string, KameleoonVariationType>} a map of feature flags with `featureKey` as a key and `KameleoonVariationType` as a value
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before `initialize` was done for `kameleoonClient`
     * - `KameleoonException.StorageRead` - Couldn't read storage data
     * - `KameleoonException.JSONParse` - Couldn't parse JSON value
     * - `KameleoonException.NumberParse` - Couldn't parse Number value
     */
    getActiveFeatureFlags: (visitorCode: string) => Map<string, KameleoonVariationType>;
    /**
     * @deprecated this method overload is deprecated and will be removed in the next major release. Please use `isFeatureFlagActive` overload with an object parameters instead.
     * @method isFeatureFlagActive - returns a boolean indicating whether the visitor with `visitorCode` has `featureKey` active for him, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request
     *
     * Note: This method **sends** tracking data
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @param {string} featureKey - 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 `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.DataInconsistency` - Allocated variation was found but there is no feature flag with according `featureKey`.
     */
    isFeatureFlagActive(visitorCode: string, featureKey: string): boolean;
    /**
     * @method isFeatureFlagActive - returns a boolean indicating whether the visitor with `visitorCode` has `featureKey` active for him, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request
     *
     * Note: This method **sends** tracking data, unless `track` is set to `false`
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {IsFeatureFlagActiveParamsType} parameters - an object with parameters of a type `IsFeatureFlagActiveParamsType`, see the type for details.
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.DataInconsistency` - Allocated variation was found but there is no feature flag with according `featureKey`.
     */
    isFeatureFlagActive({ visitorCode, featureKey, track, }: IsFeatureFlagActiveParamsType): boolean;
    isFeatureFlagActive(firstParam: string | IsFeatureFlagActiveParamsType, secondParam?: string): boolean;
    /**
     * @method getVariation - returns a variation for the visitor under `visitorCode` for the specified `featureKye`, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage
     *
     * Note: This method **sends** tracking data by default, but you can disable it by setting `track` to `false`
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {GetVariationParamsType} parameters - an object with parameters of a type `GetVariationParamsType`, see the type for details.
     *
     * @returns {Variation} a variation object containing feature flag `key`, `id`, `experimentId` and `variables`, which is a `Map` of variable keys and values
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.FeatureFlagEnvironmentDisabled` - The feature flag is disabled for the current environment
     * */
    getVariation: ({ visitorCode, featureKey, track, }: GetVariationParamsType) => Variation;
    /**
     * @method getVariation - returns all variations for the visitor under `visitorCode` for all the feature flags, this method includes targeting check, finding the according variations exposed to the visitor and saving them to storage. By default the method obtains all the variations, but if `onlyActive` is set to `true`, only active variations will be returned (those that are not `off`)
     *
     * Note: This method **sends** tracking data by default, but you can disable it by setting `track` to `false`
     * Triggered Events: `EventType.Evaluation` (For each feature flag evaluated)
     *
     * @param {GetVariationsParamsType} parameters - an object with parameters of a type `GetVariationsParamsType`, see the type for details.
     *
     * @returns {Map<string, Variation>} a `Map` with variation keys and values, each value contains an object with feature flag `key`, `id`, `experimentId` and `variables`, which is a `Map` of variable keys and values
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     */
    getVariations: ({ visitorCode, onlyActive, track, }: GetVariationsParamsType) => Map<string, Variation>;
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariation` instead.
     * @method getFeatureFlagVariationKey - returns variation key for the visitor under `visitorCode` in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request
     *
     * Note: This method **sends** tracking data
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @param {string} featureKey - a unique key for feature flag
     * @returns {string} a string containing variable key for the allocated feature flag variation for the provided visitor
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.FeatureFlagEnvironmentDisabled` - The feature flag is disabled for the current environment
     */
    getFeatureFlagVariationKey: (visitorCode: string, featureKey: string) => string;
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariation` instead.
     * @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
     *
     * Note: This method **sends** tracking data
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {GetFeatureFlagVariableParamsType} parameters - an object with parameters of a type `GetFeatureFlagVariableParamsType`, see the type for details.
     * @returns {FeatureFlagVariableType} 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` then `value` will be a `boolean` type.
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.FeatureFlagVariableNotFound` - No feature variable was found for provided `visitorCode` and `variableKey`
     * - `KameleoonException.FeatureFlagEnvironmentDisabled` - The feature flag is disabled for the current environment
     * - `KameleoonException.JSONParse` - Couldn't parse JSON value
     * - `KameleoonException.NumberParse` - Couldn't parse Number value
     */
    getFeatureFlagVariable: ({ visitorCode, featureKey, variableKey, }: GetFeatureFlagVariableParamsType) => FeatureFlagVariableType;
    /**
     * @deprecated this method is deprecated and will be removed in the next major release. Please use `getVariation` instead.
     * @method getFeatureFlagVariables - returns a list of variables for the visitor under `visitorCode` in the found feature flag, this method includes targeting check, finding the according variation exposed to the visitor and saving it to storage along with sending tracking request
     *
     * Note: This method **sends** tracking data
     * Triggered Events: `EventType.Evaluation`
     *
     * @param {string} visitorCode - a unique visitor identifier, shouldn't exceed 255 characters
     * @param {string} featureKey - a unique key for feature flag
     * @returns {Variable[]} 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 `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagConfigurationNotFound` - No feature flag was found for provided `featureKey`
     * - `KameleoonException.FeatureFlagVariationNotFound` - No feature variation was found for provided `visitorCode` and `variationKey`
     * - `KameleoonException.FeatureFlagEnvironmentDisabled` - The feature flag is disabled for the current environment
     * - `KameleoonException.JSONParse` - Couldn't parse JSON value
     * - `KameleoonException.NumberParse` - Couldn't parse Number value
     */
    getFeatureFlagVariables: (visitorCode: string, featureKey: string) => Variable[];
    /**
     * @method getRemoteData - returns a data which is stored for specified siteCode on a remote Kameleoon server.
     * @param {string} key - unique key that the data you try to get is associated with.
     * @returns {JSONType} - promise with retrieving data for specific key.
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.RemoteData` - Couldn't retrieve data from Kameleoon server
     */
    getRemoteData: (key: string) => Promise<JSONType>;
    /**
     * @method getVisitorWarehouseAudience - an async method that returns a `CustomData` instance, containing data associated with a visitor's warehouse audiences
     * which is stored for specified visitorCode on a remote Kameleoon server.
     * Retrieved data will be added to storage under the specified `customDataIndex`
     * @param {GetVisitorWarehouseAudienceParamsType} parameters - an object with parameters of a type `GetVisitorWarehouseAudienceParamsType`, see the type for details.
     * @returns {Promise<CustomData | null>} `Promise` containing an instance of `CustomData` containing data associated with a visitor's warehouse audiences or `null` if the data was retrieved successfully but nothing was found under the specified `warehouseKey`
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` - The visitor code is empty
     * - `KameleoonException.RemoteData` - Couldn't retrieve data from Kameleoon server
     */
    getVisitorWarehouseAudience: ({ visitorCode, customDataIndex, warehouseKey, }: GetVisitorWarehouseAudienceParamsType) => Promise<CustomData | null>;
    /**
     * @method getEngineTrackingCode - returns Kameleoon tracking code for the current visitor. Tracking code is built of the experiments that were triggered and feature flag variations that were assigned during the last 5 seconds
     * See [Kameleoon Automation API](https://developers.kameleoon.com/apis/activation-api-js/api-reference#trigger-1) for the details
     * @param {string} visitorCode - unique visitor identification string, can't exceed 255 characters length
     * @returns {string} Kameleoon tracking code
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     */
    getEngineTrackingCode: (visitorCode: string) => string;
    /**
     * @method onEvent - fires a callback on a specified Kameleoon `EventType`. Each event can only have one according callback.
     *
     * Note: SDK methods are marked with the `EventType` they trigger if any.
     *
     * @param {EventCallbackType<EventType>} callback - callback function with parameters that will be called upon event
     *
     * Parameter type depends on the `EventType` passed:
     * - `EventType.Evaluation` - `EvaluationEventDataType`
     * - `EventType.ConfigurationUpdate` - `ConfigurationUpdateEventDataType`
     * @returns {void}
     * @throws `KameleoonError` with one of the following `type` s:
     *
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     */
    onEvent: <E extends EventType>(event: E, callback: EventCallbackType<E>) => void;
    /**
     * @method setLogLevel - sets the log level for the Kameleoon SDK
     *
     * @param {LogLevel} logLevel - a log level to be set
     * @returns {void}
     */
    setLogLevel: (logLevel: LogLevel) => void;
    /**
     * @method setForcedVariation - Sets or resets a forced variation for a visitor in a specific experiment, so the experiment will
     * be evaluated to the variation for the visitor.
     * In order to reset the forced variation, set the `variationKey` parameter to `null`. If the forced
     * variation you want to reset does not exist, the method will have no effect.
     *
     * @param {SetForcedVariationParametersType} parameters an object with parameters of a type `SetForcedVariationParametersType`, see the type for details.
     * @returns {void}
     * @throws `KameleoonError` with one of the following `type` s:
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed it's `initialize` call
     * - `KameleoonException.FeatureFlagExperimentNotFound` - The experiment id does not exist in the feature flag.
     * - `KameleoonException.FeatureFlagVariationNotFound` - The variation key does not belong to the experiment.
     * - `KameleoonException.StorageRead` - Couldn't read storage data
     * - `KameleoonException.StorageWrite` - Couldn't update storage data
     */
    setForcedVariation: ({ visitorCode, experimentId, variationKey, forceTargeting, }: SetForcedVariationParametersType) => void;
    /**
     * @method evaluateAudiences - evaluates the visitor against all available Audiences Explorer segments and tracks those that match.
     * A detailed analysis of segment performance can then be performed directly in Audiences Explorer.
     * @param visitorCode {string} - The unique visitor code identifying the visitor.
     * @throws `KameleoonError` with one of the following `type` s:
     * - `KameleoonException.VisitorCodeMaxLength` - The visitor code length was exceeded
     * - `KameleoonException.VisitorCodeEmpty` The visitor code is empty
     * - `KameleoonException.Initialization` - Method was executed before the `kameleoonClient` completed its `initialize` call
     */
    evaluateAudiences(visitorCode: string): void;
    /**
     * @method getDataFile - retrieves the current SDK configuration (also known as the data file),
     * containing all feature flags and their variations.
     * @returns {DataFile} - The data file object containing the configuration details.
     */
    getDataFile(): DataFile;
}