> ## 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 setup and feature flag tutorial

> Set up the Kameleoon SDK and configure feature flags using this step-by-step checklist covering SDK integration, Kameleoon app setup, and optional Hybrid Mode.

<Warning>
  Always check the [SDK documentation](../../feature-experimentation/get-started/overview) 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.
</Warning>

***

## SDK checklist overview[​](#sdk-checklist-overview "Direct link to SDK checklist overview")

This guide provides a step-by-step checklist to [set up and use the Kameleoon SDK](#one-time-setup-in-the-sdk), [configure Feature Flags](#one-time-setup-in-the-kameleoon-app), and optionally [enable Hybrid Mode](#2-hybrid-mode-optional) (SDK + `engine.js`).

***

## 1. Basics[​](#1-basics "Direct link to 1. Basics")

### One-time setup (in the SDK)[​](#one-time-setup-in-the-sdk "Direct link to One-time setup (in the SDK)")

#### Step 1 – Install, configure, and initialize the SDK[​](#step-1--install-configure-and-initialize-the-sdk "Direct link to 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](../../sdks/web-sdks/php-sdk#using-the-php-sdk-without-a-cron-job) to collect data.

***

#### Step 2 – Set the visitor code[​](#step-2--set-the-visitor-code "Direct link to Step 2 – Set the visitor code")

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

***

#### Step 3 (Optional) – Enable [Cross-Device Experimentation](../../cross-device-experimentation) & [Custom Bucketing Key](../../sdks/web-sdks/nodejs-sdk#using-a-custom-bucketing-key)[​](#step-3-optional--enable-cross-device-experimentation--custom-bucketing-key "Direct link to 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[​](#step-4--handle-consent "Direct link to 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[​](#step-5--send-predefined-data "Direct link to 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[​](#step-6--exclude-and-tag-bots "Direct link to 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](https://app.kameleoon.com))[​](#one-time-setup-in-the-kameleoon-app "Direct link to one-time-setup-in-the-kameleoon-app")

#### Step 7 – Create a feature flag[​](#step-7--create-a-feature-flag "Direct link to 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[​](#step-8--define-the-segment "Direct link to 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[​](#step-9--attach-goals-to-the-flag "Direct link to Step 9 – Attach goals to the flag")

* Attach at least one goal to track conversions.

***

#### Step 10 – Activate the flag[​](#step-10--activate-the-flag "Direct link to Step 10 – Activate the flag")

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

***

### Setup for each flag (In the SDK)[​](#setup-for-each-flag-in-the-sdk "Direct link to Setup for each flag (In the SDK)")

#### Step 11 – Check feature activation[​](#step-11--check-feature-activation "Direct link to 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[​](#step-12--track-conversions-and-set-custom-data "Direct link to 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](../targeting-and-segmentation/native-segmentation#when-is-getremotevisitordata-required) or [External Data](../targeting-and-segmentation/use-external-data-to-target-users)[​](#step-13-optional--use-previously-collected-data-or-external-data "Direct link to 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)[​](#2-hybrid-mode-optional "Direct link to 2. Hybrid Mode (Optional)")

Follow these steps only if using [**Hybrid Mode**](./hybrid-experimentation) (Client-side SDK + `engine.js`).

### One-time setup (in the SDK)[​](#one-time-setup-in-the-sdk-1 "Direct link to One-time setup (in the SDK)")

#### Step 1 – Install engine.js[​](#step-1--install-enginejs "Direct link to Step 1 – Install engine.js")

* Add the `engine.js` script to the front-end.

***

#### Step 2 – Handle frontend consent[​](#step-2--handle-frontend-consent "Direct link to Step 2 – Handle frontend consent")

If consent is required, handle it using:

* The **Activation API**
* The `kameleoonQueue` via Tag Manager
* A direct code snippet:

```js theme={null}
window.kameleoonQueue.push(['Kameleoon.API.Core.enableLegalConsent', 'BOTH']); 
// or
window.kameleoonQueue.push(['Kameleoon.API.Core.disableLegalConsent', 'BOTH']);
```

***

#### Step 3 – Sync visitor code[​](#step-3--sync-visitor-code "Direct link to Step 3 – Sync visitor code")

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

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

***

### Optional: Send data to external tools (Hybrid Mode)[​](#optional-send-data-to-external-tools-hybrid-mode "Direct link to Optional: Send data to external tools (Hybrid Mode)")

#### One-time setup (in the [Kameleoon app](https://app.kameleoon.com))[​](#one-time-setup-in-the-kameleoon-app-1 "Direct link to one-time-setup-in-the-kameleoon-app-1")

##### Step 1 – Activate third-party integration[​](#step-1--activate-third-party-integration "Direct link to 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)[​](#setup-for-each-flag-in-the-kameleoon-app "Direct link to Setup for each flag (in the Kameleoon app)")

##### Step 2 – Turn on the integration[​](#step-2--turn-on-the-integration "Direct link to 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)[​](#setup-for-each-flag-in-the-sdk-1 "Direct link to Setup for each flag (in the SDK)")

##### Step 3 – Retrieve tracking code[​](#step-3--retrieve-tracking-code "Direct link to 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[​](#step-4--inject-tracking-code-into-the-page "Direct link to Step 4 – Inject tracking code into the page")

Insert the returned code into the HTML:

```js theme={null}
window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Experiments.assignVariation', 244200, 962266]);
window.kameleoonQueue.push(['Experiments.trigger', 244200, true]);
```

***

##### Step 5 – Verify event transmission[​](#step-5--verify-event-transmission "Direct link to 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).