Percentage rollouts by context attribute

Overview

This topic explains how to perform percentage rollouts by associating flag variations with context attributes, whether the user context is in an anonymous or logged-in state.

Roll out by context attribute

You can assign variations to contexts through a percentage rollout based on any attribute in the "Context kind" and "Attribute" menus.

For example, when you roll out a feature to 25% of user contexts, you can specify that each end user be assigned to a variation based on the value of the "country" attribute in their user context, rather than being assigned to a variation based on their context key. This ensures that LaunchDarkly assigns all customers with matching attribute-value pairs to the same variation. To learn more about attributes, read Context attributes.

Here is an image of a rollout by the "country" attribute for a user context:

The attribute must have either string values or integer numeric values. If you use an attribute with a numeric value that includes a fraction, or has a value type besides string or number, then the SDK cannot use the attribute value and assigns the context to an arbitrary variation.

Target and roll out by different context attributes

When you use a percentage rollout on a flag's targeting rule, you can target on one context kind, but roll out the feature based on a different context kind. We only recommend doing this if you are using multi-contexts. For example, if your app is evaluating all flags using a multi-context that includes both user and organization context kinds, you might target by an organization attribute but roll out the feature based on a user attribute.

Here is an image of a rule targeting the "country" attribute for an organization context, rolling out by user:

In this example, the feature will be rolled out to a percentage of users whose organization is in Canada.

Use caution with this approach, as it may have unintended consequences if not all of the contexts that encounter this flag are multi-contexts with both user and organization. To learn more, read Percentage rollout logic and context kinds.

Maintaining customer experience across anonymous and logged-in states

Contexts are designed to let you target different types of entities, such as devices and organizations, precisely. However, if your application requires a user login, you will probably use a "user" context, at least for some of the attributes you are storing. When your application has both anonymous and logged-in states, you want to maintain the customer experience across both states.

There are two approaches to maintaining the customer experience across pre-login (anonymous end user) and post-login (known end user) states: single contexts and multi-contexts.

Single contexts

The first approach uses single contexts. You can set an attribute in a user context and set your percentage rollouts to roll out based on that attribute.

Here's how to do this:

1. Store a unique identifier for the anonymous end user. A session ID or UUID works well.

• You can store this identifier in local storage or a cookie.
• If you are using a mobile SDK, the SDK can generate the unique identifier for you and use it as the context key.

2. Use this unique identifier as both the context's key and an attribute in the user context until the end user logs in. The attribute can be named anything, for example, uniqueId.
3. While the end user is logged in, set the context's key to their real (primary) context key, but continue to use the stored unique identifier as the context's uniqueId attribute.
4. For all flags, or for those that may affect logged out users, set your flags to serve percentage rollouts based on the uniqueId attribute.

To learn more about anonymous contexts, read Anonymous contexts.

One disadvantage to this approach is that using a uniqueId attribute, rather than context key, means that you cannot easily convert the rollout strategy from percentage rollout to experiment. To learn more, read Allocate audiences.

Multi-contexts

The second approach uses multi-contexts. You can use an attribute, such as the context key, in a non-user context and set flags' percentage rollouts based on that attribute.

Here's how to do this:

1. Store a unique identifier for the anonymous end user as the context key in a different kind of context, such as a device context. A device ID or UUID works well.
2. Target the end user based on this context key while they are not yet logged in.
3. After the end user logs in, store their user information in a user context. Associate the device context and the user context with each other. To do this, identify a multi-context that includes both individual contexts when you want the association to occur.
4. For all flags, or for those that may affect logged out users, set your flags to serve percentage rollouts based on the unique identifier in the device context.

To learn more, read Multi-contexts and context instances.