Unleash.Variant (Unleash v5.1.2)

View Source

Defines types and functions for representing and working with strategy and feature variants.

Variants extend feature flags beyond simple on/off states, enabling multiple return values for more granular feature control.

Feature flags are designed to let you decide which users have access to a feature. Variants are designed to let you decide which version of the feature are user gets access to.

## Overview

While a basic feature flag exists in either on or off states, variants allow for multiple possible states within an enabled feature. Variants can be defined:

  • Within strategies (recommended approach)
  • Directly on the feature flag (deprecated)

Variants have a weight which determines the likelihood of users receiving a specific variant.

## Common Use Case

A typical pattern involves:

  1. Using a feature flag to control access to an entire feature
  2. Applying strategies to target specific user segments
  3. Using variants to customise the feature experience for different segments

For example, you might use strategies to determine which user segments can access a new UI component, then use variants to show different button colors to different segments within that group for A/B testing.

## Documentation

Summary

Types

metadata()

Debug metadata explaining how a variant was selected.

result()
t()
variant()

A variant as stored on a feature/strategy (the struct), before selection.

Functions

select_feature_variant(feature, context)

Selects a feature-level variant for feature and context (deprecated feature variants).

select_strategy_variant(feature, variants, context)

Selects a strategy variant for feature from variants, using context for stickiness.

Types

metadata()

@type metadata() :: map()

Debug metadata explaining how a variant was selected.

result()

@type result() :: %{
  :enabled => boolean(),
  :name => String.t(),
  optional(:payload) => map()
}

t()

@type t() :: %{enabled: boolean(), name: String.t(), payload: map()}

variant()

@type variant() :: %Unleash.Variant{
  name: String.t() | nil,
  overrides: list(),
  payload: map() | nil,
  stickiness: String.t(),
  weight: integer() | nil
}

A variant as stored on a feature/strategy (the struct), before selection.

Functions

select_feature_variant(feature, context)

@spec select_feature_variant(Unleash.Feature.t(), Unleash.context()) ::
  {result(), metadata()}

Selects a feature-level variant for feature and context (deprecated feature variants).

select_strategy_variant(feature, variants, context)

@spec select_strategy_variant(Unleash.Feature.t(), [variant()], Unleash.context()) ::
  {result(), metadata()}

Selects a strategy variant for feature from variants, using context for stickiness.