Skip to main content

SDK setup and feature flag tutorial

caution

Always check the SDK documentation to ensure correct method names. The methods below are from the Node.js SDK.
Some features or methods may not be available in all SDKs.

SDK checklist overview​

This guide provides a step-by-step checklist to set up and use the Kameleoon SDK, configure Feature Flags, and optionally enable Hybrid Mode (SDK + engine.js).

1. Basics​

One-time setup (in the SDK)​

Step 1 – Install, configure, and initialize the SDK​

  • Install the SDK and configure it, paying attention to:
    • updateInterval: Defines how often the SDK fetches the latest configuration from Kameleoon.
    • trackingInterval: Defines how often the SDK sends tracked data to Kameleoon.
  • Create a new KameleoonClient and call initialize() to load configuration.
  • PHP SDK only: Install a cron job to collect data.

Step 2 – Set the visitor code​

  • Use getVisitorCode() or a custom method to set the kameleoonVisitorCode cookie.

Step 3 (Optional) – Enable Cross-Device Experimentation & Custom Bucketing Key​

  • Cross-Device Experimentation: Share the same kameleoonVisitorCode across devices.
  • Custom Bucketing Key: Show the same variation to a defined group of visitors (e.g., users from the same organization).

Step 4 – Handle consent​

  • If an experiment requires consent, call setLegalConsent(). (Not needed if the feature flag type uses Delivery Rules.)

Step 5 – Send predefined data​

  • Use addData() to target:
    • Device
    • Browser
    • Page URL
    • Other predefined criteria
  • Call flush() to send data to Kameleoon.
    (Note: flush is also called implicitly by isFeatureActive, getVariation, and trackConversion.)

Step 6 – Exclude and tag bots​

  • Exclude bots from results using addData() with the userAgent type.
  • To tag internal bots, pass curl/8.0 to userAgent in addData().

One-time setup (in the Kameleoon app)​

Step 7 – Create a feature flag​

  • Create a new feature flag in the Kameleoon App.
  • Add at least one rule (Delivery or Experiment) to the Rollout Planner.

Step 8 – Define the segment​

  • Option 1: Target all visitors in the Kameleoon App and implement custom logic in the SDK.
  • Option 2 (Recommended): Use a Kameleoon segment in the Kameleoon App.
    • Ensure you use addData() in the SDK to send data used for targeting (page URL, device, browser, etc.).

Step 9 – Attach goals to the flag​

  • Attach at least one goal to track conversions.

Step 10 – Activate the flag​

  • Turn the flag on in the Kameleoon App to start serving variations.

Setup for each flag (In the SDK)​

Step 11 – Check feature activation​

  • Call isFeatureActive() to check if a visitor is targeted:
    • Returns false if the variation is "off"
    • Returns true if active
  • Call getVariation() to retrieve the variation key.

Step 12 – Track conversions and set custom data​

  • Call trackConversion() with relevant parameters to track goals.
  • Optionally, use addData() for custom targeting and segmentation.

Step 13 (Optional) – Use previously collected data or External Data​

  • Previously Collected Data: Call getRemoteVisitorData() to reuse collected or preloaded conditions.
  • External Data: Use the Data API to collect external data and retrieve it in the SDK via getRemoteData().

2. Hybrid Mode (Optional)​

Follow these steps only if using Hybrid Mode (Client-side SDK + engine.js).

One-time setup (in the SDK)​

Step 1 – Install engine.js​

  • Add the engine.js script to the front-end.

Step 2 – Handle frontend consent​

If consent is required, handle it using:

  • The Activation API
  • The kameleoonQueue via Tag Manager
  • A direct code snippet:
window.kameleoonQueue.push(['Kameleoon.API.Core.enableLegalConsent', 'BOTH']); 
// or
window.kameleoonQueue.push(['Kameleoon.API.Core.disableLegalConsent', 'BOTH']);

Step 3 – Sync visitor code​

If consent is required, sync the visitor code cookie between the SDK and the front-end:

window.kameleoonQueue.push({
  level: "IMMEDIATE",
  command: () => Kameleoon.API.Visitor.setVisitorCode("<USER_ID>")
});

Optional: Send data to external tools (Hybrid Mode)​

One-time setup (in the Kameleoon app)​

Step 1 – Activate third-party integration​
  • In the Integrations section of the Kameleoon App, enable the analytics tool you want to use (e.g., GA4).

Setup for each flag (in the Kameleoon app)​

Step 2 – Turn on the integration​
  • In the Feature Flag Dashboard, activate the tool for the chosen rule type (Experiment or Delivery).
  • Ensure integration is enabled in the correct environment (Production, Development, or Staging).

Setup for each flag (in the SDK)​

Step 3 – Retrieve tracking code​
  • Call getEngineTrackingCode() in the SDK code within 5 seconds of activating the feature (isFeatureActive or getVariation).
Step 4 – Inject tracking code into the page​

Insert the returned code into the HTML:

window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Experiments.assignVariation', 244200, 962266]);
window.kameleoonQueue.push(['Experiments.trigger', 244200, true]);
Step 5 – Verify event transmission​
  • On the targeted page, inspect the page elements to confirm code injection.
  • For GA4, verify the event is pushed into the dataLayer.
  • In the Network tab, confirm that the event is sent to the correct analytics tool (GA4 should show a “collect” event).