> ## 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

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

### 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](../../sdks/web-sdks/php-sdk#using-the-php-sdk-without-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](../../cross-device-experimentation) & [Custom Bucketing Key](../../sdks/web-sdks/nodejs-sdk#using-a-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](https://app.kameleoon.com))

#### 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](../targeting-and-segmentation/native-segmentation#when-is-getremotevisitordata-required) or [External Data](../targeting-and-segmentation/use-external-data-to-target-users)

* **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**](./hybrid-experimentation) (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:

```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

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)

#### One-time setup (in the [Kameleoon app](https://app.kameleoon.com))

##### 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:

```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

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