Add a new rollout rule

Written by Julie Trenque

Updated on 07/10/2024

2 min


Was this content useful?

What are Rollout Rules? 

You can leverage the Rollout Planner to be as selective and precise with your releases and tests as you want. Anything that is inside of a feature flag can be toggled on whenever you choose and for whoever you choose.

Rollout rules are a sequence of actions that can be scheduled or applied immediately for your feature flag in the selected environment. They work somewhat similar to if-then-else conditions for your release management and experiments that you can target, schedule, reorder and customize based on your goals.

Add a new rule

Click on + Add a rule to open the rule configuration menu.

Here you can select between delivery or testing rules, and name your rule.

You can use a combination of any multiple rules of any type to implement your rollout strategy for your feature. Kameleoon allows you to add rules for Targeted Delivery, Progressive Delivery and Feature Experiments.

How does the rule queue work?

Once you’ve added your rollout rules, it is important to understand how the queue is evaluated by Kameleoon: 

  1. Kameleoon will check if your flag is on. If not, it will do nothing and serve everyone the default variation (which you can choose in the “Then, for everyone else in production, serve” dropdown list). 
  1. If the flag is turned on, experiments and rules in the queue will be evaluated in a top-to-bottom order, so keep that in mind when planning your rollout strategy to prevent unforeseen targeting overlaps. 
  1. New rules are automatically added to the bottom of the queue by default. However, each rule can be manually reordered by clicking the number shown on the left hand side of each rule (when the number changes to the ::: icon) and dragging it to the desired new position in the queue. 
  1. You can drag rules up or down to reorder them in the queue. This will also change the order in which Kameleoon reads and evaluates the rule, so be mindful when delivering rules that share the same audience.
  2. Paused rules are simple ignored at runtime.

User Targeting and Bucketing

Users exposed to a variation as a result of being targeted by a rule happens in two steps: targeting and bucketing. In short, being “targeted” means that a user meets the criteria defined in a rule, while being “bucketed” means that, in addition to being targeted, they have also been assigned to the variation(s) selected for that delivery or experiment rule.

Kameleoon handles targeting and bucketing differently for delivery and experiment rules. 

Consider these 2 scenarios:

Scenario 1: Delivery Rule at the top

If a visitor is first targeted for Targeted/Progressive Delivery rule: 

  • They receive the selected variation if they are bucketed
  • If targeted, but not bucketed, all targeted users will default to the “Everyone else” variation and won’t get evaluated for any other rule below. Thus, be sure to check the targeted segment for your Delivery rules especially when using the “All users” segment.

Scenario 2: Experiment Rule at the top

  • If a visitor is targeted by Experiment rule:
    • They receive the selected variation if they are bucketed
    • If they are targeted, but not bucketed, the next rule is checked until the end of the queue. All users who are not bucketed by experiment rules move down the queue, because of which it’s always a good practice to keep experiments at the top of your queue

Note: Changing the traffic split for an experiment does not change the total size of your experiment bucket. For example, an Experiment is launched that targets 20% of a user segment, with a variation split of 50/50 for its two variations. Later, if you update the split to 60/40 or even 90/10, but do not change the percentage of traffic that will be included in the experiment sample (i.e 20%), the total bucketed users will not increase or decrease. Instead, some bucketed users will only get exposed to a different variation.

When there are no more rules in the queue, all remaining users will default to the “Everyone else” variation.

Rule states

All rules in the queue will display one of these states:

  • Active (is currently live)
  • Paused
  • Planned (has been scheduled to start and/or stop at a given date/time). Planned rule changes to active at defined schedule or outdated at the end of it. 
  • Unsaved changes (this also includes new rules that are in draft state)
  • Outdated (a planned rule that automatically turned off at scheduled end date). Outdated rules are not shown in the default view but you can use filters above the queue to view them.

Pause/resume a rule

To pause a rule, open the 3-dot menu at the end of the line and click on Pause.

Paused rules are simple ignored at runtime. You can resume the rule later in the same menu.

Copy rules from another environment

You also have the option to add rules already created in another environment if you want to replicate your rollout/experiment setup from, for example, your staging environment to your production environment.

Simply 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 ones. Use the checkbox shown in the image above to toggle this behavior. Be sure to save one last time for the changes to take place.

Rollout summary

This section provides a quick overview of 2 key aspects of your rollout rules: variations and segments.

Changing the order of cards, deleting a rule, or change of rule status from active to planned or vice versa will reflect the ordering and values inside summary cards.

While the summary section accounts for untargeted (remaining users) that can be passed down to the next rule, any partial or complete overlaps between different user segments across different rules will not be accounted for or identified.  

Variations Summary

This section serves you an overview of which variations have been used in your delivery and experiment rules.

Variations that are targeting multiple segments have multiple bars inside them also displaying the percentage of the audience that you have targeted. 

Segments Summary 

This section summarizes the different user segments that are being targeted in your rollout rules.

Segments who are split into the variations being delivered to them will have them in the same bar, adding up a maximum of 100% after which any additional variations being targeted towards the segment will be ignored.

Using the Rollout Planner with outdated SDKs

If the version of your SDK does not support Feature Variations, you will have to follow a few steps when adding new rules for a Feature Flag:

  1. Only rules defined on the Production environment will be checked by Kameleoon. Rules created in the staging or development environments will be ignored. 
  2. Only the first rule in the queue will be evaluated. If there are any rules below, they will be ignored. If there are no rules at all, the default variation defined in your rollout will be served.
  3. Only the default variations On and Off are supported. 
  4. Start/Stop scheduling of rules is not supported.

Visit Kameleoon’s Github and subscribe to notifications to stay up to date with all SDK releases.

  • In this article :