JavaScript / TypeScript SDK

import {
  Environment,
  KameleoonClient,
  SDKConfigurationType,
} from '@kameleoon/javascript-sdk';

// -- Optional configuration
const configuration: Partial<SDKConfigurationType> = {
  dataFileRefreshInterval: 20,
  environment: Environment.Production,
  cookieDomain: '.example.com',
};

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

// -- 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 { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/javascript-sdk';

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

// The `NONE` log level does not allow logging.
client.setLogLevel(LogLevel.NONE);
// Or use directly KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.NONE);

// The `ERROR` log level only allows logging issues that may affect the SDK's primary behavior.
client.setLogLevel(LogLevel.ERROR);
// Or use directly KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.ERROR);

// The `WARNING` log level allows logging issues which may require additional attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
client.setLogLevel(LogLevel.WARNING);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.WARNING);

import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/javascript-sdk/full’;

// The `INFO` log level allows logging general information on the SDK’s internal processes.
// It extends the `WARNING` log level.
client.setLogLevel(LogLevel.INFO);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.INFO);

// The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
// with more granular. diagnostic output.
// This information is not intended for end-user interpretation but can be sent to our support team
// to assist with internal troubleshooting.
client.setLogLevel(LogLevel.DEBUG);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.DEBUG);

import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/javascript-sdk';

export class CustomLogger implements IExternalLogger {
  // `log` method accepts logs from the SDK
  public log(level: LogLevel, message: string): void {
    // Custom log handling logic here. For example:
    switch (level) {
      case LogLevel.DEBUG:
        console.debug(message);
        break;
      case LogLevel.INFO:
        console.info(message);
        break;
      case LogLevel.WARNING:
        console.warn(message);
        break;
      case LogLevel.ERROR:
        console.error(message);
        break;
    }
  }
}

const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    logger: new CustomLogger(),
  },
});

// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
client.setLogLevel(LogLevel.DEBUG);
// Or use KameleoonLogger
KameleoonLogger.setLogLevel(LogLevel.DEBUG);

import { IExternalStorage, KameleoonClient } from '@kameleoon/javascript-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 {
  IExternalEventSource,
  KameleoonClient,
  EventSourceOpenParametersType,
} from '@kameleoon/javascript-sdk';

// --- External EventSource implementation ---
// - Example uses native browser `EventSource`
class MyEventSource implements IExternalEventSource {
  private eventSource?: EventSource;

  public open({
    eventType,
    onEvent,
    url,
  }: EventSourceOpenParametersType): void {
    // - Initialize `EventSource`
    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();
    }
  }

  public onError(callback: (error: Event) => void): void {
    // - Set error callback
    if (this.eventSource) {
      this.eventSource.onerror = callback;
    }
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    eventSource: new MyEventSource(),
  },
});

import {
  IExternalVisitorCodeManager,
  SetDataParametersType,
  KameleoonClient,
  KameleoonUtils,
} from '@kameleoon/javascript-sdk';

// --- External Visitor Code Manager implementation ---
// - Example uses browser `document.cookie` API
class MyVisitorCodeManager implements IExternalVisitorCodeManager {
  public getData(key: string): string | null {
    const cookieString = document.cookie;

    // - Return `null` if no cookie was found
    if (!cookieString) {
      return null;
    }

    // - Parse cookie using the provided `key`
    return KameleoonUtils.getCookieValue(cookieString, key);
  }

  public setData({
    visitorCode,
    domain,
    maxAge,
    key,
    path,
  }: SetDataParametersType): void {
    // - Set cookie with provided parameters
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    document.cookie = resultCookie;
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    visitorCodeManager: new MyVisitorCodeManager(),
  },
});

import {
  RequestType,
  IExternalRequester,
  KameleoonResponseType,
  SendRequestParametersType,
  KameleoonClient,
} from '@kameleoon/javascript-sdk';

// --- External Requester Implementation
export class MyRequester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    // - Using native browser `fetch`
    return await fetch(url, parameters);
  }
}

// --- Create KameleoonClient ---
const client = new KameleoonClient({
  siteCode: 'my_site_code',
  externals: {
    requester: new MyRequester(),
  },
});

import {
  KameleoonError,
  KameleoonClient,
  KameleoonException,
} from '@kameleoon/javascript-sdk';

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

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 {
  KameleoonUtils,
  IExternalRequester,
  SendRequestParametersType,
  RequestType,
  KameleoonResponseType,
} from '@kameleoon/javascript-sdk';

// - Example of `Requester` with disabled tracking
class Requester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
    requestType,
  }: SendRequestParametersType<RequestType>): Promise<KameleoonResponseType> {
    if (requestType === RequestType.Tracking) {
      return KameleoonUtils.simulateSuccessRequest<RequestType.Tracking>(
        requestType,
        null,
      );
    }

    return await fetch(url, parameters);
  }
}

import { KameleoonUtils } from '@kameleoon/javascript-sdk';

const cookies = 'key_1=value_1; key_2=value_2';
const key = 'key_1';

const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1`

import { KameleoonClient } from '@kameleoon/javascript-sdk';

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

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

  // -- Check whether the SDK is ready
  const ready: boolean = client.isReady();

  if (ready) {
    // -- The SDK is ready; you can evaluate feature flags here
  }
}

init();

import { KameleoonClient } from '@kameleoon/javascript-sdk';

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

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

  // -- Get visitor code
  const visitorCode = client.getVisitorCode();

  // -- Get variation with tracking
  const variation = client.getVariation({
    visitorCode,
    featureKey: 'my_feature_key',
  });

  // -- Get variation without tracking
  const variation = client.getVariation({
    visitorCode,
    featureKey: 'my_feature_key',
    track: false,
  });

  // -- An Example variation:
  // {
  //  key: 'variation_key',
  //  id: 123,
  //  experimentId: 456,
  //  variables: Map {
  //    'variable_key' => {
  //      key: 'variable_key',
  //      type: VariableType.BOOLEAN,
  //      value: true,
  //    }
  //  },
  // }
}

init();

import { KameleoonClient } from '@kameleoon/javascript-sdk';

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

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

  // -- Get visitor code
  const visitorCode = client.getVisitorCode();

  // -- Get all feature flag variations with tracking
  const variations = client.getVariations({
    visitorCode,
  });

  // -- Get active feature flag variations with tracking
  const variations = client.getVariations({
    visitorCode,
    onlyActive: true,
  });

  // -- Get active feature flag variations without tracking
  const variations = client.getVariations({
    visitorCode,
    onlyActive: true,
    track: false,
  });

  // -- An Example variations:
  // Map {
  // 'feature_key' => {
  //    key: 'variation_key',
  //    id: 123,
  //    experimentId: 456,
  //    variables: Map {
  //      'variable_key' => {
  //        key: 'variable_key',
  //        type: VariableType.BOOLEAN,
  //        value: true,
  //      }
  //    },
  //   }
  // }
}

init();

import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk';

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

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

  // -- Get visitor code
  const visitorCode = client.getVisitorCode();

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

  // -- Check if the feature flag is active for visitor without tracking
  const isActive = client.isFeatureFlagActive({ visitorCode, featureKey: 'my_feature_key', track: false});
}

init();