Adaptive Variables

Change what your product shows or does without shipping an update. Variables hold values your app reads at runtime, and conditions serve a different value to the profiles that match.

What a variable is

A variable is a named value your app reads at runtime: a flag that turns a feature on, a line of copy, a color, a number, or a whole JSON object. You change it here, and your app gets the new value the next time it fetches, with no release in between.

Each variable has a key, which is the name your code asks for, and a default value, which is what every profile gets unless something more specific applies. Two things can be more specific. A condition replaces the default for the profiles it matches, as the next section explains. An experiment that uses the variable wins over both for the profiles it enrolled: while it runs, those profiles get their variant's value, and the variable's conditions apply only to everyone else.

A variable is served only while it is enabled and before its expiry time. A disabled or expired variable is left out of what your app receives.

Variables and conditions belong to one project. The Scope bar at the top of the page shows which project you are looking at, and lets you switch to another.

How conditions decide which value a profile gets

A condition is a reusable audience rule: iOS devices, profiles in the EU, members of a cohort, or a random share of profiles. You define it once on the Conditions tab and attach it to as many variables as you need, each with its own value.

When a variable has several conditions, they are checked in the order they are listed on that variable, and the first one that matches decides the value. A profile that matches none gets the default. So put the narrowest condition first: if "iOS in the EU" sits below "iOS", no iPhone in the EU ever reaches it.

A percentage rollout matches profiles by a random percentile out of 100. The percentile comes from the device and the condition's bucketing seed, so the same device gets the same percentile on every fetch, and the profiles inside a 10% rollout are still inside when you widen it to 30%. Every condition that leaves the seed blank shares one, which puts the same profiles in the same band across all of them. Give a condition its own seed when its rollout should pick an independent slice.

Details the SDK sends with the fetch itself count toward matching, so a condition on something the device reports sees the value from that request.

What an experiment is

An experiment tests different values of your variables against each other and measures which one works better. It runs a control group, which serves as the baseline, against up to 7 variants, and each variant gives the same variables its own values.

Goals say what counts as a conversion: a profile property or cohort, the events a profile triggers during the experiment, or both. An experiment tracks up to 3 goals, and each one compares the conversion rate of every variant with the control.

An experiment enrolls a share of the profiles its targeting matches, the target percentage you set. A device is enrolled when its SDK asks to be enrolled as it fetches values. While the experiment runs, enrolled profiles get their variant's value, and the variable's own conditions apply only to everyone else.

An experiment starts as a draft. Starting it makes it Running, and stopping it makes it Completed. If you set an improvement target, it also completes itself once a variant reaches that target on every goal. A fixed number of days does not stop it. Once the days are up it shows as Expired while it is still running, so stop it yourself when you have read the results.

Use Cases

Change a value without a release

Change something in your app without waiting for a release.

1. Open Experience, then Adaptive Variables, and check the project in the Scope bar.
2. Press New variable.
3. Type the key your code reads. Keys use letters, numbers, and underscores, and cannot start with a number.
4. Enter the default value: true or false, a number, text, or a JSON object.
5. Leave Status on Running to serve it straight away, or choose Disabled to save it without serving it yet.
6. To stop serving it on a date, turn on Expiration time and pick a date and time at least a day ahead.
7. Press Save.

To change the value later, open the row's menu and choose Edit. Disable and Enable in the same menu stop and resume serving without deleting anything.

Serve a different value to one audience

Give one audience a different value while everyone else keeps the default.

1. On the Conditions tab, press New condition.
2. Name it for the audience, for example "iOS in the EU", and pick a color. The color marks the condition wherever it appears.
3. Under Definition, add rules on profile properties, cohorts, or profile groups.
4. Press Save.
5. On the Variables tab, open the variable's menu, choose Edit, and press Add condition override. Pick the condition, or create one on the spot with New condition.
6. Enter the value those profiles should get. Every override needs a value before you can save.
7. If the variable has more than one override, move the most specific one to the top.
8. Press Save.

Roll a change out to a growing share of profiles

Turn a feature on for a small share of profiles first, and widen it as it holds up.

1. On the Conditions tab, press New condition and turn on Percentage rollout. The rollout can be the whole condition, or it can narrow a set of rules in the Definition, in which case a profile has to match both.
2. Choose below and type 10. The readout beside it says about 10% of profiles.
3. Leave the bucketing seed blank, or give it a name of its own so this rollout picks a different slice from your other rollouts.
4. Press Save, then attach the condition to your flag variable with the value true, and leave the default false.
5. To widen the rollout, edit the condition and raise the number. The profiles already in it stay in.

Run an A/B test and keep it on track

Find out which of two values works better before serving it to everyone, and keep the test healthy while it runs.

1. On the Experiments tab, press New experiment.
2. On Basics, name the experiment and choose how it should stop.
3. On Targeting, set the share of profiles to enroll, and narrow the audience if the test is only for some profiles.
4. On Goals, describe the conversion you care about in the primary goal.
5. On Variants, pick the variable to test. Give the control group the value you serve today and Variant A the value you want to try.
6. Press Complete. The experiment is saved as a draft, so start it from its row's menu when you are ready.
7. While it runs, look for a warning beside Total profiles. It appears when a running experiment has enrolled no profiles 15 minutes after it started. Check that its targeting matches live profiles, that the target percentage is high enough, and that your SDK asks to be enrolled when it fetches values.
8. Choose Expired experiments in the list's filter to find the ones that have run past their fixed number of days, and stop each one from its row's menu.
9. To run a completed experiment again from scratch, choose Reset in its menu. Reset deletes all of its results and puts it back to draft, so you start it again yourself.
10. Once it has completed, open it from the list to read the outcome, and press Roll out winner to make the winning values the ones your app gets.

FAQs

My app still gets the old value.

Your app receives a change on its next fetch. If it still gets the old one, check that the variable is Enabled and not Expired, that no running experiment is deciding the value (the Experiment overrides conditions note under the key), and that a broader condition above yours is not matching first.

Why are Edit and Delete grayed out on a variable?

A lock beside the key means an experiment that has not completed uses it. The variable can be changed again once that experiment completes.

Why can I create variables but not conditions?

Creating a condition needs update rights on this feature, while creating a variable needs only create rights. Ask an administrator to grant update.

Why does the Hits column differ from the breakdown?

Hits counts only the times the default value was served. The breakdown adds the serves decided by each condition.

Will widening a rollout reshuffle who is in it?

No. A device's percentile depends only on the device and the condition's seed, so raising the number adds profiles and keeps everyone already in.

What happens to my variables when I delete a condition?

The condition is removed from every variable that uses it, and those variables serve their next matching condition or their default.

Why does an experiment show Expired when nobody stopped it?

It has run past its fixed number of days but has not been completed yet. It still counts as running until it completes, so stop it from its row's menu.

What does the warning beside Total profiles mean?

The experiment is running and has enrolled no profiles 15 minutes after it started. Check its targeting and target percentage, and that your SDK asks to be enrolled when it fetches values.

Related Resources