# Welcome to Kameleoon
Source: https://docs.kameleoon.com/home/welcome
Kameleoon is a powerful, unified platform designed to help teams deliver better digital experiences through experimentation, feature management, and personalization.
## Choose your path
Select the portal that best fits your role and what you are trying to build today.
For marketers, product managers, and QA teams. Learn how to create, configure, and analyze experiments, manage personalizations, and use the Widget Studio.
For engineers and technical teams. Find implementation guides, SDK references, API documentation, and edge-compute starter kits.
***
## Don't know where to start?
Take this quick 3-question quiz to find the exact documentation you need for your tech stack and use case.
***
## Use docs with your AI assistant
Ask questions, get step-by-step guidance, and explore the full Kameleoon knowledge base—directly from your AI tool.
Open any article in Claude or ChatGPT with one click, or configure a persistent MCP server for Claude Desktop, Cursor, VS Code, and more.
***
## Core capabilities
Blend experimentation, feature management, and personalization into one platform across web, mobile, and backend environments.
Use natural language prompts to instantly generate variations, or use the visual editor to test copy, design, and layouts on any website or single-page app.
Decouple deployment from release. Roll out new features progressively, run server-side experiments, and reduce risk with targeted feature flags.
Deliver experiences tailored to specific users in real-time by leveraging behavioral data, CRM integrations, or your data warehouse.
Access reliable, real-time results powered by Kameleoon's multi-statistical engine (CUPED, Bayesian, or Sequential testing).
***
## Explore Kameleoon's tech stack
Deploy Kameleoon anywhere. We provide more than a dozen SDKs, REST APIs, and integrations to fit perfectly into your existing ecosystem.
Implement experiments quickly using JavaScript, TypeScript, React, Vue, PHP, Python, Ruby, Go, or Java.
[Explore Web SDKs →](../developer-docs/sdks/web-sdks/js-sdk)
Bring feature flagging and experimentation to your native apps with iOS, Android, Flutter, and React Native SDKs.
[Explore Mobile SDKs →](../developer-docs/sdks/mobile-sdks/ios-sdk)
Programmatically control experiments, automate workflows, and inject custom data using Kameleoon's REST and JS APIs.
[Explore APIs →](../developer-docs/apis/overview)
# Create a key page
Source: https://docs.kameleoon.com/user-manual/assets/advanced-targeting-tools/create-a-key-page
Create a key page to target visitors who access specific URLs on your website and use it as a targeting condition in segments.
Use a **key page** to target users who visit specific pages on your website.
## Create a new key page
To create a new key page:
1. Click **Settings** > **Advanced tools**.
2. Click **New tool** at the top right of the page.
3. Click **Key page**.
4. Select one or more projects, name your key page, and enter the URL of the page you want to target.
5. Click **Create**.
## Define a key page as targeting condition
To add a key page to a new segment, use the **Key pages** condition, available only in the Trigger Builder.
1. Navigate to the **Conditions** tab in the Trigger Builder.
2. Select the **Key pages** condition in the **Pages viewed** tab.
3. Select the key page in the dropdown menu and include or exclude visitors meeting the key page's criteria.
# Create an acquisition channel
Source: https://docs.kameleoon.com/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel
Create custom acquisition channels to target visitors based on their traffic source, then use them as segment conditions or result filters.
You can target visitors using acquisition channels. Kameleoon automatically creates five default channels:
* Bing
* Baidu
* Google
* Yahoo
* Google Ads
## Create a new acquisition channel
To create a new acquisition channel:
1. Click **Settings** > **Advanced targeting tools**.
2. Click **New tool** in the top right of the page.
3. Click **Acquisition channel**.
4. Select one or more projects, name your acquisition channel, and select an acquisition method in the dropdown menu:
* Referrer URL
* URL of current page
* JavaScript
### Referrer URL (regular expression)
Indicate the URL the visitor must come from for Kameleoon to target them.
### URL of the current page (regular expression)
Indicate the URL the visitor must visit for Kameleoon to target them.
See [Regular expressions](./regular-expressions) for the syntax supported by the Referrer URL and URL of the current page fields.
### JavaScript
Indicate the JavaScript assessing the visitor’s acquisition channel.
Example:
```javascript theme={null}
(function(){
if (/user-manual/param=123/.test(window.location.search) ) {
return true
}
})();
```
### Additional information about acquisition channels
Kameleoon checks the acquisition channel after each page view and stores it for the visit's duration. Each new visit has its own acquisition channel. If a visitor uses multiple acquisition channels across different visits (for example, visit 1 = SEA, visit 2 = Direct, and visit 3 = SEA), the visitor accumulates two visits for SEA and one visit for Direct in the Results page when displaying by visit. The Results page displays one visitor for SEA and one visitor for Direct in the visitor view. A visit or visitor can have several acquisition channels assigned at the same time. Kameleoon records matches in the page event.
## Add an acquisition method
You can add acquisition methods to define your acquisition channel more precisely.
Select the method and fill in the corresponding field.
Kameleoon links multiple acquisition methods with an **and** or **or** boolean. **And** limits the scope (visitor must fulfill all conditions), while **or** broadens the scope (visitors must fulfill one condition).
Click the **X** to delete an acquisition method from your acquisition channel.
## Define an acquisition channel as targeting condition
To add an acquisition channel to a new segment:
1. Select the **Acquisition channel** condition in the **Acquisition** tab.
2. In the dropdown menu, select the created channels and include or exclude the visitors meeting the acquisition channel criteria.
## Use an acquisition channel as a filter or breakdown on the Results page
You can use acquisition channels to filter or break down the data on the Results page. Both options are in the **Audience** tab of the Results page settings sidebar. See [Results page settings](../../experiment-analytics/analyze-results/results-page/results-page-settings) for more on the settings sidebar.
### Filter by acquisition channel
To filter Results page data by acquisition channel:
1. Open the settings sidebar and click the **Audience** tab.
2. Click **Add filter** > **Add filter**.
3. Select the **Acquisition channel** identifier.
4. Choose an operator, select one or more channels, and include or exclude the visitors who meet the criteria.
5. Click **Apply filter**.
### Break down by acquisition channel
To break down Results page data by acquisition channel:
1. Open the settings sidebar and click the **Audience** tab.
2. Click the chevron to expand the **Breakdown audience** menu, then click **Add breakdown**.
3. Select **Acquisition channel** and specify its criteria.
4. Click **Apply**.
You can apply this breakdown to all goals by checking the corresponding box below the dropdown list.
When you break down results by acquisition channel, two system-generated entries may appear:
* **RESTART**: Kameleoon assigns this label to sessions with no referrer. Sessions without a referrer typically occur when a visitor's session becomes inactive while the browser tab remains open and the visitor then returns to the page.
* **DELETED**: Kameleoon assigns this label to visits linked to a deleted acquisition channel. Because the channel no longer exists, Kameleoon can't match the visit to a named channel.
# Manage advanced targeting tools
Source: https://docs.kameleoon.com/user-manual/assets/advanced-targeting-tools/manage-advanced-targeting-tools
Access, create, and edit advanced targeting tools (acquisition channels and key pages) to refine visitor segmentation in your experiments.
Advanced tools improve your visitor segmentation by adding conditions to new segments.
Use criteria, like acquisition channels and key pages, to fine-tune your visitor segmentation.
Advanced tools are only available in Premium accounts. If you want to upgrade your package, [contact Kameleoon](https://www.kameleoon.com/en/contact).
## Access advanced tools
To access advanced tools:
* Click **Settings** > **Advanced tools**.
You can create two types of advanced tools:
* Acquisition channels
* Key pages
## Create a new advanced tool
To create a new advanced tool:
1. Click **New tool** in the upper-right corner of the page. A pop-in appears.
2. Choose the type of advanced tool you want to create.
The pop-in now shows your tool's setup options.
## Edit an advanced tool
To edit an advanced tool:
1. Open the **Advanced tools dashboard**.
2. Click **Edit** at the end of a tool's card.
3. Click the **three-dots menu** to:
* edit a tool's parameters
* duplicate the tool
* delete it
You can't delete a tool used in a live experiment. An icon appears in the bottom-left corner of the confirmation pop-in, indicating which experiments use which tools.
[How to create an acquisition channel](./create-an-acquisition-channel)
# Regular expressions
Source: https://docs.kameleoon.com/user-manual/assets/advanced-targeting-tools/regular-expressions
Reference for the regular expression syntax Kameleoon supports in the matches the regular expression operator across segments, goals, and advanced targeting tools conditions.
A regular expression is a pattern that matches text against a set of rules instead of a single exact string. Use a regular expression when a condition needs to match multiple variations of a URL, such as different query parameters or page numbers, rather than one exact address.
Kameleoon conditions that offer a **matches the regular expression** operator use the syntax on this page, including segment conditions like Landing page URL and Referring website URL, goal URL conditions, and advanced targeting tools like acquisition channels and key pages.
## Regular expression syntax
* `.` matches any single character. For example, `Kamele.on` matches `Kameleoon`, `Kamele0n`, and `Kamele8on`.
* `*` matches the preceding character zero or more times. For example, `Kameleoo*n` matches `Kameleon`, `Kameleoon`, and `Kameleooon`.
* `?` matches the preceding character zero or one time. For example, `Kameleoo?n` matches `Kameleon` and `Kameleoon`.
* `+` matches the preceding character one or more times. For example, `Kameleo+n` matches `Kameleoon` and `Kameleoooon`.
* `|` acts as an OR operator between two patterns. For example, `Kameleoon|Chameleoon` matches `Kameleoon` or `Chameleoon`.
* `^` matches the start of the string. For example, `^Kameleoon` matches URLs starting with `Kameleoon`.
* `$` matches the end of the string. For example, `Kameleoon$` matches URLs ending with `Kameleoon`.
* `()` groups several elements, usually combined with `|`. For example, `Kameleoon (AB Testing|Conversion) Tool` matches `Kameleoon AB Testing Tool` or `Kameleoon Conversion Tool`.
* `[]` matches any single character inside the brackets. For example, `/Kameleoon/[234]` matches `Kameleoon 2`, `Kameleoon 3`, and `Kameleoon 4`.
* `-` defines a range inside `[]`. For example, `/kameleoon/[2-9]` matches every page from `Kameleoon 2` to `Kameleoon 9`.
* `{}` sets a minimum and maximum number of repetitions of the preceding character. For example, `Kameleo{2,4}n` matches `Kameleoon`, `Kameleooon`, and `Kameleoooon`.
Escape special characters (for example, `,`, `.`, `*`) with a backslash: `\,`, `\.`, `\*`.
Regular expressions are case-sensitive.
## Examples
* `^.{10}$` matches URLs containing exactly 10 characters.
* `general\.(html|php)$` matches URLs ending with either `general.php` or `general.html`.
* `/fr/` matches URLs containing `/fr/`.
* `/annexes/.*\d{3}` matches URLs containing the fragment `/annexes/` and a three-digit number.
* `/annexes/.*\d{2}.*test.html$` matches URLs containing the fragment `/annexes/`, a two-digit number, and ending with `test.html`.
# Create custom data
Source: https://docs.kameleoon.com/user-manual/assets/custom-data/create-custom-data
Create custom data to target and segment visitors using your own data sources, such as CRM attributes, tag manager variables, or JavaScript.
Creating custom data enables you to target visitors according to data already available, like user account information.
All of your custom data is available under **Settings** > **Custom data**, where you can create and [manage custom data](./manage-custom-data).
## Create new custom data
To create new custom data:
1. Click **Settings** > **Custom data**.
2. Click **New custom data** in the top right of the page.
You must fill in several fields to set up custom data.
### Structure of the creation pop-in
1. Name the new custom data.
2. Select a project.
3. Tell Kameleoon how to retrieve custom data.
### Custom data name
Give your custom data an easily identifiable name.
If you select several websites, make sure you pull custom data from all of them.
You can have a maximum of 255 active custom data points.
### Value retrieval
#### Retrieval method
Choose the custom data's value retrieval method from the dropdown menu.
The main tag management tools are:
* GTM data layer (`dataLayer`)
* Commanders Act data layer (`tc_vars`)
* Tealium (`utag.data` & `utag_data`)
For these tag managers, you must indicate the name of the variable you want to retrieve.
**If you choose to use GTM `dataLayer`**, proceed as follows to retrieve values:
* If the key is in level 1 of the `dataLayer`, enter `name` in the **Variable Name** field.
* If the key is in level 2 of the `dataLayer`, enter `properties.countryCode` in the **Variable Name** field.
**If you choose Kameleoon Activation API**, set the value yourself from your website's JavaScript, typically your global script, using the Activation API's [`setCustomData()`](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#setcustomdata) method.
**If you choose Kameleoon SDK method**, set the value using a [Kameleoon SDK](../../../developer-docs/sdks/web-sdks/js-sdk)'s `addData()` method. Use this retrieval method when you target visitors with Kameleoon Feature Experimentation.
**If you choose Custom JavaScript code**, write the code directly into this field. Your code must return an object with two keys: `value`, with the value you want to provide for this custom data, and (optionally) `override`, with a boolean value (false by default). Kameleoon runs the code again every 100 ms for the first 3 seconds after the first invocation, then every 3 seconds after that.
Here is an example:
```javascript theme={null}
if (! window.myObject) return null;
// custom data is not set, but code runs again later
if (window.myObject) return {"value": window.myObject.x, "overwrite": true};
// returning a value and setting the custom data
if (window.someObject.value == 3) return {"value": null}
// stopping the periodic execution of the code, without setting the custom data
```
Avoid this retrieval method if possible. The code in this field must run synchronously and return its value immediately, so it can't call an asynchronous method such as `retrieveDataFromRemoteSource()`. Write your JavaScript in a different location instead, such as Tag Manager, an external script file, or inline script code in the HTML, and use the Kameleoon Activation API retrieval method to set the custom data.
#### Type
Select the structure of the data you want to retrieve from the dropdown menu.
The data type can be:
* single (example: `127`)
* list (example: `126, 127, 128`; `shoes, dress, coat`)
* count list of (example: `shoes: 3, dress: 1, coat: 1`)
#### Format
Select the format of the data you want to retrieve from the dropdown menu.
The data format can be:
* string (example: `woman dress`)
* boolean (example: `female = "true/false"`)
* number (example: `cart amount = "127"`)
#### Scope
Select your custom data's scope in the dropdown menu:
* **Page:** For each new page, Kameleoon resets the data's value. For example, cart amount.
* **Visit:** Kameleoon resets the data's value at each new visit. For example, geolocation.
* **Visitor:** The unit of data relates to the visitor and not to the visit. For example, female = true.
### Options
Click **Next** to access available options for your custom data.
#### Use this data only locally for targeting purposes
If you use your custom data solely for targeting, you don't need to store it on the server. In this scenario, use the `LocalData` API, which helps conserve server space because it doesn't count towards the limit of 255 active custom data points. However, you can't use custom data managed through the `LocalData` API for reporting on the Results page.
If you choose to store custom data on the server, be cautious not to save sensitive information. Also, the value of any custom data you send to the server can't exceed 1,000 characters.
#### Use this custom data as input for AI Predictive Targeting
If your project has [AI Predictive Targeting](../../ai-predictive-targeting/overview) enabled, you can choose whether to include this custom data as an input for the predictive model. You can't use custom data that has **Use this data only locally for targeting purposes** enabled as model input, because Kameleoon doesn't send local data to the server. Don't activate this option if the custom data is highly targeted (for example, specific to individual visitors or very small segments).
The model only accepts **Number** and **Boolean** custom data types. Avoid adding sensitive data such as dates, timestamps, or unique visitor identifiers (like email addresses or customer account numbers), as these elements are unsuitable for predictive models.
#### Use this custom data as a unique identifier for cross-device history reconciliation
When you activate this option, Kameleoon treats this custom data as a unique identifier for your visitors and uses it to map several Kameleoon visits to a unique user. For more information, see [cross-device experimentation](../../../developer-docs/cross-device-experimentation).
#### Save the values for the targeting condition associated with the custom data point
This option allows you to define a specific list of values that are then available for this custom data in the segment builder.
In the **New custom data** pop-in (first page of the creation flow), click **Paste a sample code** to get a code example.
Your code must synchronously return a JavaScript array of objects. Each object in this array should represent a possible value for the custom data and must include:
* A `value` key, containing the actual data (its type must match the custom data's defined type).
* A `label` key, providing a string description for that value.
Example:
```javascript theme={null}
return [{value:'q2f6hsbzpf', label:'First segment'},
{value:'8ney4225y65a', label:'Other segment'},
{value:'3h6vjtz26b', label:'Loyal users'}];
```
If the format is incorrect, an error message appears when you click **Next**.
Once you've entered your JavaScript, click **Next** > **Create**.
To learn how to use custom data values in the segment builder, see the [create a segment](../segments/create-a-segment) article.
## Define custom data as a targeting condition
To add a custom data to a new segment:
1. Select your desired data in the **Custom data** tab of the Conditions column.
2. In the dropdown menu, set the custom data value required to target a user.
3. Include or exclude visitors meeting the custom data condition.
Depending on the type of custom data, the targeting condition's configuration changes ("is true/is false," "contains," "is equal to").
You can also select custom data as a targeting condition directly in a personalization's **Specific visitors** targeting rule, without creating a segment. For more information, see [set up and launch a personalization](../../web-personalization/set-up-and-launch-a-personalization).
## Filter or break down by custom data on the Results page
On an experiment's Results page, you can filter or break down the results according to custom data associated with the experiment.
[More about custom data in the Kameleoon developer documentation](../../../developer-docs/custom-data)
# Manage custom data
Source: https://docs.kameleoon.com/user-manual/assets/custom-data/manage-custom-data
Find, edit, duplicate, and delete custom data from the Kameleoon Custom data dashboard using search, filter, and sort tools.
## Access the Custom data page
To access the **Custom data** page in Kameleoon, click **Settings** > **Custom data**.
## Manage your custom data
Each custom data has a card that displays its information.
### Find a custom data's index
Kameleoon assigns each custom data a numeric **index** when you create it. The index uniquely identifies a custom data, and you need it when you reference the custom data from code, including:
* The `CustomDataNameOrIndex` argument of `setCustomData()` in the [Activation API](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#setcustomdata).
* The keys of the `metadata` object passed to `processConversion()` and `triggerGoal()` (for example, `{ 5: "Amex Credit Card" }` references the custom data with index `5`).
* SDK methods that accept a custom data index.
To view the index of a custom data:
1. Click **Settings** > **Custom data**.
2. Locate the custom data in the list. The numeric value next to its name (in the **INDEX** column) is the index used in code.
You can also sort custom data by index; see [Sort custom data](#sort-custom-data).
### Find a custom data
A search bar, a filter tool, and a sorting tool help you find a particular custom data.
#### Filter custom data
You can filter the displayed custom data based on several criteria:
* Project
* Key date
* Creator
##### Project
Filter the displayed custom data by project.
Select the projects and click **Apply**.
##### Key date
Narrow the list by key date: last modification or creation date.
Select a date and click **Apply**.
##### Creator
Narrow the list by the author who created each custom data.
Check the authors and click **Apply**.
#### Sort custom data
Sort your custom data using any of the following criteria:
* Name
* Index
* Project
* Edition date
* Creation date
* Creator
##### Name
Hover over **Name** and click the chevron to sort custom data in alphabetical (or reverse alphabetical) order.
##### Index
Hover over **linked to** and click the chevron to rank the custom data by index.
##### Project
Hover over **Project** and click the chevron to sort custom data in alphabetical (or reverse alphabetical) order by project.
##### Edition date
Hover over **Edited** and click the chevron to sort custom data from newest edition to oldest or vice versa.
##### Creation date
Hover over **Created** and click the chevron to sort custom data from newest creation to oldest or vice versa.
##### Creator
Hover over **Creator** and click the chevron to sort custom data in alphabetical (or reverse alphabetical) order by creator.
### Edit a custom data
To edit an existing custom data:
1. Locate the custom data's card.
2. Click **Edit** on the custom data card. A pop-in window opens.
3. Enter your changes in the pop-in.
Click **Next** > **Save** to save your changes when they're complete.
### Duplicate a custom data
To duplicate custom data:
1. Select a custom data.
2. Click the **three-dots menu**.
3. Click **Duplicate**. The Duplicate sidebar opens.
4. Click **Save** to validate the duplication.
### Delete a custom data
To delete custom data:
1. Select a custom data.
2. Click the **three-dots** menu > **Delete**.
### Multiple selection
To select multiple custom data and apply a common action to them:
1. Select a custom data.
2. Click the **three-dots menu**.
3. Click **Select**. The custom data becomes selectable and the **Grouped actions** sidebar opens.
Two actions are possible:
* **Select all**
* **Deselect all**
To select all custom data, check the **box** next to **Select all**. To deselect all, click the **box** again.
# Create a goal
Source: https://docs.kameleoon.com/user-manual/assets/goals/create-a-goal
Create and configure goals to track conversions in your experiments, choosing from click tracking, scroll tracking, page access, time spent, and more.
*Watch the [video tutorial](https://academy.kameleoon.com/how-to-plan-your-first-experiment/162248) in the Kameleoon Academy to learn how to set up goals.*
An experiment alone can only tell you which variation each visitor saw, not whether that variation improved your site's performance. Goals close that gap: each one defines what counts as a conversion, so Kameleoon can measure whether your campaign achieves the results you're testing for. Link one or more goals to your experiment to start measuring.
All goals you create in Kameleoon are available on the **Goals** page in the **Settings** menu.
## Access the Goals page
To access your goals, click **Settings** > **Goals**.
By default, Kameleoon includes the **Retention rate** goal for all sites associated with your account. This goal records the number of visitors who click at least once after landing on the first page of their visit.
## Create a new goal
If you have protected your website using an iframe, the creation of a goal in the app may not be possible.
### Name and describe your goal
To name and describe your goal:
1. Click **New goal** on the Goals page. The **Add a new goal** modal opens.
2. Fill in the details Kameleoon needs to identify your goal:
* **Name**: A name for your goal.
* **Project**: The site the goal applies to, chosen from a dropdown of your site URLs.
* **Description** (optional): Up to 120 characters describing the purpose of your goal. This information helps you analyze results later.
* **+ Add tags**: Attach one or more tags to the goal for later filtering.
3. Click **Next** to continue, or **Cancel** to close the modal without creating the goal.
### Choose a goal type
Clicking **Next** opens the **Add a new goal** modal, showing a categorized grid of goal type cards:
**Standard goals**
* **Click tracking**: Triggered when a user clicks on a specific element.
* **Time spent**: Triggered when a user spends a defined time on your site.
* **Access to a page**: Triggered when a user visits a specific page.
* **Retention rate**: Triggered when a user clicks after landing on the first page of their visit.
* **Number of pages viewed**: Triggered when a user views a defined number of pages.
* **Scroll tracking**: Triggered when a user reaches a certain percentage of the page height.
**Advanced**
* **Custom Goal**: Target highly specific visitor behaviors by defining your own events.
* **Data warehouse tracking**: Sync events from Snowflake, BigQuery, or other external data sources.
**Formula metrics**
* **Ratio metric**: Measure relative performance by dividing one metric goal by another.
To choose a type:
1. Select a card.
2. Click **Create** to continue, or **Back** to return to the previous modal without selecting a type.
Clicking **Create** opens the **Define your goal** page, which uses a two-step progress stepper with **Step 1, Define triggering conditions** and **Step 2, Advanced settings**. Step 1 shows a green checkmark once it's complete, and Step 2 becomes available only after that. The fields on Step 1 depend on the goal type you selected.
### Click tracking
Choose how you want to define the element that triggers a conversion:
* **With the Visual Editor**: Select the interactive element you want to track with the graphical editor.
* **Using CSS selector**: Specify the CSS selector of the element you want to track.
* **From an existing experiment**: Track an element that was previously added in one of your variations.
* **With the Prompt-based Editor**: Describe the element you want to track, and Kameleoon generates the goal.
Kameleoon greys out the Prompt-based Editor option and marks it as not yet available, matching the scroll tracking visual picker described below.
#### Using CSS selector
1. In the **Click targets** field, enter one or more selectors, separated by commas.
2. Clicking **+ Add selector** opens a dropdown with the same four methods: with the Visual Editor, using a CSS selector, from an existing experiment, or with the Prompt-based Editor, which stays off. Choose one to add another target using a different method.
#### Manually with the Visual Editor
1. An **Open visual editor** dialog asks "On which page (URL) do you want to track clicks?" and prefills the field with your site's URL. Click **Open Editor** to continue, or **Cancel** to close the dialog.
2. The editor opens a split view: your live site renders on the left, and a **Define click tracking** panel opens on the right. Click each element you want to track in the preview area. Clicking an element:
* Adds a highlighted outline box around the element in the preview, confirming your selection.
* Auto-fills the panel's **Selector** field with the element's CSS selector. For example, clicking a button auto-fills a selector like `#pbx-btn-send`.
3. Use the field's clear (X) control or its three-dot options menu to adjust a selection, or click **+ Add selector** to pick more elements. Click **Next** to save your selections, or **Cancel** to close the editor without saving.
#### Choose where to track this goal
Regardless of which method you use to define the target element, choose where the click counts as a conversion:
* **Anywhere on the site** (default): Records a conversion whenever a visitor clicks the element. If several pages share the same CSS selector, every matching click counts.
* **Only on specific pages**: Records a conversion only when the click happens on a page that matches URL conditions you define. Selecting this option reveals a URL-condition builder: choose a match type (for example, **URL contains**) and enter a URL in the text field, such as `www.kameleoon.com/products/`. Click **+ Add target URL** to add further conditions.
If several pages share the same CSS selector, use **Only on specific pages** to scope the goal to a single page instead of relying on a page-unique selector.
If your server settings use the X-Frame-Options header to block your website from displaying in an iframe, the visual editor doesn't display your URL, and you can't add click tracking this way. You must change your server settings and add an exception for the `kameleoon.com` domain and subdomains.
### Scroll tracking
Step 1 for a Scroll tracking goal has two tabs, **Manual** (selected by default) and **Visual picker**.
Kameleoon greys out Visual picker and marks it as not yet available, so the selected-element mode described below stays manual-only for now.
Under **Manual**, configure:
1. **URL of the page**: The URL of the page on which you want to create the scroll tracker.
2. **visitor scrolls down to**: How Kameleoon measures scroll depth, chosen from a dropdown:
* **the selected element**: Visualize the elements of the page by hovering over them, then click the one you want to use as the scroll target. The level appears directly below the selected element.
* **a precise percentage** (default): Enter a percentage of the page height using the numeric stepper, for example 60%. The percentage measures from the top of the page: 0% places the level at the very top, 50% in the middle, and 100% at the very bottom.
* **a height in pixels**: Enter a fixed height in pixels using the numeric stepper. 0 pixels corresponds to the very top of the page, and the maximum height correlates with the page size.
If your server settings use the X-Frame-Options header to block your website from displaying in an iframe, the page preview doesn't display your URL, and you can't add scroll tracking this way. You must change your server settings and add an exception for the `kameleoon.com` domain and subdomains.
### Access to a page
Enter the page a visitor must reach to convert. Choose one of three match types:
* **contains**: Targets all pages sharing the same URL fragment.
* **matches exactly**: Targets only the page with the exact URL you entered.
* **matches the regular expression**: Targets a URL and its variations, according to the regular expression you enter. For help creating regular expressions, see [Regular expressions](../advanced-targeting-tools/regular-expressions).
URL fragments and regular expressions are case-sensitive.
**Example:**
Your product page URLs are typically structured like this: `https://www.mysite.com/products/product-1`
Here's how to apply an **Access to a page** goal for different scenarios:
* **To a specific product page:**
* Select **matches exactly** and enter the full, precise URL. For example: `https://www.mysite.com/products/product-1`
* **To all product pages:**
* Select **contains** and type in `/products/`. Your goal then applies to all pages that include the `/products/` fragment in their URL.
* **For URLs with common variations (for example, "product" vs. "products"):**
* If your product page URLs sometimes contain "product" instead of "products," use a regular expression. For instance, `https://www.mysite.com/products*` matches URLs containing either "products" or "product" at that point.
### Time spent
Enter the time a visitor must spend on your website to convert. Choose a limit:
* **more than**: The visitor must spend at least a given time on the page.
* **exactly**: The time spent must match exactly.
* **less than**: The time spent must not exceed a given duration.
Enter a value and select a unit from the dropdown menu: seconds, minutes, or hours.
### Number of pages viewed
Enter the number of pages a visitor must view to convert. You can choose an exact number, a minimum, or a maximum.
### Retention rate
Kameleoon includes this goal by default for every new site in your account. The retention rate records the number of visitors who clicked at least once after landing on their entry page, so its Step 1 page needs no extra fields once you name and describe it.
### Custom goal
The Custom Goal setup page displays three collapsible cards in a two-column layout showing three ways to trigger a custom goal. An up-chevron marks a card as expanded.
#### Option 1: Using a front-end event triggered by the JS Activation API
Choose this option if the conversion event happens **in the user's browser (client-side)**.
* **How it works:** Kameleoon provides a specific function (`Kameleoon.API.Goals.processConversion(ID)`, where `ID` is your goal's unique identifier) that you insert into your JavaScript code. When the user performs the action you are tracking, your code executes this function to send the conversion signal directly to the Kameleoon platform.
Kameleoon generates the goal's ID once you create the goal.
Click the **Copy** icon to copy the event code and implement it in your JavaScript (or pass it along to your development team for implementation). For more information on the `processConversion()` method, see [the Activation API reference](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#processconversion).
#### Option 2: Using a back-end event via SDK (for example, Node JS)
Choose this option if the conversion event happens **on your server (backend)**. This method is necessary for tracking actions that don't rely on the user's browser session (for example, successful payment processing).
**How it works:** the Kameleoon server-side SDK uses a specific method (`trackConversion()`) to communicate the conversion event directly from your server to the Kameleoon platform.
Click the **Copy** icon to copy the SDK event code and pass it to your backend development team for implementation.
**Code example:**
```typescript theme={null}
trackConversion({visitorCode, goalId})
```
* **`visitorCode`** is the visitor's unique identifier you want to target.
* **`goalId`** is the goal's unique identifier.
Kameleoon generates the goal's ID once you create the goal.
For more information on the `trackConversion()` method, see the [Node.js SDK reference](../../../developer-docs/sdks/web-sdks/nodejs-sdk#trackconversion).
#### Option 3: Using custom JavaScript code
Choose this option if you need to run specific JavaScript logic to determine when to trigger the goal. Custom JavaScript is the most flexible option and is useful if you need to dynamically calculate revenue or capture additional metadata before sending the conversion signal.
* **How it works:** The code you enter in the wider code-editor panel runs automatically once your site is ready. Within that code, use the `triggerGoal()` method to fire a conversion. You can also optionally pass revenue and metadata parameters.
Enter your custom JavaScript code directly into the panel, which prefills a comment scaffold showing usage examples. Click the fullscreen-expand icon to edit in a larger view.
| Function | Description | Example code |
| -------------------------------- | -------------------------------------------------- | ---------------------------------- |
| `triggerGoal()` | Triggers a conversion with no parameters. | `triggerGoal();` |
| `triggerGoal(revenue)` | Triggers a conversion with a revenue value. | `triggerGoal(49.99);` |
| `triggerGoal(revenue, metadata)` | Triggers a conversion with revenue and extra data. | `triggerGoal(49.99, {5: "Gold"});` |
For more information on using custom JavaScript code for custom goals, see Kameleoon's [developer documentation](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#triggergoal-custom-code-for-custom-goal).
***
Alternatively, if you are initiating a conversion from a tag management system (for example, Google Tag Manager), use the [Kameleoon Command Queue](../../../developer-docs/apis/activation-api-js/api-reference/command-queue), which delays the command's execution until the Kameleoon engine finishes loading.
To set this up in Google Tag Manager:
1. Go to **GTM** > **Tags** > **New** > **Tag Configuration** > **Custom HTML** and insert the following code:
```html theme={null}
```
2. Select the trigger that sends the goal conversion call to Kameleoon.
For more information about `Kameleoon.API.Goals`, see the [API reference](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#kameleoonapigoals).
### Data warehouse tracking
Select **Data warehouse tracking** from the **Advanced** group in the type grid to pull conversion data from an external warehouse instead of tracking events directly on your site. Step 1 shows a **Datawarehouse goal** header with a **Datawarehouse integration** dropdown—choose **BigQuery**, **Snowflake**, **Redshift**, or **Databricks**—plus a **Frequency** dropdown and a **Query** textarea.
The remaining fields change based on the integration you choose, since each warehouse identifies and connects to your data differently:
* BigQuery asks for a **BigQuery project ID** and a **Region**.
* Snowflake asks for a **Warehouse**, a **Database**, and a **Schema**.
* Databricks asks for a **Catalog** and a **Schema**.
* Redshift asks whether your cluster runs in **Provisioned** or **Serverless** mode, a **Redshift cluster ID**, a **Region**, and a **Database**.
For the exact fields and query format for your integration, see:
* [Use BigQuery as a source](../../integrations/data-warehouses/bigquery/use-bigquery-as-a-source-pulling-events-for-reporting)
* [Using Snowflake as a source](../../integrations/data-warehouses/snowflake/use-snowflake-as-a-source-pulling-events-for-reporting)
* [Use Databricks as a source](../../integrations/data-warehouses/databricks/use-databricks-as-a-source-pulling-events-for-reporting)
* [Use Amazon Redshift as a source](../../integrations/data-warehouses/amazon-redshift/use-amazon-redshift-as-a-source-pulling-events-for-reporting)
### Ratio metric
Select **Ratio metric** from the **Formula metrics** group in the type grid to create a goal that divides one existing metric by another. Step 1 shows an A/B builder where you pick both metrics and preview the resulting formula live.
For the full configuration walkthrough, see [Ratio Metrics](../../experiment-analytics/analyze-results/data-and-metrics/ratio-metrics#creating-a-ratio-metric).
## Metadata
Most goal types' setup flow ends with an **Attach additional data to conversions (Optional)** card. Before you add any, it shows "No metadata added yet" with the helper text "Enrich your conversions with custom properties to get deeper insights," alongside a **+ Add metadata** button. Ratio metric goals are the exception: since they combine two existing goals' data rather than capturing their own conversions, their setup flow ends directly with the A/B formula builder and has no metadata card.
### What's metadata?
Metadata are additional properties attached to a goal conversion. They let you filter or break down your results by specific values (for example, payment method, delivery type).
For example, if you want to track how many "Purchase" conversions happened with each payment type, you can use metadata to capture that value.
### Using metadata
To use metadata:
1. Define a custom data. For more information, see [Create custom data](../custom-data/create-custom-data).
2. Link the custom data as metadata when creating or editing a goal by selecting it from the dropdown.
Kameleoon won't consider custom data marked **Use this data only locally for targeting purposes**, because it doesn't send that data to its servers.
## Advanced settings
Step 2 of the **Define your goal** page, **Advanced settings**, becomes available once Step 1 shows a green checkmark. It has three sections, **Properties** (which includes outlier handling for Custom goals), **Usage**, and **Data sharing**.
### Handle outliers
*This option is only available for Custom goals.*
[More about Winsorization at Kameleoon](../../experiment-analytics/statistical-methods/winsorization)
### Usage
Three toggles control who can use the goal, all off by default:
* **Make this goal only available for specific experiments**: By default, this goal is available for all experiments. Enable this toggle to select which ones can use it.
* **Make this goal only available for specific personalizations**: By default, this goal is available for all personalizations. Enable this toggle to limit which ones can use it.
* **AI Predictive Targeting**: Trains a model on this goal at the key moments you define, to target visitors by their likelihood to convert. Enabling this toggle reveals an **Add prediction trigger** button. Click it, then select the triggers you want to enable. [More about triggers](../triggers/create-a-trigger)
### Data sharing
Select which integrations should receive data when this goal converts. A live "N integrations selected" counter tracks your selections, and a "Can't find it? Browse integrations" link opens the integrations catalog if none of the listed options match.
**Google Analytics 4**
After you set up the integration in Kameleoon, Kameleoon automatically sends goal conversions to GA4. GA4 doesn't need additional configuration to receive them.
Each goal conversion appears in GA4 as an event with the same name as your Kameleoon goal. For example, if you name your goal `Purchase complete`, it appears in GA4 as a `Purchase complete` event. Each event includes the following parameters:
* `type`: the goal type (for example, `CLICK` or `CUSTOM`)
* `id`: the Kameleoon goal ID
* `source`: always `Kameleoon`
* `revenue`: only included when you pass a revenue value with the conversion
You don't need to manually create these as Custom Events in GA4 for Kameleoon to send them. However, if you want to mark them as GA4 conversions or create audiences from them, you must configure those manually in GA4 after the data starts arriving.
**Google Tag Manager:** if your site uses GTM, Kameleoon pushes goal events into the `dataLayer` rather than sending them directly to GA4. You must configure a GTM tag and trigger to forward those events to GA4. The `dataLayer` is also a useful place to verify that goal events are firing correctly before checking GA4 reports. For setup instructions, see [Google Tag Manager](../../integrations/as-a-destination/analytics/google-analytics-4/google-tag-manager).
The code below defines the available goal types:
```typescript theme={null}
const enum GoalType {
CLICK = "CLICK",
CUSTOM = "CUSTOM",
SCROLL = "SCROLL",
PAGE_VIEWS = "PAGE_VIEWS",
URL = "URL",
TIME_SPENT = "TIME_SPENT",
RETENTION_RATE = "RETENTION_RATE",
}
```
When you finish configuring Step 1 and Step 2, save the goal to add it to your account.
## The goal summary page
Saving a goal takes you to its Summary page, where you can review the configuration you just set and continue managing the goal without returning to the Goals dashboard.
The page header shows the goal's name, status (for example, **Active**), and **Goal ID**. Below the header, two tabs organize the page:
* **Insights**: the goal's performance data, including key metrics, a daily events timeline, and impacted campaigns. For details, see [Goal reporting](goal-reporting).
* **Summary**: the goal's configuration, selected by default right after you create the goal.
The Summary tab groups the goal's configuration into cards:
* **Definition**: the triggering condition you set in Step 1, plus any metadata attached to conversions. Click **Edit** to change these settings.
* **Usage**: the toggles you set in Step 2 that control who can use the goal, plus a **Set this goal as your project primary goal** toggle that defines this goal as your project's main success metric. Only one goal can be primary per project. Click **Edit** to change these settings.
* **Data sharing**: the integrations you selected in Step 2 to receive data when the goal converts, or **No data sharing tools** if you didn't select any. Click **Edit** to change this setting.
A sidebar next to the Definition and Usage cards lists the goal's **Project**, what it's **Linked to** (for example, an experiment, or **Not set** if it isn't linked to any campaign), its **Last modification** and **Created** dates, and its **Creator**.
# Create a goal conversion from GTM
Source: https://docs.kameleoon.com/user-manual/assets/goals/create-a-goal-conversion-tag-from-gtm
Create Kameleoon goal conversion tags in Google Tag Manager to track events, revenue, and metadata without modifying your site's code directly.
If you manage your site's tracking through Google Tag Manager, you can fire Kameleoon goal conversions directly from GTM tags, without modifying your site's code. This is useful when your development workflow runs through GTM, or when you want to keep all conversion tracking centralized in one place. This article covers how to create a basic conversion tag, a tag that records revenue, and a tag that passes metadata alongside the conversion.
## Create a tag
1. Click **New**.
2. Name your tag (for example, "Kameleoon - add to cart", "Kameleoon - transaction").
3. Select **Custom HTML** in **Tag Configuration**, and insert this code:
```javascript theme={null}
;
```
* You must replace `123456` with the Kameleoon goal ID.
4. Select an existing trigger or create a new one (depending on the `dataLayer` format).
## Create a tag with revenue
To create a tag with revenue:
1. Click **New**.
2. Name your tag.
3. Select **Custom HTML** in **Tag Configuration**, and insert this code:
```javascript theme={null}
```
`123456` is the Kameleoon goal ID, and `{{TransactionRevenue}}` is a variable with revenue attached to the conversion.
4. Select an existing trigger or create a new one (depending on the `dataLayer` format).
## Create a tag with metadata
The example below adds a payment method and order ID as metadata to the goal conversion. To create a tag with metadata:
1. Click **New**.
2. Name your tag.
3. Select **Custom HTML** in **Tag Configuration**, and insert this code:
```javascript theme={null}
```
* **`123456`** is the Kameleoon goal ID.
* **`{{ TransactionRevenue }}`** is a variable with revenue attached to the conversion.
* **`{{ paymentMethod}}`** is a variable with the payment method attached to the conversion, and **`0`** is the index of the custom data where the variable will be added.
* **`{{ orderID }}`** is a variable with the order ID attached to the conversion, and **`1`** is the index of the custom data where the variable will be added.
4. Select an existing trigger or create a new one (depending on the `dataLayer` format).
# Goal reporting
Source: https://docs.kameleoon.com/user-manual/assets/goals/goal-reporting
Review a goal's health, recent activity, and the experiments impacting it from a single, consolidated Goal Reporting page.
The Goal Reporting page gives you a single, consolidated view of a goal. Instead of piecing together information from the Goals dashboard tooltip, Live Events, and individual Results pages, you can confirm that a goal is collecting data and behaving normally, review its recent activity, and see how your experiments have impacted it over time.
## Access Goal Reporting
In the Goals dashboard, click a goal's name to open its Goal Reporting page.
## Page header
The header identifies the goal and sets the time range for the rest of the page:
* **Goal name** and its current status (for example, **Active**).
* A **health badge** (for example, **Needs attention**) that flags when the goal's recent activity warrants review, such as when anomalies are detected.
* **Goal ID**, with a copy button.
* A **time range selector** with preset ranges: **7D**, **14D**, **30D**, **3M**, and **6M**. The selected range applies to the KPI cards and the Daily events timeline. It does not affect the Impacted campaigns table (see below).
## Secondary actions
Click the **⋮** button at the top of the page to access the following options:
* **Copy link**: copies a direct link to the Goal Reporting page.
* **Refresh**: reloads the page data.
* **Edit settings**: opens the goal's settings so you can update its configuration.
## Key metrics
Three KPI cards summarize the goal's performance over the selected time range. Each card shows the metric value and a badge with the change against the previous equivalent period, in green for an increase or red for a decrease.
* **Events**: the total number of times the goal was triggered.
* **Conversion rate**: the percentage of visitors who triggered the goal over the period.
* **Revenue**: the total revenue generated from goal conversions. Shows `0 €` when no revenue is tracked for the goal.
## Daily events timeline
The timeline charts the goal's daily events across the selected time range, so you can spot trends, seasonality, and gaps in collection at a glance.
* **Expected range (± 2σ)**: the shaded band shows the statistically expected range for daily activity. Values inside the band are considered normal.
* **Anomaly detection**: days that fall outside the expected range are highlighted on the chart, and an **anomalies detected** indicator shows how many were found (for example, *2 anomalies detected*).
* Use the controls in the top right of the card to zoom in and out and to refresh the chart, and the chevron next to the section title to collapse or expand it.
## Impacted campaigns
The Impacted campaigns table consolidates experiment-level results into one view, so you can see how your experimentation program has affected the goal without opening each Results page individually. The table groups experiments by the direction of their impact, under **Positive impact experiments** and **Negative impact experiments** headings, with the highest-impact experiments listed first within each group.
The table shows the following columns:
* **Experiment**: the name of the experiment.
* **Variation**: the variation measured against the goal.
* **Status**: the experiment's current status.
* **Improvement rate**: the variation's measured effect on the goal.
* **Reliability**: the statistical reliability of the result.
* **Confidence interval**: the confidence interval around the improvement rate.
The statistical method behind the Reliability and Confidence interval columns depends on the experiment's status: **Online** experiments use sequential testing, and **Paused** or **Stopped** experiments use the classical frequentist method.
Each row also includes quick actions to open the experiment and view its results.
### Which experiments appear
An experiment appears in the Impacted campaigns table only when it meets the following criteria:
* It is a web experiment that uses the goal and is currently **Online**, **Paused**, or **Stopped**. The table excludes draft and planned experiments, personalizations, and feature flags.
* It has a measurable effect on the goal. The table excludes experiments with a 0% improvement rate.
The table shows up to 10 experiments. Because of these filters, the number of experiments listed can be lower than the "Linked to" count shown on the Goals dashboard.
### Data freshness
The Impacted campaigns table reflects pre-aggregated historical data. Kameleoon refreshes it once a day, and it is current through the previous day (for example, *Last updated: Yesterday at 02:00 UTC*). Unlike the KPI cards and timeline, the table is independent of the time range selector: it always shows the consolidated data rather than the selected period.
### Change an experiment's status
You can change an experiment's status directly from the table using the **Status** dropdown. Only the transition from **Online** to **Paused** is available; Paused and Stopped experiments show a read-only badge. Because changing the status affects the experiment everywhere in the platform (not only on this page), a confirmation dialog appears before the change takes effect.
# Manage goals
Source: https://docs.kameleoon.com/user-manual/assets/goals/manage-goals
Find, edit, duplicate, delete, and bulk-manage goals from the Kameleoon Goals dashboard using filters, sort options, and grouped actions.
As your experimentation program grows, goals accumulate across experiments and sites. Without a central place to manage them, updating or finding a goal requires opening each experiment individually. The Goals page centralizes that work in one dashboard, from quick edits to bulk cleanup.
## Access the Goals page
Click **Settings** > **Goals** to open the Goals page.
## Manage your goals
Each goal appears as a row on the Goals page.
Kameleoon includes the **Retention rate** goal by default for all sites associated with your account. It records the number of visitors who click at least once after landing on the first page of their visit.
### Find a goal
Use the **search bar**, **filter tool**, and **sorting tool** to locate a specific goal.
#### Filter goals
To filter goals, select one or more criteria, then click **Apply**:
* **Project**: show goals associated with specific websites.
* **Type**: show goals of a specific type (for example, custom goals only).
* **Status**: show goals by status, either Active or Inactive.
* **Tag**: show goals with specific tags.
* **Key date**: show goals by last modification or creation date.
* **Creator**: show goals created by specific users.
* **Tracking AI**: show goals that use tracking AI.
#### Sort goals
To sort goals, hover over a column header and click the chevron to toggle ascending or descending order. You can sort by:
* **Name**: alphabetical order.
* **Linked to**: campaign type.
* **Edited**: edition date.
* **ID**: goal ID.
* **Created**: creation date.
* **Website**: associated website, alphabetically.
### Edit a goal
Clicking into an existing goal, whether from its row's name or its **Edit** action, opens the same **Define your goal** page used to create it, pre-filled with the goal's current configuration. The page uses the same two-step stepper described in [Create a goal](../../assets/goals/create-a-goal), with **Step 1, Define triggering conditions** and **Step 2, Advanced settings**.
To edit an existing goal:
1. Find the goal's row and click its name, or click **Edit**, to open the **Define your goal** page.
2. Update Step 1 or Step 2 as needed, then save your changes.
Editing a goal used by a running, paused, or planned experiment changes how Kameleoon measures your conversions, making results analysis more complex. Stop and duplicate the experiment before editing any of its goals.
### Duplicate a goal
To duplicate a goal:
1. Find the goal's row and click the **three-dots menu** on the right.
2. Click **Duplicate**. The Duplicate sidebar opens.
3. Click **Continue** to confirm the duplication.
### Delete a goal
Deleting a goal is permanent and can't be undone. If the goal is still linked to an experiment, feature flag, or personalization, remove it from that campaign first. Deleting a goal that's still in use breaks the campaign's tracking and can invalidate its historical results.
To delete a goal:
1. Find the goal's row and click the **three-dots menu** on the right.
2. Click **Delete**.
### Select multiple goals
You can select multiple goals and apply a bulk action to all of them at once.
To enter multi-select mode:
1. Click the **three-dots menu** on any goal's row.
2. Click **Select**. The goals become selectable and the **Grouped actions** sidebar opens.
To select or deselect all goals on the page, click **Options**, then **Select all** or **Deselect all**.
The following bulk actions are available in the **Grouped actions** sidebar:
* **Activate**: activate all selected goals.
* **Disable**: turn off all selected goals.
* **Manage tags**: apply or remove tags across selected goals.
* **Export**: export selected goals as **PDF** or **Excel**. Set export options if needed, then click **Export Dashboard**.
# Retention, bounce, and exit rates
Source: https://docs.kameleoon.com/user-manual/assets/goals/retention-bounce-and-exit-rates
Understand how Kameleoon measures retention and bounce rates and how these metrics compare to engagement and bounce rates in Google Analytics 4.
If you use Kameleoon alongside Google Analytics 4, you may notice that their retention and bounce rate numbers don't match. This happens because the two platforms define these metrics differently: Kameleoon measures whether a visitor clicked on their landing page, while GA4 measures session engagement across a broader set of criteria.
Understanding this difference is important before you interpret experiment results or compare data across tools. This article explains how each platform calculates retention and bounce rates, what those numbers mean in practice, and how to track bounce rate in Kameleoon. It also covers the exit rate, which exists in GA4 but has no equivalent in Kameleoon.
## Retention rate
In Kameleoon, the retention rate measures **how many visitors and visits make a click on the first page they land on**. It is the **opposite of the bounce rate**. Kameleoon provides this as a pre-created goal, so you only need to attach it to an experiment to start tracking conversions.
Use this goal only for experiments running on landing pages. Otherwise, the goal may trigger before the visitor is targeted, which prevents the test from recording the conversion. Tests only record post-targeting conversions.
**Kameleoon example:**
The page's retention rate above is higher for the variations compared to the original version. In the screenshot above, approximately 55% of visits included at least one click on their landing page, which is also the targeted page (the click occurred after the targeting).
GA4 defines the engagement rate as the **percentage of sessions that lasted more than 10 seconds, had conversion events, or included more than one page view**. It measures engagement **at the session level**, meaning that if a user interacts with a second page or triggers an event, GA4 considers the session engaged. The engagement rate is useful for analytics, providing insights into engagement across any page of the entire site.
**GA4 example:**
The site's engagement rate above is the percentage of engaged sessions compared to the total sessions. In the above screenshot, email led to 1,356 engaged sessions out of 1,630 total, equating to an engagement rate of 83.19%.
See the [GA4 documentation](https://support.google.com/analytics/answer/12195621?hl=en) for more information on how to improve the retention rate.
## Bounce rate
The bounce rate measures **how many visitors and visits leave the site without making any click on the page**. This metric is the **opposite of the retention rate**.
You can add the code below to the **Kameleoon Global Script** to track conversions when visitors bounce (when they leave the page without clicking). This script runs on **all pages**, meaning the script records a bounce on the **last page the visitor viewed**. To track the **bounce rate for a specific page**, simply wrap the code in an `if` statement that checks the page URL.
```javascript theme={null}
// set the right GOAL_ID below
if(document.location.href.includes('cart')) {
Kameleoon.API.Goals.processConversion(GOAL_ID)
const handleBounceConversion = () => {
Kameleoon.API.Goals.cancelConversion(GOAL_ID)
document.removeEventListener('click', handleBounceConversion)
}
Kameleoon.API.Utils.addEventListener(document, 'click', handleBounceConversion)
}
```
**Kameleoon example:**
The page's bounce rate above is lower for the variations compared to the original version (which is set as the winning variation since it has a higher conversion rate). In the screenshot, about 45% of visits did not make any clicks on their landing page. Note that, in this example, the code only tracks the bounce goal on the landing page.
GA4 defines the bounce rate as the **percentage of sessions that lasted less than 10 seconds, had no conversion events, or included only one page view**. It measures bounce **at the session level**, meaning that if a user interacts with a second page or triggers an event, GA4 does not consider the session a bounce. The bounce rate is useful for analytics, providing insights into engagement across any page of the entire site.
**GA4 example:**
GA4 doesn't have a standard bounce rate report. You'll need to customize individual reports in order to see it.
Bounce rate is the percentage of sessions that aren't engaged. In the case above, that would be 16.81% (because you can subtract the 83.19% of engaged sessions from 100%).
See the [GA4 documentation](https://support.google.com/analytics/answer/12195621?hl=en) for more information on how to improve the bounce rate.
## Exit rate
In GA4, for a given page, the exit rate is the ratio of sessions where that page was the last page viewed to the total number of sessions that included that page.
**GA4 example:**
* Session 1: page A → page B → page C
* Session 2: page A
* Session 3: page A → page C
* Session 4: page B → page C → page A → page B
The exit rate for page C is **66%**, as it was the last page viewed in 2 sessions (sessions 1 and 3) out of 3 sessions that included that page (sessions 1, 3, and 4).
See more info in [GA4 documentation](https://support.google.com/analytics/answer/11080047?hl=en).
Kameleoon cannot record the exit rate, because its data structure is based on visits and visitors rather than page views.
# Revenue goal
Source: https://docs.kameleoon.com/user-manual/assets/goals/revenue-goal
Set up accurate revenue goal tracking in Kameleoon using tag managers, global scripts, or SDKs, with guidance on currency, format, and deduplication.
Setting up a revenue goal in Kameleoon is straightforward, but it requires careful configuration to ensure everything works correctly. Every website has its own structure, purchase flow, tracking setup, and edge cases, so there's no one-size-fits-all solution. Without proper configuration, you risk missing key data points, double-counting transactions, or misinterpreting performance.
The recommendations below cover the most common challenges Kameleoon users encounter and offer flexible solutions you can adapt to your setup.
## Implementation method
Kameleoon supports multiple integration methods to track revenue goals effectively, depending on your experimentation type and technical setup. The sections below cover the recommended approaches for both Web Experimentation (WE) and Feature Experimentation (FE), including support for offline conversions via the Kameleoon Data API.
### Web Experimentation
* **Using a tag manager:** Implement the [`kameleoonQueue`](../../../developer-docs/apis/activation-api-js/api-reference/command-queue#syntax), which ensures that conversion events trigger in sync with your analytics platform, maintaining data consistency across tools and improving your site's performance. For a detailed implementation guide in Google Tag Manager, refer to [this comprehensive guide](../../integrations/as-a-destination/analytics/google-analytics-4/google-tag-manager) and the configuration steps below to set up the revenue goal.
* **[Using the global custom script:](../../project-management/manage-your-projects#global-script)** If `kameleoonQueue` isn't compatible with your setup, you can manually implement the revenue goal using the Activation API within the global custom script in the Kameleoon app.
### Feature Experimentation
If you're using one of [Kameleoon's SDKs](../../../developer-docs/feature-experimentation/get-started/overview), you can track revenue goals using the [`trackConversion()`](../../../developer-docs/sdks/web-sdks/nodejs-sdk#trackconversion) method. Refer to the steps below to properly configure the revenue goal based on your SDK environment.
### Data API
*(Applicable for both WE and FE)*
For offline conversions, such as purchases completed over the phone or in-store, you can use the [Kameleoon Data API](../../../developer-docs/apis/data-api-rest/tutorials/processing-offline-goal-conversions-in-experiments#sending-offline-goal-conversion) to process offline goal conversions. This method is best when the conversion event occurs outside the user's online journey but still must be tracked and attributed within your Kameleoon experiments.
## Configuration
### Scope
Before setting up your revenue goal, check whether the transaction confirmation always occurs on a single, consistent page. In some setups—especially those involving mobile apps, embedded checkouts, or third-party payment providers—the confirmation might appear in a web view or on a separate domain. Install Kameleoon on **all** relevant pages or views where confirmation may appear. This ensures Kameleoon reliably tracks conversions and captures all revenue data. If a user can complete a transaction across multiple URLs (due to variations in query parameters or different payment flows, for example), add **all relevant URLs** in Kameleoon's settings so that no conversions are missed.
### Transaction goal (access the confirmation page)
Set a goal for accessing the confirmation page without a revenue amount. This goal helps you identify missing conversions for the revenue goal—delays in loading the revenue amount on the page (in the DOM, `dataLayer`, or a similar object) are a common cause of missed conversions. To set up a transaction goal in WE, choose between two goal types:
* **Access to a page:** Set the URL in the goal's configuration. Depending on the URL's structure, use either **URL contains** or **Matches the regular expression** to account for variations in the URL (different paths or query parameters, for example). Avoid **Corresponds exactly to**, as the URL will likely include parameters that vary.
When using the **Access to a page** goal type, if visitors can reload the confirmation page without being redirected (to the homepage, for example), the goal may trigger again. In this case, use the **converted visits** metric rather than **all conversions** on the Results page to avoid overcounting.
* **Custom goal:** This goal type prevents the goal from converting again if the confirmation page reloads. Implement a custom goal in the global custom script and use a `sessionStorage` check to prevent duplicate conversions (see the example code below). This approach is recommended because you can reuse the same code to trigger the revenue goal, which improves performance by eliminating the need for a native **Access to a page** goal.
```javascript theme={null}
if (
document.location.href.includes("/confirmation/") &&
!window.sessionStorage.getItem("kameleoonGoalConverted")
) {
// Set an item in sessionStorage to prevent a second conversion if the page is reloaded
window.sessionStorage.setItem("kameleoonGoalConverted", "true");
// Convert the transaction goal, replace the ID below
Kameleoon.API.Goals.processConversion(355733);
} else if (!document.location.href.includes("confirmation")) {
// Remove the item from sessionStorage to allow conversion for a new transaction
window.sessionStorage.removeItem("kameleoonGoalConverted");
}
```
### Revenue format
Ensure the revenue amount is properly formatted and validated before processing:
* Replace commas (`,`) with periods (`.`) for decimal consistency.
* Remove any spaces (can be present in amounts over 1,000).
* Strip out currency symbols (such as `$`).
* Convert the cleaned string into a numeric data type for accurate calculations.
For example:
```javascript theme={null}
let revenue = parseFloat(revenue.replace(",", ".").replace(/[^0-9.]/g, "").replace(/\s+/g, ""));
```
### Currencies
A website may support multiple currencies. Compare conversion values expressed in the same currency to avoid misleading results or incorrect analyses. Verify that the currency used in your tracking and reporting is consistent across all conversions.
You can trigger a goal for each currency and/or use Kameleoon's conversion web service. The endpoint is provided below—ensure all arguments passed are valid.
```
;
```
Never convert the same goal using amounts in different currencies. You must either create a separate goal for each currency, or unify them by setting up a global goal using the web service endpoint above. This service converts all amounts into a single currency of your choice.
See the complete code example at the end of this article for a detailed implementation of the currency conversion web service.
### Order ID
Add a [custom data](../custom-data/create-custom-data) to store the order ID and use it as [metadata](./create-a-goal#metadata) for the revenue goal. This links each conversion to the order ID, making it easier to match transactions with your analytics tool and investigate data discrepancies.
Configure the custom data using the screenshot below as a reference. Adjust the format depending on whether the order ID on your site is a number or a string.
To associate the **OrderID** custom data with your revenue goal:
1. In the goal creation flow, enter your goal's information and select **Custom goal** as the goal type.
2. Click **Next** > **Advanced settings**.
3. Toggle **Collect metadata, associating goals to custom data**.
4. Select **OrderID** from the dropdown.
See the complete code sample below for how to set the custom data value.
## Complete example
*This example is for WE and can be used as a reference for implementation in FE.*
Now that you've reviewed each key element—scope, transaction logic, revenue format, currency handling, and order ID tracking—you're ready to bring everything together.
Below is a complete example of how to implement the revenue goal using the global custom script in Kameleoon.
```javascript theme={null}
// Amount conversion using Kameleoon's currency conversion web service
const convertCurrency = async (revenue, inputCurr, outputCurr) => {
if (revenue == 0) return 0;
const response = await fetch(
`https://customers.kameleoon.com/kameleoon/currencies/convert?inputCurr=${inputCurr}&outputCurr=${outputCurr}&amount=${revenue}`,
{
method: 'GET',
headers: {
'Content-Type': 'text/plain',
},
}
);
return response.json();
};
// Logic to:
// - Convert the transaction goal
// - Convert a goal for each currency
// - Convert the global revenue goal
// - Set the orderID custom data
// repalce all goal IDs in the code
if (document.location.href.includes("/confirmation/") && !window.sessionStorage.getItem("kameleoonGoalConverted")) {
Kameleoon.API.Goals.processConversion(355733); // Transaction goal
sessionStorage.setItem("kameleoonGoalConverted", "true");
let revenueLayer;
Kameleoon.API.Core.runWhenConditionTrue(() => {
revenueLayer = window.dataLayer?.find(layer => layer.ecommerce?.purchase?.actionField?.revenue);
return revenueLayer;
}, () => {
let revenue = parseFloat(revenueLayer.ecommerce.purchase.actionField.revenue);
const inputCurr = revenueLayer.ecommerce.purchase.actionField.inputCurrency;
const orderID = revenueLayer.ecommerce.purchase.actionField.orderID;
if (!isNaN(revenue)) {
revenue = revenue.toString().replace(",", ".").replace(/[^0-9.]/g, "").replace(/\s+/g, "");
// Currency-specific revenue goals
switch (inputCurr) {
case 'GBP':
Kameleoon.API.Goals.processConversion(355641, revenue);
break;
case 'USD':
Kameleoon.API.Goals.processConversion(355643, revenue);
break;
case 'EUR':
Kameleoon.API.Goals.processConversion(355642, revenue);
break;
default:
Kameleoon.API.Goals.processConversion(355649); // Other currencies (no revenue passed)
}
// Global revenue goal in output currency (you can use ISO 4217 codes for each country)
const outputCurr = "USD";
convertCurrency(revenue, inputCurr, outputCurr).then((convertedRevenue) => {
// The custom data must be set before the goal is converted
Kameleoon.API.Data.setCustomData("orderID", orderID);
Kameleoon.API.Goals.processConversion(353518, convertedRevenue);
}).catch((error) => {
// Create a Custom Data to store potential errors for debugging
Kameleoon.API.Data.setCustomData("[KAM] - currency webservice error", `error: ${error.toString()}; revenue: ${revenue}; inputCurr ${inputCurr}; outputCurr ${outputCurr}`);
console.error("Error in currency conversion:", error);
});
}
});
} else if (!document.location.href.includes("/confirmation/")) {
sessionStorage.removeItem("kameleoonGoalConverted");
}
```
Below is a screenshot of the `dataLayer` structure on the confirmation page for reference.
Setting up a reliable revenue goal in Kameleoon requires careful alignment with your site's structure, `dataLayer` setup, and currency formats. By following the guidelines above, whether through a tag manager or global custom script, you can ensure accurate tracking, reduce discrepancies with your analytics tools, and gain more meaningful insights from your experiments. Test thoroughly and validate your implementation to maintain data integrity.
# Set up a goal campaign
Source: https://docs.kameleoon.com/user-manual/assets/goals/set-up-a-goal-campaign
Apply a goal to an experiment or personalization to start tracking conversions and measuring campaign performance.
Creating a goal makes it available in Kameleoon, but goals don't track conversions on their own. You must link each goal to the specific experiments or personalizations where you want to measure performance. Until you do, those campaigns have no way to record whether a visitor converted.
## Create a new goal
[Read this article to learn how to create a new goal](./create-a-goal).
## Set up a goal in an experiment
To apply a goal to an experiment:
1. Go to the **Goals** section on the editor's finalization page. The list of existing goals appears.
2. Select the goal you created.
3. Click **Next**.
## Set up a goal in a personalization
To add a goal to a personalization:
1. [Open your desired personalization or create a new one](../../web-personalization/set-up-and-launch-a-personalization).
2. Open the **Goals** section in the finalization flow. The list of existing goals appears.
3. Select an existing goal.
# Edit an image
Source: https://docs.kameleoon.com/user-manual/assets/images/edit-an-image
Resize, crop, draw, add shapes, and apply filters to images directly in the Kameleoon Media library Image editor.
The Kameleoon Media library is the repository where all visual assets you upload to Kameleoon live. It includes a robust Image editor that lets you modify images directly within the platform. This article helps you access and use the editor.
## Access the Image editor
* **During upload:** After uploading a new image, the editor opens automatically, letting you make adjustments before saving the image to your library.
* **From the Media library:** To edit an existing image in the library, hover over an image and click the three-dots menu. Select **Edit Image** from the dropdown menu. The Image editor opens.
## Structure of the Image editor
* **The top toolbar** includes options to:
* Resize
* Crop
* Flip
* **The left toolbar** provides more in-depth editing tools, such as:
* Frame
* Draw
* Shapes
* Filters
* **In the top right** of the Image editor, you can expand the pop-up, undo your changes, reapply them, or swap the current image for another without leaving the editor.
## Edit image content
Use the left toolbar to make changes to your image. You can resize, crop, add shapes, or apply filters.
### Frame
The Frame tool lets you resize, crop, or flip your image.
#### Resize
To resize your image, click **Resize**. Enter the desired dimensions or use the slider to adjust the image's size.
#### Crop
Select **Crop** if you need to trim your image's edges. You can choose a preset dimension or freely select the crop area.
#### Flip
Use the **Flip** tool to flip your image horizontally or vertically.
### Draw
Use **Draw** to draw on your images. Select the brush size and color to personalize your drawing.
### Shapes
Insert shapes using the **Shapes** tool. You can adjust the size, color, and position of the shapes as needed.
### Filters
Apply filters to your image using **Filters**. You can also adjust your image's brightness, noise, or threshold by clicking **Adjustments**.
## Edit image details
You can edit metadata such as the image name, tags, or description by clicking **Edit Image Details** at the bottom of the editor.
## Save or discard changes
* **Save image**: Click **Save image** to save your changes and return to the Media library.
* **Discard changes**: Close the editor without saving to discard your changes.
# Manage your images
Source: https://docs.kameleoon.com/user-manual/assets/images/manage-your-images
Search, filter, sort, and perform actions on images in the Kameleoon Media library, including editing, tagging, duplicating, and deleting.
The Kameleoon Media library is the repository where all visual assets you upload to Kameleoon live. It offers a variety of tools to help you manage your images. This article covers using the search and filter options, accessing image-specific actions, and customizing your library view.
## Searching and filtering images
* **Search bar:** Located at the top of the Media library, the search bar lets you find images by entering a keyword or file name.
* **Filters:** On the Media library's right side, you can filter images by file type (for example, JPEG, PNG, GIF, WEBP, SVG). Select a file type, then click **Apply** to update the displayed images.
## Image display options
The Media library provides two display options:
* **Grid view (default view):** Displays images in a thumbnail format.
* **List view:** Displays images in a list format with additional details, such as modification date, creator, and tags.
Switch between views by clicking their icons in the upper-right corner.
## Sorting images
Click the **Sort** icon to change the images' display order. You can sort images by:
* **Modification date** (newest or oldest first)
* **Upload date** (newest or oldest first)
* **Alphabetical order** (A to Z or Z to A)
## Managing individual images
Click an image's **three-dots** menu to access available secondary actions:
* **Edit image:** Opens the selected image in the Image editor.
* **See image details:** Displays the image’s metadata, including size, format, dimensions, creator, creation date, and modification date. You can also copy the image link or edit the image's name, alt text, and description.
* **Manage tags:** Tags help organize images, making them easier to find when searching. Click **Add a tag** in the **Image details** panel to assign tags to the image.
* **Download image:** Allows you to download a copy of the image to your device.
* **Duplicate image:** Creates a copy of the image within the library.
* **Select multiple images:** Enables grouped actions by selecting multiple images.
* **Delete:** Permanently removes the image from the library.
# Upload an image
Source: https://docs.kameleoon.com/user-manual/assets/images/upload-an-image
Access the Kameleoon Media library and upload images from your computer or via URL to use in your campaigns.
The Kameleoon Media library is the repository where all visual assets you upload to Kameleoon live, letting you manage images used in your campaigns. This article helps you access the Media library, understand its structure, and upload new images.
## Accessing the Media library
To access the Media library, click **Studio** > **Media library**.
## Media library structure
In the Media library, you'll find:
* **Search bar:** At the top of the page, you can search for images by name.
* **Filter options:** Filters on the right let you refine images by file type.
* **Image display:** The Media library displays images in a grid view by default. You can toggle between grid and list view for easier navigation.
* **Add an image button:** Upload new images using this button.
* **Image details and options:** Hover over any image to access details and options.
## Uploading a new image
Follow these steps to upload a new image to the Media library:
1. Click **Add an image**.
2. Choose a project to associate the image with in the dropdown > click **Continue**.
3. Choose an upload method:
* **Upload from computer:** Select an image file from your computer.
* **Upload via URL:** Provide the URL of the image you want to use.
The Media library accepts the following file formats: PNG, JPG, GIF, SVG, and WebP, with a maximum file size of 3 MB.
4. After you select an image, the **Image editor** opens, letting you edit your image (for example, resizing, cropping, or adding shapes).
5. Click **Save Image** to add it to the Media library.
Kameleoon automatically removes images from your library after 12 months if they're not associated with an active campaign or widget.
# Create a segment
Source: https://docs.kameleoon.com/user-manual/assets/segments/create-a-segment
Learn how to use the Kameleoon Segment Builder to define and target visitor groups based on their characteristics and behavior.
*For a video tutorial on targeting segments, visit [the Kameleoon Academy](https://academy.kameleoon.com/how-to-plan-your-first-experiment/162036?utm_source=user_manual\&utm_medium=online).*
Use segments to target your visitors. You can create, modify, and duplicate segments with the Kameleoon Segment Builder.
## Access the Segment Builder
### From the app
To access the Segment Builder in the Kameleoon app, click **Settings** > **Segments**.
Click **New segment**. Kameleoon opens the segment creation pop-in.
### From the A/B finalization flow
You can create a new segment directly from the A/B test finalization flow, which opens the segment creation pop-in.
## Create a new segment
### Types of segmentation
Kameleoon manages two types of segmentation:
* ***A posteriori* segmentation** occurs after the test. *A posteriori* segmentation only shows if a variation's performance has increased in a given segment. Kameleoon doesn't manage this type of segmentation. Your web analytics solution (for example, Google Analytics, KISSmetrics, or AT Internet) usually handles it.
* ***A priori* segmentation** targets a specific fragment of your traffic because the test only applies to this segment. For instance, if you have a website with international users, you might want to run an experiment for only users in France. Similarly, you could test an offer that only displays to a specific segment (for example, first-time visitors). Kameleoon manages this type of segmentation.
### Enter segment information
Fill in:
* Your segment's name.
* The site for which you are creating this segment.
* The type of campaign for which you are creating this segment:
* **Web experiment/Personalization**
* **Feature flag/SDK experiment**
* **All experiment types**
The available conditions in the next step depend on the campaign type you choose.
You can also add a description, tags, or choose to use the segment in [Audiences](../../ai-opportunity-detection/audiences-segment-analysis).
You can update your segment information in the final step of the creation process within the recap panel.
### Select and set a condition
To add a condition, drag and drop a condition from the left-hand list to the field on the right.
The pop-in shows the condition's settings after you drag and drop it. Configure the condition as needed.
### Delete a condition
Click the **X** icon to delete a condition.
### Narrow or add a new condition
To add a new condition when you've already selected a condition, two options are available:
* **Narrow an existing condition:** Further specifies a condition, similar to using mathematical parentheses: (Condition A and Condition B) and Condition C.
* **Add a new condition:** Adds a condition at the same level: Condition A and Condition B and Condition C.
For more information, refer to the [FAQ](../../faq).
#### Quickly add conditions
You can quickly add multiple conditions of the same type by clicking the small **+** icon on the right side of the condition. This feature is available for conditions frequently used in large numbers.
When you add multiple identical conditions, Kameleoon links them with an **OR** operator. The dropdown menu updates to **is including any of** or **is not including any of**.
Once you add multiple identical conditions, you can delete them individually.
### Use logical links between conditions
Create effective targeting segments by combining various conditions to define your audience. The use of the logical operators AND/OR is crucial in this process. Additionally, understanding the distinction between “include” and “exclude” conditions is essential for accurate segment configuration.
#### Logical operators: AND vs. OR
**AND operator:** use the AND operator (select **If all** from the dropdown) when you want the visitor to meet all specified conditions to include them in your segment. This operator narrows your target audience to those who meet all defined criteria.
* **Example:** If you set an AND condition for "New Visitors" AND "On Mobile," Kameleoon only includes visitors who are both new to your site and accessing it via a mobile device.
**OR operator:** use the OR operator (select **If any** from the dropdown) when you want the visitor to meet any one of the specified conditions to include them in your segment. This operator broadens your target audience.
* **Example:** If you set an OR condition for "New Visitors" OR "On Mobile," Kameleoon includes visitors who are either new to your site or accessing it via a mobile device.
Kameleoon prioritizes AND over OR.
### Is versus Is not conditions
**Is condition:** select an **Is** condition to include visitors who meet specific criteria in your target segment.
* **True:** Visitor possesses the characteristic (for example, desktop device type is true).
* **False:** Visitor doesn't possess the characteristic (for example, desktop device type is false).
**Is not condition:** specify an **Is not** condition to exclude visitors who meet specific criteria from your target segment.
* **True:** Visitor doesn't possess the characteristic (for example, desktop device type is false, meaning the device type is **not** desktop, so Kameleoon includes them).
* **False:** Visitor possesses the characteristic (for example, desktop device type is true, meaning the device type **is** desktop, so Kameleoon excludes them).
### Practical examples and common pitfalls
* **Including New Visitors on Smartphone:**
* **Condition 1:** New Visitor (Is)
* **Condition 2:** On Smartphone (Is)
* **Logical link:** AND
* **Outcome:** Kameleoon includes only new visitors accessing the site on mobile devices.
* **Excluding Returning Visitors on Desktop:**
* **Condition 1:** New Visitors (Is)
* **Condition 2:** On Desktop (Is not)
* **Logical link:** AND
* **Outcome:** Kameleoon excludes returning visitors on desktop.
* **Including Visitors from Specific Acquisition Channels:**
* **Condition 1:** Acquisition Channel is SEO (Is not)
* **Condition 2:** Acquisition Channel is SEA (Is)
* **Logical Link:** AND
* **Outcome:** Kameleoon includes only visitors arriving via SEA campaigns (excluding SEO).
* **Excluding Checkout Process Pages:**
* **Condition 1:** URL contains /cart (Is not)
* **Condition 2:** URL contains /login (Is not)
* **Condition 3:** URL contains /payment (Is not)
* **Logical Link:** OR
* **Outcome:** Kameleoon excludes pages related to the checkout process.
If you aren't sure if you configured everything correctly, [use the simulation panel](../../experimentation/web-experimentation/configure-and-launch/simulate-a-campaign).
## Review and save
After you click **Next**, a summary panel opens on the right. Review the settings and definition.
* **Settings:** Displays the segment name, project, campaign type, description, tags, and whether an audience uses the segment. Click the **pencil** icon to edit any of these settings, then click **Save changes**.
* **Definition:** Displays your segment's definition. You can view a visual summary under the **Block Summary** tab or a text-based summary under the **Written Summary** tab.
Click **Create segment** to finish.
### Targeting conditions
Kameleoon offers targeting conditions to include or exclude specific visitor types.
The targeting conditions offered in the Segment Builder depend on the chosen campaign type.
#### Visitor characteristics
* **Device type:** includes or excludes visitors based on their device (tablet, smartphone, computer). You can also find this feature in the personalization creation flow.
* **Browser:** includes or excludes visitors based on their web browser. You can specify the browser version or target versions that are newer or older to other versions.
* **Geolocation:** includes or excludes visitors according to geolocation data (country, state, city).
* **Kameleoon segment:** This condition lets you include or exclude visitors based on their segment. You can import an existing segment into the Segment Builder, which then associates its targeting conditions with the new segment you're creating. For example, suppose you import the Kameleoon segment Returning visitors on mobile that you created and often use as a base. You adapt it to a specific campaign by adding the **Goal converted** condition, and you create this new segment.
* **Note:** You can't modify the conditions that make up the imported segment: Kameleoon treats the segment as a whole. When you use the same segment as a base in several segments associated with active campaigns, any change affects all relevant campaigns. Therefore, be careful when modifying your core segment. You can only nest segments one level deep. You can't add a segment that already contains a Kameleoon segment inside another one. You can use the **Kameleoon Segment** condition several times to combine multiple segments.
* **Visitor IP Address:** includes or excludes visitors based on their IP address.
* **New or returning:** includes only new visitors (first visit) or those returning to your website.
* **Screen resolution:** includes or excludes visitors based on the size of their screen (in pixels).
* **Operating system:** includes or excludes visitors based on their operating system (for example, Windows MacOS).
* **Browser language:** includes or excludes visitors based on the language set in their browser.
* **Ad blocker:** includes or excludes visitors using an ad blocker.
#### Campaign exposure
* **Web experiment:** includes or excludes visitors exposed to a specific experiment who saw a specific variation or any of the variations (including the original). The condition considers the current visit or previous visits. The selected experiment can be Online, Paused, or Stopped.
* **Personalization:** includes or excludes visitors exposed to a specific personalization. The condition considers the current visit or previous visits. The selected personalization can be Online, Paused, or Stopped.
* **Feature Flag:** includes or excludes visitors exposed to a specific feature flag.
* **Exclusive Campaign:** excludes visitors already taking part in an experiment, a personalization, or both:
* If another campaign already exposed a visitor (in the current or a previous visit), that visitor won't be eligible for your current experiment.
* Other experiments that don't have the **Exclusive campaign** condition can still target a visitor, even if they're part of an exclusive campaign. In other words, the **Exclusive campaign** condition doesn't prevent participation in other experiments; it only stops visitors from entering experiments that share the same exclusivity requirement.
You can't delete a campaign or variation that a segment uses as a targeting condition.
#### Conversions
* **Converted goal:** includes or excludes visitors based on whether they converted on a certain goal during the current visit or during previous visits.
* **Likelihood to convert:** Kameleoon's machine-learning algorithms predict each visitor's purchase or engagement intention in real-time. You can use this condition to automatically trigger personalization campaigns. For more information, refer to the [AI Predictive Targeting documentation](../../ai-predictive-targeting/target-users-based-on-likelihood-to-convert).
#### Technical
* **Custom JS:** Define a custom JavaScript function that returns true or false to determine whether Kameleoon includes a visitor in an experiment. There are three available options:
* **Run the condition in loop until it returns True, False or Timeout:** The function executes immediately and continues running until it returns a decision. It runs every 75 milliseconds before DOM Ready, then every 250 milliseconds after DOM Ready. To stop the execution, return `true` to target the visitor or return `false` to exclude them. For example:
```javascript theme={null}
if (window.dataLayer && window.dataLayer.some(layer => layer.pageType === "homepage")) return true; if (window.dataLayer && window.dataLayer.some(layer => layer.pageType !== "homepage")) return false;
```
* **Wait until the page has loaded:** Kameleoon only checks the condition after DOM Ready, executing every 250 milliseconds until it returns a decision. To stop the execution, return `true` to target the visitor or return `false` to exclude them. If the function returns `undefined`, it keeps running in a loop at the defined intervals.
* **Run the condition asynchronously:** Use this option when waiting for a response from an API or external service before deciding whether to include the visitor. Instead of returning a value, call `setTargeting(true)` or `setTargeting(false)`. For example:
```javascript theme={null}
const userId = localStorage.getItem("user\_id");
if (!userId) {
setTargeting(false);
return;
}
const apiUrl = `https://api.example.com/check-segment?userId=${userId}`;
fetch(apiUrl, { method: "GET", headers: { "Content-Type": "application/json" } })
.then(response => response.json())
.then(data => {
setTargeting(data?.isInSegment === true);
})
.catch(() => {
setTargeting(false);
});
```
* **Custom data:** This set of conditions lets you include or exclude visits based on custom data. For more information, see the [advanced targeting tools](../advanced-targeting-tools/manage-advanced-targeting-tools) article. If you set values when creating your custom data, you can select them in the Segment Builder. Choose **is among the values** in the dropdown and check the values. You can also select custom data directly as a targeting condition for specific visitors in a personalization, without creating a segment. This option isn't yet available for experiments or feature flags.
* **Browser cookie:** includes or excludes visitors based on the presence of a cookie in their browser and, if possible, its value.
* **SDK Type:** includes or excludes visitors based on the SDK type used.
* **App version:** includes or excludes visitors based on the version of the app.
#### Acquisition
* **Landing page URL:** includes or excludes visitors based on the URL of their landing page.
* **Traffic type:** includes or excludes visitor based on the website they came from, such as a search engine, an email link, or another referring website.
* The **traffic type** condition depends on either the landing page URL or the referrer URL:
* **Emailing** if the landing page URL contains the pattern `utm_medium=email or utm_medium=newsletter`.
* **Search engine (advertising, SEM)** if the landing page URL is from a Google domain and has `aclk` as path, **or** has the parameter `aclk` in the query.
* **Search engine (organic, SEO)** if the referrer URL contains `google`, `bing`, `yahoo`, `yandex`, or `baidu`.
* **Direct** if the referrer URL is empty (`null`).
* **Referrer sites (affiliation)** if you have a landing page URL and a referrer URL that doesn't contain `google`, `bing`, `yahoo`, `yandex`, or `baidu`.
* **Referring website URL:** includes or excludes visitors based on the referring URL.
* **Acquisition channel:** includes or excludes visitors based on the marketing or referral source that brought them to your website.
Landing page URL and Referring website URL support the **matches the regular expression** operator for pattern-based matching. See [Regular expressions](../advanced-targeting-tools/regular-expressions) for the supported syntax.
# Manage targeting segments
Source: https://docs.kameleoon.com/user-manual/assets/segments/manage-targeting-segments
Find, filter, sort, edit, duplicate, and delete targeting segments from the Kameleoon Segments dashboard.
## Access the Segments page
To access the Segments page in Kameleoon:
* Click **Configure** > **Segments** in the left sidebar.
## Manage your segments
Each segment is represented by a card that indicates its main information.
### Find a segment
A **search bar**, a **filter tool**, and a **sorting tool** help you find a particular segment.
#### Filter segments
You can filter the displayed segments based on several criteria:
* Project
* Tag
* Campaign type
* Linked to
* Key date
* Creator
* Characteristics
* Goal
##### Website
Filter the displayed segments by their associated website.
Check the websites and click **Apply**.
##### Campaign type
*This filter is only available for Web experimentation + Feature experimentation customers.*
Filter the displayed segments by their associated campaign type.
Here are the conditions for these filter criteria:
* **Feature flag/SDK experiment:** Segments containing the Visitor code condition or the Feature experimentation conditions, not used in any experiment or personalization.
* **All experiment type:** Segments used in a Feature experiment that also contain conditions common to both Feature and Web experimentation.
* **Web experiment/Personalization:** All other segments.
##### Linked to
Filter the displayed segments by whether they're linked to a campaign.
##### Tag
Filter the displayed segments by their associated tags.
Select or search for a tag. Kameleoon displays the segments associated with those tags on the page. You can also check or uncheck all tags.
Click **Apply**.
##### Key date
Filter the displayed segments by their associated key date: last modification or creation date.
Select a date then click **Apply**.
##### Creator
Filter the displayed segments by their creator.
Check a creator then click **Apply**.
#### Characteristics
Filter the displayed segments by whether they're used in Audiences.
Check a filter then click **Apply**.
#### Sort segments
The sorting option lets you sort your segments according to several criteria:
* Name
* Linked to (Campaign)
* Edition date
* Segment ID
* Creation date
* Website
##### Name
Hover over **Name** and click the chevron to sort segments in alphabetical (or reverse alphabetical) order.
##### Linked to
Hover over **Linked to** and click the chevron to rank segments based on campaign type.
##### Edition date
Hover over **Edited** and click the chevron to sort segments from newest edition to oldest or vice versa.
##### Segment ID
Hover over **ID** and click the chevron to sort segment IDs in ascending or descending order.
##### Creation date
Hover over **Created** and click the chevron to sort segments from newest creation to oldest or vice versa.
##### Website
Hover over **Website** and click the chevron to organize segments by website, in alphabetical or reverse alphabetical order.
### Columns
Click **Columns** to edit which columns appear in the Segments table. Uncheck a box to remove the associated column from the table. Select your sorting criteria under **Sort by**. Click **Apply** to apply your changes.
Click **Save as view** to save your selection as a view. You can then select the view from the **Views** menu.
### Edit a segment
To edit an existing segment:
1. Navigate to a segment's card.
2. Click **Edit**. A pop-up opens.
3. Make your changes in the **Segment Builder**.
4. Click **Edit** to save your changes once they're complete.
### Duplicate a segment
To duplicate a segment:
1. Click the **three-dots menu** on the right side of a segment's card.
2. Click **Duplicate**. The **Duplicate** sidebar opens.
3. Click **Save** to validate the segment's duplication.
### Delete a segment
To delete a segment:
1. Click the **three-dots menu** on the right side of a segment's card.
2. Click **Delete**.
### Multiple selection
You can select multiple segments at the same time and apply a common action to them. For example, you can delete several segments simultaneously.
To select multiple segments:
1. Click the **three-dots menu** on the right side of a segment's card.
2. Click **Select**. The segments become selectable and the **Grouped actions** sidebar opens.
Several actions are possible:
#### Select all/deselect all
To select all segments, check the box next to **Select all**. To deselect all segments, click the **checkbox** again.
Kameleoon applies the actions you perform to all selected segments.
#### Manage tags
In the **Grouped actions** sidebar, click **Manage tags**.
#### Export segments
In the **Grouped actions** sidebar, click **Export**.
Select a format: PDF or Excel. Set the export options if needed. Then, click **Export Dashboard**. Only the checked segments appear in the file.
# Set up a segment in a campaign
Source: https://docs.kameleoon.com/user-manual/assets/segments/set-up-a-segment-in-a-campaign
Associate a targeting segment with an experiment or personalization to control which visitors your campaign includes.
## Create a new segment
[To learn how to create a segment, read this article](./create-a-segment)
## Set up a segment in an experiment
In the finalization panel, select **Target a segment** in the **Targeting** step.
In the list of existing segments, select the segment you created.
Hover over the **information** icon to display the segment's targeting conditions.
Click the **X** icon to dissociate the segment from the experiment.
To associate a segment, you can also select **Target specific visitors** in the **Targeting** step. Select the segment and connectors you need. Using this option allows you to create quickly targeting conditions without re-creating a segment.
Click **Next**. Kameleoon associates this segment with your experiment.
## Set up a segment in a personalization
Once you create a segment, you must associate it with a personalization.
In the **Targeting** step, click **Target a segment** in the **Segments** panel. Then, click the segment you want to target.
The segment your experiment is targeting displays at the top of the page. Proceed with [finalization](../../experimentation/web-experimentation/configure-and-launch/finalizing-an-experiment) normally.
# Create a theme
Source: https://docs.kameleoon.com/user-manual/assets/themes/create-a-theme
Build a standardized design system in the Theme Builder by defining brand colors, fonts, and reusable components for your team's widgets.
When your team builds widgets without a shared design system, colors, fonts, and components can drift from your brand guidelines across projects. Creating a theme in the Theme Builder gives your team a standardized design system: you set specific colors, upload brand fonts, and pre-build components that every widget uses consistently.
## Create a new theme
1. Go to **Studio** > **Themes** in the left sidebar.
2. Click **Add a theme**.
3. Enter a name for the theme and select the **Projects** it affects.
4. (Optional) Add a description and tags.
5. Click **Next** to open the **Theme Builder**.
### Define colors
Use the **Colors** section to define the palette available to users.
To restrict users to specific brand colors, toggle **Define theme colors** to **ON**.
* **Add a color:** Enter a hex code or click the **+** icon. You can select a color from the gradient, adjust opacity, or use the eyedropper tool to sample from your screen.
* **Manage colors:** Drag and drop colors to reorder them. Click the **trash** icon to remove a color.
If you add a component to the theme while **Define theme colors** is **ON**, Kameleoon automatically adds that component's default colors to your theme colors list.
Colors added here are available under **Theme Colors** in the Widget Studio.
#### Modifying locked colors
If a component in your theme currently uses a color, you can't delete it. However, you can edit the color. When you modify a color, the change automatically applies to every component in the theme that uses that color.
### Add fonts
In the **Fonts** section, determine which distinct typography users can access. Check a font from the list to include it in your theme. Use the search bar to search for a specific font.
You must select at least one font to add components to your theme. If you remove a font that's currently in use, the system defaults to the first font in your list.
To add a font:
1. Click **+ Add font**.
2. Select your font source:
* **From your website:** Enter the Font Family name.
* **Link to a font file:** Enter the Font Family name and the URL to the file.
* **Embed code:** Enter the Font Family name and the import code.
3. Click **Preview & add**.
4. Select the font weights you want to include.
5. Click **Add**.
### Add and manage components
The **Components** section allows you to pre-configure elements (like buttons, images, or forms) for your team and define which components belong in the theme. You can add the same component type multiple times to create variations, for example, a distinct "Submit" button and a "Cancel" button.
#### Add a component
1. Click **+ Add** next to **Components**.
2. Search for a component or browse categories in the left sidebar.
3. Select the components you want to include.
4. Click **Add components**.
#### Edit and lock components
After you add a component to your list, click the **secondary actions** (three dots) menu to manage it:
* **Rename:** Give the component a descriptive name (for example, "Primary CTA").
* **Edit:** Open the component editor to adjust styles using [Widget Studio tools](../widgets/create-a-widget-with-the-widget-studio/edit-your-widgets).
* **Lock:** Restrict editing permissions for this component. Alternatively, click the **lock** icon next to the **Secondary actions** menu to lock a component.
* **When locked:** Users can only modify the content (text or images), position, and size. They can't design elements like colors or borders.
* **When unlocked:** Users have full control to change the design.
## Activate your theme
When you finish configuring your theme, click **Activate** in the top right corner. The theme is now available for use in your experiments and personalizations.
To deactivate a theme later, click the status dropdown (**Active**) and select **Deactivate**, or use the Themes dashboard.
# Manage themes
Source: https://docs.kameleoon.com/user-manual/assets/themes/manage-themes
Search, sort, filter, and configure theme usage settings to enforce brand guidelines across projects in the Widget Studio.
When different teams build widgets across projects without a shared reference, colors, fonts, and components can drift from your brand guidelines. Themes let you enforce brand guidelines across projects: by defining specific colors, fonts, and reusable components, you ensure that every widget built in the Widget Studio stays consistent with your brand identity.
This article explains how to access, organize, and configure usage settings for your themes.
## Access the themes dashboard
To access the Themes dashboard, click **Studio** > **Themes** in the left sidebar.
From the dashboard, you can organize your view:
* **Search:** Use the search bar to find a specific theme by name.
* **Sort:** Click the **Sort** icon to order themes by **Modification date** (newest to oldest or oldest to newest) or alphabetically (**A to Z**, **Z to A**).
* **View:** Switch between **Block view** (grid) and **List view** using the icons next to the sort options.
* **Filter:** Open the **Filters** sidebar to refine the list by **Project** or **Status** (Active/Inactive). Click **Apply** to update the list.
## Configure theme usage and defaults
Administrators can control how strict theme usage is for each project. You can require users to apply a theme or allow them to create widgets without one.
1. On the **Themes** dashboard, click the **settings** (cog wheel) icon.
2. In the **Theme Usage & Default Themes** panel, locate the project you want to configure.
3. Select the usage mode:
* **Optional:** Users can choose whether to apply a theme when creating widgets.
* **Mandatory:** Users must select a theme to create a widget.
4. (Optional) Select a **Default Theme**. Kameleoon pre-selects this theme for users creating new widgets in this project.
5. Click **Save**.
## Edit and manage existing themes
Each theme card provides quick access to management actions:
* **Edit:** Click the **Pencil** icon to open the Theme Builder and modify colors, fonts, or components.
* **Secondary actions:** Click the **secondary actions** (three dots) menu to:
* **Preview theme:** View how the theme appears.
* **Rename theme:** Change the internal display name.
* **Manage tags:** Add or remove tags for organization.
* **Duplicate theme:** Create a copy of the theme.
* **Activate/Deactivate:** Toggle the theme's availability.
* **Delete:** Permanently remove the theme.
# Create a trigger
Source: https://docs.kameleoon.com/user-manual/assets/triggers/create-a-trigger
Learn how to use the Kameleoon Trigger Builder to define when and where an experiment or personalization should activate based on real-time visitor behavior.
A **trigger** defines the specific conditions visitors must meet for an experiment or personalization to activate. Use triggers to target visitors based on their real-time behavior or visit characteristics.
## Access the Trigger Builder
To start creating a new trigger:
1. In the left sidebar, click **Settings** > **Triggers**.
2. Click **New trigger**.
3. In the **New Trigger** window, enter a name for your trigger.
4. Select the **Project** you want to associate with this trigger.
5. (Optional) Add a description and tags to help organize your triggers.
6. Click **Next**.
## Define conditions
The Trigger Builder is where you define your trigger's logic. Select conditions from the sidebar and configure how they relate to one another.
1. **Select a condition:** In the left sidebar, scroll through the list or use the search bar to find a condition (for example, **Number of visits**). Click the condition to add it to the builder.
2. **Configure the condition:** Enter the relevant values for the condition (for example, **3 visits**).
3. **Add more conditions:** To add another layer of targeting, click **Refine** on an existing condition or select a new condition from the sidebar.
### Manage logic (AND/OR)
When you use multiple conditions, define how they work together using the dropdown menu at the top of the Trigger Builder or [condition group](#create-complex-groups):
* **If all (AND):** Kameleoon fires the trigger only if the visitor meets **every** condition in the group.
* **If any (OR):** Kameleoon fires the trigger if the visitor meets **at least one** of the conditions in the group.
### Create complex groups
Group conditions together to create advanced logic (nested conditions).
* **Reorder:** Click and drag a condition to move it up or down in the list.
* **Nest (Group):** Click and drag one condition on top of another to combine them into a subgroup with its own independent logic (**If any**/**If all**).
* For example, you can create a condition that targets visitors who have visited the site three times today **AND** viewed a certain product page at least once.
### Copy or delete conditions
* **Copy:** Click the **Copy** icon to clone a condition.
* **Delete:** Click the **X** icon to remove a condition.
#### Quickly add conditions
You can quickly add multiple conditions of the same type by clicking the small **+** icon on the right side of the condition. This feature is available for conditions frequently used in large numbers.
When you add multiple identical conditions, Kameleoon links them with an **OR** operator. The dropdown menu updates to **is including any of** or **is not including any of**.
Once you add multiple identical conditions, you can delete them individually.
***
When you are satisfied with your conditions, click **Next**.
## Review and save
After you click **Next**, a summary panel opens on the right. Review the settings and definition.
* **Settings:** Displays the trigger name, project, campaign type, description, and tags. Click the **pencil** icon to edit any of these settings, then click **Save changes**.
* **Definition:** Displays your trigger's definition. You can view a visual summary under the **Block Summary** tab or a text-based summary under the **Written Summary** tab.
Click **Create trigger** to finish.
***
After you save your trigger, it becomes available for use in experiments and personalizations.
## Conditions
This section provides a comprehensive list of available conditions and their functions.
### Page
* **Page URL:** includes or excludes visitors based on their current page URL.
* **Element on the page:** includes or excludes visits based on the presence of an element on the page. The condition performs a `querySelectorAll` loop until the DOM ready event. After that, the condition returns `false`.
* **Landing Page URL:** includes or excludes visitors based on the URL of the page where their visit started.
* **Page Title:** includes or excludes visitors based on their current page title.
* **Previous page:** includes or excludes visitors based on the URL of their previous page.
* **Key pages:** includes or excludes visitors who have visited specific pages that you defined as key pages.
* **Visited product pages:** includes or excludes visitors based on which/how many product pages they visited.
* **Price of the product page displayed:** includes or excludes visitors based on the price of the product they're currently viewing.
### Browsing behavior
* **Elapsed time since page loaded:** includes or excludes visitors based on the time since the page loaded.
* **Website exit:** includes or excludes visitors whose cursor has left the browser window. Use the Website exit condition to display retention-focused content, such as a discount offer or an email sign-up form, before a visitor navigates away. For a step-by-step example, see [Create an exit intent widget](../widgets/create-a-widget-with-the-widget-studio/create-an-exit-intent-widget).
* **Number of pages viewed:** includes or excludes visitors who have seen a certain number of pages.
* **Total number of visits:** includes or excludes visitors based on the total number of their visits.
* **Number of visits by page:** includes or excludes visitors based on their number of visits to a specific page.
* **Number of visits today:** includes or excludes visitors based on their number of visits today.
* **Number of visited product pages:** includes or excludes visitors based on how many product pages they have visited.
* **Elapsed time:** includes or excludes visitors based on the time elapsed during the session.
* **Elapsed time since first visit:** includes or excludes visitors based on the time since their first visit.
* **Elapsed time since last visit:** includes or excludes visitors based on the time since their last visit.
* **Elapsed time since session became active:** includes or excludes visitors based on the time since the beginning of the session.
### Campaign exposure
* **Web Experiment:** includes or excludes visitors that Kameleoon has exposed to a specific experiment and who have seen a **specific variation** OR **any of the variations** (original included). The condition considers current or previous visits. The selected experiment can be **Online**, **Paused**, or **Stopped**.
* **Personalization:** includes or excludes visitors that Kameleoon has exposed to a specific personalization. The condition considers current or previous visits. The selected personalization can be **Online**, **Paused**, or **Stopped**.
* **Feature Flag:** includes or excludes visitors that Kameleoon has exposed to a specific feature flag and assigned to **any variation** or a **specific variation**, who have seen **any of the variations**, **On**, or **Off**.
* **Exclusive Campaign:** excludes visitors already participating in an experiment, a personalization, or both, meaning that:
* If another campaign has already exposed the visitor (in a current or previous visit), Kameleoon doesn't target them in the current experiment.
* Other experiments that don't have the **Exclusive campaign** condition can still target the visitor, even if the visitor is currently part of an exclusive campaign. In other words, this condition doesn't prevent participation in other experiments. It lets visitors participate in experiments that don't have the same exclusivity requirement.
Kameleoon prevents the deletion of campaigns or variations used as targeting conditions in a segment.
### Conversions
* **Converted goal:** includes or excludes visitors based on whether they converted on a certain goal during the current visit or during previous visits.
### Technical
* **Custom JS:** Define a custom JavaScript function that returns `true` or `false`. If the result is `true`, Kameleoon includes the visitor in the experiment. Kameleoon evaluates this function each time the page displays, or you can run it asynchronously.
* **Check condition immediately or when the page has loaded:** If the function returns `undefined`, Kameleoon retries execution every 75 ms for the first 3 seconds, then every 250 ms.
* **Run the condition asynchronously:** Kameleoon evaluates your JavaScript for each experiment.
* If you use the asynchronous condition, the callback function is `setTargeting`. Replace it in the code with `setTargeting(true)` or `setTargeting(false)`.
* **Custom data:** includes or excludes visitors based on specific custom data. To use this condition, you must first [create custom data](../custom-data/create-custom-data).
* **Custom event:** starts a personalization only when your code triggers a specific event using the [`Kameleoon.API.Events.trigger(eventName)`](../../../developer-docs/apis/activation-api-js/api-reference/api-reference#trigger) method.
* **Browser cookie:** includes or excludes visitors based on a cookie's presence in their browser and its value.
* **Explicit trigger:** explicitly triggers a campaign using the Kameleoon Activation API. Use explicit triggers for campaigns you implement with a modern JS framework (for example, React, Vue, Angular).
* **Kameleoon trigger:** includes or excludes visitors based on whether they fired another trigger.
### Acquisition
* **Traffic type:** includes or excludes visitors from specific sources (for example, search engine, emailing, website tributary).
* **Referring Website URL:** includes or excludes visitors based on the referring URL.
* **Acquisition channel:** includes or excludes visitors based on their acquisition channel.
### External environment
* **Day / Night:** includes or excludes visits during the day or night.
* **Weekday:** includes or excludes visitors on a specific day of the week.
* **Timeslot:** includes or excludes visitors within a given time period.
* **Date range:** includes or excludes visitors to the website during a given date range.
* **Sky condition:** includes or excludes visitors based on the weather in their location.
* **Temperature:** includes or excludes visitors based on their location's temperature.
# Manage your targeting triggers
Source: https://docs.kameleoon.com/user-manual/assets/triggers/manage-your-targeting-triggers
Find, filter, sort, edit, duplicate, and delete targeting triggers from the Kameleoon Triggers page.
## Access the Triggers page
To access the **Trigger** page, click **Configure** > **Triggers**.
## Manage your triggers
Each trigger is represented by a card that indicates its main information.
### Find a trigger
A search bar, a filter tool, and a sorting tool help you find a particular trigger.
#### Filter triggers
You can filter the displayed triggers based on several criteria:
* Project
* Linked to
* Tag
* Key date
* Creator
* Characteristics
* Goal
##### Project
You can filter the displayed triggers based on the projects with which they are associated. Check the projects and click **Apply**.
##### Campaign type
*This filter is only available for Web experimentation + Feature experimentation customers.*
You can filter the displayed triggers based on the type of campaign with which they are associated.
You can select from the following campaign types:
* **Feature flag / SDK experiment**: Triggers containing the “Visitor code” condition or Feature experimentation conditions not used in any experiment or personalization.
* **All experiment types:** Triggers used in a Feature experiment that also contain conditions common to both Feature experimentation and Web experimentation.
* **Web experiment / Personalization:** All other segments.
##### Linked to
You can filter the displayed triggers based on whether they are associated with a campaign.
##### Tag
You can filter the triggers based on the tags with which they are associated.
Select or search for a tag. Kameleoon displays the triggers associated with these tags on the page. You can also check or uncheck all tags. Then, click **Apply**.
##### Key date
You can filter the displayed triggers based on the key date with which they are associated: last modification or creation date.
Select a date and click **Apply**.
##### Creator
You can filter the displayed triggers based on their creator. Check the creators and click **Apply**.
##### Characteristics
You can display triggers used in Audiences or with AI Predictive targeting. Check the filter and click **Apply**.
#### Sort triggers
You can sort triggers based on several criteria:
* Name
* Linked to (Campaign)
* Edition date
* Segment ID
* Creation date
* Project
##### Name
Hover over **Name** and click the chevron to sort triggers in alphabetical (or reverse alphabetical) order.
##### Linked to
Hover over **linked to** and click the chevron to rank triggers based on the campaign type.
##### Edition date
Hover over **Edited** and click the chevron to sort triggers from newest edition to oldest or vice versa.
##### Segment ID
Hover over **ID** and click the chevron to sort the triggers' IDs in ascending or descending order.
##### Creation date
Hover over **Created** and click the chevron to sort triggers from newest creation date to oldest or vice versa.
##### Project
Hover over **Project** and click the chevron to sort triggers based on the website on which they are configured in alphabetical (or reverse alphabetical) order.
### Edit a trigger
To edit a trigger:
1. Navigate to the trigger's card.
2. Click the **pencil** icon. The Trigger Builder opens.
3. Make your changes and click **Save** to save them.
### Duplicate a trigger
To duplicate a trigger:
1. Navigate to the trigger's card.
2. Click the **three-dots menu** > **Duplicate**. The **Duplicate** sidebar opens.
3. Click **Save** to validate your trigger's creation.
### Delete a trigger
1. Navigate to the trigger's card.
2. Click the **three-dots menu** > **Delete**.
### Multiple selection
You can select multiple triggers at the same time and apply a common action to them. For example, it is possible to delete several triggers simultaneously. To apply multiple actions to triggers:
1. Navigate to a trigger's card.
2. Click the **three-dots menu** > **Select**.
Triggers become selectable and the **Grouped actions** sidebar opens.
Several actions are available.
#### Select/deselect all
To select all triggers, click the **checkbox** next to **Select all**. Click the **checkbox** again to deselect all triggers.
#### Manage tags
Click **Manage tags** in the **Grouped actions** sidebar.
# Set up a trigger in a campaign
Source: https://docs.kameleoon.com/user-manual/assets/triggers/set-up-a-trigger-in-a-campaign
Add a trigger condition to an experiment to control when your campaign activates based on visitor events.
## Create a new trigger
Read [this article](./create-a-trigger) to learn how to create a trigger.
## Set up a trigger in an experiment
For more information on defining segments and triggers, refer to [this article](../../experimentation/web-experimentation/configure-and-launch/define-your-experiments-targeting).
To set up a trigger in an experiment:
1. Click **Targeting** > **Target specific visitors** in the Graphic editor's finalization panel.
2. Select **Trigger** from the list of conditions.
3. Select the event with which you want to associate your trigger.
4. Click **Next** to associate the trigger with your experiment.
Click the **X** icon to dissociate a trigger from the experiment. You can add multiple conditions to your experiments.
# Analyze your widget results
Source: https://docs.kameleoon.com/user-manual/assets/widgets/analyze-your-widget-results
Use the widget results page to track exposure and completion metrics, read AI-generated learnings, and browse individual responses to your widget.
The widget results page gathers all the data collected by a widget across the campaigns it is linked to. It shows how many users saw and completed the widget, AI-generated learnings, and every individual response.
## Access the widget results page
To open a widget's results page, go to the [Widgets dashboard](./manage-your-widgets) and click the **three-dots menu** on the widget's card, then select **See results**.
The header of the results page displays the widget's name, ID, and status. From the header, you can:
* Click **Export** to export the widget's data.
* Select the period to analyze: a custom date range, **All days**, **30D** (last 30 days), or **7D** (last 7 days).
The results page contains three tabs: **Overview**, **Learnings**, and **Responses**.
## Overview
The **Overview** tab summarizes the widget's key metrics over the selected period.
* **Key metrics:** The number of users exposed to the widget across all linked campaigns, the number of users who completed it, the completion rate, and the average response time per completion.
* **Widget responses over time:** A chart comparing the number of users exposed to the number of users who completed the widget, day by day. Hover over the chart to see the values for a specific date.
* **Linked campaigns:** A table listing every campaign the widget is linked to, with its status, the number of users exposed, the number of users who completed the widget, and the completion rate. The last row totals these metrics across all campaigns.
## Learnings
The **Learnings** tab provides an AI-generated summary of the widget's results. The date of the last update is displayed at the top of the tab. Click the **refresh** icon to regenerate the summary with the latest data.
* **Overall insights & recommendations:** **Insights** summarize the widget's key metrics and the main takeaways from the responses. **Recommendations** suggest concrete next steps based on those insights.
* **Detailed insights:** A breakdown of the responses to each question/input of the widget, highlighting the main trends and segments.
* **Notes:** A free-text field where you can write down your own observations and conclusions.
## Responses
The **Responses** tab lists every individual response submitted through the widget. The total number of responses is displayed next to the search bar, which you can use to search within the responses.
By default, each response displays the visitor code, the date the widget was seen, the date it was submitted, the answers to each question, the submission URL, and the campaign and variation the response was collected on.
### Customize the responses table
Use the sidebar on the right of the tab to customize the table:
* **Filters:** Filter the responses.
* **Columns:** Select which columns to display, and choose the criteria and order by which to sort the responses (for example, newest to oldest). Click **Apply** to apply your changes, or **Reset** to restore the default configuration.
* **Views:** Manage saved views of the responses table.
# Create a new widget
Source: https://docs.kameleoon.com/user-manual/assets/widgets/create-a-new-widget
Start building a new widget in Kameleoon using the Widget Studio, the code editor, or PBX.
To create a new widget in [Kameleoon](https://login.kameleoon.com/app):
* Click **Studio** > **Widgets** > **New widget**.
You can choose to create a widget using an AI prompt, the Widget Studio, or code. Select an option to continue.
* [Learn how to create a widget from code](./create-a-widget-from-code/creating-a-widget-from-code)
* [Learn how to create a widget using the Widget Studio](./create-a-widget-with-the-widget-studio/create-a-widget)
* [Learn how to create a widget using PBX](../widgets/pbx-widgets)
# Creating a widget from code
Source: https://docs.kameleoon.com/user-manual/assets/widgets/create-a-widget-from-code/creating-a-widget-from-code
Learn how to build highly customizable widget templates by coding them directly in the Kameleoon platform.
Create highly customizable widget templates by coding them directly in the Kameleoon platform.
Use one of our ready-to-use widgets or ask your developer for help if you are not comfortable coding.
## Create a new template
Follow these steps to create a new widget template with code:
1. Click **Studio** > **Widgets** > **New widget**.
2. Select **Using code**.
3. Name your template, associate a website, and optionally write a description and add tags.
4. Click **Create**.
## The template editor
The template editor contains three distinct areas.
### Left panel
The top-left corner displays your template's title. Hover over the title and click the **pencil icon** to rename the template.
Access two essential steps for creating your template in this panel:
* **Code to run**
* **Configuration form**
### Content zone
Enter your template's code in this area.
## Code the template
Use the central content area to code your widget template. This code generates the widget on your website's page. The editor provides three tabs for different code types:
* **JS** (JavaScript)
* **CSS**
* **HTML**
By default, the **JS** tab is active. Write your code in the blank area.
To validate your template, enter at least 10 characters in the **JS** tab. JavaScript is sufficient to create your template, but you can also add HTML or CSS.
Use this default CSS to format elements, such as lists and text fields, according to the Kameleoon stylesheet:
```css theme={null}
@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@300;400;500;700&display=swap');
body * {
font-family: "Montserrat";
font-size: 12px;
}
fieldset {
border: none;
border-bottom: 1px solid #dedede;
}
label {
display: block;
font-size: 12px;
margin-bottom: 5px;
}
input, select, textarea {
display: block;
padding: 8px 12px;
width: 100%;
border-radius: 4px;
border: 1px solid #eeeeee;
outline: none;
font: 400 12px "Roboto", sans-serif;
color: #333333;
background: white;
-webkit-transition: border-color 0.25s ease;
-o-transition: border-color 0.25s ease;
transition: border-color 0.25s ease;
}
input:hover, select:hover, textarea:hover,
input:focus, select:focus, textarea:focus {
border-color: #c6c6c6;
}
textarea {
resize: vertical;
}
input[type="checkbox"] {
display: inline-block;
width: auto;
position: relative;
top: 1px;
}
input[type="checkbox"] + label {
display: inline-block;
}
```
After writing the code, click **Configuration form** in the left panel to move to the user interface step.
### Special case: variables
To use a field (a variable) specified by the user in your widget, add the `templateData` attribute to the corresponding field in the **User Interface** tab.
**Example:**
`input id="message" type="text" templateData="messageContent" placeholder="Type your message"`
To retrieve the variable, use `UserData` in the **Code to run** tab.
**Example:**
`var userInput = UserData.messageContent;`
`alert(userInput);`
## Create the configuration form
Use the **Configuration form** tab to build the user interface that team members use to set up your widget. Only the **HTML** and **CSS** tabs are available in this section.
### HTML tab
Enter the HTML code for your configuration form in the **HTML** tab. Users interact with this form to set up their template and create a widget.
Every field in the form must include an attribute with the following syntax: `templateData="[NameOfYourChoice]"`.
### CSS tab
Styles that you add in the **CSS** tab apply to the user interface form. This step is optional.
## Activate the template
To finalize your template, click **Activate** in the top-right corner of the editor page.
If you enter fewer than 10 characters in the JavaScript field, **Activate** is unavailable.
## Manage created templates
After you create a template, it appears as a card on the **Widgets** dashboard.
## Use the widget in an experiment
To associate a code widget with an experiment:
1. Open or create an experiment using the **Graphic editor**.
2. In the left sidebar, click **Add** next to **Elements**.
3. In the **Add element** sidebar that opens, click **Widgets**.
4. Select your custom widget from the list and configure it.
## Preview your widget
Code-based widget templates don't have a direct **Simulate** action. The **Widgets** dashboard's three-dots menu offers only **Rename**, **Manage tags**, **Duplicate**, **Activate**, and **Delete** for a code-based widget, and the template editor's header offers only **Activate**.
To preview a code-based widget, add it to a draft experiment using the **Graphic editor**: click **Add** next to **Elements** in the left sidebar, click **Widgets**, and select your widget from the list. Then click **Simulate** in the **Graphic editor** to test the campaign, including your widget, in a production-like environment before publishing it live. For details on the simulation panel, see [Simulate a campaign](../../../experimentation/web-experimentation/configure-and-launch/simulate-a-campaign).
# Add a slider to a widget
Source: https://docs.kameleoon.com/user-manual/assets/widgets/create-a-widget-with-the-widget-studio/add-a-slider-to-your-widget
Add a slider element to your widget, edit slides, position it, and customize transition animations and autoplay behavior.
A slider lets you cycle through multiple images, offers, or messages inside a single widget element.
In this article, you learn how to:
* Add a slider
* Edit slides
* Position a slider
* Customize slide transitions
## Add a slider
To add a slider to your widget:
1. Click **Add element** in the left sidebar.
2. Unfold the **Media** section in the list.
3. Click **Slider**. A panel opens where you can edit the slider.
## Edit slides
A new slider contains three slides by default.
To add a slide, click **Add new slide** in the **Slider Content** section. To edit an existing slide, click **Edit** next to it.
## Position a slider
Drag the slider on the canvas to place it anywhere in your widget.
## Customize slide transitions
Click **Slider Animation** to configure how your slides transition:
* **First slide**: the slide that displays first.
* **Speed**: the transition duration, in milliseconds.
* **Autoplay**: advances slides automatically, without visitor interaction.
* **Effect**: the transition style between slides.
* **Direction**: the direction slides move in.
* **Allow touch move**: lets visitors swipe between slides on touch devices.
You can also customize the previous and next arrows and the pagination indicator from the same panel.
# Associate events and actions with your widget
Source: https://docs.kameleoon.com/user-manual/assets/widgets/create-a-widget-with-the-widget-studio/associate-events-and-actions-with-your-widget
Learn how to define interactive behaviors for your widgets by connecting event triggers with automated actions in the Kameleoon Widget Studio.
Define how and when your widget behaves by associating events and actions. Events are triggers that detect specific visitor behaviors or page states, while actions are the responses that Kameleoon executes when those events occur.
For example, you can create a multi-step pop-in flow where submitting an email address in the first pop-in (Event) triggers the display of a second "thank you" pop-in (Action).
## Access the Events section
To manage your widget's triggers and responses, open the Widget Studio and click **Events** in the left sidebar.
## Manage events
An event defines when Kameleoon performs one or more actions. You configure an event's conditions and its actions together in the same panel.
### Create an event
To create a new event:
1. Click **Add event**. The **Create new event** panel opens.
2. Select the type of event you want to create and click **Next**.
3. Under **Conditions**, use the dropdowns to define the values that trigger the event. Click **Add device trigger** to add a condition based on the visitor's device.
4. Under **Actions**, define the action Kameleoon performs when the conditions are met. Click **Add action** to add more actions to the same event, and click the trash icon next to an action to remove it.
5. Optional: click the pencil icon next to the panel title to rename the event.
6. Click **Save** to save the event.
### Edit or delete an event
To manage an existing event, hover over its card in the **Events** section, then:
* **Edit:** Click the pencil icon.
* **Delete:** Click the trash can icon.
### Event types
Kameleoon offers several event types to trigger actions:
| Event type | Description |
| :-------------------- | :---------------------------------------------------------------------------------------------- |
| **Click** | Triggers when a visitor clicks a specific element. |
| **URL** | Triggers when the page URL contains a specific value or matches a regular expression. |
| **Display** | Triggers before or after the widget appears. |
| **Survey** | Triggers based on a survey or form value. |
| **Language** | Triggers based on the visitor's browser language. |
| **Timer** | Triggers based on time factors, such as a delay. |
| **Custom data value** | Triggers when a specific custom data value meets defined conditions. |
| **Device** | Triggers based on the visitor's device type. |
| **Wheel of fortune** | Triggers based on a wheel of fortune action. Requires a wheel of fortune element on the widget. |
| **Scratch card** | Triggers based on a scratch card action. Requires a scratch card element on the widget. |
| **Countdown** | Triggers when a countdown ends. Requires a countdown element on the widget. |
| **Video** | Triggers when a video ends. Requires a video element on the widget. |
## Action types
You configure an event's actions under **Actions** in the **Create new event** panel. Kameleoon offers the following action types:
| Action type | Description |
| :------------------- | :---------------------------------------------------------------------------------------- |
| **Elements** | Shows or hides a specific element within the widget. |
| **Screens** | Shows or hides a specific screen within the widget. |
| **Kameleoon goals** | Converts or cancels a Kameleoon goal. |
| **Kameleoon events** | Triggers a custom event for segment targeting. |
| **Kameleoon data** | Sets a custom data value. |
| **URL redirects** | Redirects the visitor to a specified URL. |
| **JavaScript code** | Runs custom JavaScript code. |
| **Survey/Form** | Enables or disables a survey or form element. |
| **Browser storage** | Sets a value in local storage, session storage, or a browser cookie. |
| **Wheel of fortune** | Rotates a wheel of fortune element. Requires a wheel of fortune element on the widget. |
| **Translation** | Displays the widget in a specific language. Requires translations enabled for the widget. |
# Create a widget
Source: https://docs.kameleoon.com/user-manual/assets/widgets/create-a-widget-with-the-widget-studio/create-a-widget
Create a new widget in the Widget Studio by selecting a template and content type such as banner, NPS, survey, or countdown.
To view a video tutorial about the Widget Studio, visit [our academy](https://academy.kameleoon.com/get-started-with-web-experimentation/164461?utm_source=user_manual\&utm_medium=online)
To create a widget:
1. Click **Studio** > **Widgets** > **New widget**.
2. Select **Using the Widget Studio**. If you prefer to build a widget by prompting an AI, view [this article](../pbx-widgets); if you prefer to create a widget from code, view [this article](../create-a-widget-from-code/creating-a-widget-from-code#create-a-new-template).
3. Enter the required information in the pop-in.
4. Click **Create**.
## Choose a theme
After you click **Create**, a pop-in prompts you to choose a theme for your widget. The list always includes the [master theme](../../themes/create-a-theme), plus any custom themes available to your team. Select a theme and click **Next**.
## Select a template
Select a template for your widget. You can search for a specific template, apply filters, and access your custom or favorite templates. You can also import a widget from another account by clicking **Create from JSON file** in the upper-right corner.
### Content types
There are several content types to choose from:
* **Banner:** Add a banner to your page.
* **Emailing/Newsletter:** Improve return rates by incentivizing visitors with a pop-in.
* **Countdown/Timer:** Create urgency for better conversions.
* **Slider**: Create carousels to animate your website.
* **NPS:** See what your visitors think using an NPS widget.
* **Feedback/Survey:** Ask visitors for their opinions or information about their experience.
* **Social:** Allow users to access your social media accounts.
Both the timer and the countdown create a sense of urgency, but the first is in hours, while the second is in days. Use the timer for short-term offers (for instance, limited-time free shipping), and the countdown for long-term offers (for instance, a week-long sale).
# Manage your widgets
Source: https://docs.kameleoon.com/user-manual/assets/widgets/manage-your-widgets
Access the Widgets dashboard to search, filter, edit, duplicate, simulate, activate, and delete your Kameleoon widgets.
## Access the Widgets dashboard
To access the **Widgets** dashboard, click **Studio** > **Widgets**.
## Structure of the Widgets dashboard
* **Header:** Contains the **New widget** button.
* **Search bar:** Searches for widgets and displays the total count of created widgets.
* **Display options:** Switches the layout between **Card view** and **List view**. Sorts widgets by modification date or alphabetically.
* **Cards:** Display widget details, such as status. Each card includes an **Edit** button and a **More actions** menu to manage the widget.
* **Sidebar:** Filters results, customizes columns, and manages saved views.
## Widget information
Each widget is represented by a card that indicates its main information.
Hover over the tooltip to the right of a widget's name to access detailed information about the widget.
## Dashboard sidebar
### Filter
You can filter your widgets based on several criteria:
* Project
* Widget type
* Status
* Linked to
* Tag
* Creator
Select the filters and click **Apply**. Click **Save as view** to save your configuration as a [view](#views).
### Columns
#### Display
Select which columns you'd like to display on the dashboard table. Click the **checkbox** associated with a column to select or deselect it. Click **Apply** to apply your changes.
#### Sort by
Select the criteria by which to sort your widgets and the associated sorting rule (for example, newest to oldest, alphabetical, ascending number of tags).
### Views
Select which view you'd like to apply to the dashboard. To change the default view, click a view's **three-dots** menu > **Default**.
## Edit a widget
Click the **pencil** icon to edit a widget. Depending on how you set up the widget, Kameleoon takes you to the Code editor or the Widget Studio.
## Secondary actions
Click the **three-dots menu** on a widget's card to access the available actions. The actions depend on your widget's status.
### See results
You can view a widget's results, including exposure and completion metrics, AI-generated learnings, and individual responses. See [Analyze your widget results](./analyze-your-widget-results).
The **See results** action only appears if you've enabled response collection for the widget in PBX or the Widget Studio and linked it to an active campaign.
### Edit
You can edit a widget. Depending on how you set up the widget, Kameleoon takes you to the Code editor or the Widget Studio.
### Simulate
You can simulate a widget and preview it in a production-like context on the URL entered when the widget was created, without needing to associate the widget with an experiment. A sidebar appears with settings to define before launching the simulation.
Code-based widgets don't have a **Simulate** action. To preview a code-based widget, associate it with a draft experiment and simulate the campaign instead. See [Preview your widget](./create-a-widget-from-code/creating-a-widget-from-code#preview-your-widget).
### Rename
You can rename a widget.
Click **Save** to validate the widget's renaming.
### Manage tags
You can manage the tags associated with a widget.
Tags associated with your widget are highlighted in the **Manage tags** sidebar and widget card. You can associate tags and create new ones. Click **Save** to validate your choices.
### Duplicate
You can duplicate a widget.
Click **Save** to validate the widget's duplication. You can find the new widget in the dashboard.
### View code
You can view a widget's code.
You can change which devices the widget displays on and its position on the page. Click **View code** again to view the widget's JS and CSS code, copy the code, or expand the window.
### Export to .json
Download your widget as a `.json` file.
### Activate/Deactivate
You must activate a widget to use it in a campaign.
A widget's status is indicated on its card. If its card is white, the widget is activated. If its card is gray, the widget is deactivated.
If you deactivate a widget, you can't use it in your campaigns.
### Delete
You can delete a widget.
Confirm your choice in the pop-in to validate the widget's deletion.
# Create a widget with PBX
Source: https://docs.kameleoon.com/user-manual/assets/widgets/pbx-widgets
Learn how to use PBX, an AI-powered UI generator, to build widgets using natural language prompts.
# Create a widget with PBX
**PBX Widgets** is an AI-powered UI generator that helps you create widgets for your experiments and personalizations created in the new personalization builder. Instead of manually writing HTML, CSS, and JavaScript, you describe the widget in natural language, and PBX generates the component automatically.
This approach enables marketers, product managers, and CRO specialists to build UI components quickly without technical expertise.
Typical widgets created with PBX include:
* Newsletter subscription popups
* Promotional banners
* Exit-intent offers
* Lead capture forms
* Product recommendation panels
* Survey or feedback modals
PBX widgets are not compatible with legacy personalization. You can ask your CSM to get access to the new personalization if needed.
## Create a widget
Follow these steps to generate and refine a widget using PBX.
### 1. Open PBX
To start generating a widget in the Kameleoon interface:
1. Go to **Studio** > **Widgets**.
2. Click **New widget**.
3. Select **Using a prompt**.
4. Enter the required information in the pop-in menu.
5. Click **Create**.
### 2. Write a prompt
Describe the widget you want to build in the prompt field. PBX uses this description to generate the widget UI automatically.
**Example prompt:**
```text theme={null}
Create a centered modal popup widget.
- Layout: Two columns with an image placeholder on the left and a subscription form on the right.
- Content:
- Title: Join an Exclusive Community
- Description: Subscribe for exclusive discounts and get 15% off your next purchase.
- Form: Email input field with placeholder "Enter your email address"
- CTA button: Subscribe now
- Secondary link: No thanks
- Style:
- Modern ecommerce design
- Rounded UI elements
- Light beige background
- Dark CTA button
- Behavior:
- Display after 5 seconds
- Close button in top right corner
- Close popup when clicking "No thanks"
- Tracking: Track a goal called "Newsletter Signup" when the CTA button is clicked.
- Image: Use the following image in the image placeholder on the left: [https://www.whereyourimagelives.com](https://www.whereyourimagelives.com)
```
### 3. Preview and iterate
The fastest way to reach your desired result is to use a prompt-iteration workflow. Review the generated widget and refine it by writing follow-up prompts, such as:
* "Make the CTA button larger"
* "Change the background color to a darker beige"
* "Make the popup appear after 3 seconds"
### 4. Edit the widget's code
Edit a generated widget's JS or CSS code directly, instead of refining it through prompts.
1. Click the **code** icon in the header to open the **View code** tab.
2. Click **Edit code**.
3. Edit the widget's JS or CSS code.
If you generate multiple versions of the widget, select the one you want to edit from the **Selected version** dropdown. You can edit only the last version. For older versions, you can view and copy the code, but you can't edit it.
### 5. Add goals
Track user interactions—such as email submissions, button clicks, form completions, or widget displays—by adding goals to your prompt.
You must configure the goals in [**Settings**](../goals/create-a-goal) before you can track them in a PBX widget.
**Example prompts for goals:**
* Newsletter signup: `Track a goal called "Newsletter Signup" when the user clicks the Subscribe button.`
* CTA click: `Track a goal when the CTA button is clicked. Goal name: Promo CTA Click`
* Widget engagement: `Track a goal when the popup is displayed. Goal name: Widget Viewed`
## Collect widget responses in Kameleoon (optional)
If your widget asks visitors a question, such as an NPS score or a feedback comment, you need a way to gather those answers without setting up an external tool like Google Sheets. PBX detects when a widget contains a question or input and lets you collect the resulting responses directly in Kameleoon (currently in beta), then export them as a CSV file.
### 1. Enable response collection
When PBX generates a widget that contains a question or input, it prompts you to choose whether to collect the responses.
1. In the **Collect widget responses?** prompt, select an option:
* **Yes, collect responses via Kameleoon:** Kameleoon collects each response and makes it available for CSV export.
* **No, don't collect responses:** Kameleoon doesn't collect widget response data.
2. Click **Apply**.
### 2. Name the widget fields
Kameleoon uses the widget field names as the column headers in the exported CSV file, so give each field a clear, descriptive name.
1. Open the **Widget response settings** panel.
2. Review the automatically generated field names, listed as **Field 1**, **Field 2**, and so on.
3. Hover over a field name and click the pencil icon to edit it.
4. Enter a name, then click the checkmark to confirm or the cancel icon to discard the change.
5. Click **Apply** to save your changes.
**Apply** stays disabled until you make at least one change to a field name.
### What's included in the export
Kameleoon exports responses collected through a PBX widget under the same conditions as [survey CSV exports](./create-a-widget-with-the-widget-studio/create-csat-nps-and-surveys/survey-data-export#kameleoon-csv). The exported file includes:
* Response timestamps
* Visitor code
* Answers per question
* Campaign and variation details
## Send widget responses to Google Sheets (optional)
You can configure a PBX widget to [send survey and form responses directly to Google Sheets](./create-a-widget-with-the-widget-studio/create-csat-nps-and-surveys/send-survey-responses-to-google-sheets). You must first configure your Google Sheet as described in [this guide](./create-a-widget-with-the-widget-studio/create-csat-nps-and-surveys/send-survey-responses-to-google-sheets).
When writing the prompt to connect your widget to Google Sheets, follow these guidelines:
1. **Define a clear submission trigger:** Specify which element triggers the request. The trigger is typically the main CTA button (for example, `SubmitButton`).
2. **Use an external HTTP POST request:** Set the method to **POST** and include your Google Apps Script Web App URL.
3. **Provide the Web App URL explicitly:** Always include the full URL (for example, `https://script.google.com/macros/s/XXXXXXXX/exec`). PBX cannot infer or generate this automatically.
4. **List all elements to send:** Explicitly name every field (for example, `email`, `rating`, `comment`).
Do not rely on implicit behavior. PBX requires exact field names.
5. **Match parameter names exactly:** Ensure the names match exactly across your widget element names, the request payload, and the Google Sheets column headers.
**Example prompt for Google Sheets integration:**
```text id="example_pbx_google_sheets" theme={null}
Add a system to send widget form data to a Google Sheet using an HTTP request.
- Submission trigger: Use the button named "SubmitButton"
- Request configuration:
- Request name: SendToGoogleSheets
- Method: POST
- Action URL: https://script.google.com/macros/s/AKfycbxxxxxxx/exec
- Data to send: Send the values of the following elements as parameters:
- email
- rating
- comment
- Payload rules:
- Each parameter key must exactly match the element name
- Keys must also match the column headers in the Google Sheet
- Behavior:
- Trigger the request when the SubmitButton is clicked
- After successful submission, display a confirmation message: "Thank you for your response"
- Optionally handle errors if the request fails
```
## Write effective prompts
Well-written prompts significantly improve the quality of the generated widget.
### Use a clear structure
The best prompts follow a logical structure:
```text theme={null}
- Widget type
- Layout
- Content
- Style
- Behavior
```
**Example:**
```text theme={null}
Create a modal popup widget.
- Layout: Two columns with an image on the left and a form on the right.
- Content:
- Title: Join our community
- Description: Get 15% off your first order
- Email field
- CTA button: Subscribe now
- Style:
- Modern ecommerce design
- Rounded buttons
- Dark beige background
- Behavior:
- Display after 5 seconds
- Close button in top right corner
- Image: Use the following image in the image placeholder on the left: https://www.whereyourimagelives.com
```
### Be specific
Specific prompts produce more accurate layouts and styles.
**Bad prompt:**
`Create a popup for a newsletter`
**Better prompt:**
`Create a centered modal popup for newsletter subscription with a modern ecommerce design. Include an email input field and a large CTA button offering 15% off.`
### Define UI elements explicitly
Always specify the elements you need, such as titles, buttons, inputs, secondary links, icons, or images.
**Example:**
```text theme={null}
Add:
- Email input field
- Large CTA button
- Small legal disclaimer text
- "No thanks" link below the button
```
### Describe behavior
PBX can generate widget logic if you specify it.
**Examples:**
* `Show popup after 5 seconds`
* `Close popup when clicking outside`
* `Close popup when clicking "No thanks"`
### Iterate instead of rewriting
Rather than rewriting the entire prompt, refine your widget step-by-step. Iterative prompting improves results efficiently.
**Examples:**
* `Make the CTA button darker`
* `Increase padding inside the popup`
* `Add rounded corners to the input field`
# Define feature variables
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variables
Define feature variables to dynamically control your feature flag's content across environments without redeploying code.
You can define feature variables to remotely update your feature flags' content in your chosen environment. A feature variable defines a single piece of content, such as a discount percentage or a button color, that you can update without redeploying code. A feature variation is a named combination of variable values that Kameleoon serves to a specific group of users. You must create feature variables [to create feature variations](./define-feature-variations). There is no limit on the number of feature variables you can create.
## Creating feature variables
1. Navigate to your feature flag or create a new one.
2. In the left sidebar, click **Set Up** > **Variables** > **Add Variable**.
3. Select your variable's **Type**.
* If you select **Enum**, enter a list of allowed values separated by commas. This type creates a predefined list of options that you can select from when you define feature variations, rather than typing values manually.
4. Enter a **Variable Key**.
5. Set the **Default Value**.
* For **Enum** variables, select the default value from the list you defined in step 3.
6. Click **Save**.
To retrieve a feature variable from your source code, you must call the `getVariation()` method. If you use feature variations, Kameleoon automatically buckets the user in a variation and returns the value that variation defines for the variable, so you don't need to call the `getVariation()` method in that case.
## Benefits of feature variables
Feature variables let you variabilize parts of your feature flag code, so you can dynamically assign values to variables without coding them in your source code.
Once the feature variable's code is in production, changing it doesn't require redeployment. For example, if your feature is a discount offer for premium customers, but you're not sure what the discount percentage will be, you can create a **Discount Percentage** variable in your code and update it from the Kameleoon app without changing or pushing new code.
Developers and product owners can work together to variablize parts of your feature that might change, so product updates aren't blocked by development and deployments.
Choose your SDK language and use the sample code provided to set up the SDK in your app in any of the following languages:
* [Android](/developer-docs/sdks/mobile-sdks/android-sdk)
* [iOS](/developer-docs/sdks/mobile-sdks/ios-sdk)
* [Java](/developer-docs/sdks/web-sdks/java-sdk)
* [C#](/developer-docs/sdks/web-sdks/csharp-sdk)
* [Node.js](/developer-docs/sdks/web-sdks/nodejs-sdk)
* [PHP](/developer-docs/sdks/web-sdks/php-sdk)
* [Ruby](/developer-docs/sdks/web-sdks/ruby-sdk)
* [Go](/developer-docs/sdks/web-sdks/go-sdk)
* [Flutter](/developer-docs/sdks/mobile-sdks/flutter-sdk)
* [Python](/developer-docs/sdks/web-sdks/python-sdk)
* [Rust](/developer-docs/sdks/web-sdks/rust-sdk)
* [Elixir](/developer-docs/sdks/web-sdks/elixir-sdk)
# Define feature variations
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variations
Create and customize feature variations to control which feature version appears for each user based on your flag's rules.
You can create variations of your feature and decide which one to show each user, based on the criteria you define in the feature flag.
A feature variation is a named combination of values assigned to your feature variables. A feature variable defines a single piece of content, such as a discount percentage or a button color, that you can update remotely without redeploying code. You define variables first, then assign their values within each variation.
## Creating feature variations
You can customize any variable you create in the **Variables** page for any variation. You don't need to code any values into your source code.
To create a feature variation:
1. Navigate to your feature flag or create a new one.
2. In the left sidebar, click **Set up** > **Variations** > **Add variation**.
3. Edit your variation's **Name** and **Variation Key**.
4. Click **Save**.
## Default feature variations
When you create a new feature flag, Kameleoon generates two default variations: **On** and **Off**.
* **Off Variation:** Users assigned to this variation see your app or website as it appears when you turn off the feature flag. This variation lets you test new features on a limited group of users. Keep in mind that any custom variables you've created for the feature flag won't be available in the Off variation.
* **On Variation:** The On variation presents your flagged feature's default or control version. This variation serves as the baseline experience for your feature and will only use the default values for all defined feature variables.
Utilizing these default variations helps you manage user experience for different segments of your audience. You can view a summary of which variations Kameleoon serves to your users in the [Rollout Summary](../using-the-rollout-planner/rules-and-targeting/add-a-new-rollout-rule#rollout-summary).
The `getVariation()` method returns the variation key associated with the user.
# Manage environments
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments
Create and manage feature flag environments to separate development, staging, and production deployments within your projects.
Kameleoon Environments are used to categorize and manage your application's deployment locations. They help organize your technical infrastructure by separating development, testing, and production environments. Environments provide a structured approach for managing feature flags and deployments across platforms.
When you create a new project, Kameleoon automatically creates three feature environments: Production, Staging, and Development. These environments are intended to iterate, test, and refine software, minimizing risks and ensuring a safe release cycle.
## Customizing Environments
Navigate to the **Set Up** menu and click **Environments** to see your current project environments.
You’re free to customize these environments (except Production, which can only be renamed) or create additional environments. TO create a new environment, click **Add an Environment**.
Enter a name and key for your new environment. You can also reorder the environments to your liking.
## Scope of Environments
You can use feature variables, variations, and goals across all environments—you don't have to create them separately for each environment when setting up a feature. However, environments apply to the entire project, not just the flag you're working on. Any changes made to environments will affect all feature flags in the project.
You can filter flags by project and environment key in the Feature Flags dashboard. Hover over the ⓘ icon to see the projects on which a key has been used.
To use Kameleoon’s multi-environments feature flagging, you must use the parameter called “environment” within the YAML configuration file to define the environment key. If there are no environments specified within your YAML file, the configuration associated with the Production environment will be applied by default. Read your SDK’s [documentation](../../../../developer-docs/feature-experimentation/get-started/overview#supported-platforms) to learn more.
# Approvals for flag changes
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/approvals-for-flag-changes
Implement a request-and-review workflow to control and audit feature flag changes before they go live.
Enabling approvals for flag changes introduces a request-and-review mechanism for feature flag edits. Team members can request changes, and designated approvers can review and approve or reject these requests before they take effect.
Flag approvals give you greater control over which changes apply to your flags. After you configure approval settings, changes that certain users make pass through a request-and-review process, so only approved changes reach end users.
## Activate approvals for a project
Only users with **Admin** rights can configure approvals. Read [User roles](/user-manual/account-and-team-management/users-and-teams/user-roles) to learn what each role can do. To activate flag approvals:
1. Click **Features** > **Flags & Experiments** in the left sidebar.
2. Click the **Settings** tab, then select **Approval settings**.
3. Select the project for which you want to enable flag approvals from the dropdown.
4. Select the users who can review requests, then click **Save**.
If you select the option to trigger approvals only for the production environment, Kameleoon applies the workflow only to the environment with the key `production`. However, changes that indirectly affect the production environment, such as updates to variables, variations, or goals, also trigger the approval workflow.
Approvals don't control environments, integrations, or the flag toggle. Only users with **Production** permissions can change a flag's state (on/off).
## Request approval for flag changes
After you activate approvals for a project, non-reviewer users see an approval request popup when they save their changes. You can customize the title of the request and add a comment that the approver can see.
Requesters can make and submit changes in bulk across different sections of the setup or environments. Kameleoon notifies approvers of pending requests so they can review the proposed changes.
All approval requests are visible in the **Review** section. To withdraw an individual request that's still **Pending**, click the request, then click **Withdraw request**.
## Approve change requests
On the main dashboard, approvers can see an overview of each flag's review status:
* **Pending**: The flag has at least one pending request.
* **Reviewed**: An approver has approved or rejected every request.
Hover over the review stage to display additional information.
When editing a feature flag, reviewers can navigate to the **Review** section to see all requests. Click a request to view its details, including proposed changes and comments. Requests can have one of four states:
* **Pending**: Awaiting review.
* **Approved**: Kameleoon approved and applied the change.
* **Rejected**: The approver declined the change.
* **Invalid**: A newer change makes this request no longer applicable. Kameleoon rejects it by default.
For each request, approvers can approve or decline the proposed changes. Kameleoon applies or discards the associated changes accordingly.
Approvers can only review requests in top-down order (newest request first).
## FAQs
No. After you enable approvals, all flags in a project must go through the approval workflow. If the process seems too stringent, consider revising the list of approvers.
Kameleoon discards rejected requests, but requesters can always resubmit their changes.
A newest-first review process flags and ignores invalidated requests, eliminating any risk of data conflicts.
# Create a feature flag
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag
Create a new feature flag in Kameleoon and configure it using the Rollout Planner to control feature delivery across environments.
This guide shows you how to create a new feature flag.
## Access the Feature flag creation page
1. Click **Features** > **Flags & Experiments** > **New feature flag**.
2. Enter a name for your flag.
3. Choose the project on which you want to activate the flag.
4. Choose a flag type: **Temporary** for a flag you plan to remove after launch, or **Permanent** for one that stays in your codebase long-term. Read [Manage feature flag technical debt](./manage-feature-flag-technical-debt) to learn how Kameleoon tracks each type.
5. Add a description (optional).
6. Click **Save**.
Kameleoon generates a flag key automatically based on your flag's name, but you can edit it before you save.
The flag key is the unique ID that identifies the feature flag in your source code. Be sure to update the key in Kameleoon before editing it in your source code.
By default, your flag is **OFF**. You can activate it once it's configured.
## Structure of the Rollout Planner
The Rollout planner consists of several blocks.
* A **header** indicating the flag's name, the associated sitecode (you can copy and paste it directly from here), and the flag key. Click the flag's name to edit its details.
* A **Setup** menu, to create and manage your feature variables and feature variations URL.
* A **Rollout Planner** specific to each environment. Changes to a feature flag apply only to the environment you select in this section. Kameleoon lets you link your production and staging/QA environments to the app.
* A **toggle** that turns your feature flag **On** or **Off**.
* An area for you to add rollout rules.
* A **toolbar** for accessing the AI assistant, reverting your changes, and opening secondary actions (**Simulate** and **Calculate duration**).
* A **Save** button.
Confirm the flag exists in Kameleoon and that you can retrieve it from your source code with a Kameleoon SDK's `isFeatureActive()` or `getVariation()` method. Then go to your feature flag in Kameleoon and continue configuration.
# Feature Experimentation dashboard
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/feature-experimentation-dashboard
Navigate the Feature Experimentation dashboard to manage flags, review approvals, monitor flag health, and access holdout settings.
Managing flags across multiple projects and environments can get cluttered fast. The Feature Experimentation dashboard centralizes project, environment, and flag management into a clear layout. This article outlines the dashboard's sections and how to use them.
## Dashboard structure
### Tabs
The dashboard has four main tabs:
* **Overview:** The standard view, which lets you navigate your flags and their rules.
* **Approvals:** Lists flags or rules waiting for approval before rollout.
* **Health:** Displays flag health, last evaluation, and last modification to better manage technical debt.
* **Settings:** Access to approval and holdout settings. You can access holdout reporting from this tab.
### Environment selector and views
At the top of the flag list, you can switch between your projects' environments, or select **All environments** for a consolidated view across all of them.
The view toggle also lets you adjust how flags appear:
* **Collapsed:** Compact list of all flags, similar to the previous dashboard.
* **Expanded:** Shows details at a rule level for a more complete picture of the rollouts and experiments in your flag's environments.
### Flag actions
From the dashboard list, you can also:
* Toggle a flag **On** or **Off**.
* Open the flag configuration using the edit icon.
* Click the edit or results icon at the end of a rule's row to open its configuration or reporting page.
# Feature flag comments
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/feature-flag-comments
Add, reply to, and manage comments directly on feature flags to centralize team discussions and decisions in Kameleoon.
Feature flag comments let your team centralize discussions and decisions directly within Kameleoon. Instead of relying on external tools, you can easily communicate about specific feature flags, ensuring everyone has the necessary context, leading to faster decisions and better collaboration.
## Access the Comments panel
1. In the left sidebar, click **Features** > **Flags & Experiments**.
2. **Edit** an existing feature flag or **create a new one** (for more information on creating feature flags, see [this article](./create-a-feature-flag)).
3. On the feature flag configuration screen, click the **text bubble icon** in the top-right corner.
The **Comments** panel opens on the right side of the screen. The panel has two tabs: **Active** and **Archived**.
## Use comments to collaborate
### Add a new comment
1. In the **Active** tab, click **Add comment** and type your comment in the text field.
* To notify a teammate and help them find the comment, use the **@** symbol to tag them (for example, `@JaneDoe`).
2. Click **Save**.
### Reply to a comment
1. Find the comment you want to respond to.
2. Click **Add reply** beneath the comment.
3. Enter your response.
4. Click **Save**.
#### View and hide replies
* To view replies, click **Show reply** or **Show replies** (the number of replies is shown in brackets).
* To hide replies, click **Hide reply** or **Hide replies**.
### Edit or delete your comments
You can edit or delete comments that you posted.
1. Click the **three-dots menu** associated with your comment.
2. Click **Edit** to modify the text **or** **Delete** to permanently remove the comment.
## Manage comments
### Resolve and archive comments
Once a discussion is complete, mark the comment as resolved to declutter your active list.
* In the **Active** tab, click the **Checkmark icon** next to the comment you want to resolve.
The comment is marked as resolved and automatically moved to the **Archived** tab.
### View and unresolve archived comments
1. Click the **Archived** tab to view all resolved comments.
2. To move a resolved comment back to the active list, click the **checkmark icon** next to it.
The comment is marked as unresolved and moves back to the **Active** tab.
### Search and filter comments
Use the search bar above the comments list to quickly find specific discussions in either the **Active** or **Archived** tab.
### Adjust display settings
Customize how comments display in the list.
1. Click the **cog icon**.
2. Choose a sorting option:
* **Newest on top**
* **Oldest on top**
* **By author (A to Z)**
3. To filter the list, select the option to **only display comments tagging you**.
# Manage feature flag technical debt
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/manage-feature-flag-technical-debt
Track flag health and classify flags as temporary or permanent to proactively identify and clean up stale flags in your codebase.
Your feature flag dashboard can help in managing technical debt in your codebase and proactively cleanup obsolete or stale flags.
## Flag creation
When creating a new flag, you can define whether it’s a **temporary** or **permanent** flag. This distinction is crucial for managing technical debt effectively to keep track of their health and status moving forward.
* **Temporary Flags:** Used to control features that have a short-term purpose or are part of an ongoing experiment. They are ideal for situations where you need to roll out a new feature with safeguards or precisely schedule your release. Temporary flags are not intended to be part of your codebase in the long run and are thus regularly checked for staleness to ensure they are actively managed.
* **Permanent Flags:** Permanent flags are intended for long-term use and are meant to be a permanent part of your codebase. They are ideal for features that are core to your application’s functionality. Unlike temporary flags, permanent flags are exempt from staleness checks and Kameleoon will not highlight them for removal.
## Dashboard utilities for flag cleanup
Your dashboard features a summary of total active flags, running Experiments, and stale/permanent flag counts for your Production environment (only).
You also have two columns in the dashboard regarding flag status:
* **Last Evaluation:** This column displays the last time the feature flag in your code was referenced (for example, the most recent instance of an end user being evaluated by the flag in your application code to determine which variation to expose the user to), giving you a clear indication of when the flag was last in active use.
* **Status:** Based on its most recent evaluation and the last time it was edited or toggled in Kameleoon, a flag will be categorized into one of four possible statuses depending on whether it's permanent or temporary:
* **Healthy:** The **temporary** flag is new or has been edited or evaluated in the last 15 days, indicating active usage.
* **Stale:** The **temporary** flag has not been edited or evaluated in code for more than 15 days. This status may indicate that the rollout or experiment has reached a stable point and the flag is no longer being used, or that the flag has not been referenced in the code for a while.
* **Outdated:** The **temporary** flag has not been edited or evaluated in code for more than 30 days. This status is a clear sign that the flag may be outdated and no longer necessary.
* **Permanent:** The flag is **permanent** and exempt from staleness checks.
## Changing flag type
You can change a feature flag's type from temporary to permanent and vice versa. As features and projects evolve, the nature of certain features may change. Converting a flag’s type ensures it aligns with the current development trajectory.
Navigate to the secondary actions menu for any flag from the dashboard, and use the **Mark as temporary** button to change the flag type.
It’s useful to consider your short and long-term goals and ensure that flag types reflect them. This consideration keeps dashboard features effective for cleanup. If you’re working in a team, ensure everyone involved is aware of the rationale and importance of keeping track of technical debt in your codebase and in the Kameleoon app.
# Manage your feature flags
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/create-and-manage-flags/manage-your-feature-flags
Search, filter, sort, and inspect your feature flags and their rules from the Overview tab, in Collapsed or Expanded view, and perform actions on them.
To learn how to create a new feature flag, read [Create a feature flag](./create-a-feature-flag).
## Access the Feature flags dashboard
To access the Feature flags dashboard, click **Features** > **Flags & Experiments**. The dashboard opens on the Overview tab.
Use the environment dropdown to choose which environment's data the table displays:
* **Production**
* **Staging**
* **Development**
* **All environments**, which shows data from every environment at once and changes the table's layout. Read [View flags across all environments](#view-flags-across-all-environments) for details.
Use the view toggle to switch how the table displays your flags:
* **Collapsed:** A compact view showing one row per feature flag.
* **Expanded:** Shows each flag's rules beneath it, including each rule's name, type, and status.
## Collapsed view columns
In Collapsed view, each row represents a feature flag and displays the following columns:
* **Name:** The flag's name. A colored bar to the left of the name indicates the flag's project.
* **Rule status:** The number of active rules out of the flag's total rules, for example **2/3 rules Active**, with a colored dot indicating the status.
* **Rule type:** The number of rules of each type, shown next to a distinct icon for Targeted Delivery, [Experimentation](../using-the-rollout-planner/rules-and-targeting/create-feature-experiments), and [Progressive Delivery](../using-the-rollout-planner/rules-and-targeting/define-progressive-delivery-rules).
* **Modified:** The flag's last-modified date, shown as a relative time (for example, **yesterday**) or a date depending on how recently the change occurred.
* **Created:** The flag's creation date.
* **Tags:** The flag's tags.
* **Team:** The flag's team. Blank if the flag has no team.
If the table can't display every column at once, click the arrow at the end of the row to reveal the remaining columns.
## View additional details for a flag
Hover over the information icon on a flag's card to see additional details. The tooltip scrolls, so keep scrolling to see every field. It has two sections:
**On this environment** shows information specific to the environment you've selected in the dropdown, including its key dates, such as the **Last state changes** date, which shows when the flag's state last changed in that environment.
**On the feature flag (all environments)** shows information that applies to the flag generally, across all environments:
* URL
* Feature key
* Feature status, which refers to the flag's health rather than its on/off state. Read [Manage feature flag technical debt](./manage-feature-flag-technical-debt) to learn how Kameleoon calculates this status.
* Tags
* Creator
* Key dates: creation date, last content change, last modification, and last evaluation.
## Find a feature flag
Use the search bar, the Filters tab, and the Columns tab's sort options to locate specific flags.
Use the search bar at the top of the Overview tab to find a flag by name.
### Filter flags
Click **Filters** in the right sidebar to filter the flags in the table. Filter by:
* Project
* Tags
* State
* Health
* Key date
* Rule state
* Rule type
* Integrations
[Save these filters as a view](#select-a-view) for later retrieval.
Kameleoon generates a unique URL with custom parameters when you apply filters. To share this URL with team members, click **Copy link to this filtered dashboard** on the right side of the dashboard.
### Sort flags by modification date, creation date, or tags
Hover over the **Modified** or **Created** column header to reveal two arrows. Click the upward arrow to sort flags from least recent, or the downward arrow to sort flags from most recent.
Hover over the **Tags** column header to reveal the same two arrows, and click one to sort flags alphabetically or in reverse alphabetical order.
### Choose which columns appear
Click **Columns** in the right sidebar to choose which columns appear in the table. Check a column to show it, or clear it to hide it. Kameleoon always shows the **Name** column, which you can't hide. In Expanded view, this selection also determines which columns appear on each rule's row.
Besides the default columns covered in [Collapsed view columns](#collapsed-view-columns), you can also choose to display **ID/Key**, **Audience**, and **Traffic Allocation**.
Define a sorting rule under **Sort by**. For example, select **Name** from the first dropdown and **Sort A to Z** from the second dropdown to sort flags alphabetically by name.
## Select a view
Kameleoon applies the **Production environment** view by default.
Click **Views** in the right sidebar to select a saved view, or create a custom view to save your current filter and column settings.
To load a specific view automatically when the dashboard opens, set it as the default view by clicking the **three-dots** menu > **Default**.
Kameleoon generates a unique URL with custom parameters when you create a view. To share this URL with team members, click the **three-dots** menu > **Copy URL**.
## Turn a flag on or off
Click the toggle on a flag's card to turn the feature flag on or off. Read [Turn your feature flag on or off](../using-the-rollout-planner/basics/turn-your-feature-flag-on-or-off) for more detail.
## Edit a flag
Hover over a flag's card and click the pencil icon to edit the flag in the [Rollout Planner](../using-the-rollout-planner/basics/rollout-planner-structure).
## Use a flag's actions menu
Click the three-dots menu on a flag's card to access the following actions:
### Edit
Opens the flag in the [Rollout Planner](../using-the-rollout-planner/basics/rollout-planner-structure).
### Results
Opens the flag's overall Results page. Read [View your feature flag's overall results](../../../experiment-analytics/analyze-results/feature-flag-results/analyze-a-feature-flags-overall-results) to learn what it shows.
### Mark as permanent/temporary
Changes the flag's type. Kameleoon shows only the option that applies to the flag's current type, for example **Mark as Permanent** for a temporary flag. Read [Manage feature flag technical debt](./manage-feature-flag-technical-debt) to learn how Kameleoon tracks flag types.
### Rename
Rename an existing feature flag.
The **Rename** sidebar opens. To confirm the new name, click **Save**.
### Manage tags
Manage the tags associated with a feature flag.
The **Manage tags** sidebar opens. The list and the flag card highlight the tags already associated with the flag.
Associate existing tags or create new ones. Click **Save** to confirm your choices.
### Duplicate
Duplicate an existing feature flag to quickly create similar flags.
The **Duplicate** sidebar opens. To confirm the creation of the new feature flag, click **Save**.
Duplication clones the rule configurations (for all environments), flag setup, and the original flag's tags.
### Archive
Archives the flag.
### Delete
Delete an existing feature flag.
You must set the flag to OFF in all environments before you can delete it.
To validate the deletion, confirm your choice in the pop-up.
### Select
Selects multiple flags to apply a grouped action. Read [Perform grouped actions](#perform-grouped-actions) for the list of available grouped actions.
## Expanded view
In Expanded view, each flag's rules appear beneath it. Rule rows display the same columns you selected in the [Columns sidebar tab](#choose-which-columns-appear) as their parent flags, though each rule's status and type appear as text instead of an icon:
* **Name:** The rule's name.
* **Rule status:** Whether the rule is active or paused.
* **Type:** [Targeted Delivery](../using-the-rollout-planner/rules-and-targeting/define-targeted-delivery-rules), [Experimentation](../using-the-rollout-planner/rules-and-targeting/create-feature-experiments), or [Progressive Delivery](../using-the-rollout-planner/rules-and-targeting/define-progressive-delivery-rules).
* **Modified:** The rule's last-modified date.
* **Created:** The rule's creation date.
* **Tags:** The rule's tags.
* **Team:** The rule's team.
## View additional details for a rule
Hover over the information icon on a rule to see additional details: the rule's project, ID, type, status, and creation date, plus the associated experiment's ID and creation date.
## Edit a rule or view its results
Hover over a rule to access two icons:
* Click the pencil icon to edit the rule in the [Rollout Planner](../using-the-rollout-planner/basics/rollout-planner-structure).
* Click the results icon to open the rule's own Results page. What you see there depends on the rule's type. Read [Analyze a rule's results](../../../experiment-analytics/analyze-results/feature-flag-results/analyze-a-rules-results) to learn how each type differs.
## View flags across all environments
Selecting **All environments** from the environment dropdown changes the table's layout in both Collapsed and Expanded view.
In **Collapsed** view, each flag lists its environments beneath it (Production, Staging, and Development). Each environment row shows the date its state last changed and includes its own toggle to turn the flag on or off in that environment.
In **Expanded** view, the layout is similar, but each environment row also shows the flag's rules beneath it.
## Perform grouped actions
Apply actions to multiple feature flags simultaneously using the **Grouped actions** sidebar.
1. Click the **More options** (three-dots) menu on any feature flag card.
2. Click **Select**. The **Grouped actions** sidebar opens.
3. Select the checkboxes next to the feature flags you want to modify.
4. In the sidebar, click the action you want to perform:
* **Manage tags**
* **Archive**
* **Remove**
* **Mark as temporary**
* **Mark as permanent**
* **Turn on**
* **Turn off**
5. Confirm the action in the pop-up window.
# Create goals for feature flags
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/track-your-feature-experiments/create-goals-for-feature-flags
Add goals to your feature flags to track experiment and delivery performance across all environments using Kameleoon's reporting tools.
Goals help you measure the success of your product or feature releases and experiments. Goals are tracked across all environments (development, staging, and production) and for all delivery rules you've set.
Kameleoon reporting is only available if you've added **at least one goal**. If you remove all goals from an active flag, Kameleoon will stop tracking the flag and reporting will be unavailable.
Goals are not necessary for your feature flag if you're not using Kameleoon's reporting tools.
Click **Set up** > **Goals** > **Add goal**. Choose from existing goals or create a new one. [Learn more about creating goals](../../../assets/goals/create-a-goal).
You must choose at least one goal when creating a feature flag you want Kameleoon to report. The first goal you choose is automatically the **Primary goal**. Additional goals you add will be **Secondary goals**.
You can untrack a goal or assign a primary goal by clicking the three dots next to each goal.
# Managing third-party integrations
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/track-your-feature-experiments/managing-third-party-integrations
Configure which data Kameleoon sends to your third-party analytics tools for delivery rules and feature experiments.
Managing third-party analytics tools for your feature flags is simple once you've [set up your integrations](../../../integrations/integrations-overview).
Integrations for third-party tools are only compatible with web SDKs. They're not available for mobile SDKs.
Create or open a feature flag. Then, click **Reporting** > **Integrations**.
Accessing the Reporting section requires the Marketing role. Learn more in [User roles](/user-manual/account-and-team-management/users-and-teams/user-roles).
You must identify what data you want to collect and analyze before Kameleoon relays it to your third-party analytics tool. Use the **Integrations** page to identify what data is useful for a particular flag.
The **Admin** menu displays all the integrations you've linked to Kameleoon. You can also choose whether to export data for:
* **Delivery Rules**: Sync data for Targeted and Progressive delivery rules only.
* **Feature Experiments**: Sync data for Experiment rules only.
Choosing one or both of these options gives you control over how much data goes to your analytics tool. Check your integration configurations first to ensure your analytics data is accurate, relevant, and actionable.
You must implement our SDK and Kameleoon JavaScript tag to use this feature. We recommend implementing the [Kameleoon Asynchronous tag](../../../../developer-docs/web-experimentation/implementation-and-deployment/standard-implementation#asynchronous-tag-without-anti-flicker), which you can install before closing the `` tag in your HTML page. Use the Asynchronous tag for tracking purposes only.
All Kameleoon SDKs use the [`getEngineTrackingCode()`](../../../../developer-docs/sdks/web-sdks/nodejs-sdk#getenginetrackingcode) method to return the JavaScript code, insert it in your page, and automatically send the exposure events to the analytics solution you're using.
# Experiment on LLM prompts and AI-agent configurations
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/use-cases/ab-test-llm-prompts
Use Kameleoon feature flags to run controlled experiments on the prompts, models, and configurations behind an LLM application or AI agent, and measure impact with AI-quality, operational, and business metrics.
LLM-powered applications and AI agents are non-deterministic. Changing a prompt, model, retrieval strategy, tool configuration, or agent workflow can affect response quality, operating cost, latency, and user behavior in different, hard-to-predict ways. Evaluation frameworks such as RAGAS score whether an individual response meets a quality bar, but that score doesn't tell you whether the change helps users accomplish what they came to your product to do.
You can use Kameleoon Feature Experimentation capabilities to customize, test, and roll out the configuration behind a generative AI application or AI agent. A feature variable holds a single piece of that configuration (a prompt, a model parameter, a retrieval strategy, a tool definition), so your team can manage it outside your application code. Each variation represents a candidate configuration, which lets you iterate, experiment, and release changes more safely, without redeploying. For example, an AI customer-support agent might expose its system prompt, model, reasoning effort, and retrieval settings as four separate variables, so you can test a new combination of all four at once instead of waiting on a deploy for each one.
Split traffic between variations and compare their impact using several types of metrics:
* **AI-quality metrics**, such as correctness, groundedness, relevance, context quality, safety, or compliance
* **Agent-performance metrics**, such as successful tool use or task completion
* **Operational metrics**, such as latency, token consumption, errors, and cost
* **User and business metrics**, such as satisfaction, escalation, conversion, retention, and revenue
Because the configuration lives in a feature flag instead of your source code, you can add, edit, or roll back a variation directly from the Kameleoon platform at any time.
## Evaluation and experimentation solve different problems
Evaluation determines whether an individual model or agent output meets a defined quality standard. Observability tools let you inspect the prompts, responses, traces, retrieval steps, and tool calls behind that output. Experimentation determines whether a change to the underlying configuration causes a measurable improvement for users or the business: a question neither evaluation nor observability answers.
For example, an LLM judge might score a customer-support agent's rewritten system prompt as more grounded than its current one. A Kameleoon experiment answers the questions your team is accountable for: whether that same configuration resolves more tickets without escalating to a human, and what it costs in latency and token spend to get there.
Kameleoon doesn't replace your LLM observability or evaluation stack. Feed evaluator scores from RAGAS, an LLM judge, or a human review process into Kameleoon as a [custom goal](/user-manual/assets/goals/create-a-goal#custom-goal), and track those scores alongside the behavioral and business goals your experiment already measures. Your model-level quality signals then connect to a statistically reliable measurement of real user impact.
For most AI experiments, combine several metric types rather than relying on one:
* Set a user or business outcome as the primary goal.
* Track AI-quality metrics as secondary goals or guardrails.
* Monitor latency, cost, errors, and safety as operational guardrails.
* Validate automated judges against a sample of human-reviewed examples before you trust their scores at scale.
## How it works
An experiment on an LLM application or AI agent moves through five stages in Kameleoon:
1. **A feature flag holds the configuration.** Each part of the configuration, such as a prompt or a model name, becomes a feature variable on the flag.
2. **Each variation sets its own values.** A variation is one complete candidate configuration, with a value for every variable.
3. **The SDK assigns each visitor a variation.** When a visitor reaches your application, your code requests the flag and receives the assigned variation's values, then uses them to call the LLM or configure the agent.
4. **Goals record what happened.** Your application tracks a conversion against each goal attached to the flag, including a guardrail conversion that fires only when a response breaches an acceptable quality or latency threshold.
5. **The results page compares the variations.** After you collect enough traffic, compare the variations across every attached goal to decide which configuration to roll out.
## Prerequisites
* A Kameleoon account with a project set up for Feature Experimentation.
* Your account's client ID and client secret. To find these values, see [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials).
* A server-side application where you can install a Kameleoon SDK, for example a Python application.
## Set up your AI-agent experiment in Kameleoon
The following steps build one concrete experiment: does a rewritten system prompt, combined with a stronger model and a higher reasoning effort, help a customer-support AI agent resolve more tickets on its own, and does it keep latency within an acceptable range while doing so? Configure the feature flag, variations, and tracking goals in the Kameleoon platform before you touch your application code.
### Create the feature flag
Create a feature flag to hold your agent's configuration and control the rollout of your experiment.
1. In the Kameleoon app, click **Features** > **Flags & Experiments** > **New feature flag**.
2. Enter a name, for example `AI support agent config`, and select the project for the flag.
3. In the **Description** field, note what the flag controls, for example "Controls the system prompt, model, reasoning effort, and retrieval settings for the support chatbot," so other members of your team understand its purpose.
4. Click **Validate**.
5. Kameleoon generates a feature key from the flag's name. Note the generated key, or edit it to `ai_support_agent`. Your application code identifies the flag by this key, not by its name, so the two must match.
New flags start in the **OFF** state. You turn the flag on in the Rollout Planner after you finish configuring it.
For more detail, see [Create a feature flag](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag).
### Store the agent configuration in feature variables
Add one feature variable for each part of the agent's configuration you want to test, so you can change any of them from the Kameleoon platform without editing your application code. This example tests four variables:
| Variable key | Type | Example default value |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `system_prompt` | String | `You are the support assistant for Kameleoon's help center. Answer only using the article excerpts provided below, and say you'll escalate to a human agent if the answer isn't in them.` |
| `model` | String | `claude-sonnet-5` |
| `reasoning_effort` | String | `low` |
| `retrieval_top_k` | Number | `3` |
1. On the flag's page, in the left sidebar, click **Set Up** > **Variables** > **Add Variable**.
2. Set the variable's **Type** to match the table, either **String** or **Number**.
3. Enter the **Variable Key** from the table, for example `system_prompt`.
4. Set the **Default Value** to the value your application uses in production today. Every variation you create later starts pre-filled with these values, so accurate defaults save you work and give you a known-good configuration to fall back on.
5. Click **Save**.
6. Repeat these steps for each remaining variable in the table.
Kameleoon also offers an **Enum** type, where you enter the allowed values as a comma-separated list and then pick from a drop-down when you define variations. Consider it for a variable that only accepts a fixed set of values, since a drop-down prevents a typo from reaching your LLM provider. In this example, you could define `model` as an Enum with the list `claude-sonnet-5,claude-opus-5`, and `reasoning_effort` as an Enum with the list `low,medium,high`.
For more detail, see [Define feature variables](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variables).
### Create your variations
A delivery rule can only serve **Off** or a variation you created yourself, so an A/B comparison needs a variation for your current configuration as well as one for each new configuration you want to test. This example creates two variations: `Baseline`, which mirrors what your application already serves in production, and `Grounded, high reasoning`, a challenger that combines a rewritten, more explicit prompt with a stronger model and more reasoning effort.
Don't use **Off** as the comparison arm of an experiment, even if your application already has a hardcoded fallback for when it can't read the flag. **Off** represents your application with the flag turned off, and it carries none of the flag's feature variables, so code that reads `system_prompt` or `model` from an **Off** assignment gets nothing back. A hardcoded fallback doesn't solve that problem either: it lives in your source code, not in Kameleoon, so promoting a winning configuration later still means a deploy, and nothing keeps it in sync if the flag's variables change. Create an explicit `Baseline` variation instead, so your current configuration stays visible and editable alongside the challenger you're testing against it.
| Variation | `system_prompt` | `model` | `reasoning_effort` | `retrieval_top_k` |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------ | ----------------- |
| Baseline | Same as the default value | `claude-sonnet-5` | `low` | `3` |
| Grounded, high reasoning | `You are the support assistant for Kameleoon's help center. Using only the article excerpts provided below, answer the visitor's question and cite the specific article title for each claim you make. If the excerpts don't fully answer the question, say so explicitly and escalate to a human agent instead of guessing.` | `claude-opus-5` | `high` | `5` |
1. In the left sidebar, click **Set Up** > **Variations** > **Add variation**.
2. Enter a **Name**, for example `Baseline`, and a matching **Variation Key**, for example `baseline`. Each variable is pre-filled with its default value, so leave all four unchanged.
3. Click **Save**.
4. Repeat these steps for a second variation named `Grounded, high reasoning` (key `grounded_high_reasoning`), editing each of the four variables to match the value in the table for this variation.
5. Click **Save**.
For more detail, see [Define feature variations](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variations).
### Attach goals for business impact, AI quality, and latency
Attach several goals to the feature flag so you can compare variations across the outcomes your team is accountable for, not just response quality. Because Kameleoon is a unified platform, you can attach any goal that already exists in your organization, or create a goal specific to your LLM-powered feature. This example attaches three goals, one from each of the metric categories that matter for an AI agent:
| Goal | Metric category | Type | What it answers |
| ------------------------------------ | ----------------- | ----------- | ------------------------------------------------------------------- |
| `Ticket resolved without escalation` | User and business | Custom goal | Did the agent actually solve the visitor's problem? |
| `Response groundedness score` | AI quality | Custom goal | Did more responses fall below an acceptable groundedness threshold? |
| `Response latency` | Operational | Custom goal | Did more responses take longer than an acceptable threshold? |
Create all three as **Custom goals** that your backend triggers, since your application fires them rather than the visitor's browser. When you create each goal, select **Custom goal** as the **Type**, then choose [the option for a back-end event via SDK](/user-manual/assets/goals/create-a-goal#option-2-using-a-back-end-event-via-sdk-for-example-node-js).
1. On the flag's page, in the **Set Up** menu, click **Goals** > **Add goal**.
2. Select an existing goal, or click **Create a new goal** to define one. Add `Ticket resolved without escalation` first, since Kameleoon automatically sets the first goal you attach as the **Primary goal**.
3. Click **Save**.
4. Repeat these steps for `Response groundedness score` and `Response latency`, which Kameleoon attaches as **Secondary goals**.
If a goal ends up with the wrong designation, click the three dots next to it to reassign which goal is primary.
`Response groundedness score` and `Response latency` don't carry a numeric value. Your application decides whether a given response breached an acceptable threshold, either too slow or too ungrounded, and triggers the goal's conversion only when it did. Kameleoon then reports each goal's conversion rate per variation, telling you what fraction of responses breached that threshold.
For more detail on goal types, including how to trigger a custom goal from your backend, see [Create a goal](/user-manual/assets/goals/create-a-goal#custom-goal).
### Roll out the experiment
Add an Experiment rule that splits traffic between your two variations, then turn the flag on to start collecting data. The **Add a rule** menu groups rules by purpose. **Feature testing** contains the Experiment rule, which splits traffic and measures a statistically significant comparison between variations, while **Feature delivery** contains Progressive delivery and Targeted delivery, which release a single variation gradually or to a specific segment without comparing arms. An A/B test needs the Experiment rule.
1. In the **Rollout Planner**, select the environment you want to target, for example **Production**.
2. Click **Add a rule**, then under **Feature testing**, select **Experiment**.
3. Under **Variations to serve**, set `Baseline` as the **Control** and add `Grounded, high reasoning` as a **Treatment**. Kameleoon measures every treatment's results against the control, so the control must be the configuration you already run in production.
4. Set the traffic distribution across the two variations, for example 50% each.
5. Set the rule's targeting to include the visitors you want to test, for example all visitors who open a support conversation.
6. In the **Then, for everyone else in production, serve** drop-down, select `Baseline`. Visitors who fall outside the rule's targeting then receive your current, validated configuration, and your application still gets a full set of variables for them.
7. Turn the flag's **ON/OFF** toggle to **ON**.
8. Click **Save**.
For more detail, see [Create feature experiments](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/create-feature-experiments).
After you save the rule, Kameleoon starts assigning visitors to a configuration and serving the corresponding variables. To change a value or add a variation later, edit it directly in the Kameleoon platform. You don't need to redeploy your application to make these changes.
## Retrieve the configuration in your application
Install the Kameleoon Python SDK, then retrieve the visitor's assigned configuration and track a conversion for each goal as the visitor's ticket progresses. The same pattern applies to any [Kameleoon server-side SDK](/developer-docs/feature-experimentation/get-started/overview#server-side-sdks), including Node.js, Java, and Go. Because Kameleoon only supplies the configuration values, the same pattern also works with any agent framework, such as the OpenAI Agents SDK, the Claude Agent SDK, or LangChain. Most agent code runs on Python or TypeScript, so pick whichever matches your application.
1. Install the SDK as a dependency:
```bash theme={null}
pip install kameleoon-client-python
```
2. Initialize the client with your site code and credentials. Set `environment` to the same Rollout Planner environment that holds your Experiment rule, otherwise the SDK evaluates a different environment's rules:
```python theme={null}
from kameleoon import KameleoonClientConfig, KameleoonClientFactory
SITE_CODE = "a8st4f59bj"
FEATURE_KEY = "ai_support_agent"
TASK_GOAL_ID = 12345 # "Ticket resolved without escalation"
QUALITY_GOAL_ID = 12346 # "Response groundedness score"
LATENCY_GOAL_ID = 12347 # "Response latency"
configuration = KameleoonClientConfig(
client_id="your-client-id",
client_secret="your-client-secret",
environment="production",
)
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration)
if not await kameleoon_client.wait_init_async():
# The SDK failed to initialize. Fall back to your production configuration.
...
```
3. Retrieve the assigned configuration before you call your LLM, and track a conversion for each goal as the visitor's ticket progresses:
```python theme={null}
from anthropic import AsyncAnthropic
judge_client = AsyncAnthropic()
# Mirrors the flag's default values, for use when the SDK can't reach Kameleoon.
FALLBACK_CONFIG = {
"system_prompt": "You are the support assistant for Kameleoon's help center. ...",
"model": "claude-sonnet-5",
"reasoning_effort": "low",
"retrieval_top_k": 3,
}
# A response breaches the latency guardrail above this value.
LATENCY_THRESHOLD_MS = 5000
# A response breaches the groundedness guardrail below this value.
QUALITY_THRESHOLD = 0.7
def get_agent_config_for_visitor(visitor_code: str) -> dict:
try:
variation = kameleoon_client.get_variation(visitor_code, FEATURE_KEY)
# These exception classes ship with the Kameleoon SDK.
except (FeatureNotFound, FeatureEnvironmentDisabled, VisitorCodeInvalid):
# The visitor isn't in the experiment, so serve the known-good configuration.
return FALLBACK_CONFIG
variables = variation.variables
if not variables:
return FALLBACK_CONFIG
return {
"system_prompt": variables["system_prompt"].value,
"model": variables["model"].value,
"reasoning_effort": variables["reasoning_effort"].value,
"retrieval_top_k": int(variables["retrieval_top_k"].value),
}
def track_ticket_resolved(visitor_code: str) -> None:
kameleoon_client.track_conversion(visitor_code, TASK_GOAL_ID)
# LLM-as-a-judge: extracts the factual claims in `response` and scores
# the fraction that `retrieved_context` supports.
async def score_response_groundedness(retrieved_context: str, response: str) -> float:
judge_prompt = (
"List the factual claims in RESPONSE. For each claim, check "
"whether CONTEXT supports it. Return only a number from 0 to 1: "
"the fraction of RESPONSE claims that CONTEXT supports.\n\n"
f"CONTEXT:\n{retrieved_context}\n\nRESPONSE:\n{response}"
)
judge_reply = await judge_client.messages.create(
model="claude-opus-5",
max_tokens=10,
messages=[{"role": "user", "content": judge_prompt}],
)
return float(judge_reply.content[0].text)
def track_quality_score(visitor_code: str, score: float) -> None:
if score < QUALITY_THRESHOLD:
kameleoon_client.track_conversion(visitor_code, QUALITY_GOAL_ID)
def track_response_latency(visitor_code: str, latency_ms: float) -> None:
if latency_ms > LATENCY_THRESHOLD_MS:
kameleoon_client.track_conversion(visitor_code, LATENCY_GOAL_ID)
```
Call `get_agent_config_for_visitor()` with the visitor's `visitor_code` before you send a request to your LLM, and use the returned values to build the request, the system prompt, model, reasoning effort, and number of retrieved documents. Call `track_ticket_resolved()` when the agent resolves the visitor's issue without escalating to a human. After the agent responds, call `score_response_groundedness()` with the documents it retrieved and the response it generated, then pass the returned score to `track_quality_score()`. Call `track_response_latency()` with the response time in milliseconds after each LLM call. Both `track_quality_score()` and `track_response_latency()` track a conversion only when the value breaches its threshold, so a response that stays within both guardrails triggers neither goal.
`score_response_groundedness()` is a minimal LLM-as-a-judge example: it asks a model to compare the response's claims against the retrieved context and return the fraction it supports. [RAGAS's Factual Correctness metric](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/factual_correctness/) scores the same underlying idea, and you can substitute it, or another evaluation framework your team already uses, for a hand-rolled judge prompt.
Kameleoon then reports each goal's conversion rate per variation, telling you what fraction of responses breached the quality or latency guardrail, rather than tracking the raw score or millisecond value itself.
Always handle the case where a visitor falls outside the experiment. An LLM call built from a missing prompt or model fails at request time, so return a complete fallback configuration rather than letting a lookup raise or return `None`.
Use [`get_visitor_code()`](/developer-docs/sdks/web-sdks/python-sdk#get_visitor_code) to assign a unique ID to each visitor, and [`set_legal_consent()`](/developer-docs/sdks/web-sdks/python-sdk#set_legal_consent) if your application requires visitor consent before tracking data. For the full client initialization and configuration reference, see the [Python SDK developer guide](/developer-docs/sdks/web-sdks/python-sdk#developer-guide).
## Monitor and iterate
Open the feature flag's results page to compare `Baseline` and `Grounded, high reasoning` across all three attached goals. Kameleoon tracks exposures and conversions automatically whenever your application calls `get_variation()` and `track_conversion()`, so you don't need any additional instrumentation.
Read the three goals together rather than in isolation. The challenger in this example runs a larger model at a higher reasoning effort and retrieves more documents, so it costs more per conversation and is more likely to breach the latency guardrail. A win on `Ticket resolved without escalation` justifies that trade only if `Response latency` and `Response groundedness score` don't convert more often for the challenger than for `Baseline`. If the primary goal moves but a guardrail's conversion rate rises past what you're willing to accept, keep serving `Baseline` and refine the challenger.
You don't need to watch the results page yourself to catch a challenger that underperforms. Add a rollback condition to the experiment rule, for example turning it off when `Response groundedness score` breaches a threshold you define, and Kameleoon automatically disables the rule and returns all visitors to `Baseline` once the condition triggers.
See [Automatically rollback a feature](../using-the-rollout-planner/validation-and-rollback/automatically-rollback-a-feature).
When a challenger wins, promote it: update each variable's **Default Value** to the winning configuration so it becomes the new known-good baseline, then retire the experiment rule or reuse the variation for your next hypothesis.
For more detail, see [Analyze a feature flag's overall results](/user-manual/experiment-analytics/analyze-results/feature-flag-results/analyze-a-feature-flags-overall-results).
## Next steps
* Read the [Python SDK reference](/developer-docs/sdks/web-sdks/python-sdk) for advanced options such as custom data, cross-device experimentation, and targeting conditions.
* Attach [precise segmentation criteria](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) to target the experiment at a specific audience, for example only tickets tagged with a certain product area.
* Add a token-cost goal alongside latency, tracking tokens consumed per conversation as a numeric custom goal, so you can price the difference between a Sonnet and an Opus configuration directly. See [Create a goal](/user-manual/assets/goals/create-a-goal#custom-goal).
* Add a context-relevance goal to check whether raising `retrieval_top_k` actually improves which documents the agent retrieves, since a grounded answer can still come from the wrong documents. See [Create a goal](/user-manual/assets/goals/create-a-goal#custom-goal).
* Add a direct user-feedback goal, such as a thumbs-up or thumbs-down control after each response, to capture visitor satisfaction alongside the behavioral signals this example already tracks. See [Create a goal](/user-manual/assets/goals/create-a-goal#custom-goal).
* Add more variables to test other parts of the agent's configuration, such as temperature, tool definitions, or a fallback model for retries. See [Define feature variables](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variables).
* Validate your `Response groundedness score` threshold by comparing a sample of automated scores against a human review before you trust it at scale. See [Create goals for feature flags](/user-manual/experimentation/feature-experimentation/track-your-feature-experiments/create-goals-for-feature-flags).
# Build whitelists to roll out a feature to internal users
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/use-cases/build-whitelists-to-rollout-a-feature-for-internal-users
Use visitor code whitelists and targeted delivery rules to QA feature experiments with specific internal users before a broader release.
If you want to QA a feature experiment or roll out a feature variation to an internal group of users, you can combine a user whitelist with a targeted delivery rule. This combination is one of the easiest ways to do it.
For example, suppose you want to release a new feature with two variations: Feature A and Feature B. Before launching the experiment, you want to QA its live behavior by showing Feature A to a group of internal users and Feature B to a group of stakeholders. Follow these steps to set up that QA test:
1. Create segments of whitelisted users (Group A and Group B).
2. Create a targeted delivery rule for each group of users.
Avoid setting many user IDs (fewer than 20 per variation): the size of your data file increases, and so does the latency, since the SDK must fetch a larger file. If you want to target more users, you can set a custom data attribute for the whole audience (for example, internal users only), then target the experience with that audience.
## Create a targeted delivery rule for each group of users
1. Click **Activate** > **Feature flags** and edit your feature flag.
2. Add a new rule and select **Targeted delivery**.
3. On the right side of the panel, create a new segment (Group A) and look for the **Visitor code** condition. Add the user IDs that you want to be part of Group A.
4. Choose the variation you want to serve, for example, Variation A. All users from Group A receive Variation A of your flag.
5. Add a second **Targeted delivery** rule and replicate the steps for Variation B and Group B.
# Run feature experiments with feature flags
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/use-cases/run-feature-experiments-with-feature-flags
Run data-driven feature experiments using feature flags to validate hypotheses, reduce risk, and optimize user experiences at scale.
## Are feature flags all you need to experiment?
Feature experiments using feature flags enable a powerful and data-driven approach for all teams to test hypotheses and validate assumptions before fully releasing new features to users.
By gradually rolling out experiments to targeted user segments, teams can gather valuable insights and fine-tune their products to meet user needs effectively. This article will guide you through running a feature experiment using Kameleoon, helping you optimize user experiences and drive engagement for your products.
## Is feature experimentation the right option for you?
Feature experiments using feature flags offer several advantages over traditional web experimentation approaches. Here are some key reasons why you should consider making the switch:
* **Advanced server-side experimentation:** Feature experiments offer all the benefits you may associate with server-side testing such as reduced client-side dependencies, improved performance, enhanced security, and granular targeting. Feature experimentation also ensures consistency across different platforms, version independence, and compliance with data privacy regulations – making it vastly scalable for larger user bases.
* **Real-time Control and Safety:** With feature flags, you can control the rollout of a new feature in real-time. This control provides a safety net to quickly disable the feature if any issues arise, ensuring a smooth user experience and minimizing potential negative impacts—all without having to write or deploy any new code.
* **Gradual Rollout and Risk Reduction:** Feature flags allow for gradual feature rollout to a subset of users. This controlled release mitigates risks associated with full deployment, letting you test the feature in a controlled environment before exposing it to your entire user base.
* **Iterative Development:** Feature experiments using dynamic variables facilitate iterative development. Product teams can make continuous improvements to a feature based on user feedback and data insights, without requiring a full redeployment.
* **Faster Experimentation Cycles:** Feature flagging speeds up experimentation cycles since you can quickly introduce, modify, or remove features without redeploying the entire application.
* **Reduced Technical Debt:** Traditional web experimentation may require maintaining multiple code branches to support different variations of the experiment. Depending on your team’s practices, feature flags centralize this control, reducing technical debt and code complexity.
* **Enhanced Collaboration:** Feature flagging fosters collaboration between product, engineering, and business teams. It enables cross-functional teams to work together seamlessly on feature development and experimentation. Feature experimentation is also more well-suited for modern development practices.
Overall, feature experiments using feature flags give your teams greater control, flexibility, and speed, making them a more efficient and effective approach to validating hypotheses and improving product features.
## Step-by-step guide
Getting started with feature flags for experimentation may seem complex, but a simple, systematic approach can ensure successful implementation and testing and set you up for long-term success. It helps to clearly outline your experimentation goals and what you want to achieve with feature flagging. Identify specific features or hypotheses you wish to test and validate. This planning will give you a clear direction and purpose for using feature flags in your experimentation process.
### Step 1: Identify the hypothesis
Begin by clearly defining the hypothesis you want to test, for example, a change you believe should move your metrics in an expected direction.
For instance, if you have new ideas for a streamlined checkout process that will increase conversion rates, formulate your hypothesis accordingly.
### Step 2: Create a feature flag
Now, [create a feature flag in Kameleoon](../create-and-manage-flags/create-a-feature-flag) for the new checkout process feature and keep it off for the time being, so the new checkout flow is initially hidden from all users.
### Step 3: Variabilize your feature (optional)
When your developer codes your new checkout process, they can [use Kameleoon’s feature variables](../configure-your-feature-flags/define-feature-variables) to ensure they won’t have to revisit the source code again. They can use the Kameleoon app to dynamically update values and parameters inside your code using variables if you are testing different versions of the same feature.
### Step 4: Targeting and segmentation
[Decide which user groups or segments](../using-the-rollout-planner/rules-and-targeting/add-a-new-rollout-rule) will be part of the experiment. Kameleoon lets you target specific demographics, user attributes, or even beta testers to receive the new feature.
### Step 5: Start your experiment
[Initiate the experiment by rolling out the variants of your streamlined checkout process to a small percentage of the targeted users](../using-the-rollout-planner/rules-and-targeting/define-progressive-delivery-rules). Controlling the rollout percentage helps you minimize risks and measure the feature’s impact, while ensuring you can still test your ideas.
### Step 6: Monitor and analyze
As users interact with the new checkout flow, monitor their behavior using the Results page. Track essential metrics such as conversion rates, user engagement, and drop-off points to assess performance. You can now easily [compare the performance](../../../experiment-analytics/analyze-results/feature-flag-results/analyze-a-rules-results) of the experiment group (users with the new feature) against the control group (users without the feature). Analyze the data to determine if the streamlined checkout process positively influenced user behavior.
If needed, you can also export your experiments' results to any of the several partnered third-party tools Kameleoon allows integrations with.
### Step 7: Iterate and make decisions
Based on the experiment's results, make informed decisions about whether you want to roll out the best-performing checkout variant to a larger percentage of your users. If the data supports the hypothesis, proceed with a full rollout to all users. Alternatively, if the results are inconclusive or disappointing, iterate on the feature by tweaking your variables and variations from the app, and conduct additional experiments to optimize its conversion rates.
## Conclusion
Running feature experiments using feature flags equips your teams with valuable insights, helping them validate hypotheses and optimize user experiences. By leveraging feature management tools to control feature rollout and collect real-time data, teams can refine their products with confidence and deliver exceptional user satisfaction. Remember to utilize data-driven insights from feature experiments to continuously enhance your product, staying responsive to user needs and preferences as your product evolves.
# Rollout Planner structure
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/basics/rollout-planner-structure
Understand the Rollout Planner layout, including the header, setup menu, delivery rules section, and rollout summary.
The Rollout Planner consists of several blocks.
* A **header** in the top left indicating the flag's name, associated site code, and feature key.
* A **Setup** menu to create and manage your feature variables and feature variations.
* A **Rollout Planner** specific to each of your environments. Changes made to a feature flag are specific to the environment you select in this section.
* A **reporting section** which lists the Results pages for your created experiments.
* A **toggle** that turns your feature flag on or off.
* A **Delivery rules** section, where you add your rollout rules.
* A **rollout summary** that summarizes the variations you're deploying through your rollout rules and the segments your rollout rules target.
Accessing the reporting section requires the Marketing role. Learn more in [User roles](/user-manual/account-and-team-management/users-and-teams/user-roles).
# Turn your feature flag on or off
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/basics/turn-your-feature-flag-on-or-off
Toggle your feature flag on or off and configure the default variation served to users not targeted by any rollout rule.
You can turn your feature flags on or off.
## Choosing a default variation
At the end of your rollout rules queue, there's a dropdown list that defines which variation Kameleoon delivers to users that aren't targeted by any rule.
* **Example 1:** If you want to roll out a new feature to 10% of your audience, Kameleoon delivers this default variation to 90% of users.
* **Example 2:** If you have two delivery rules running with each targeting 40% of your total audience, the remaining 20% receive this default variation.
Kameleoon automatically sets the default variation to the **Off** variation. However, you can change which variation appears by default. Changing the default variation has no effect when you turn your flag off.
## Manual toggle
The manual toggle is the primary method of controlling your flag's state (on or off).
When you turn your feature flag toggle **on**, Kameleoon evaluates all delivery and experiment rules you've defined in the rules queue. However, while **off**, Kameleoon doesn't evaluate any delivery rules.
# Using the Activity Log
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/basics/using-the-activity-log
Monitor and troubleshoot feature releases using the Activity Log's chronological record of actions performed on a feature flag.
The Activity Log is available for each feature flag you create. You can use the Activity Log to monitor and troubleshoot feature releases.
Create or edit a feature flag, and click **Reporting** > **Activity Log**.
Accessing the Reporting section requires the Marketing role. Learn more in [User roles](/user-manual/account-and-team-management/users-and-teams/user-roles).
The **Activity Log** menu provides a chronological record of actions performed on this feature flag.
Click the **eye** icon to view changes' details.
## Filters
The available filters are on the right side of the screen:
* Filter by environment
* Filter by date range
* Filter by event type
* Filter by flag contributor
# Multi-armed bandit optimizations for feature experiments
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/optimizations-and-scheduling/multi-armed-bandit-optimizations-for-feature-experiments
Learn how to use multi-armed bandits and contextual bandits to maximize experiment performance through dynamic traffic allocation.
Kameleoon offers two types of dynamic traffic allocation algorithms to help maximize experiment performance: **multi-armed bandits (MABs)** and **contextual bandits**. Both approaches use real-time performance data to allocate more traffic to better-performing variations but differ in how they treat user data. The following sections explain how these algorithms work, when to use them, and how to activate them in your experiments.
To enable dynamic traffic allocation, create a new experiment, or open an existing one.
In the **Variation to serve** section, select the preferred allocation from the dropdown menu. Choose between **Multi-armed bandit** or **Contextual bandit** optimization.
Kameleoon updates the allocation based solely on the lift of the primary goal.
## Multi-armed bandits
When using dynamic allocation (such as MABs), you can't manually edit exposure rates. Instead, Kameleoon automatically measures improvement over the original variation and estimates the gain in total conversions using the Epsilon Greedy algorithm. Kameleoon repeats this process hourly. The MAB algorithm redirects traffic to higher-performing variations, even without statistical significance, which can drastically reduce the time required to identify winning or losing variations.
Auto-optimized experiments rely on the original variation ("off" for Feature Experiments) to optimize the deviations. If the original variation doesn't receive traffic, the deviation might not update, causing the allocation to remain at 50/50 despite a clear winning variation.
MABs don't rely on a control or baseline experience. Unlike A/B tests, MABs prioritize improvement over an initial equal allocation and dynamically adjust traffic based on real-time performance. In cases where statistical analysis is less important and you must minimize "exploration" time, MABs are useful because they focus more on "exploitation."
## Contextual bandits
Contextual bandits dynamically optimize traffic allocation in experiments using machine learning. They adapt in real-time to redistribute traffic based on variation performance and user context to maximize effectiveness.
Key differences distinguish multi-armed bandits from contextual bandits:
* **Multi-armed bandits:** These optimize traffic distribution among multiple variations (arms) to maximize a defined goal, such as click rates or conversions. They treat all users equally, with no distinction based on user attributes, which suits scenarios where user-specific data is unavailable or unnecessary and the focus remains on finding the highest-performing variation for the overall audience. Kameleoon places no limit on the number of variations you can use with multi-armed bandits.
* **Contextual bandits:** These incorporate additional user-specific data, such as device type, location, or behavior, into decision-making. They facilitate more personalized decisions by tailoring variations to specific users for improved outcomes. The variability introduced by user attributes allows contextual bandits to optimize decisions in dynamic environments. Contextual bandits support a maximum of 5 variations, including the original, because of how the underlying machine learning model works.
While multi-armed bandits optimize traffic allocation uniformly across users, contextual bandits leverage contextual data to make more personalized, data-driven decisions.
Read the [Dynamic traffic allocation](https://www.kameleoon.com/blog/dynamic-traffic-allocation) article to learn more about how MAB optimization works, or read the [Kameleoon statistical paper](https://storage.googleapis.com/kameleoon-storage-documentation/user-manual/pdf/statistics-at-kameleoon.pdf) to dive deeper into the technical details of the MAB algorithm.
# Reshuffle traffic for a rule
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/optimizations-and-scheduling/reshuffle-a-traffic-rule
Manually redistribute user traffic across variations for an active rule, re-bucketing users to adjust your experiment's distribution.
Reshuffling lets you manually redistribute your user segment's traffic towards the chosen variations for any active rule. You initiate a complex re-bucketing process by reshuffling, meaning that Kameleoon may expose users to different variations than before.
To reshuffle traffic for a rule:
1. Navigate to the delivery or experiment rule for which you want to reshuffle traffic.
2. Click the three-dots menu.
3. Click **Reshuffle**.
**Reshuffle only takes effect after saving**. You can dequeue the reshuffle action by repeating the same steps and choosing **Undo reshuffle**.
Once saved, Kameleoon redistributes traffic among the rule’s variations. Some users may see a different variation than they previously encountered, while others may continue to see the same variation.
If you are monitoring results and metrics for an ongoing feature experiment or delivery, reshuffling traffic skews your results and may impact user behavior and key metrics.
Use reshuffling when results prior to it are irrelevant or unnecessary. Avoid reshuffling any rule that's active for a substantial amount of time since results are likely invalidated after reshuffling.
# Schedule a feature's rollout
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/optimizations-and-scheduling/schedule-a-features-rollout
Schedule the start and end dates for rollout rules to automatically activate or deactivate a feature at a specified time.
You can schedule when a rule should activate or reactivate.
A calendar opens when you select a start or end date. Use the calendar to pick the date and time for the rule to take effect or expire.
# Add a new rollout rule
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/add-a-new-rollout-rule
Add and configure rollout rules in the Rollout Planner to control feature delivery with targeted, progressive, or experiment-based strategies.
## What are rollout rules?
The Rollout Planner gives you granular control over your releases and tests. You can activate or deactivate any feature flag at any time for specific users.
Rollout rules are like conditional statements for your releases and experiments. You can set up a sequence of actions that triggers under certain conditions. You can schedule these rules, apply them immediately, target them to specific groups, reorder them, and customize them to align with your goals.
## Add a new rule
Click **Add a rule** to open the rule configuration menu.
Here, you can choose between delivery or testing rules, and name your rule.
You can combine rules of any type to implement your feature's rollout strategy. Kameleoon lets you add rules for [Targeted Delivery](./define-targeted-delivery-rules), [Progressive Delivery](./define-progressive-delivery-rules) and [Feature Experiments](./create-feature-experiments).
## How does the rule queue work?
Once you’ve added your rollout rules, it's important to understand how Kameleoon evaluates the queue:
* Kameleoon checks if your flag is on or off. If it's off, visitors see the default variation (which you can choose in the "*Then, for everyone else in production, serve*" dropdown list).
* If you turn the flag on, Kameleoon evaluates experiments and rules in the queue in a top-to-bottom order. Keep the evaluation order in mind when planning your rollout strategy to prevent unforeseen targeting overlaps.
* Kameleoon adds new rules to the bottom of the queue by default. However, you can manually reorder rules by clicking and dragging its card to a new position. Reordering rules in the queue also changes the order in which Kameleoon reads and evaluates the rule. Be mindful when delivering rules that share the same audience.
* Paused rules are simply ignored at runtime.
### User targeting and bucketing
Exposing a user to a variation follows a two-step process: **targeting** and **bucketing**. Targeting means the user meets the conditions specified in a rule. Bucketing means Kameleoon has assigned the user to the variation associated with that rule.
Kameleoon handles targeting and bucketing differently for delivery and experiment rules.
Consider these two scenarios:
#### Scenario 1: Delivery rule at the top
If Kameleoon first targets a visitor for a Targeted/Progressive Delivery rule:
* They receive the selected variation if Kameleoon buckets them.
* If targeted, but not bucketed, the visitor receives the "Everyone else" variation, and Kameleoon doesn't evaluate the visitor against any other rule.
```mermaid theme={null}
flowchart TD
A["Delivery rules"] --> B(["🎯 Targeted"])
A --> C(["✕ Not targeted"])
B --> D["✅ Exposed"]
B --> E["⬜ Not exposed"]
C --> F["⏭️ Go to the next rule"]
D --> G["📊 Bucketed into a variant"]
E --> H["📊 See default variation *"]
```
The variant marked with an asterisk (\*) is the one selected in the "Then, for everyone else in production, serve" dropdown list.
#### Scenario 2: Experiment rule at the top
* If Kameleoon targets a visitor with an Experiment rule:
* They receive the selected variation if Kameleoon buckets them.
* If Kameleoon targets them, but doesn't bucket them, it checks the next rule until the end of the queue. All users whom experiment rules don't bucket move down the queue, so it's always a good practice to keep experiments at the top of your queue.
```mermaid theme={null}
flowchart TD
A["Experiment rule"] --> B(["🎯 Targeted"])
A --> C(["✕ Not targeted"])
B --> D["✅ Exposed"]
B --> E["⬜ Not exposed"]
C --> F["⏭️ Go to the next rule"]
D --> G["📊 Bucketed into a variant"]
E --> H["⏭️ Go to the next rule"]
```
Changing the traffic split for an experiment doesn't change the total size of your experiment bucket. For example, say you launch an experiment that targets **20%** of a user segment with a variation split of 50/50 for its two variations. If you update the split to 60/40 or 90/10, but don't change the percentage of traffic included in the experiment sample (**20%**), the total bucketed users don't increase or decrease. Instead, some bucketed users get exposed to a different variation.
When there are no more rules in the queue, all remaining users receive the "Everyone else" variation.
### Rule states
All rules in the queue display one of these states:
* **Active** (is live)
* **Paused**
* **Planned** (scheduled to start and/or stop at a given date/time). Planned rule changes to *active* at the defined schedule or *outdated* at the end of it.
* **Unsaved changes** (this also includes new rules that are in the draft state)
* **Outdated** (a planned rule that automatically turned off at scheduled end date). The default view hides outdated rules, but you can use filters to view them.
## Pause or resume a rule
To pause a rule, click the three-dots menu on an experiment's card and click **Pause**.
Kameleoon ignores paused rules at runtime. You can resume the rule later in the same menu.
## Copy rules from another environment
You can also add rules you created in another environment. Copying rules lets you replicate your rollout/experiment setup from your **staging** environment to your **production** environment, for example.
The rule configuration menu offers these rule types:
| Category | Rule type | Description |
| ---------------- | -------------------- | --------------------------------------------------------------------- |
| Feature testing | Experiment | Run a test to compare the KPI impact of different feature variations. |
| Feature delivery | Targeted Delivery | Target a custom audience to roll out a feature variation to. |
| Feature delivery | Progressive Delivery | Gradually roll out a feature variation to a custom audience. |
| Other | Copy | Copy rules from another environment. |
Select **Copy** when adding rules in your destination environment and select the source environment in the next step.
You'll have the option to append the copied rules at the bottom of your rules queue, or replace all existing rules with the copied rules.
## Rollout summary
This section provides an overview of **variations** and **segments**.
Changing the cards' order, deleting a rule, or changing a rule's status affects the ordering and values inside summary cards.
While the summary section accounts for untargeted (remaining) users that Kameleoon can pass down to the next rule, it doesn't account for or identify any partial or complete overlaps between different user segments across different rules.
### Variations summary
This section provides an overview of which variations your delivery and experiment rules have used.
Variations that target multiple segments have multiple bars displaying the percentage of the audience you have targeted.
### Segments summary
This section summarizes the different user segments that your rollout rules target.
Variations assigned to a segment combine to reach a maximum of 100%. If you exceed this limit, Kameleoon ignores any remaining variations.
## Using outdated SDKs
If your SDK's version doesn't support [Feature Variations](../../../../../developer-docs/feature-experimentation/get-started/overview#supported-platforms), keep a few things in mind when adding new rules for a feature flag:
* Kameleoon checks only the rules defined in the Production environment and ignores rules you created in the staging or development environments.
* Kameleoon evaluates only the first rule in the queue and ignores any rules below it. If there are no rules at all, Kameleoon serves the default variation defined in your rollout.
* Kameleoon only supports the default variations **On** and **Off**.
* Kameleoon doesn't support start/stop scheduling of rules.
Visit Kameleoon's [Github](https://github.com/Kameleoon) and subscribe to notifications to stay up to date with all SDK releases.
# Create feature experiments
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/create-feature-experiments
Create experiment rules to deliver and compare multiple feature variations, measuring their performance against your defined goals.
With Experiments, you can create different variations of your features and test them to compare their performance. By combining variations and experiments, you can efficiently and continuously test and improve your features.
Experiments let you deliver various feature variations to set up your feature test and define the distribution among them.
You must associate at least one [goal](../../track-your-feature-experiments/create-goals-for-feature-flags) with your experiment.
# Define Progressive Delivery rules
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/define-progressive-delivery-rules
Configure progressive delivery rules to gradually roll out a feature to an increasing audience using linear or custom ramp-up schedules.
Progressive rollouts let you spread out large feature releases by gradually rolling them out to an increasing audience. You can customize the feature variation you want to roll out, the audience you want to target, and the interval and increment size of the ramp-up.
When setting up the exposure for your Progressive Delivery rule, you can select from two types of ramp-ups: **linear** or **custom**.
## Linear ramp-up
When configuring your linear ramp-up, you must define the following custom parameters:
* The rollout's start date.
* Initial exposure (audience percentage immediately exposed to the feature).
* Increment percentage for rollout audience.
* Time interval between increments.
* Final exposure limit: define the percentage at which you want the rollout to stop. Below this section, a confirmation shows when and at what exposure percentage the rollout stops.
## Custom ramp-up
Click **Add step** to add a custom increment. You must select a date/time and an exposure rate for each step you add.
# Define Targeted Delivery rules
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/define-targeted-delivery-rules
Enable a feature variation for specific user segments using Targeted Delivery rules based on attributes like location, device, or demographics.
Targeted Delivery is the easiest way to enable a feature variation for specific users or your entire audience. You can use multiple Targeted Delivery rules to implement advanced rollout strategies that suit your needs.
Use Targeted Delivery rules to gain rollout flexibility based on user attributes, such as geographical region, demographic data, or operating system.
# Target groups of users with rules
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/rules-and-targeting/target-groups-of-users-with-rules
Select or create segments to target specific user groups in your rollout rules using Kameleoon's available SDK targeting conditions.
You must select a segment or create a new one when creating a rule in the **Targeting** section.
Select one of the three targeting conditions available:
* **Target all visitors**: Includes your entire user base. Chosen by default.
* **Target a segment:** You can choose from a drop-down of existing segments or create a new segment in the segment builder by clicking **+**.
* **Target specific visitors:** This method is a lite version of the segment builder, allowing you to create common targeting conditions using *Custom Data* or *Visitor Code* attributes to define an audience without creating and saving a new segment. Don't use this method if the target audience requires sophisticated targeting.
## SDK conditions available
If you want to create a new segment or add precise targeting conditions for choosing your audience, you can use Kameleoon’s pre-existing conditions available [depending on which SDK you’re using](../../../../../developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation):
* **Browser:** Includes or excludes visitors based on their browser.
* **Device:** Includes or excludes visitors based on their device type: phone, tablet, or desktop.
* **Conversion:** Includes or excludes visits during which a visitor converts a specific goal.
* **Custom Data:** Includes or excludes visits based on a custom data's value.
* **Page URL:** Includes or excludes visitors based on the displayed page's URL.
* **Page Title:** Includes or excludes visitors based on the displayed page's title.
* **SDK Language:** Includes or excludes visitors based on their languages.
* **App Version**: Includes or excludes visitors based on their app's version.
* **Visitor Code:** Includes or excludes visitors based on their visitor code.
* **Browser Cookie:** Includes or excludes visitors based on the presence of a cookie in their browser, and possibly its value.
* **Operating System:** Includes or excludes visitors based on their operating system.
* **IP Geolocation:** Includes or excludes visitors based on their location.
* **Segment:** Includes or excludes visitors based on their Kameleoon segment.
* **Previous Page:** Includes or excludes visitors based on the previous page's URL.
* **Number of Page Views:** Includes or excludes visitors that have seen a specific number of pages.
* **Time since First Visit:** Includes or excludes visitors based on the time elapsed since their first visit.
* **Time since Last Visit:** Includes or excludes visitors based on the time elapsed since their last visit.
* **Number of Visits Today:** Includes or excludes visitors based on their number of visits today.
* **Total Number of Visits:** Includes or excludes visitors based on their total number of visits.
* **New or Returning Visitors:** Allows you to include only new visitors or only returning visitors on your website.
* **Exclusive Feature Flag:** Only includes users who aren't targeted by any ongoing rollout or feature/web experiment.
* **Targeted Feature Flag:** Includes or excludes visitors that another feature flag has already targeted and exposed to a variation.
* **Likelihood to Convert**: Target visitors based on their Kameleoon Conversion Score (KCS). Requires the Contextual Bandit and AI Targeting add-on.
Next, choose the rule's exposure rate: the percentage of your chosen segment that Kameleoon exposes while the flag stays on.
See Kameleoon's [developer documentation](../../../../../developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) to learn how to use targeting conditions in a Kameleoon SDK.
Kameleoon also integrates with [Mixpanel](../../../../integrations/as-a-destination/analytics/mixpanel/setting-up-mixpanel), [Segment](../../../../integrations/as-a-destination/cdp/segment/setting-up-segment), or [GA4](../../../../integrations/as-a-destination/analytics/google-analytics-4/setting-up-google-analytics-4), allowing you to use segments (or cohorts) that you've defined in those tools.
# Automatically roll back a feature
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/automatically-rollback-a-feature
Set up automatic rollback conditions to turn off a rule or environment when a feature's performance drops below defined thresholds.
Automatic rollbacks help you manage feature releases. You can set up custom rollback conditions, or "triggers," that monitor your features' performance to automatically turn off the appropriate rule or flag.
## Setting up rollback conditions
Create a new rule or click an existing one. Then, navigate to the Rollback Condition at the bottom of the edit pane for your desired rule. Here, add a new condition and fill in the fields:
1. Choose whether to turn off only the selected **rule** or turn off the toggle for the entire **environment**. Turning off the environment stops all active rules, including deliveries and experiments, in that environment.
2. Choose the performance indicator to check against: **Uplift**, **Downlift**, or **Conversion Rate**.
3. Define the condition (**higher than** or **lower than**) and enter the threshold percentage which triggers the automatic rollback.
4. Select which **goal** to monitor and evaluate for performance. Here, you can pick from any Kameleoon goal that you’ve created for this project.
5. Select the **minimum visitors** to evaluate before Kameleoon can execute the rollback.
Once saved, Kameleoon continuously monitors the metrics you specified against the defined conditions. You can choose to add as many additional conditions as you’d like by repeating the same steps; however, Kameleoon executes whichever condition triggers first and ignores the rest.
## Setting up email alerts
Set up email alerts to receive notifications when a rollback occurs. These alerts ensure your team stays informed about unexpected adverse effects on your key performance metrics.
To enable alerts, select **Send email alerts** and enter the recipients' email addresses. Click **Save** to finalize.
# Using simulation mode
Source: https://docs.kameleoon.com/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode
Preview and test feature experiment configurations in a controlled environment before deploying them to production.
Simulation mode enables you to preview and test experiments in a controlled environment before you deploy them to production.
For Feature Experimentation, Kameleoon primarily uses the simulation panel for testing and debugging. It doesn't offer the full capability available in Web Experimentation. For more details, see [What the simulation panel does](#what-the-simulation-panel-does).
## Prerequisites
If you implement Kameleoon Web Experimentation or use Feature Experimentation in [Hybrid mode](../../../../../developer-docs/feature-experimentation/get-started/hybrid-experimentation), simulation mode works automatically on all major web browsers. You don't need any additional setup.
If you *only* use Feature Experimentation, you must manually inject the Kameleoon tag to test your configuration. To inject the tag, use the Kameleoon Chrome extension.
Simulation mode only supports web SDKs. It doesn't support mobile SDKs.
To manually inject the Kameleoon tag:
1. Install the [Kameleoon Chrome Extension](https://chromewebstore.google.com/detail/kameleoon/nimncjjomfcjmfnghgaopccmdggjfoam).
2. Open the extension in your browser console and follow the on-screen instructions to log in.
3. Open the **DevTools** panel and click **Tag Injection**.
4. Enter your **Sitecode**, select your **Environment**, and select the **Add Anti-Flicker** checkbox.
5. Apply the changes and refresh the page.
6. In **DevTools**, open the **Network** tab and verify the `kameleoon.js?injected=true` request appears. This request confirms successful tag injection.
## Access the simulation panel
After you confirm the tag injection, click the **three dots** menu for a rule, then click **Simulate**.
To ensure the SDK recognizes the flag configuration, verify the flag toggle is **ON** and the rule is **Active**.
Alternatively, open the **three dots** menu in the top right of the editor, click **Simulate**, and select a rule from any environment to launch.
The simulation panel appears in the bottom half of the page.
## What the simulation panel does
* **Displays variants:** The simulation panel enables you to select and preview a variant in your browser for testing.
* To test a variant in production without exposing it to users, set the allocated traffic for the variant to 0%.
* **Overrides targeting behavior:** The simulation panel ignores targeting rules. The SDK manages targeting, but the simulation panel overrides these rules to force the display of the selected variant.
# Comment mode
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-features/comment-mode
Use Comment mode to exchange feedback on experiment variations directly in Kameleoon, keeping team discussions organized and in context.
Feedback on experiment variations often lives outside Kameleoon, scattered across Slack threads, emails, or sticky notes that lose their context the moment the conversation moves on. **Comment mode** (in beta) keeps that feedback where the work happens, letting you and your team exchange comments directly on the variations you're discussing. Whether you're reviewing variations, discussing changes, or resolving issues, Comment mode keeps conversations organized and tied to the exact variation they're about. This article covers how to access, use, and manage comments.
## Accessing Comment mode
To access Comment mode, click the **text bubble icon** in the mode toolbar.
The **Comments** sidebar opens.
## Adding a comment
To add a new comment:
1. Select your desired variation in the **Variations** sidebar.
2. Click **+Add** in the **Comments** sidebar.
3. Type your comment in the text field and click **Save**.
Your comment is now visible in the **Active** comments tab of the Comments sidebar. A visual indicator noting the number of comments appears next to the relevant variation or element’s name.
## Actions in the Comments sidebar
### Editing and deleting a comment
To edit a comment:
1. Click the **three-dots menu** > **Edit comment**.
2. Edit the comment’s text.
3. Click **Save**.
To delete a comment:
* Click the **three-dots menu** > **Delete comment** > **YES**.
You can delete a comment only during the first 15 minutes after its creation, and only if it has no replies.
### Reply to a comment
To reply to a comment:
1. Click **Add reply**.
2. Type your reply into the text field.
3. Click **Save**.
### Resolve a comment
To resolve a comment:
* Hover over the comment and click the **checkmark icon**.
You've now resolved the comment. You can view resolved comments by clicking **Archived**. Click a comment’s **checkmark icon** in the Archived tab to un-resolve it.
## Settings
You have access to a variety of settings in the Comments sidebar. Click the **cog icon** to view the available settings.
You can:
* **Sort comments**
* You can sort comments newest to oldest, oldest to newest, or alphabetically by the author’s name.
* **Display in list**
* You can choose to display only comments in which you’re mentioned or all replies.
# Contextual bandits
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-features/contextual-bandits
Learn how contextual bandits use real-time user signals to dynamically allocate traffic to the best-performing variation for each visitor.
Personalization is no longer a luxury—it’s an expectation. But delivering the right experience to each visitor, at the right time, is a daunting task, especially when you’re operating at scale. Traditional methods like A/B and multivariate testing (MVT) offer structured ways to improve user experiences, but they come with trade-offs: slow learning curves, limited flexibility, and static assumptions.
To address these limitations, there are **contextual bandits** (CBs)—a machine learning-based approach that offers a dynamic, data-driven alternative to traditional experimentation. In this article, we’ll explore:
* How contextual bandits work
* What kind of data powers them
* What “behavior” really means in this context
* Real-world use cases where CBs shine.
## What are contextual bandits?
Contextual bandits are a machine learning approach that balances **exploration** (trying new options) and **exploitation** (using the best-known option). Crucially, the algorithm now checks the status of the Learning phase every hour, similar to AI Predictive Targeting, letting it adapt more quickly and intelligently.
Contextual bandits use the same machine learning model as [AI Predictive Targeting](../../../ai-predictive-targeting/overview). By default, the model does not use custom data as input. To use custom data with contextual bandits, subscribe to the AI Predictive Targeting add-on.
Unlike A/B or MVT tests, which are static and split traffic evenly across fixed variants, CBs are **dynamic**. They adjust variant allocation in real time based on what’s working best for different types of users.
It’s also important to distinguish CBs from traditional multi-armed bandits (MABs). While MABs consider only the performance of each option overall, CBs factor in real-time user context (like behavior, device type, referral source, and more) to make smarter decisions for each visitor.
## Learning phase
Because contextual bandits use the same machine learning model as AI Predictive Targeting, they go through the same learning phase before the algorithm starts allocating traffic dynamically.
The model requires both 7 days of data and 100,000 visits together, so reaching only one of these thresholds isn't enough to complete the learning phase. During the learning phase, Kameleoon splits traffic evenly across the selected variations, the same way a classic A/B test does. Once the learning phase completes, the contextual bandit starts allocating traffic to the best-performing variation for each visitor.
The number of variations in an experiment doesn't affect the length of the learning phase. However, an experiment can include a maximum of 5 variations, including the original, because of how the underlying machine learning model works.
## How contextual bandits work
At the heart of CBs is a continuously improving decision loop. Here’s how it works:
1. A user lands on your website.
2. The CB algorithm evaluates real-time contextual signals (for example, device, location, past behavior).
3. It selects the variant most likely to result in a positive outcome.
4. It observes the result (conversion, click, engagement).
5. It learns and updates its models accordingly.
This feedback loop happens constantly and is powered by live user data. Kameleoon uses contextual multi-armed bandits (CMABs), an advanced form of CB that incorporates multiple layers of user context to inform decisions.
## Understanding behavior in contextual bandits
In Kameleoon, behaviors include any interaction or signal from a user that can help predict their intent or preferences, which includes:
* Page views
* Scroll depth
* Time on site
* Clicks on CTAs
* Products browsed
* Cart contents
These behaviors feed into both our CB algorithm and our Kameleoon Conversion Score (KCS), creating a standardized behavioral foundation across all personalization tools.
## What makes contextual bandits smart?
The intelligence of a CB system comes down to the quality of data it receives. High-quality, real-time behavioral signals lead to better predictions and faster optimization.
Kameleoon’s real-time data pipeline ensures that CBs make informed decisions by:
* Capturing clean, relevant contextual signals instantly
* Feeding them into the model without delay
* Enabling hour-by-hour updates of the Learning phase status.
Kameleoon ensures your personalization efforts improve quickly and accurately.
## Use cases for contextual bandits
CBs are incredibly versatile. Here are a few ways you can put them to work:
### Optimizing homepage layouts
Show different homepage modules (like banners, featured products, or CTAs) depending on real-time user behavior. The CB continuously adapts to determine which layout performs best for different types of users.
### Saving personalized promotional offers
Instead of manually creating audience segments for promotions, let the CB do the heavy lifting. It analyzes signals such as cart value (which is a [custom data](../../../assets/custom-data/create-custom-data)), browsing history, or traffic source and shows the most effective offer automatically.
### Rolling out new features dynamically
Gradually introduce a new feature or UI component to users who are more likely to respond positively, based on how they interact with your site in real time.
## When to use contextual bandits
Contextual bandits are a powerful tool, but they aren’t always the right choice. Here’s a short guide:
**Best for:**
* Personalization at scale
* Continuous learning environments
* High-traffic pages with lots of user interaction
**Not ideal for:**
* Experiments where strict control and interpretability are essential.
* Low-traffic environments where learning would take too long.
## Summary
Contextual bandits are a smarter, more adaptive approach to experimentation. By continuously learning from high-quality real-time data, CBs let you deliver better experiences faster—no rigid tests or manual segmentation required.
Importantly, the behaviors that power Kameleoon’s contextual bandits are the same ones that fuel our AI propensity scores. This shared behavioral foundation means smart and consistent personalization across your experiments and optimizations.
In short, contextual bandits help you meet your users where they are—intelligently, efficiently, and at scale.
For more information on integrating CBs in your web experiments, refer to [this](../configure-and-launch/finalizing-an-experiment#contextual-bandits) article. Read [this](../../feature-experimentation/using-the-rollout-planner/optimizations-and-scheduling/multi-armed-bandit-optimizations-for-feature-experiments#contextual-bandits) article to learn more about CBs in feature experiments.
# Predefined tags
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-features/predefined-tags
Apply predefined tags like TECHNICAL, DELAYED, LIVE-UPDATE, HOLDOUT, and MUTUALLY EXCLUSIVE GROUP to modify how Kameleoon runs your experiments.
You can apply predefined tags to your experiments to change Kameleoon's default behavior:
* **TECHNICAL**:\
When you add a `TECHNICAL` tag to an experiment, Kameleoon displays the variation but doesn't collect or send data to an analytics platform until the visitor gives [consent](../../../project-management/consent-management-policy#consent-policy).\
This tag is typically used for experiments or personalization campaigns that display the same variant to all users.
* **DELAYED**:\
Adding the `DELAYED` tag to an experiment allows you to delay non-essential experiments until after the first page load. Experiments with this tag are intelligently managed:\
Kameleoon doesn't download the configuration until at least 10 seconds of idle time pass after the initial page load, **or** until it targets the visitor and allocates a variant other than the control variant.
* **LIVE-UPDATE**:\
By default, Kameleoon downloads active experiments and includes them in the app file (`kameleoon.js`).\
The browser stores and caches this file for 90 minutes. If you pause, stop, or modify an experiment, targeted visitors returning to a page with active experiments within the 90-minute caching period may still see the experiment because their browser serves the cached version. Outside that caching window, a paused or stopped experiment no longer assigns its variation, and visitors revert to the original experience on their next page evaluation.\
To update more frequently than browser caching normally allows, add the `LIVE-UPDATE` tag: it refreshes any experiment within **1 minute**, which is particularly useful for campaigns that require regular updates.
* **HOLDOUT**:\
Create a control group that remains unaffected by any active campaigns, so you can establish a reliable baseline that measures the aggregate impact of all changes against a group that experiences no modifications.\
Set up an experiment in Kameleoon and tag it with the `HOLDOUT` label.\
[More about this tag](/user-manual/experiment-analytics/analyze-results/advanced-analysis/create-reliable-baselines-with-holdouts)
* **MUTUALLY EXCLUSIVE GROUP**:\
Group campaigns so that each visitor sees only one campaign per group, reducing overlap and improving test clarity.\
Follow the naming convention `ME-GROUP-{GROUP NAME}` to tag each campaign in the group, such as `ME-GROUP-A`.\
This naming signals Kameleoon to treat the campaigns within each group as mutually exclusive.\
[More about this tag](/user-manual/experiment-analytics/analyze-results/advanced-analysis/prevent-overlapping-campaigns-with-mutually-exclusive-groups)
# Using Shadow DOM elements in the Graphic editor
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-features/using-shadow-dom-elements-in-the-graphic-editor
Select and modify Shadow DOM elements in the Kameleoon Graphic editor using shadow root paths and the ::SHADOW-ROOT:: selector syntax.
Shadow DOM is an advanced web development feature that lets developers encapsulate a part of their webpage's structure, creating a separate "shadow" section. Think of it like creating a miniature webpage within a component of your main site. This "mini-page" operates independently of the rest of your page, preventing conflicts between styles and scripts used within the component and those used on the main page.
If you're working in the Kameleoon Graphic editor, you'll need to know how the DOM (Document Object Model) works to use Shadow DOM elements. Since Shadow DOM elements aren't visible in the main DOM by default, things like placing widgets or personalizing experiments can be trickier than working with standard DOM elements.
This feature assumes development experience. If you're not comfortable working with the DOM or Shadow DOM encapsulation, reach out to a developer or look into online resources about Web Components and Shadow DOM fundamentals.
## Limitation of standard selectors
Standard CSS selectors or JavaScript methods like `querySelector()` or `$()` won't work on elements inside a Shadow DOM. The shadow root hides these elements from the main page, meaning:
* You can't target elements inside a Shadow DOM using the usual selection methods in the Kameleoon Graphic editor.
* Targeting these elements using traditional CSS or jQuery-style selectors in your experiment might fail.
* Any modifications (like text changes, style updates, or content insertion) may not apply unless you take special steps to pierce the Shadow DOM boundary.
If you’re unsure whether you’re dealing with a Shadow DOM, inspect the element using your browser’s developer tools. Look for `#shadow-root` in the **Elements** panel.
## Working with Shadow DOM in the Graphic editor
In most cases, users can select elements inside a shadow root directly from the preview zone in the Kameleoon Graphic editor.
### When the additional "Shadow root path" input appears
In some cases, when you attempt to select or edit an element inside a Shadow DOM using the Kameleoon Graphic editor, you may see an additional input field labeled **Shadow root path**. This field appears when Kameleoon detects that the target element exists within a shadow tree that standard selectors can't reach.
The Shadow root path lets you define a specific path through nested Shadow DOM layers so Kameleoon can reach and modify the element during experiment execution.
**Mock connection:** the Graphic editor uses this path to “mock” the connection between the main DOM and the element inside the Shadow DOM, which lets you visually edit and preview changes as if the element were part of the regular page structure.
## Examples
### Targeting a button inside a shadow root
In the Kameleoon Graphic editor, you can target elements inside a shadow root:
* **Directly in the Preview zone:** If the element is accessible, you can select it within the editor preview, just like any standard element.
* **Using “Edit selector”:** For more complex structures you can manually construct the selector path using the Edit selector input. Use the `::SHADOW-ROOT::` separator to indicate a step into shadow root.
### Inspecting Shadow DOM in DevTools
1. Right-click the element > **Inspect**.
2. In the **Elements** panel, look for `#shadow-root (open)` under the custom element.
3. Expand it to view the inner elements.
For example:
```html theme={null}
#shadow-root (open)
```
## Visual cues or labels in the UI
While working with web pages that use Shadow DOM, the Kameleoon Graphic editor provides several visual indicators to help you identify when elements are part of a shadow root.
### `#shadow-root` in the Elements panel
In the editor’s **Elements** panel, components that use Shadow DOM display `#shadow-root` as part of their CSS selector, showing that the shadow root encapsulates the element rather than exposing it in the main DOM tree.
### "Shadow root path" field in the selector panel
When selecting an element inside a shadow root, an additional **Shadow root path** input appears in the **Edit CSS selector** panel. This input lets you build a full path through shadow roots using the `::SHADOW-ROOT::` syntax.
## How to write a selector path for Shadow DOM elements
When working with Shadow DOM elements in Kameleoon’s Graphic editor, a standard CSS selector isn't sufficient. You must define a selector path that includes the shadow root.
To target an element inside a **single-level shadow root**, use the `::SHADOW-ROOT::` separator:
`custom-element::SHADOW-ROOT::.target-button`
The `::SHADOW-ROOT::` separator causes Kameleoon to enter the shadow root of the specified element and continue targeting inside it using standard CSS selectors.
Kameleoon supports navigating only **one level** into the Shadow DOM. If the element sits within multiple nested shadow roots, you can't target it using a full selector path.
### Example
```html theme={null}
#shadow-root
```
Your selector path is `my-element::SHADOW-ROOT::.cta`
This selector path directs Kameleoon to:
* Select the `my-element` element.
* Enter its shadow root.
* Target the `.cta` button inside it.
## Limitations and considerations
When working with Shadow DOM, keep the following limitations in mind:
* **Closed Shadow DOMs:** You can't access or modify elements in a closed shadow root using the Graphic editor or standard JavaScript.
* **Dynamic or script-generated content:** If a script generates or updates content inside a shadow root dynamically, your changes may not persist or take effect as expected.
* **Styling restrictions:** Styles applied from outside the shadow root often won’t affect inner elements due to Shadow DOM’s style encapsulation. You may need to apply CSS rules directly within the component’s internal structure instead, which isn’t possible via the Graphic editor.
### Shadow root (closed)
Some web components use a closed shadow root, meaning their internal DOM is completely hidden from the browser’s developer tools and JavaScript.
Unlike an open shadow root, which you can access using `.shadowRoot`, a closed shadow root **doesn't** expose its content through the DOM, making it inaccessible to:
* The Graphic editor
* JavaScript-based targeting
* Selector paths or custom scripts
Because a closed shadow root hides its internal elements, you can't select or modify them in Kameleoon. Even if you see the outer wrapper component, its internal structure remains sealed.
#### What can you do?
If a key element is inside a closed shadow root, you’ll need help from a developer. They may:
* Rebuild the component using an open shadow root.
* Expose specific elements for external targeting.
* Provide a hook or workaround for targeting.
If you can’t inspect the inside of a component in browser DevTools, it’s likely using a closed shadow root.
### Nested shadow roots
You can nest Shadow DOMs multiple layers deep (for example, a shadow root inside another shadow root). This case isn't supported in Kameleoon's current version.
If an element isn’t responding to edits, double-check if it’s inside a closed shadow root or if you’re missing part of the path.
### Adding widgets to shadow root
You can’t add widgets inside Shadow DOM elements in Kameleoon’s Graphic editor because the shadow root isolates its content from the DOM nodes the editor can reach.
### Add click tracking from the Graphic editor
You can't add a click tracking goal directly from the Graphic editor for Shadow DOM elements. However, you can create and manage one using Kameleoon's [API](../../../../developer-docs/apis/activation-api-js/api-reference/api-reference#runwhenshadowrootelementpresent).
# Multi-language experiments
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-types/multi-language-experiments
Create multi-language A/B test variations in the Kameleoon Graphic editor to test content changes across different languages simultaneously.
Kameleoon makes it quick and easy to implement multi-language experiments. In this tutorial, you will learn how to create a multi-language variant using the Graphic editor, using the [Fossil website](https://www.fossil.com/) as an example.
## Goal
The goal of this guide is to change the header label "Order Status" ("Statut de la commande" in French) to "Order Tracking" ("Suivi de commande" in French).
## Steps
1. Launch the Graphic editor.
2. Select "Order Status" in the header and generate the selector based on **Content**. If the label you want to edit is in a Shadow DOM see [this article](../advanced-experiment-features/using-shadow-dom-elements-in-the-graphic-editor#working-with-shadow-dom-in-the-graphic-editor)
3. Enter "Order Tracking".
4. Change the language to French by clicking **Ship to** > **Europe** > **France**.
5. Repeat step **2** and **3**, entering "Statut de la commande" in the header.
6. Change the text to "Suivi de commande".
7. Simulate the experiment to verify your variant.
# Multi-page experiments
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-types/multi-page-experiments
Design experiment variations that span multiple pages and configure URL-based targeting to run tests across entire user journeys.
Testing a change across a user journey, such as a checkout flow or a multi-step signup, usually means building and coordinating a separate experiment for each page involved. Multi-page experiments let you design variations that span multiple pages within a single experiment, so you can test the whole journey as one unit.
Multi-page experiments offer the following benefits:
* **Holistic testing:** Evaluate the impact of your changes across user journeys that span multiple pages.
* **Unified experiment management:** Create and manage variations that affect different pages within the same experiment.
* **Streamlined workflow:** Design variations for multiple pages at once, reducing the need for separate experiments.
**Creating multi-page variations:**
1. Launch the Graphic editor on all desired pages.
2. Design your variations and incorporate changes for each page within the same variation.
3. Define the targeting criteria for your multi-page experiment during finalization.
Kameleoon also supports the [simultaneous selection of multiple elements on one or several pages](../graphic-based-experiments/getting-started-with-the-graphic-editor). Multiple selection enables efficient edits to elements with identical IDs or classes across multiple targeted pages. For example, you can automatically apply a change to an "Add to Cart" CTA on one page to all other "Add to Cart" CTAs on targeted pages in the experiment.
## Target pages according to their URL
Once your variations are complete, click **Finalize** to proceed to the experiment configuration.
In the finalization flow, the **Targeting** step defines the conditions under which your experiment exposes visitors to your variations. This step contains two sections: **Segments**, where you build audience conditions such as page URL or device type, and **Triggers**, where you define when and where the experience fires. This article covers the page-based and entire-site targeting options, which live in the **Triggers** section.
### Several pages sharing the same URL
To target several distinct pages by URL:
1. In the finalization flow, click **Target a segment** > **Create a new segment**. The segment creation window opens.
2. Double-click the **Page URL** condition or drag and drop to select it. You can add this condition as many times as you need.
3. Indicate the URL or URL fragment you want to target on your website, and specify whether you want to include or exclude it.
A wide range of targeting conditions are available. For more information about targeting conditions, see [Manage targeting segments](../../../assets/segments/manage-targeting-segments).
Kameleoon offers three options:
* **Contains:** Runs the test on all URLs containing a URL fragment.
* **Corresponds exactly to:** Runs the test only on the URL you choose. If your URL contains changing parameters, use the **Matches the regular expression** option.
* **Matches the regular expression:** Use this option if your A/B test runs on a group of pages with specific parameters, such as `?x=exemple&y=exemple2`.
Take this regular expression as an example:
The regular expression above tells Kameleoon to run the test on pages containing the path `mywebsite.com/article/january` and the parameter `x=y`.
Among the five following examples, only the first two URLs count toward the A/B test:
`http://www.mywebsite.com/article/january?x=y`
`https://mywebsite.com/article/january?a=b&x=y&c=d`
`http://www.mywebsite.com/article/january`
`http://www.mywebsite.com/article/january/?x=y`
`http://www.mywebsite.com/article/january/monday?x=y`
Explanation:
* The third URL does not contain the `x=y` parameter.
* The fourth URL contains a `/` after `january`.
* The fifth URL has `monday` added at the end.
### Several pages with the same URL fragment
To target several pages that contain the same URL fragment, either build a segment with a **Page URL** condition set to **Contains**, or select **The URLs containing a specific fragment** trigger option in the **Triggers** section of the **Targeting** step.
For example, to change the color of the add-to-basket button on each of your product pages, where all of the URLs contain one identical fragment, select this trigger option:
When you select **The URLs containing a specific fragment**, a field appears where you can enter the fragment. If all of your pages contain the `/product/` fragment, enter `/product/` in this field so the experiment runs only on pages that contain this fragment.
### From an element on the page
URL-based targeting doesn't work in every case. Two common scenarios require a different approach:
* All the URLs are different.
* You want to test only the last step of a multi-step process, such as registration or checkout, where every step shares one URL. Targeting that URL would include every step in the A/B test, not just the last one.
To target pages accurately despite dynamic content, use the **Presence of an element on the page** condition.
1. Create a new segment within your experiment.
2. Select the **Technical** category > **Element on the page**.
3. Define the element that must be present on the page to include visitors in the experiment.
If your page contains a unique element, particularly for a multi-step process that shares one URL, use this method: indicate the HTML element's ID or CSS selector to define the element.
For optimal performance, choose an element located near the top of the page when using **Presence of an element on the page**. Placing the element lower on the page increases the likelihood of flickering, because Kameleoon waits for the element to load before triggering the experiment.
### On the whole website
You can also run the experiment on every page of your website.
To do so, select **The entire site** trigger option in the **Triggers** section of the **Targeting** step.
Selecting **The entire site** targets all pages within the project scope. Confirm that your variations are compatible with every page before using this option.
# Running an A/B test on a Shopify store
Source: https://docs.kameleoon.com/user-manual/experimentation/web-experimentation/advanced-experiment-types/running-an-ab-test-on-a-shopify-store
Run A/B tests on Shopify using content swapping, the Graphic editor, or the Kameleoon JS SDK in Liquid templates.
You might want to test different variations of your product page and measure how visitors interact with it based on key KPIs, such as the number of "Add to cart" actions, entries into the checkout funnel, and, ultimately, the number of completed orders.
Imagine a typical product page, as shown in the image below. A user can either choose to buy the product immediately or add it to their cart. But what if most of your visitors typically only purchase one product? In that case, you might consider showing only a single "Buy Now" CTA to streamline the checkout process and reduce friction for your users.
There are several ways to create experiments using Kameleoon. For example, you can:
* **Content swap test:** Each variant of your experiment lives on a different Shopify template, which you can access through a dedicated page URL (for example, `www.mystore.com/products/products/produc-name?view=version-b`). The A/B testing tool lets you swap your content with the variant, such as pages B or C.
* **Use a Visual editor:** Create variants directly on your product page using the Graphic editor, or customize them by injecting JS/CSS.
* **Leverage Shopify's Liquid and a JS SDK:** Add logic in your Liquid template to activate or deactivate specific variants for a subset of users.
The following sections explore each method in more detail.
Install Kameleoon on your Shopify store before you start. Every experiment requires this installation.
* If you're running **web experiments**, use the [**Shopify x Kameleoon app**](https://apps.shopify.com/kameleoon-abtesting-app), which simplifies setup. See the [documentation](../../../integrations/cms-e-commerce/shopify/shopify-plus) for step-by-step instructions.
* If you're running **feature flags or feature experiments**, follow the guidelines outlined in the Feature Experimentation [documentation](../../../../developer-docs/sdks/web-sdks/js-sdk).
## Content swapping testing
A **Content Swapping test** is an A/B/n experiment that shows users different content under the same URL, with each version representing a variant of the same page. Unlike URL redirects, it doesn't create a [Sample Ratio Mismatch](../../../experiment-analytics/statistical-methods/sample-ratio-mismatch).
With Shopify, content swapping tests are easy to set up using the `?view` URL parameter, which lets you serve alternate templates for the same page. For example:
* `https://kameleoon-segment-test.myshopify.com/products/vans-sh-8-hi`
* `https://kameleoon-segment-test.myshopify.com/products/vans-sh-8-hi?view=version-b`
In this case, `?view=version-b` uses [Shopify's alternate template feature](https://www.shopify.com/partners/blog/shopify-alternate-templates), letting you create multiple versions of templates for products, collections, carts, and more, which is ideal for content swapping experiments.
This section walks through how to configure a content swap test in Shopify and Kameleoon.
In your Shopify store, go to **Online Store** > **Themes** > **Actions** > **Edit Code**, and open the `product.liquid` template. The template includes two main sections:
* `product-template`: contains the product page's source code.
* `product-recommendations`: contains the code for the "You may also like" recommendation block.
To set up your content swap experiment, you must create an alternate template for **variant B** and duplicate the `product-template` section, removing the code related the **Add to Cart** button.
Here's how:
1. Click **Add a new template** in your Shopify theme editor.
2. Choose the **Product** template type and name it (this example uses `version-b`, but you can use any name).
The name you choose will appear in the URL (for example, `?view=version-b`), so pick something that makes sense to your team but isn't confusing to users.
3. Click **Add a new section**; name it **`product-template-version-b`**, and **copy and paste** the code from your original `product-template.liquid` file into this new section.
You should now have four liquid files.
4. Remove the **Add to cart** button code from the **`product-template-version-b.liquid`** section.
5. Call your modified section (`product-template-version-b`) from the alternate product template you created (`product.version-b.liquid`).
Your updated code should look something like this:
Once you've saved your changes, you have a second variant of your product page.
Shopify lets you load alternate template files using the `?view=` URL parameter. As long as the value matches a template file in your theme, Shopify renders that version of the page.
For example, visiting `https://kameleoon-store.myshopify.com/products/vans-sh-8-hi?view=version-b` now displays the product page **without the Add to Cart button**, as intended.
With the template updates complete, configure your content swap experiment in Kameleoon so that 50% of your visitors see **variation B** instead of the original product page. It's a simple process:
1. Go to the [Kameleoon app](https://app.kameleoon.com/).
2. Click **New experiment** > **With the code editor**.
3. Enter the required information and click **Create**.
The Code editor will open. From there, you can set up and launch your experiment.
4. Click the **chevron** next to **Add variation** > **Add code variation**.
5. Add the **following code**, adapting the `VIEW` and the `SELECTOR` variables to suit your use case
```javascript theme={null}
(function () {
var VIEW = 'version-b'; // Alternate template handle, e.g. 'version-b'
var SELECTOR = '#MainContent'; // Main container selector
function executeScripts(container) {
container.querySelectorAll('script').forEach(function (oldScript) {
var newScript = document.createElement('script');
for (var i = 0; i < oldScript.attributes.length; i++) {
var attr = oldScript.attributes[i];
newScript.setAttribute(attr.name, attr.value);
}
newScript.textContent = oldScript.textContent;
oldScript.replaceWith(newScript);
});
}
Kameleoon.API.Core.runWhenElementPresent(
SELECTOR,
function () {
fetch(window.location.pathname + '?view=' + encodeURIComponent(VIEW), {
credentials: 'same-origin'
})
.then(function (r) {
if (!r.ok) {
throw new Error('Unexpected status ' + r.status);
}
return r.text();
})
.then(function (html) {
var doc = new DOMParser().parseFromString(html, 'text/html');
var newContent = doc.querySelector(SELECTOR);
if (!newContent) {
console.error('[Kameleoon] Swap failed: selector not found in fetched template');
return;
}
var main = document.querySelector(SELECTOR);
main.replaceWith(newContent);
executeScripts(newContent);
})
.catch(function (err) {
console.error('[Kameleoon] Swap failed:', err);
});
}
);
})();
```
Content swapping only pulls the HTML from the alternate template. Browsers never execute `