SDK setup and feature flag tutorial

Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

​

SDK checklist overview​

​

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)​

​

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​

• 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​

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​

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).