Skip to content

Commit 53d8922

Browse files
typotterjoepeeples
typotter
and
joepeeples
authored
[DOCS-13875] Add Unity Feature Flags documentation (#35341)
* Add Unity Feature Flags documentation Add comprehensive Unity Feature Flags documentation with two implementations: 1. unity.md - Direct FlagsClient API (current implementation) - Uses DdFlags.CreateClient() and direct FlagsClient methods - Synchronous flag evaluation (GetBooleanValue, GetStringValue, etc.) - Simpler API without async/await 2. unity-openfeature.md - OpenFeature integration (future/alternative) - Uses OpenFeature Api.Instance.GetClient() - Async flag evaluation methods - Standards-based approach Both pages: - Include cross-links to each other for easy navigation - Follow the structure of Android/iOS feature flags docs - Include installation, setup, evaluation, and advanced config sections - Add Unity card to feature flags client navigation The documentation is ready for preview and user feedback. * Simplify Unity Feature Flags docs to placeholders Replace full documentation with minimal placeholder pages to test CI: - Keep navigation links and cross-references - Add 'Documentation coming soon' message - Reduce from ~270 lines to ~28 lines each - Test if minimal changes pass all CI checks Full documentation will be added incrementally after CI validation. * Add Overview, Installation, and Initialize SDK sections to OpenFeature docs Incremental update to unity-openfeature.md: - Add detailed Overview explaining OpenFeature integration - Add complete Installation instructions (EDM4U, Unity package, Android setup) - Add Initialize SDK section with reference to Unity Monitoring Setup - Add reference links at bottom File size: 27 → 68 lines (+41 lines) * Restore full OpenFeature docs for Unity Feature Flags Add back all sections to unity-openfeature.md: - Enable flags - Create and retrieve a client - Set the evaluation context - Evaluate flags (boolean, string, integer, double, object) - Flag evaluation details - Advanced configuration Also fixes duplicate further_reading partial and adds OpenFeature external link to further_reading frontmatter. * Restore full Unity Feature Flags direct API documentation Add back all sections to unity.md: - Overview - Installation - Initialize the SDK - Enable flags - Create and retrieve a client - Set the evaluation context - Evaluate flags (boolean, string, integer, double, object) - Flag evaluation details - Advanced configuration * Remove preview callout from Unity Feature Flags docs Feature flags are no longer in preview. Removed the callout from both unity.md and unity-openfeature.md to match the other SDK pages (android, ios, javascript, react). * Update Unity Feature Flags docs with correct API and Getting Started section - FlagsConfiguration is now immutable (constructor-based, not object initializer) - Add Getting Started quickstart section to unity.md - Fix DdFlags.Instance.CreateClient() throughout unity.md - Update parameter names to match constructor signatures (camelCase) - Add EvaluationFlushIntervalSeconds clamp range [1, 60] to both pages * Fix Unity OpenFeature docs to match openfeature SDK worktree - Revert FlagsConfiguration to object initializer syntax (mutable properties, PascalCase) - Restore DdFlags.SetEvaluationContext() as static method (not on client) - DdFlags.CreateClient() returns void; OpenFeature client retrieved via Api.Instance.GetClient() - Add Getting Started quickstart section - Restore correct advanced config property names (PascalCase) * Rewrite Unity OpenFeature docs to match intended API design - DdFlags is an instance class with immutable FlagsConfiguration (constructor syntax) - DdFlags.Instance.CreateProvider() returns provider for registration with OpenFeature - Provider registered via Api.Instance.SetProviderAsync(provider) - Evaluation context set via OpenFeature standard EvaluationContext.Builder() - No Datadog-specific context types or direct provider method calls - Rename "Create and retrieve a client" section to "Register the provider" * Fix Unity OpenFeature docs to match intended API design - Evaluation context set via client.SetEvaluationContext(FlagsEvaluationContext) not OpenFeature context builder - DdFlags.Instance.CreateClient() returns FlagsClient (held for context setting); OpenFeature client retrieved separately via Api.Instance.GetClient() - Show Unity coroutine pattern (WaitUntil) for async flag evaluation — MonoBehaviour does not support await - Fix named provider registration: Api.Instance.SetProviderAsync("domain", provider) - Add Getting Started as full MonoBehaviour example - Remove unused openfeature.dev footnote * Consolidate Unity Feature Flags into a single page - Merge unity.md and unity-openfeature.md into one page, OpenFeature-first - Add aliases for old unity-openfeature URLs - Direct FlagsClient API moved to collapsed advanced section at the bottom - Drop FlagDetails documentation (FlagDetails<T> and FlagEvaluationError are now internal) - Flag evaluation details section uses OpenFeature FlagEvaluationDetails types only - Delete unity-openfeature.md and unity.md.bak * Remove openfeature URL aliases from Unity docs * Update Unity Feature Flags docs for PR #210 API changes - new DatadogFeatureProvider(client) replaces DdFlags.Instance.CreateProvider() - DatadogFeatureProvider is in separate com.datadoghq.unity.flags.openfeature package - using Datadog.Unity.Flags.OpenFeature namespace required - DdFlags.Instance is always non-null (static readonly singleton) - CreateClient() returns IFlagsClient (public interface) - FlagDetails<T> and FlagEvaluationError are public — restore detail methods in direct API section - Installation section updated for two-package architecture and NuGetForUnity * Fix installation: NuGetForUnity is a transitive UPM dep, not a manual install step * Rewrite Unity Feature Flags docs: direct API only, no OpenFeature - Remove all OpenFeature references and the openfeature package install steps - Follow iOS page structure: Enable → Create client → Set context → Evaluate → Advanced config - DdFlags.Enable() / DdFlags.Instance.CreateClient() / client.SetEvaluationContext() - Synchronous typed getters: GetBooleanValue, GetStringValue, GetIntegerValue, GetDoubleValue, GetObjectValue - FlagDetails<T> detail methods documented - FlagsConfiguration uses constructor syntax (immutable) - Backup of previous state at typo/unity-feature-flags-docs-openfeature-backup * add new Unity page to side nav * Address joepeeples review comments on unity.md - Remove /feature_flags/setup/unity/ alias (URL never existed) - Simplify Git URL installation step wording - ensure -> help ensure (Vale rule) - once the -> after the (Vale rule) --------- Co-authored-by: Joe Peeples <joe.peeples@datadoghq.com>
1 parent 23b01bd commit 53d8922

3 files changed

Lines changed: 247 additions & 0 deletions

File tree

‎config/_default/menus/main.en.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5866,6 +5866,11 @@ menu:
58665866
parent: feature_flags_client
58675867
identifier: feature_flags_client_react_native
58685868
weight: 106
5869+
- name: Unity
5870+
url: feature_flags/client/unity
5871+
parent: feature_flags_client
5872+
identifier: feature_flags_client_unity
5873+
weight: 107
58695874
- name: Server SDKs
58705875
url: feature_flags/server
58715876
parent: feature_flags

‎content/en/feature_flags/client/unity.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
title: Unity Feature Flags
3+
description: Set up Datadog Feature Flags for Unity applications.
4+
further_reading:
5+
- link: "/feature_flags/client/"
6+
tag: "Documentation"
7+
text: "Client-Side Feature Flags"
8+
- link: "/real_user_monitoring/application_monitoring/unity/"
9+
tag: "Documentation"
10+
text: "Unity Monitoring"
11+
- link: "https://github.com/DataDog/dd-sdk-unity"
12+
tag: "Source Code"
13+
text: "dd-sdk-unity source code"
14+
---
15+
16+
## Overview
17+
18+
This page describes how to instrument your Unity application with the Datadog Feature Flags SDK. Datadog feature flags provide a unified way to remotely control feature availability in your app, experiment safely, and deliver new experiences with confidence.
19+
20+
This guide explains how to install and enable the SDK, create and use a `FlagsClient`, and configure advanced options.
21+
22+
## Installation
23+
24+
Declare the Datadog Unity SDK as a dependency in your project. The Datadog Unity SDK includes feature flags support.
25+
26+
1. Install the [External Dependency Manager for Unity (EDM4U)][1]. This can be done using [Open UPM][2].
27+
28+
2. Add the [Datadog SDK Unity package][3] using its Git URL `https://github.com/DataDog/unity-package.git`.
29+
30+
3. (Android only) Configure your project to use [Gradle templates][4], and enable both `Custom Main Template` and `Custom Gradle Properties Template`.
31+
32+
4. (Android only) If you build and receive `Duplicate class` errors (common in Unity 2022.x), add the following code to the `dependencies` block of your `mainTemplate.gradle`:
33+
34+
```groovy
35+
constraints {
36+
implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.0") {
37+
because("kotlin-stdlib-jdk8 is now a part of kotlin-stdlib")
38+
}
39+
}
40+
```
41+
42+
## Initialize the SDK
43+
44+
Initialize Datadog as early as possible in your app lifecycle. Navigate to your `Project Settings` and click on the `Datadog` section to configure your client token, environment, and other settings.
45+
46+
For more information about setting up the Unity SDK, see [Unity Monitoring Setup][5].
47+
48+
## Enable flags
49+
50+
After initializing Datadog, enable `Flags` to attach it to the current Datadog SDK instance and prepare for client creation and flag evaluation:
51+
52+
{{< code-block lang="csharp" >}}
53+
using Datadog.Unity.Flags;
54+
55+
DdFlags.Enable();
56+
{{< /code-block >}}
57+
58+
You can also pass a configuration object; see [Advanced configuration](#advanced-configuration).
59+
60+
## Create and retrieve a client
61+
62+
Create a client once, typically during app startup:
63+
64+
{{< code-block lang="csharp" >}}
65+
var client = DdFlags.Instance.CreateClient();
66+
{{< /code-block >}}
67+
68+
You can also create multiple clients by providing the `name` parameter:
69+
70+
{{< code-block lang="csharp" >}}
71+
var checkoutClient = DdFlags.Instance.CreateClient("checkout");
72+
{{< /code-block >}}
73+
74+
<div class="alert alert-info">If a client with the given name already exists, the existing instance is reused.</div>
75+
76+
## Set the evaluation context
77+
78+
Define who or what the flag evaluation applies to using a `FlagsEvaluationContext`. The evaluation context includes user or session information used to determine which flag variations should be returned. Call this method before evaluating flags to help ensure proper targeting.
79+
80+
{{< code-block lang="csharp" >}}
81+
client.SetEvaluationContext(
82+
new FlagsEvaluationContext(
83+
targetingKey: "user-123",
84+
attributes: new Dictionary<string, object>
85+
{
86+
{ "email", "user@example.com" },
87+
{ "tier", "premium" },
88+
}
89+
),
90+
onComplete: success =>
91+
{
92+
if (success)
93+
{
94+
// Flags are ready — begin evaluating
95+
}
96+
else
97+
{
98+
// Fetch failed — evaluations return default values
99+
}
100+
}
101+
);
102+
{{< /code-block >}}
103+
104+
This method fetches flag assignments from the server asynchronously in the background. The operation is non-blocking and thread-safe. Flag updates are available for subsequent evaluations after the background operation completes.
105+
106+
## Evaluate flags
107+
108+
After creating the `FlagsClient` and setting its evaluation context, you can start reading flag values throughout your app. Flag evaluation is _local and instantaneous_—the SDK uses locally cached data, so no network requests occur when evaluating flags. This makes evaluations safe to perform on the main thread.
109+
110+
Each flag is identified by a _key_ (a unique string) and can be evaluated with a _typed getter_ that returns a value of the expected type. If the flag doesn't exist or cannot be evaluated, the SDK returns the provided default value.
111+
112+
### Boolean flags
113+
114+
Use `GetBooleanValue(key, defaultValue)` for flags that represent on/off or true/false conditions. For example:
115+
116+
{{< code-block lang="csharp" >}}
117+
var isNewCheckoutEnabled = client.GetBooleanValue("checkout.new", false);
118+
119+
if (isNewCheckoutEnabled)
120+
{
121+
ShowNewCheckoutFlow();
122+
}
123+
else
124+
{
125+
ShowLegacyCheckout();
126+
}
127+
{{< /code-block >}}
128+
129+
### String flags
130+
131+
Use `GetStringValue(key, defaultValue)` for flags that select between multiple variants or configuration strings. For example:
132+
133+
{{< code-block lang="csharp" >}}
134+
var theme = client.GetStringValue("ui.theme", "light");
135+
136+
switch (theme)
137+
{
138+
case "light": SetLightTheme(); break;
139+
case "dark": SetDarkTheme(); break;
140+
default: SetLightTheme(); break;
141+
}
142+
{{< /code-block >}}
143+
144+
### Integer and double flags
145+
146+
For numeric flags, use `GetIntegerValue(key, defaultValue)` or `GetDoubleValue(key, defaultValue)`. These are appropriate when a feature depends on a numeric parameter such as a limit, percentage, or multiplier:
147+
148+
{{< code-block lang="csharp" >}}
149+
var maxItems = client.GetIntegerValue("cart.items.max", 20);
150+
151+
var priceMultiplier = client.GetDoubleValue("pricing.multiplier", 1.0);
152+
{{< /code-block >}}
153+
154+
### Object flags
155+
156+
For structured or JSON-like data, use `GetObjectValue(key, defaultValue)`. This method returns an `object`, which can be cast to the appropriate type. Object flags are useful for remote configuration scenarios where multiple properties need to be provided together. For example:
157+
158+
{{< code-block lang="csharp" >}}
159+
var config = client.GetObjectValue(
160+
"ui.config",
161+
new Dictionary<string, object>
162+
{
163+
{ "color", "#00A3FF" },
164+
{ "fontSize", 14 },
165+
}
166+
);
167+
168+
if (config is Dictionary<string, object> configDict)
169+
{
170+
var color = configDict["color"] as string;
171+
var fontSize = (int)configDict["fontSize"];
172+
}
173+
{{< /code-block >}}
174+
175+
### Flag evaluation details
176+
177+
When you need more than just the flag value, use the `Get<Type>Details` methods. These methods return both the evaluated value and metadata explaining the evaluation:
178+
179+
* `GetBooleanDetails(key, defaultValue)` -> `FlagDetails<bool>`
180+
* `GetStringDetails(key, defaultValue)` -> `FlagDetails<string>`
181+
* `GetIntegerDetails(key, defaultValue)` -> `FlagDetails<int>`
182+
* `GetDoubleDetails(key, defaultValue)` -> `FlagDetails<double>`
183+
184+
For example:
185+
186+
{{< code-block lang="csharp" >}}
187+
var details = client.GetStringDetails("paywall.layout", "control");
188+
189+
Debug.Log($"Value: {details.Value}"); // Evaluated value (for example: "A", "B", or "control")
190+
Debug.Log($"Variant: {details.Variant}"); // Variant name, if applicable
191+
Debug.Log($"Reason: {details.Reason}"); // Why this value was chosen (for example: "TARGETING_MATCH" or "DEFAULT")
192+
Debug.Log($"Error: {details.Error?.ToString()}"); // The error that occurred during evaluation, if any
193+
{{< /code-block >}}
194+
195+
Flag details may help you debug evaluation behavior and understand why a user received a given value.
196+
197+
## Advanced configuration
198+
199+
The `DdFlags.Enable()` API accepts optional configuration with options listed below.
200+
201+
{{< code-block lang="csharp" >}}
202+
DdFlags.Enable(new FlagsConfiguration(
203+
trackExposures: true,
204+
trackEvaluations: true,
205+
evaluationFlushIntervalSeconds: 10.0f
206+
));
207+
{{< /code-block >}}
208+
209+
`trackExposures`
210+
: When `true` (default), the SDK automatically records an _exposure event_ when a flag is evaluated. These events contain metadata about which flag was accessed, which variant was served, and under what context. They are sent to Datadog so you can later analyze feature adoption. Set to `false` to disable exposure tracking.
211+
212+
`trackEvaluations`
213+
: When `true` (default), the SDK tracks flag evaluations and sends aggregated evaluation telemetry to Datadog. This enables analytics about flag usage patterns and performance. Set to `false` to disable evaluation tracking.
214+
215+
`evaluationFlushIntervalSeconds`
216+
: The interval in seconds at which batched evaluation events are sent to Datadog. Accepted values are between `1` and `60`. Default is `10.0` seconds.
217+
218+
`customFlagsEndpoint`
219+
: Configures a custom server URL for retrieving flag assignments.
220+
221+
`customExposureEndpoint`
222+
: Configures a custom server URL for sending flags exposure data.
223+
224+
`customEvaluationEndpoint`
225+
: Configures a custom server URL for sending flags evaluation telemetry.
226+
227+
## Further reading
228+
229+
{{< partial name="whats-next/whats-next.html" >}}
230+
231+
[1]: https://github.com/googlesamples/unity-jar-resolver
232+
[2]: https://openupm.com/packages/com.google.external-dependency-manager/
233+
[3]: https://github.com/DataDog/unity-package
234+
[4]: https://docs.unity3d.com/Manual/gradle-templates.html
235+
[5]: /real_user_monitoring/application_monitoring/unity/setup

‎layouts/partials/feature_flags/feature_flags_client.html‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,13 @@
6565
</div>
6666
</a>
6767
</div>
68+
<div class="col">
69+
<a class="card h-100" href="/feature_flags/client/unity/">
70+
<div class="card-body text-center py-2 px-1">
71+
{{ partial "img.html" (dict "root" . "src" "integrations_logos/rum-unity_large.svg" "class" "img-fluid" "alt" "Unity" "width" "400") }}
72+
</div>
73+
</a>
74+
</div>
6875
</div>
6976
</div>
7077
</div>

0 commit comments

Comments
 (0)