JSON targeting

Overview

This topic explains how to create and edit flag targeting rules using JSON.

Editing flag rules using JSON follows the same model as the JSON response from the Get feature flag endpoint in the REST API.

View JSON targeting rules

To view a flag’s targeting rules in JSON, navigate to the Targeting tab and click the icon in the “Targeting configuration” section:

Basic JSON structure

Below is an example of the basic JSON structure for a boolean feature flag:

1
{
2
  "on": false, // the flag is toggled off
3
  "prerequisites": [], // the flag has no prerequisites
4
  "contextTargets": [], // the flag has no individual targeting rules
5
  "rules": [], // the flag has no custom targeting rules
6
  "fallthrough": {
7
    "variation": 0 // the fallthrough, or default, variation is true
8
  },
9
  "offVariation": 1 // the off variation is false
10
}

This example flag:

• is toggled off
• has no prerequisites
• has no targeting rules besides the default rule
• has true (0) as the default rule
• has false (1) as the off variation

Variation IDs

For boolean flags, the ID of the true variation is always 0, and the ID of the false variation is always 1.

For multivariate flags, the ID of the first variation is 0, the ID of the second variation is 1, and so on.

Flag on/off status

To toggle a flag on or off, set on to true or false.

Here is what a flag toggle looks like in the user interface (UI):

Here is an example of how to toggle a flag on:

1
{
2
  "on": true
3
}

To learn about toggling flags on and off in the UI, read Turning flags on and off.

Off variation

The off variation is the variation served to all contexts when a flag is off.

Here is an example of how to set the off variation:

1
{
2
  "offVariation": 1 // the off variation is false
3
}

To learn how to set the off variation in the UI, read The off variation.

Default rule or variation

The default, or fallthrough, rule is the rollout or variation that a flag serves when a context doesn’t match any other targeting rules on the flag.

Here is what a default rule looks like in the UI:

To set a default variation, use fallthrough and set variation to the ID of the flag variation you want to use as the default variation.

Here is an example of setting the default variation on a boolean flag:

1
{
2
  "fallthrough": {
3
    "variation": 1 // the default variation is false
4
  }
5
}

You can also set a rollout, instead of a single variation, as the default rule. To learn how, read Rollouts.

To learn how to set the default rule in the UI, read The default rule.

Prerequisites

To set a prerequisite, use prerequisites with the following key/value pairs:

• key: the prerequisite flag key.
• variation: the ID of the prerequisite flag’s variation you want to require.

Here is what a prerequisite rule looks like in the UI:

Here is an example prerequisite rule requiring the prerequisite variation for the flag alt-sort-order to be true:

1
{
2
  "prerequisites": [
3
    {
4
    "key": "alt-sort-order", // the prerequisite flag key
5
    "variation": 0 // the prerequisite flag variation must be true
6
    }
7
  ]
8
}

In the above example, if the prerequisite flag is on: true, and a context encountering this flag is receiving the true (0) variation of the prerequisite flag, then the context is subject to this flag’s targeting rules.

If the prerequisite flag is on: false, or the context is receiving a variation other than true (0), then the context will receive this flag’s offVariation of false (1).

To learn how to use prerequisite flags in the UI, read Flag prerequisites.

Individual targeting

Individual targeting lets you serve chosen variations to specific contexts.

Here is what an individual targeting rule looks like in the UI:

To individually target a context, use contextTargets with the following key/value pairs:

• variation: the ID of the variation you want to serve.
• values: the context keys you want to target.
• contextKind: the context kind of the contexts you want to target.

Here is an example individual targeting rule for a user context:

1
{
2
  "contextTargets": [{
3
    "variation": 0, // this individual targeting rule serves the true variation
4
    "values": [
5
      "user-key-123abc" // the context key
6
    ],
7
    "contextKind": "user" // the context kind is user
8
  }]
9
}

To learn how to target individual contexts in the UI, read Individual targeting.

Target multiple context kinds

You can use multiple rules if you need to target multiple context kinds.

This example flag targets both user and organization contexts:

1
{
2
  "contextTargets": [{
3
    "variation": 0, // this individual targeting rule serves the true variation
4
    "values": [
5
      "user-key-123abc", // the first user context key
6
      "user-key-456def" // the second user context key
7
    ],
8
    "contextKind": "user" // the context kind is user for both contexts
9
  },
10
  {
11
    "variation": 0, // this individual targeting rule serves the true variation
12
    "values": [
13
      "org-key-123abc", // the first organization context key
14
      "org-key-456def" // the second organization context key
15
    ],
16
    "contextKind": "organization" // the context kind is organization for both contexts
17
  }]
18
}

Target different variations

You can use multiple rules if some individually targeted contexts should receive different variations than others.

This example flag serves true to some contexts and false to others:

1
{
2
  "contextTargets": [{
3
    "variation": 0, // this individual targeting rule serves the true variation
4
    "values": [
5
      "user-key-123abc", // the first user context key
6
      
7
    ],
8
    "contextKind": "user" // the context kind is user
9
  },
10
  {
11
    "variation": 1, // this individual targeting rule serves the false variation
12
    "values": [
13
      "user-key-456def" // the second user context key
14
    ],
15
    "contextKind": "user" // the context kind is user
16
  }]
17
}

Segment targeting

Segment targeting rules let you serve chosen variations to specific LaunchDarkly segments.

Here is what a segment targeting rule looks like in the UI:

To target a segment, use clauses with the following key/value pairs:

• attribute: segmentMatch or not-SegmentMatch, depending on whether or not you want the rule to target contexts in the chosen segment, or not in the chosen segment
• op: segmentMatch
• negate: set to false if you set attribute to segmentMatch. Set to true if you set attribute to not-segmentMatch.
• values: the segment keys you want to target in the rule

1
{
2
  "rules": [
3
    {
4
      "clauses": [
5
        {
6
          "attribute": "segmentMatch", // this rule will target contexts in the segment
7
          "contextKind": "", // leave the contextKind blank for segment targeting
8
          "negate": false, // the attribute is segmentMatch, so this is set to false
9
          "op": "segmentMatch", // op is always segmentMatch
10
          "values": [
11
            "internal-testers", // the segment key of the segment you want to target
12
          ]
13
        }
14
      ],
15
      "description": "Include internal testers", // the rule description, optional
16
      "variation": 0 // this rule is serving true
17
    }
18
  ]
19
}

To learn how to build segment targeting rules in the UI, read Segment targeting.

Mobile targeting

Mobile targeting rules let you control which mobile apps and devices receive a variation of a feature flag.

Here is an example of a mobile targeting rule in the UI:

To target mobile devices, use rules with the following key/value pairs:

• description (optional): the description of the rule.
• variation: the ID of the variation you want to serve.
• clauses with the following key/value pairs:
  • contextKind: either ld_application or ld_device, depending on if you want to target mobile applications or mobile devices in this rule.
  • attribute: the context attribute you want to use in the rule.
  • op: the operators available depend on your context kind and attribute:
    • if your contextKind is ld_application, and your attribute is version support status, then applicationVersionSupported is the only available operator.
    • otherwise, use the standard operator you want to use in the rule.
  • negate: set to true to use the inverse of the operator. For example, if op is set to in, use "negate": true to use “is not in” as the operator. Otherwise, set to false.
  • values: the attribute values you want to use in the rule.

1
{
2
  "rules": [
3
    {
4
      "description": "Support for versions 12.5 and higher", // the rule description, optional
5
      "variation": 0, // this mobile rule serves the true variation
6
      "clauses": [
7
        {"contextKind": "ld_application",
8
          "attribute": "version_support_status",
9
          "op": "applicationVersionSupported",
10
          "negate": false,
11
          "attribute": "version_support_status", // the application attribute is "version support status"
12
          "contextKind": "device", // the context kind is device
13
          "negate": false,
14
          "op": "applicationVersionSupported", // the operator is "is supported for"
15
          "values": [
16
            "12.5" // the application version number is 12.5
17
          ]
18
        }
19
      ]
20
    }
21
  ]
22
}

To learn how to build mobile targeting rules in the UI, read Mobile targeting.

Custom targeting rules

Custom targeting rules let you target contexts based on their context kind and attributes.

Here is an example of a custom targeting rule in the UI:

To target custom context kinds and attributes, use rules with the following key/value pairs:

• description (optional): the description of the rule.
• variation: the ID of the variation you want to serve.
• values: the context keys you want to target.
• clauses, with the following key/value pairs:
  • contextKind: the context kind of the contexts you want to target.
  • attribute: the context attribute you want to use in the rule.
  • op: the standard operator you want to use in the rule.
  • negate: leave set to true, or set to false to use the inverse of the operator. For example, if op is set to in, use "negate": true to use “is not in” as the operator.
  • values: the attribute values you want to use in the rule.
• trackEvents (optional): true or false depending on whether or not you want to send feature events to LaunchDarkly.

Here is an example custom targeting rule that targets customers with an email address that ends in .edu:

1
{
2
  "rules": [{
3
    "description": "Student customers", // the rule description, optional
4
    "variation": 0, // this custom rule serves the true variation
5
    "clauses": [{
6
      "contextKind": "user", // the context kind is user
7
      "attribute": "email", // the context attribute is "email"
8
      "op": "endsWith", // the rule operator is "ends with"
9
      "negate": false, // the operator is not negated
10
      "values": [
11
        ".edu" // the attribute value
12
      ]
13
    }],
14
    "trackEvents": false // the flag is not sending feature events to LaunchDarkly, optional
15
  }]
16
}

Here is an example targeting rule that targets accounts for an Early Access Program (EAP):

1
{
2
  "rules": [{
3
    "description": "Early access accounts", // the rule description, optional
4
    "variation": 0, // this custom rule serves the true variation
5
    "clauses": [{
6
      "contextKind": "account", // the context kind is account
7
      "attribute": "eap-account", // the context attribute is "eap-account"
8
      "op": "in", // the rule operator is "is one of"
9
      "negate": false, // the operator is not negated
10
      "values": [
11
        "true" // the attribute value is true
12
      ]
13
    }],
14
    "trackEvents": true // the flag is sending feature events to LaunchDarkly, optional
15
  }]
16
}

To learn how to build custom targeting rules in the UI, read Custom rules.

Rollouts

When you create a custom rule or default rule, you can choose to serve a rollout instead of a single variation.

There are three kinds of rollouts:

• Manual percentage rollout
• Progressive rollout
• Guarded rollout

Manual percentage rollout

Percentage rollouts let you roll out your feature to a small percentage of contexts and, as you become more confident your feature is working as intended, manually increase the percentage over time.

Here is what a percentage rollout looks like in the UI:

To create a manual percentage rollout, use percentageRolloutConfig with the following key/value pairs:

• contextKind (optional): the context kind you want to roll out by. Defaults to your default context kind.
• bucketBy (optional): the attribute value you want to roll out by. Defaults to key.
• variations, with the following key/value pairs:
  • variation: the ID of the variation you want to serve.
  • weight: the percentage of contexts you want to include in that variation. Include three decimal places in the percentage, with no . or ,. Do not include leading 0s. For example:
    • to include 5.5% of contexts in a variation, set the weight to 5500.
    • to include 75.5% of contexts in a variation, set the weight to 75500. The weight must add up to 100% between all of the variations.

The below example shows how to rollout the true variation to 50% of contexts and the false variation to 50% of contexts on the default rule of a flag.

Here is how to set the rollout using JSON:

1
{
2
  "percentageRolloutConfig": {
3
    "contextKind": "user", // rolling out to user contexts,
4
    "bucketBy": "key", // by user key
5
    "variations": [
6
      {
7
        "variation": 0, // this part of the rollout serves the true variation
8
        "weight": 50000 // 50% of contexts will be served this variation
9
      },
10
      {
11
        "variation": 1, // this part of the rollout serves the false variation
12
        "weight": 50000 // 50% of contexts will be served this variation
13
      }
14
    ]
15
  }
16
}

To learn how to create percentage rollouts in the UI, read Percentage rollouts.

Progressive rollout

A progressive rollout lets you serve a given flag variation to a specified percentage of contexts, and gradually increases that percentage over a specified time.

Here is what a progressive rollout looks like in the UI:

To create a progressive rollout, use progressiveRolloutConfig with the following key/value pairs:

• contextKind: the context kind you want to roll out by. Defaults to your default context kind.
• controlVariation: the variation ID of the variation you want to serve at the beginning of the rollout. For boolean flags, this variation is automatically set based on the value the flag is currently serving, usually the off variation or the default variation.
• endVariation: the variation ID of the variation you want to roll out over time. For boolean flags, this variation is automatically set based on the variation not currently being served.
• steps, with the following key/value pairs:
  • rolloutWeight: the percentage of contexts you want to include in that rollout step. Include three decimal places in the percentage, with no . or ,. Do not include leading 0s. For example, to include 5.5% of contexts in a rollout step, set the rolloutWeight to 5500. To include 10.5% of contexts in a variation, set the rolloutWeight to 10500. The weight must add up to 100% between all of the rollout steps.
  • duration with the following key/value pairs:
    • quantity: the length of time you want that step in the rollout to last, in the units specified in unit.
    • unit: the unit of time you want to use in the rollout. Options include:
      • day
      • hour
      • minute

The below example shows a progressive rollout over 20 hours on the default rule of a flag.

Here is how to set the rollout using JSON:

1
{
2
  "fallthrough": {
3
    "progressiveRolloutConfig": {
4
        "contextKind": "user", // rolling out by user context kind
5
        "controlVariation": 1, // the starting variation is false. Not required for boolean flags
6
        "endVariation": 0, // the flag is rolling out to true. Not required for boolean flags
7
        "steps": [
8
          {
9
            "rolloutWeight": 1000, // 1% of contexts are in the first step
10
            "duration": {
11
                "quantity": 4,
12
                "unit": "hour" // each step will take four hours
13
            }
14
          },
15
          {
16
            "rolloutWeight": 5000, // 5% of contexts are in the second step
17
            "duration": {
18
                "quantity": 4,
19
                "unit": "hour"
20
            }
21
          },
22
          {
23
            "rolloutWeight": 10000, // 10% of contexts are in the third step
24
            "duration": {
25
                "quantity": 4,
26
                "unit": "hour"
27
            }
28
          },
29
          {
30
            "rolloutWeight": 25000, // 25% of contexts are in the fourth step
31
            "duration": {
32
                "quantity": 4,
33
                "unit": "hour"
34
            }
35
          },
36
          {
37
              "rolloutWeight": 50000, // 50% of contexts are in the fourth step
38
              "duration": {
39
                  "quantity": 4,
40
                  "unit": "hour"
41
          }
42
        }
43
      ]
44
    }
45
  }
46
}

To learn how to build progressive rollouts in the UI, read Progressive rollouts.

Guarded rollout

Guarded rollouts let you attach a metric to a rollout to monitor the performance of a flag over time, and to take action on the results.

Here is what a guarded rollout setup looks like in the UI:

To create a guarded rollout, use guardedRolloutConfig with the following key/value pairs:

• randomizationUnit: the context kind you want to target by.
• stages with the following key/value pairs:
  • monitoringWindowMilliseconds: the length of time you want that step in the rollout to last, in milliseconds.
  • rolloutWeight: the percentage of contexts you want to include in that rollout step. Include three decimal places in the percentage, with no . or ,. Do not include leading 0s. For example, to include 5.5% of contexts in a rollout step, set the rolloutWeight to 5500. To include 10.5% of contexts in a variation, set the rolloutWeight to 10500. The weight must add up to 100% between all of the rollout steps.
• metrics with the following key/value pairs:
  • metricKey: the key of the metric you want to monitor.
  • onRegression with the following key/value pair:
    • rollback: whether or not you want LaunchDarkly to automatically roll back the release in the event of a regression. Options include true or false.
• regressionThreshold: the regression threshold you want for the metric.

The below example shows a guarded rollout over 24 hours on the default rule of a flag, using a metric called sentry-errors.

Here is how to set the guarded rollout using JSON:

1
{
2
  "guardedRolloutConfig": {
3
    "randomizationUnit": "request", // the context kind to target by
4
    "controlVariation": 1, // the starting variation is false. Not required for boolean flags
5
    "endVariation": 0, // the flag is rolling out to true. Not required for boolean flags
6
    "stages": [
7
      {
8
        "monitoringWindowMilliseconds": 17280000, // this stage lasts 4.8 hours
9
        "rolloutWeight": 1000 // 1% of contexts are in the first stage
10
      },
11
      {
12
        "monitoringWindowMilliseconds": 17280000, // this stage lasts 4.8 hours
13
        "rolloutWeight": 5000 // 5% of contexts are in the second stage
14
      },
15
      {
16
        "monitoringWindowMilliseconds": 17280000, // this stage lasts 4.8 hours
17
        "rolloutWeight": 10000 // 10% of contexts are in the third stage
18
      },
19
      {
20
        "monitoringWindowMilliseconds": 17280000, // this stage lasts 4.8 hours
21
        "rolloutWeight": 25000 // 25% of contexts are in the fourth stage
22
      },
23
      {
24
        "monitoringWindowMilliseconds": 17280000, // this stage lasts 4.8 hours
25
        "rolloutWeight": 50000 // 50% of contexts are in the fifth stage
26
      }
27
    ],
28
    "metrics": [
29
      {
30
        "metricKey": "sentry-errors", // the metric key
31
        "onRegression": { // if a regression is detected, then
32
            "rollback": true, // LaunchDarkly will automatically roll back the release
33
        },
34
        "regressionThreshold": 0.01 // the custom regression threshold for the metric is set to 1%
35
      }
36
    ]
37
  }
38
}

To learn how to build guarded rollouts in the UI, read Guarded rollouts.