Predefined variations documentation

website/docs/advanced/predefined-variations.mdx

@@ -0,0 +1,114 @@
+---
+id: predefined-variations
+title: Predefined Variations
+description: Learn about free-form values and predefined variations in ConfigCat, how they differ, and when to use each approach for managing feature flag values.
+---
+
+ConfigCat supports two value-modes for feature flags: _free-form values_ and _predefined variations_. This guide explains the differences between these approaches and helps you choose the right one for your use case.
+
+
+## Overview
+
+In ConfigCat, you can configure feature flags to operate in either of these modes:
+
+- **Free-form values** - Allows arbitrary feature flag values. You can set served values to any value.
+- **Predefined variations** - Constrains feature flag values to a set of variations specified beforehand. You can select served values from a dropdown.
+
+<p>
+    <img src="/docs/assets/predefined-variations/usage_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+</p>
+
+## Free-form values
+Free-form values are the traditional, unrestrictive mode that lets you enter a feature flag's exact value each time you set it.
+
+<p>
+    <img src="/docs/assets/predefined-variations/free-form-create_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+</p>
+
+### Characteristics
+
+- **Direct Input**: You type or input the value directly when setting up flag rules
+- **Ad-hoc Definition**: Values are defined on-the-fly as needed
+- **No Reusability**: Each value must be entered separately for each rule
+- **Simple Setup**: Straightforward for basic use cases
+- **Flexible**: Any valid value can be entered at any time
+
+### Use cases
+
+Free-form values work well when you have simple, one-off configurations where feature flag values are unique and unlikely to be reused. They're ideal when you need quick setup without upfront planning, especially when working with primitive values like booleans or simple strings and numbers. This approach is also suitable when values change frequently or unpredictably.
+
+
+
+## Predefined variations
+
+Predefined variations allow you to define a set of reusable values upfront when creating a feature flag. These variations can then be selected from a dropdown when setting up flag rules. Each variation consists of three fields:
+
+<p>
+    <img src="/docs/assets/predefined-variations/predefined-variations-create_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+</p>
+
+### Variation fields
+
+| Field | Description |
+|-------|-------------|
+| Served value | **Required.** The actual value that feature flag evaluation will return in your application when this variation is selected. |
+| Display name | Optional. A human-readable identifier for the variation displayed in the dropdown. If not provided, a string representation of the served value is displayed instead. |
+| Hint | Optional. Additional context or description to explain when or why to use this variation. It will be visible as a tooltip. |
+
+### Characteristics
+
+- **Defined at Creation**: Variations must be defined when creating the feature flag
+- **Reusability**: Define once, use multiple times across flag rules
+- **Consistency**: Ensures the same values are used throughout your configuration
+- **Dropdown Selection**: Choose from predefined options instead of typing
+
+### Use cases
+
+Predefined variations are ideal when you have a standard set of values used across multiple rules, especially when consistency is critical for things like color schemes, API endpoints, or configuration objects. They work well when multiple team members need to understand what each value represents and you want to prevent typos or invalid values. This approach is particularly valuable when complex values like JSON objects need to be reused, when you need to provide guidance on when to use specific values, and when values are known upfront and relatively stable.
+
+
+## Converting between free-form values and predefined variations
+
+ConfigCat provides an easy way to convert feature flags between free-form values and predefined variations.
+
+### Converting to predefined variations
+
+When you convert a feature flag from free-form values to predefined variations, ConfigCat automatically collects all currently used values from your existing flag rules. These collected values are presented as suggested variations, but you can modify their display names and hints, or even add new variations.
+
+The conversion doesn't affect your deployed applications.
+
+### Converting to free-form values
+
+When you convert a feature flag from predefined variations to free-form values, the actual values from variations are extracted and feature flag values are updated to use the values directly. Display names and hints are irreversibly deleted, leaving only the values.
+
+The conversion doesn't affect your deployed applications.
+
+## Working with predefined variations
+
+### Creating a feature flag with predefined variations
+
+When creating a new feature flag, you can choose between free-form values and predefined variations.
+
+### Managing predefined variations
+
+You can add/remove/modify predefined variations for a feature flag by clicking the related button in any served value dropdowns or by clicking the **Manage predefined variations** item in the kebab (3 dots) menu of the feature flag.  
+
+<p>
+    <img src="/docs/assets/predefined-variations/manage_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+</p>
+
+You can create additional variations as needed at any time. However, you can only remove a predefined variation if it is not currently in use.  
+
+You can modify the display name and hint of predefined variations at any time, but you can only change the served value of a predefined variation if it is not currently in use.
+
+## Variation ID vs predefined variations
+
+ConfigCat also has a feature called _Variation ID_, but this is different from predefined variations, as it is designed primarily for analytics and A/B testing integrations. It is a hashed identifier of the feature flag's served value.
+
+However, since predefined variations require unique served values, there is an inherent connection between the two concepts: a Variation ID uniquely identifies a predefined variation.
+
+Therefore, if you enable the Variation ID feature in your product's preferences as explained [here](../variation-id-for-analytics/#how-to-access-variation-ids), the **Manage predefined variations** dialog will also display the Variation IDs corresponding to the variations.
+
+:::tip
+Learn more about Variation ID [here](../variation-id-for-analytics).
+:::

website/docs/advanced/variation-id-for-analytics.mdx

@@ -0,0 +1,34 @@
+---
+id: variation-id-for-analytics
+title: Variation ID for analytics
+description: Learn about how to utilize the Variation ID to enrich feature flag evaluation events.
+---
+
+To support working with feature flags, especially A/B testing and analytics, ConfigCat provides an auto-generated identifier called Variation ID for each distinct served value. This identifier is particularly useful when integrating with analytics tools.
+
+## What is a Variation ID?
+
+The _Variation ID_ is a hashed version of the feature flag's served value. For feature flags with lengthy values (such as JSON objects), the Variation ID provides a shorter, more manageable identifier that can be sent to analytics platforms, instead of the full value.
+
+## How to access Variation IDs
+
+You can view Variation IDs on the ConfigCat Dashboard by enabling the **Show Variation IDs to support A/B testing** setting. Learn more about this setting <a href="https://app.configcat.com/product/preferences" target="_blank">here</a>.
+
+## Variation ID vs. PredefinedVariationID
+
+:::note
+`Variation ID` (for analytics) is different from `PredefinedVariationID` available in the Public Management API:
+
+`Variation ID` is a hashed identifier of the feature flag's served value, used for analytics and A/B testing integrations. This is what you send to analytics tools like Amplitude, Google Analytics, Mixpanel, and Segment.  
+`PredefinedVariationID` is the resource identifier in the ConfigCat Public Management API that can be used to reference a specific predefined variation when managing feature flags programmatically. Read more at [Predefined variations](/advanced/predefined-variations).
+:::
+
+## Using Variation IDs with analytics integrations
+
+When integrating ConfigCat with analytics platforms, you can send the Variation ID along with (or instead of) the feature flag value. This is especially recommended for text feature flags with lengthy values (such as JSON configurations), maintaining consistent identifiers across analytics reports, and simplifying A/B test analysis.
+
+For detailed integration instructions, see the documentation of
+- [Amplitude integration](/integrations/amplitude),
+- [Google Analytics integration](/integrations/google-analytics),
+- [Mixpanel integration](/integrations/mixpanel),
+- [Segment integration](/integrations/segment).

website/docs/integrations/amplitude.mdx

@@ -253,6 +253,8 @@ you have to send the `user_id` property as well to identify your user. You can u
 :::note
 For Text feature flags with lengthy values (e.g., JSON), send the `variationId` instead of the `value` as the `variant` to Amplitude.
 The `variationId` is a hashed version of the feature flag value, accessible on the ConfigCat Dashboard by enabling the _Show VariationIDs to support A/B testing_ setting. Learn more [here](https://app.configcat.com/product/preferences).
+
+For more information about Variation IDs, see [Variation ID for analytics](/advanced/variation-id-for-analytics).
 :::
 
 4. Deploy your application and wait for feature flag evaluations to happen so Experiments in Amplitude could be populated.

website/docs/integrations/google-analytics.mdx

@@ -76,6 +76,8 @@ While our documentation primarily provides code examples for JavaScript-based SD
 
 :::note
 For Text feature flags with lengthy values (e.g., JSON), send the `variationId` instead of the `value` as the `exp_variant_string` to Google Analytics. The `variationId` is a hashed version of the feature flag value, accessible on the ConfigCat Dashboard by enabling the _Show VariationIDs to support A/B testing_ setting. Learn more [here](https://app.configcat.com/product/preferences).
+
+For more information about Variation IDs, see [Variation ID for analytics](/advanced/variation-id-for-analytics).
 :::
 
 4. **Deploy your application** and wait for feature flag evaluations to occur. This process might take 1-2 days for the `experience_impression` events to populate in Google Analytics.

website/docs/integrations/mixpanel.mdx

@@ -259,6 +259,8 @@ you have to send the [distinct_id](https://docs.mixpanel.com/docs/tracking-metho
 :::note
 For Text feature flags with lengthy values (e.g., JSON), send the `variationId` instead of the `value` as the `Variant name` to Mixpanel.
 The `variationId` is a hashed version of the feature flag value, accessible on the ConfigCat Dashboard by enabling the _Show VariationIDs to support A/B testing_ setting. Learn more [here](https://app.configcat.com/product/preferences).
+
+For more information about Variation IDs, see [Variation ID for analytics](/advanced/variation-id-for-analytics).
 :::
 
 4. Deploy your application and wait for feature flag evaluations to happen so Experiments in Mixpanel could be populated.

website/docs/integrations/segment.mdx

@@ -421,6 +421,8 @@ you can integrate with other languages by sending an event to Twilio Segment wit
 :::note
 For Text feature flags with lengthy values (e.g., JSON), send the `variationId` instead of the `value` as the `value` to Twilio Segment.
 The `variationId` is a hashed version of the feature flag value, accessible on the ConfigCat Dashboard by enabling the _Show VariationIDs to support A/B testing_ setting. Learn more [here](https://app.configcat.com/product/preferences).
+
+For more information about Variation IDs, see [Variation ID for analytics](/advanced/variation-id-for-analytics).
 :::
 
 4. Deploy your application and wait for feature flag evaluations to happen so feature flag evaluation events can be sent to Twilio Segment.

website/docs/main-concepts.mdx

@@ -28,6 +28,22 @@ A _Feature Flag_ is a _Setting_ of type Bool.
 | Whole Number   | Integer      | Any whole number within the range of `Int32`.                                      |
 | Decimal Number | Double       | Any decimal number within the range of `double`.                                   |
 
+### Free-form values vs predefined variations
+
+ConfigCat supports two value-modes for feature flags:
+- **Free-form values**: Allows you to enter a feature flag's exact value each time you set it. Best for simple, one-off configurations or quick experiments.
+  <p>
+    <img src="/docs/assets/predefined-variations/free-form-create_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+  </p>
+- **Predefined Variations**: Allows you to define a set of reusable values upfront when creating a feature flag. These variations can then be selected from a dropdown when setting up flag rules. Choose this mode to ensure consistency across rules, prevent typos in complex values (like JSON configurations), and provide self-documenting configurations for your team.
+  <p>
+    <img src="/docs/assets/predefined-variations/predefined-variations-create_192dpi.png" alt="Clone feature flag" width="1366" height="768" decoding="async" loading="lazy" />
+  </p>
+
+:::tip
+Learn more about [predefined variations](/advanced/predefined-variations), including when to use this value-mode, how to convert between the two value-modes, and best practices.
+:::
+
 ## Config
 
 A _Config_ is a collection of _Settings_. _Configs_ help you organize settings around topics, or around your software components. A _Config_ is like an online version of a traditional config file.

website/sidebars.ts

@@ -35,6 +35,7 @@ const docs: SidebarConfig = [
         ],
       },
       'advanced/data-governance',
+      'advanced/predefined-variations',
       {
         label: 'Targeting',
         type: 'category',
@@ -58,6 +59,7 @@ const docs: SidebarConfig = [
           'targeting/feature-flag-evaluation',
         ],
       },
+      'advanced/variation-id-for-analytics',
       'advanced/caching',
       'advanced/troubleshooting',
       'zombie-flags',

website/src/pages/index.js

@@ -29,6 +29,8 @@ const features = [
     links: [
       { url: 'api/reference/configcat-public-management-api', title: 'Public Management API' },
       { url: 'advanced/data-governance', title: 'Data Governance - CDN' },
+      { url: 'advanced/predefined-variations', title: 'Predefined Variations' },
+      { url: 'advanced/variation-id-for-analytics', title: 'Variation ID for analytics' },
       { url: 'advanced/caching', title: 'Polling modes & Caching' },
       {
         url: 'advanced/team-management/team-management-basics',