Demo: Feature Experimentation

This hands-on tutorial for developers demonstrates how Feature Experimentation works on the Kameleoon platform. You’ll start with a sample app and follow step-by-step instructions to configure a set of feature flags in the Kameleoon app, enable them in the sample app, and see how the feature flags affect the visitor’s page. The sample uses TypeScript, but you don’t need to know TypeScript to complete this tutorial. Experience with any modern programming language should be enough to understand the important points.

​

Prerequisites

Before you get started, you need to create a couple accounts:

• Sign up for a free 30-day Kameleoon trial account. You’ll need to complete this tutorial within 30 days after requesting the account, but the tutorial should only take about 30 minutes to complete.
• A GitHub account.

​

Run the sample app

You can run the sample app either in GitHub Pages or on your local machine. Sign in to your GitHub account before you start either path.

​

Deploy to GitHub Pages

Deploying to GitHub Pages means you don’t need to worry about setting up a web server.

1. In the Bouncing ball repo in GitHub, click Fork. Follow the prompts to create your own fork of the sample app in github.com/<your_username>/bouncing-ball. (Replace <your_username> throughout this tutorial with your GitHub username.)
2. In your new https://github.com/<your_username>/bouncing-ball repo in GitHub, click the Actions tab and click the button to enable workflows.
3. In the Settings tab, click Pages, click the Source dropdown, and click GitHub Actions.
4. In the Actions tab, click Deploy static content to Pages > Run workflow > Run workflow.

Once the build and deploy process completes (this might take a minute or two), you should be able to see the demo app running in a browser at https://<your_username>.github.io/bouncing-ball! It should look something like this:

​

Run the app locally

You can also run the sample app on your local machine instead of deploying it to GitHub Pages. Working locally makes it easier to see debug output in your browser console as you go through this tutorial.

1. Clone your fork: git clone https://github.com/<your_username>/bouncing-ball.git.
2. Install the dependencies: npm install.
3. Start the local development server: npm run dev.
4. Open the URL that the terminal prints, for example http://localhost:5173.

Use this local URL instead of https://<your_username>.github.io/bouncing-ball for the rest of this tutorial, including as the site’s URL when you create your Kameleoon project.

​

Reduce the configuration polling interval

To make project changes faster, the update interval at which the SDK checks for configuration changes in the Kameleoon account can be programmatically adjusted:

1. In your GitHub repo, in the Code tab, open the src/main.ts file.
2. Click the Edit this file button (with the pencil icon).
3. Find and edit the /src/main.ts file. Find the following line:
   const client = new KameleoonClient({ siteCode });
   
   Replace the line with the following code:
   const configuration = {   updateInterval: 1,};const client = new KameleoonClient({ siteCode, configuration });
   
   The new code adds a configuration with an updateInterval of 1. This value reduces the frequency with which the SDK polls for changes in the configuration to once every minute (from the default of 60 minutes). Avoid this frequent polling in a production environment due to the performance impact, but it’s helpful for the tutorial. Kameleoon also offers a premium streaming option that pushes configuration changes to the SDK immediately.
4. Click Commit changes….

​

Set up a Kameleoon project

You’ll need your Kameleoon trial account credentials before you start this section.

1. Sign in to the Kameleoon app using your trial account credentials.
2. In the left menu, expand Admin and click Projects > New project.
3. In the dialog, click Site: Feature flags in the first dropdown, and paste https://<your_username>.github.io/bouncing-ball (or your local URL, if you’re running the app locally) as the URL of site. Remember to replace <your_username> with your GitHub username. Click Add.
4. Copy the site code that’s shown on the next page.
   
5. In your GitHub repo, in the Code tab, edit the src/constants file. Replace the siteCode value with the site code you just copied and click Commit changes.

If you check your app in the browser again (https://<your_username>.github.io/bouncing-ball, or your local URL), you should see that all the bouncing circles have disappeared. That’s because a Kameleoon feature flag in a different project added the circles. You just changed the site code so the site is now controlled by your Kameleoon project, which you haven’t fully configured yet. Don’t worry, you’ll add your own circles back to the app with your own feature flags.

​

Set up feature flags

Feature flags allow you to roll out new features to a limited audience and test their effectiveness before a full rollout. Developers or other team members can manage this configuration. Understanding how you configure feature flags in the Kameleoon interface helps you use variables effectively within the app.

1. In the Kameleoon app, in the Activate menu, click Feature flags.
2. Click New feature flag.
3. Complete the fields with the following values:
   • Name: Bouncing ball demo
   • Project: {Select your project from the dropdown}
   • Flag type: Permanent
   • Feature key: bouncing_ball_demo You can leave the tags and description field empty.
4. Click Validate.

​

Set up variables

Variables are strings, numbers, boolean, or JSON values that you use in your app code to modify the app’s behavior. Their values change depending on which variation Kameleoon assigns the visitor to. For example, to determine whether visitors stay on a site longer when served a “Party time” variation versus a “Hypnotize” variation, set up a variation for each option and run an experiment.

1. On the new page that appears, expand the Set Up menu and click Variables.

2. Use the + Add Variable button to add 6 variables with the following values:

   Variable key	Type	Default value
   title_text	String	Default variation: 1 green ball
   randomize_on_bounce	Boolean	False
   balls_amount	Number	1
   ball_speed	Number	10
   ball_color	String	green
   ball_size	Number	20

   Watch for typos. The variable key names and types must match exactly. If you look at the src/main.ts file in your GitHub repo, you’ll see why. The code sample uses these exact variable key names to retrieve the values of the variables, depending on the variation that Kameleoon assigns the visitor to.
3. Click Save.

You’ve now set up a set of variables with default values. The default values are the values your app uses when there are no active campaigns for the visitor. If you turn on your feature flags now, you see the default variation, with 1 green ball bouncing around slowly, because you haven’t set up any variations yet.

​

Set up variations

Variations define the possible combinations of variables that control what appears in your app for each visitor. Kameleoon assigns each visitor a variation on their first visit to the app.

1. In Set Up, click Variations.
2. Use the + Add variation button to add two new variations:
   • Name: Party time
     • ball_size: 50
     • ball_color: random
     • ball_speed: 75
     • balls_amount: 75
     • randomize_on_bounce: True
     • title_text: Hey! Get up and dance!
   • Name: Hypnotize
     • ball_size: 200
     • ball_color: blue
     • ball_speed: 2
     • balls_amount: 10
     • randomize_on_bounce: False
     • title_text: You're getting very, very sleepy

​

Set up a goal

Next, you’ll set up a goal. Goals define how you want to measure the effectiveness of your variations. There are a number of different types of customizable goal types you can use, but this tutorial uses a basic “time spent” metric.

1. In the Set Up menu, click Goals > + Add goal.
2. In the Configure goals section, click + Create a new goal and complete the following fields:
   • Name: Time spent
   • Type: Time Spent
   • Project: {Select your project}
3. Click Next and set the goal to: The visitor spent more than 30 seconds.
4. Click Validate.

​

Roll out an experiment

Now that you’ve configured your variations, you can create an experiment that displays the two variations to a subset of your audience. You’ll display one variation to 40% of your visitors and the other variation to a separate 40% of visitors. The remaining 20% of visitors will see an unmodified version of the app (the default).

1. In the Rollout Planner section, click Production.
2. Click + Add a rule > Experiment.
3. Reduce the Exposure slider to 80%.
4. Under Variations to serve, click Party time and change the Exposition value to 40.00%.
5. Click + Add a variation. Kameleoon should select the variation Hypnotize automatically (if not, select it yourself). Change the Exposition value to 40.00%.
6. Turn the ON/OFF toggle to ON.
7. Click Save.

​

Test the app

Now you’ll test the feature flag you configured, using the SDK’s debug output, a few browser techniques, and the Kameleoon app’s live events to confirm everything works.

​

Enable debug logging

Debug-level logs show every internal decision the SDK makes, which helps you understand why a variation wasn’t served or why an event didn’t track. Enable debug logging before you open the app for the first time, so you have full visibility from your very first visit.

1. In src/main.ts, change the SDK import so KameleoonLogger and LogLevel come from the full bundle instead of the default one:
   import { EventType, KameleoonClient, KameleoonLogger, LogLevel } from "@kameleoon/javascript-sdk/full";
   
2. Right after you create the client, set the log level:
   const client = new KameleoonClient({ siteCode });
   client.setLogLevel(LogLevel.DEBUG);
   
3. Commit your changes (or save the file, if you’re running the app locally).
4. Open your browser’s DevTools console before you load the app. You’ll see detailed logs for configuration loading, visitor code assignment, and variation calculation.

For the full list of log levels and what each one reports, see Logging.

​

View your variation

Open the app in a browser, using either your GitHub Pages URL or your local URL. You should see one of the three possible variations: the Party time variation, the Hypnotize variation, or the Default variation.

​

See a different variation

Because your browser saves a visitorCode, which is a unique ID that identifies you, refreshing the page always serves the variation you were first assigned to. To look like a new visitor, use one of the following methods:

• Switch to a different browser or device.
• Open the app in a new private window each time (depending on your chosen browser, you might see this called “Incognito,” “Private Browsing,” or something similar).
• Use the Rollout Planner’s simulation panel to select a specific variation without generating a new visitor code. See Using simulation mode for setup steps, including the Chrome extension required for projects that only use Feature Experimentation.

After enough attempts, you should be able to see all three of the variations. If so, congratulations. You’ve successfully set up a feature experiment with Kameleoon. 🎉🎉🎉

​

Verify tracking with live events

A variation appearing in your browser doesn’t confirm that Kameleoon tracked the visit. Check Live events in the Kameleoon app to verify that Kameleoon received the event.

1. In the Kameleoon app, go to Insights > Live events.
2. Select your project.
3. Filter by the Experiment event type.
4. Look for a row with a recent timestamp and your feature flag’s name.

Live events works the same whether the app runs on GitHub Pages or on your local machine, since Kameleoon receives the event over the network either way. See Live events for details on filtering and event types.

​

Troubleshoot common issues

• The same variation appears every time. Your browser already stored a visitorCode in a cookie. Use a private window, switch browsers, or use the simulation panel to preview a different variation without resetting your visitor code.
• No variation appears, or you always see the Default variation. Check that the rule’s ON/OFF toggle in the Rollout Planner shows ON and that the rule’s status shows Active.
• The app still shows an old configuration after you change a rule. The SDK polls for configuration updates at a set interval, 60 minutes by default. Confirm you set a shorter updateInterval value in your configuration and committed the change, then wait at least the length of that interval before you test again.
• Debug logs don’t appear in the console. Confirm your import statement uses @kameleoon/javascript-sdk/full instead of @kameleoon/javascript-sdk. The default bundle strips debug and info logs to reduce its size.
• A variation appears, but no event shows up in Live events. The simulation panel previews a variation without sending a trackable event, so it never appears in Live events. Visit the app normally, without the simulation panel, to generate an event you can verify.

​

Next steps

• In the Reporting section of your experiment, look through some of the initial results, available integrations, and activity log. You won’t have access to a lot of results data yet, due to low traffic.
• Look through the sample code to understand how the code applies the variables. If you’re comfortable writing TypeScript, try adding your own variable.
• Look through the rest of this developer documentation and the Experimentation User Guide to learn more about all of the available options and features.
• Install the SDK of your choice and start building your own feature flags, personalizations, and other experiments.