Add a Feature Flag - Confidence Documentation

By the end of this guide, you have a header-redesign flag with two variants, a rule that serves a variant to a test user, and code that resolves the flag. The guide has these steps:

Create a client for the website so that it can resolve flags.
Create a flag for the header design, and define its schema.
Create variants of the header.
Use the flag in the website to control the header.
Force a variant for a user to test a specific variant.
Test resolving the flag with an evaluation context.

Each step shows how to do it with AI first, then in the Confidence app.

Do it with AI. Connect the Confidence MCP servers to your AI assistant, then run the whole guide with one prompt:

Create a client called "Web client" if it doesn't exist. Create a flag called
"header-redesign" on that client with a string property "color" and an integer
property "size". Add a variant "default-style" (color "black", size 14) and a
variant "new-style" (color "blue", size 16). Add an individual targeting rule
that serves "new-style" to user_id "user-test-id", then test resolving the flag
for that user.

Before You Begin

You need a Confidence account.
For the AI path, set up Confidence for your AI assistant. The Flags MCP server creates clients, flags, variants, and rules. The Docs MCP server returns SDK code snippets.

This video gives a quick overview of how feature flags work in 2 minutes and 10 seconds.

Use this guide to set up a flag that you resolve, but without changing anything in your code. This way, you can use the traffic the flag receives to set up and run A/B tests or rollouts using the A/B test quickstart or the rollout quickstart. Since the resolved flag value isn’t used in your code, nothing changes for your users.

Choose a Resolution Method That Fits Your Application

You can resolve a Confidence feature flag in two ways: by using Confidence’s managed resolver or hosting your own self-hosted resolver. Read more about the resolution options in the documentation.

Create a Client

You must associate all feature flags with at least one client. A client can, for example, be a backend service or a website. Clients use flags to deliver different user experiences. To resolve flags, a client must authenticate with Confidence using client credentials.

Confidence includes a default client that has the same name as your Confidence account. You can use this client, or create a more specific one for web feature flags in this quickstart.

With AI
In the App

Create a client called "Web client" if it doesn't exist, and give me its client secret.

The assistant uses the Flags MCP tools listClients, createClient, and getClientSecret.

Go to the Clients page

You can find it under the Admin section in the sidebar in Confidence.

Click Create and name the client

Name the client Web client (unless it already exists).

Click Create credential

You have now created a web client, and created the associated client credentials. These credentials are later used to resolve the flag.

Create a Flag

Flags let Confidence control the behavior of your application. For example, use a flag to control which machine learning model serves a recommendation, the number and size of tiles on a page, or a call to action message and its position on a sign-up page. For this tutorial, create a flag that controls the color and size of a header. The flag value has a schema. The value of a flag isn’t a single value, but a key-value map of properties. To avoid errors and make flags easier to work with, Confidence requires you to define a schema for the flag value. The schema describes the shape of the flag value by defining properties and their data types. In this guide, your flag controls the design of a header on a website. The design consists of color and size, so your flag needs two properties: color and size.

With AI
In the App

Create a flag called "header-redesign" on "Web client" with a string
property "color" and an integer property "size".

The assistant uses the Flags MCP tool createFlag, which sets the client and schema in one call.

Go to Confidence

Select Flags on the left sidebar.

Click + Create to create a new flag

Name the flag header-redesign

Select Web client in the clients dialog

Or select the client with the same name as your account.

Choose the flag type

Select JSON, because this flag has more than one property. A Boolean flag only turns a feature on or off.

Define the properties

For each property, enter a name and select a type. Add color with type String and size with type Integer.

You can add properties to an existing flag after you create it. Open the schema on the right sidebar to edit it.

When you create the flag, you associate the flag with a specific client. This means only that client can resolve the header-redesign flag. Limiting which flags are available to which clients is valuable for several reasons. For example, it prevents exposing flags to clients that run in uncontrolled environments such as mobile apps or server-side web apps. It also saves resources when resolving flags in batch (for example, at app start) by restricting resolution to only the relevant flags. Now that you defined the schema, you can create variants that have specific values for the color and size properties.

Create Variants

The two variants for the header redesign are black with size 14, and blue with size 16.

With AI
In the App

Add a variant "default-style" to header-redesign with color "black" and
size 14, and a variant "new-style" with color "blue" and size 16.

The assistant uses the Flags MCP tool addFlagVariant.

Click + Create variant and name it default-style

Enter values for the default style

Enter black as the value for color, and 14 as the value for size.

Click Save

Click + Create variant and name it new-style

Enter values for the new style

Enter blue as the value for color, and 16 as the value for size.

The two variants are now created, but they’re not yet reaching any user. To test your flag, use an individual targeting rule next.

Use the Flag

When resolving a flag into a value, you specify a default value. This default value applies if a user doesn’t match or isn’t assigned by a rule. The following sections show how to integrate the Confidence SDKs and set the default value for the header-redesign flag to color green and size 10. To have your AI assistant write the integration code for your stack, ask it:

Show me how to resolve the header-redesign flag with the Confidence SDK in my
project, with defaults color "green" and size 10.

The assistant uses the Docs MCP tool getCodeSnippetAndSdkIntegrationTips. To write the code yourself, follow the next sections.

Install Dependencies

You first need to install the necessary dependencies.

yarn add @openfeature/web-sdk @spotify-confidence/openfeature-web-provider

yarn add @openfeature/server-sdk @spotify-confidence/openfeature-server-provider-local

<!-- Add to pom.xml -->
<dependency>
    <groupId>com.spotify.confidence</groupId>
    <artifactId>openfeature-provider-local</artifactId>
    <version>latest</version>
</dependency>

go get github.com/spotify/confidence-resolver/openfeature-provider/go
go get github.com/open-feature/go-sdk

# Add to Cargo.toml
[dependencies]
spotify-confidence-openfeature-provider-local = "<latest>"
open-feature = "<latest>"

pip install confidence-openfeature-provider

// When using Swift Package Manager, add the following to Package.swift
.package(url: "git@github.com:spotify/confidence-sdk-swift.git", from: "<latest>")
.product(name: "Confidence", package: "confidence-sdk-swift"),
.product(name: "ConfidenceOpenFeature", package: "confidence-sdk-swift"),

implementation("com.spotify.confidence:openfeature-provider-android:<latest>")

Initialize Confidence

With dependencies installed, you can now create a Confidence provider for your platform and connect it to the OpenFeature SDK. You only need to do this once, preferably on app startup.

import { OpenFeature } from '@openfeature/web-sdk';
import { createConfidenceWebProvider } from '@spotify-confidence/openfeature-web-provider';

const provider = createConfidenceWebProvider({
  clientSecret: 'your-client-secret',
  timeout: 3000,
});

// Set the context that is relevant for your flag, like the user ID.
OpenFeature.setContext({
  user_id: 'user-test-id',
  plan: 'premium'
});

try {
  await OpenFeature.setProviderAndWait(provider);
} catch (error) {
  console.error('Failed to initialize Confidence provider:', error);
}

import { OpenFeature } from '@openfeature/server-sdk';
import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-server-provider-local';

const provider = createConfidenceServerProvider({
  flagClientSecret: 'your-client-secret',
});

await OpenFeature.setProviderAndWait(provider);

import com.spotify.confidence.OpenFeatureLocalResolveProvider;
import dev.openfeature.sdk.OpenFeatureAPI;
import dev.openfeature.sdk.Client;
import dev.openfeature.sdk.MutableContext;

// Create and register the provider
OpenFeatureLocalResolveProvider provider =
    new OpenFeatureLocalResolveProvider("your-client-secret");
OpenFeatureAPI.getInstance().setProviderAndWait(provider);

import (
    "context"
    "github.com/open-feature/go-sdk/openfeature"
    "github.com/spotify/confidence-resolver/openfeature-provider/go/confidence"
)

ctx := context.Background()

provider, err := confidence.NewProvider(ctx, confidence.ProviderConfig{
    ClientSecret: "your-client-secret",
})
if err != nil {
    log.Fatalf("Failed to create provider: %v", err)
}

openfeature.SetProviderAndWait(provider)

use open_feature::{EvaluationContext, OpenFeature};
use spotify_confidence_openfeature_provider_local::{ConfidenceProvider, ProviderOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = ProviderOptions::new("your-client-secret");
    let provider = ConfidenceProvider::new(options)?;

    OpenFeature::singleton_mut()
        .await
        .set_provider(provider)
        .await;

    Ok(())
}

from openfeature import api
from confidence import ConfidenceProvider

provider = ConfidenceProvider(client_secret="your-client-secret")

api.set_provider_and_wait(provider)

import Confidence
import ConfidenceProvider
import OpenFeature

let confidence = Confidence.Builder(clientSecret: "your-client-secret", loggerLevel: .NONE)
    .build()
let provider = ConfidenceFeatureProvider(
    confidence: confidence,
    initializationStrategy: .fetchAndActivate
)

let ctx = ImmutableContext(
    targetingKey: "user-test-id",
    structure: ImmutableStructure(
        attributes: [
            "user_id": .string("user-test-id"),
            "plan": .string("premium")
        ]
    )
)

await OpenFeatureAPI.shared.setProviderAndWait(provider: provider, initialContext: ctx)

import com.spotify.confidence.ConfidenceFactory
import com.spotify.confidence.ConfidenceFeatureProvider
import com.spotify.confidence.ConfidenceRegion
import com.spotify.confidence.InitialisationStrategy
import dev.openfeature.sdk.OpenFeatureAPI
import dev.openfeature.sdk.ImmutableContext
import dev.openfeature.sdk.Value

val confidence = ConfidenceFactory.create(
    context = app.applicationContext,
    clientSecret = "your-client-secret",
    region = ConfidenceRegion.EUROPE
)

val provider = ConfidenceFeatureProvider.create(
    confidence,
    initialisationStrategy = InitialisationStrategy.FetchAndActivate
)

OpenFeatureAPI.setProviderAndWait(provider)

val evaluationContext = ImmutableContext(
    targetingKey = "user-test-id",
    attributes = mapOf(
        "user_id" to Value.String("user-test-id"),
        "plan" to Value.String("premium")
    )
)
OpenFeatureAPI.setEvaluationContextAndWait(evaluationContext)

Access the Flag

You can access the flag and its values using dot notation for nested properties.

const client = OpenFeature.getClient();

// value of header-redesign is { size: <some int>, color: <some string>}
const size = client.getNumberValue('header-redesign.size', 10);
const color = client.getStringValue('header-redesign.color', 'blue');

const client = OpenFeature.getClient();

const context = {
  targetingKey: 'user-test-id',
  user_id: 'user-test-id',
  plan: 'premium'
};

// value of header-redesign is { size: <some int>, color: <some string>}
const size = await client.getNumberValue('header-redesign.size', 10, context);
const color = await client.getStringValue('header-redesign.color', 'blue', context);

Client client = OpenFeatureAPI.getInstance().getClient();

// Create evaluation context
MutableContext ctx = new MutableContext("user-test-id");
ctx.add("user_id", "user-test-id");
ctx.add("plan", "premium");

// value of header-redesign is { size: <some int>, color: <some string>}
Integer size = client.getIntegerValue("header-redesign.size", 10, ctx);
String color = client.getStringValue("header-redesign.color", "blue", ctx);

client := openfeature.NewClient("my-app")

evalCtx := openfeature.NewEvaluationContext("user-test-id", map[string]interface{}{
    "user_id": "user-test-id",
    "plan":    "premium",
})

// value of header-redesign is { size: <some int>, color: <some string>}
size, _ := client.IntValue(ctx, "header-redesign.size", 10, evalCtx)
color, _ := client.StringValue(ctx, "header-redesign.color", "green", evalCtx)

let client = OpenFeature::singleton().await.create_client();

let context = EvaluationContext::default()
    .with_targeting_key("user-test-id")
    .with_custom_field("user_id", "user-test-id")
    .with_custom_field("plan", "premium");

// value of header-redesign is { size: <some int>, color: <some string>}
let size = client
    .get_int_value("header-redesign.size", Some(&context), None)
    .await
    .unwrap_or(10);
let color = client
    .get_string_value("header-redesign.color", Some(&context), None)
    .await
    .unwrap_or_else(|_| "green".to_string());

from openfeature.evaluation_context import EvaluationContext

client = api.get_client()

context = EvaluationContext(
    targeting_key="user-test-id",
    attributes={
        "user_id": "user-test-id",
        "plan": "premium",
    }
)

# value of header-redesign is { size: <some int>, color: <some string>}
size = client.get_integer_value("header-redesign.size", default_value=10, evaluation_context=context)
color = client.get_string_value("header-redesign.color", default_value="blue", evaluation_context=context)

let client = OpenFeatureAPI.shared.getClient()

// value of header-redesign is { size: <some int>, color: <some string>}
let size = client.getIntegerValue(key: "header-redesign.size", defaultValue: 10)
let color = client.getStringValue(key: "header-redesign.color", defaultValue: "green")

val client = OpenFeatureAPI.getClient()

// value of header-redesign is { size: <some int>, color: <some string>}
val size = client.getIntegerValue("header-redesign.size", 10)
val color = client.getStringValue("header-redesign.color", "blue")

curl -H "Content-type: application/json" \
     --data '{
        "evaluation_context": {
          "user_id": "user-test-id",
          "plan": "premium"
        },
        "flags": ["flags/header-redesign"],
        "client_secret": "your-client-secret"
     }' \
     "https://resolver.confidence.dev/v1/flags:resolve"

The code snippets above set two fields in the context: the user_id and the plan this user is on, in this case premium. You can use the plan field in the context to create targeted rules. For example, with this information in the evaluation context, an A/B test can include only users on the premium plan as its target audience. This video gives a quick overview how targeting and evaluation contexts work in 2 minutes and 10 seconds.

If you were to run the code above you would only get the default values for the flag. Nothing tells the client that it should return any other value. To do so, you need to create flag variants and a rule that returns a variant.

Force a Variant For a User

To try out a variant, you can force it for a user with a specific user ID. You do this by creating an individual targeting rule on the flag. Individual targeting rules let you target specific attribute values, such as a list of user IDs. For example, you can add the identifiers of your team members so only your team can test the new experience in its early stages.

With AI
In the App

Create an individual targeting rule on header-redesign that serves
"new-style" to user_id "user-test-id".

The assistant uses the Flags MCP tool addOverrideRule.

If you re-run the code that fetches the flag value you now see that the flag resolves to a value other than the default.

Force all Variant For 50% of Employees

You can create a conditional targeting rule with a targeting audience that includes a subset of the users in that audience. For example, you can create a conditional targeting rule that targets 50% of the users in the "plan": "employee" audience. This way, provided that all employees have their plan set to employee, you can test the new experience on a subset of your colleagues.

With AI
In the App

Add a targeting rule on header-redesign that serves "new-style" to 50% of
users where plan is "employee", randomized on user_id.

The assistant uses the Flags MCP tool addTargetingRule.

On the flag page:

Click + Create rule and select Conditional targeting

Select new-style as the variant

Add attribute criterion

In the audience section, click Add attribute criterion and write plan as field name with type string and click Add.

Set the inclusion rule to be plan is employee

Enter user_id as the randomization unit

Set the allocation to 50%

Click Save

Enable the rule

Click the toggle on the rule card to enable it.

Since you now have two rules, the rules evaluate in the order of the list on the flag page. If a user is eligible for the first rule, it returns a variant for the user. If not, Confidence evaluates if the user is eligible for the second rule. In this case, since only the user with ID user-test-id is eligible for the individual targeting rule, Confidence evaluates eligibility for the second rule for everyone else. The second rule, in turn, only targets users on the employee plan. Change the priority of the rules by dragging the rule cards into the desired order and clicking save.

Test Flag Resolution

Test that the rule you expect returns a variant. You give an evaluation context and see which variant the flag resolves to.

With AI
In the App

Test resolving header-redesign for user_id "user-test-id".

The assistant uses the Flags MCP tool resolveFlag. Expect the new-style variant.

The Resolve tester shows which rules match and which don’t, together with the reasons why.On the page of your flag, select Test rules at the top of the list of rules. Click Add evaluation context and give the context you want to test to resolve. For example, to test the individual targeting rule for the user with ID user-test-id, add the user_id field with the value user-test-id to the evaluation context. Click Resolve to confirm that the individual targeting rule succeeds and returns the new-style variant.

Most of the SDKs also output log messages that redirect you to the resolve tester specifically for the flag evaluation that the SDK performed. The link has a message with the prefix:

See resolves for <flagName> in Confidence:

To share a specific test run with someone, copy the URL and send it as a link. The link directs them to the Resolve tester with all context data preserved.

Create a Metric

Set up a metric to measure the impact of your flags

Launch a Rollout

Gradually release your feature to users

Launch an A/B Test

Run an experiment to compare variants

Flags Reference

Deep dive into feature flag concepts and configuration

​Before You Begin

​Choose a Resolution Method That Fits Your Application

​Create a Client

​Create a Flag

​Create Variants

​Use the Flag

​Install Dependencies

​Initialize Confidence

​Access the Flag

​Force a Variant For a User

​Force all Variant For 50% of Employees

​Test Flag Resolution

​Related Resources

Create a Metric

Launch a Rollout

Launch an A/B Test

Flags Reference

Before You Begin

Choose a Resolution Method That Fits Your Application

Create a Client

Create a Flag

Create Variants

Use the Flag

Install Dependencies

Initialize Confidence

Access the Flag

Force a Variant For a User

Force all Variant For 50% of Employees

Test Flag Resolution

Related Resources