[codex] Fix Feature Flags documentation guidance

content/en/feature_flags/_index.md

@@ -27,7 +27,31 @@ further_reading:
 
 ## Overview
 
-Feature flags enable you to toggle features on and off, conduct A/B/n testing, gradually roll out new functionality, and personalize user experiences—all without the need for extensive code deployments. With feature flags, you can empower your team to make dynamic changes, iterate rapidly, and deliver enhanced user experiences.
+Datadog Feature Flags is Datadog's flag management product. You create flags in Datadog, deliver flag configuration to Datadog Feature Flags SDKs, and evaluate variants in your application through Datadog or OpenFeature APIs.
+
+Datadog Feature Flags is built on the [OpenFeature standard](https://openfeature.dev/docs/reference/intro/), an open-source, vendor-neutral specification for feature flag APIs. See OpenFeature's getting-started guide if you're new to OpenFeature concepts like providers, evaluation context, and hooks.
+
+Feature flags enable you to toggle features on and off, conduct A/B/n testing, gradually roll out new functionality, and personalize user experiences without the need for extensive code deployments. With feature flags, you can empower your team to make dynamic changes, iterate rapidly, and deliver enhanced user experiences.
+
+If your flags are managed by LaunchDarkly, Split, ConfigCat, or another provider and you only want Datadog to record evaluated variants in RUM, see [RUM Feature Flag Tracking](/real_user_monitoring/feature_flag_tracking/) instead.
+
+Use a client-side SDK when the flag must be evaluated in a browser, mobile app, or game client. Use a server-side SDK when the decision should happen in a backend service and the flag configuration can be delivered through the Datadog Agent and Remote Configuration.
+
+### Credentials at a glance
+
+| Credential | Used by | Where it goes | Sensitive? |
+| --- | --- | --- | --- |
+| Client token | Browser, mobile, and game SDKs | Client application configuration | Public-shipping token |
+| Application ID | Browser and RUM-backed client SDKs | Client application configuration | Public-shipping identifier |
+| API key | Datadog Agent for server-side Remote Configuration | Agent configuration only | Secret |
+
+Do not put API keys in browser, mobile, or game applications.
+
+### Evaluation context and telemetry
+
+Evaluation context attributes are the flat string, number, and Boolean values that Datadog uses for targeting rules and rollout bucketing. Set a stable `targetingKey`, such as a user ID, session ID, or device ID, so percentage rollouts are consistent.
+
+Feature Flags telemetry includes exposure events, flag evaluation metrics, and optional RUM correlation depending on the SDK and configuration.
 
 ## Further reading
 

content/en/feature_flags/client/_index.md

@@ -19,8 +19,22 @@ further_reading:
 
 Set up Datadog Feature Flags for your applications. Follow the platform-specific guides below to integrate feature flags into your application and start collecting feature flag data:
 
+Datadog Feature Flags is built on the [OpenFeature standard](https://openfeature.dev/docs/reference/intro/), an open-source, vendor-neutral specification for feature flag APIs. See OpenFeature's getting-started guide if you're new to OpenFeature concepts like providers, evaluation context, and hooks.
+
 {{< partial name="feature_flags/feature_flags_client.html" >}}
 
+## Telemetry options by platform
+
+The web, mobile, and Unity providers expose similar telemetry controls with platform-specific option names. When a telemetry option is exposed, its default value is `true`.
+
+| Concept | Web (`@datadog/openfeature-browser`) | Android (`dd-sdk-android-flags`) | iOS (`DatadogFlags`) | React Native | Unity |
+|---|---|---|---|---|---|
+| Send exposure events | `enableExposureLogging` | `trackExposures` | `trackExposures` | `trackExposures` | `trackExposures` |
+| Send aggregated evaluation telemetry | `enableFlagEvaluationTracking` | `trackEvaluations` | `trackEvaluations` | Not exposed | `trackEvaluations` |
+| Attach evaluations to RUM | `enableRumFeatureFlagTracking` | `rumIntegrationEnabled` | `rumIntegrationEnabled` | `rumIntegrationEnabled` | Not exposed |
+
+<div class="alert alert-info">The iOS OpenFeature bridge (<a href="https://github.com/DataDog/dd-openfeature-provider-swift">dd-openfeature-provider-swift</a>) is currently in development. For production iOS workloads, use the <code>FlagsClient</code> API directly.</div>
+
 ## Testing with in-memory providers
 
 Datadog supports these testing approaches:

content/en/feature_flags/client/android.md

@@ -30,7 +30,7 @@ Here's a minimal example to get feature flags working in your Android app:
 ```kotlin
 // 1. Add dependencies (see Installation section)
 
-// 2. Initialize Datadog SDK (in Application.onCreate)
+// 2. Initialize the Datadog Android SDK (in Application.onCreate)
 val configuration = Configuration.Builder(
     clientToken = "<CLIENT_TOKEN>",
     env = "<ENV_NAME>",
@@ -94,7 +94,7 @@ Datadog.initialize(this, configuration, TrackingConsent.GRANTED)
 
 ## Enable flags
 
-After initializing Datadog, enable `Flags` to attach it to the current Datadog SDK instance and prepare for provider creation and flag evaluation:
+After initializing Datadog, enable `Flags` to attach it to the current Datadog Android SDK instance and prepare for provider creation and flag evaluation:
 
 {{< code-block lang="kotlin" >}}
 import com.datadog.android.flags.Flags
@@ -128,6 +128,8 @@ OpenFeatureAPI.setProviderAndWait(provider)
 
 Define who or what the flag evaluation applies to using an `ImmutableContext`. The evaluation context includes user or session information used to determine which flag variations should be returned. Set this before evaluating flags to help ensure proper targeting.
 
+<div class="alert alert-warning">Datadog Feature Flags requires evaluation context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div>
+
 {{< code-block lang="kotlin" >}}
 import dev.openfeature.kotlin.sdk.ImmutableContext
 import dev.openfeature.kotlin.sdk.Value
@@ -143,7 +145,7 @@ OpenFeatureAPI.setEvaluationContext(
 )
 {{< /code-block >}}
 
-<div class="alert alert-info">All attribute values must use a <code>Value.String()</code> wrapper. The targeting key should be consistent for the same user to help ensure consistent flag evaluation across sessions. For anonymous users, use a persistent UUID stored, for example, in <code>SharedPreferences</code>.</div>
+<div class="alert alert-info">OpenFeature attributes must use flat <code>Value</code> primitives such as <code>Value.String()</code>, <code>Value.Integer()</code>, <code>Value.Double()</code>, or <code>Value.Boolean()</code>. The targeting key should be consistent for the same user to help ensure consistent flag evaluation across sessions. For anonymous users, use a persistent UUID stored, for example, in <code>SharedPreferences</code>.</div>
 
 ## Evaluate flags
 
@@ -288,6 +290,7 @@ You can configure individual providers with custom endpoints before creating the
 val provider = FlagsClient.Builder()
     .useCustomFlagEndpoint("https://your-proxy.example.com/flags")
     .useCustomExposureEndpoint("https://your-proxy.example.com/exposure")
+    .useCustomEvaluationEndpoint("https://your-proxy.example.com/evaluations")
     .build()
     .asOpenFeatureProvider()
 

content/en/feature_flags/client/angular.md

@@ -50,12 +50,15 @@ pnpm add @datadog/openfeature-browser @openfeature/angular-sdk @openfeature/web-
 
 ## Initialize the provider
 
-Create a `DatadogProvider` instance with your Datadog credentials. To create a client token, see [Client tokens][2].
+Create a `DatadogProvider` instance with your Datadog credentials. `applicationId`, `clientToken`, `site`, and `env` are required. To create a client token, see [Client tokens][2].
+
+Note: Browser Feature Flags are currently not supported on GovCloud sites.
 
 ```typescript
 import { DatadogProvider } from '@datadog/openfeature-browser';
 
 const provider = new DatadogProvider({
+  // Required client-side Datadog credentials
   applicationId: '<APPLICATION_ID>',
   clientToken: '<CLIENT_TOKEN>',
   site: '{{< region-param key="dd_site" code="true" >}}',
@@ -71,6 +74,8 @@ Import the `OpenFeatureModule` in your Angular module and configure it using the
 
 Define who or what the flag evaluation applies to using an evaluation context. The evaluation context includes user or session information used to determine which flag variations should be returned. Reference these attributes in your targeting rules to control who sees each variant.
 
+<div class="alert alert-warning">Datadog Feature Flags requires evaluation context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div>
+
 <div class="alert alert-info">The <code>targetingKey</code> is used as the randomization subject for percentage-based targeting. When a flag targets a percentage of subjects (for example, 50%), the <code>targetingKey</code> determines which "bucket" a user falls into. Users with the same <code>targetingKey</code> always receive the same variant for a given flag.</div>
 
 ### Using a static object
@@ -489,10 +494,67 @@ export class MyComponent {
 }
 {{< /code-block >}}
 
+## Configure browser provider options
+
+The Angular provider uses the Datadog browser provider, which also supports these optional settings:
+
+| Option | Default | Use |
+| --- | --- | --- |
+| `enableExposureLogging` | `true` | Send exposure events to the exposures intake. |
+| `enableFlagEvaluationTracking` | `true` | Send aggregated evaluation telemetry. |
+| `enableRumFeatureFlagTracking` | `true` | Add flag evaluations to RUM events. This is the setting that can affect RUM usage. |
+| `flagEvaluationTrackingInterval` | `10000` ms | Flush interval for evaluation telemetry. |
+| `initialFlagsConfiguration` | `{}` | Bootstrap with precomputed flags. |
+| `flaggingProxy` | unset | Fetch flags through a proxy instead of `site`. |
+| `customHeaders` | unset | Add headers to flag-fetch requests. |
+| `overwriteRequestHeaders` | `false` | Replace default request headers with `customHeaders`. |
+
+## Testing
+
+You can test against a dedicated Datadog test environment with the real `DatadogProvider`, or swap it for OpenFeature's `TypedInMemoryProvider` to control flag values directly in test code. This section shows the in-memory approach, which keeps tests hermetic and offline. `TypedInMemoryProvider` is exported from `@openfeature/web-sdk`, which is already installed for Angular Feature Flags.
+
+{{< code-block lang="typescript" >}}
+import { TestBed } from '@angular/core/testing';
+import { firstValueFrom } from 'rxjs';
+import { FeatureFlagService, OpenFeatureModule } from '@openfeature/angular-sdk';
+import { TypedInMemoryProvider } from '@openfeature/web-sdk';
+
+const flags = {
+  new_checkout_button: {
+    variants: { on: true, off: false },
+    defaultVariant: 'on',
+    disabled: false,
+  },
+};
+
+beforeEach(async () => {
+  await TestBed.configureTestingModule({
+    imports: [
+      OpenFeatureModule.forRoot({
+        provider: new TypedInMemoryProvider(flags),
+        context: { targetingKey: 'test-user' },
+      }),
+    ],
+  }).compileComponents();
+});
+
+afterEach(() => {
+  TestBed.resetTestingModule();
+});
+
+it('uses in-memory flag values', async () => {
+  const flagService = TestBed.inject(FeatureFlagService);
+  const details = await firstValueFrom(flagService.getBooleanDetails('new_checkout_button', false));
+
+  expect(details.value).toBe(true);
+});
+{{< /code-block >}}
+
+The Web SDK flag shape requires `variants`, `defaultVariant`, and `disabled`. Register the in-memory provider before injecting services or rendering components that read flags.
+
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://openfeature.dev/docs/reference/sdks/client/web/angular/
 [2]: /account_management/api-app-keys/#client-tokens
-

content/en/feature_flags/client/ios.md

@@ -94,7 +94,7 @@ Datadog.initialize(
 
 ## Enable flags
 
-After initializing Datadog, enable `Flags` to attach it to the current Datadog SDK instance and prepare for client creation and flags evaluation:
+After initializing Datadog, enable `Flags` to attach it to the current Datadog iOS SDK instance and prepare for client creation and flags evaluation:
 
 {{< code-block lang="swift" >}}
 import DatadogFlags
@@ -131,6 +131,8 @@ let flagsClient = FlagsClient.shared(named: "checkout")
 
 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 ensure proper targeting.
 
+<div class="alert alert-warning">Datadog Feature Flags requires evaluation context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div>
+
 {{< code-block lang="swift" >}}
 flagsClient.setEvaluationContext(
     FlagsEvaluationContext(
@@ -240,7 +242,7 @@ When you need more than just the flag value, use the `get<Type>Details` APIs. Th
 For example:
 
 {{< code-block lang="swift" >}}
-let details = flags.getStringDetails(
+let details = flagsClient.getStringDetails(
     key: "paywall.layout",
     defaultValue: "control"
 )
@@ -387,12 +389,15 @@ Flags.enable(with: config)
 `customExposureEndpoint`
 : Configures a custom server URL for sending flags exposure data.
 
+`customEvaluationEndpoint`
+: Configures a custom server URL for sending flag evaluation telemetry.
+
 `customFlagsHeaders`
 : Sets additional HTTP headers to attach to requests made to `customFlagsEndpoint`. It can be useful for authentication or routing when using your own flags service.
 
 ## Testing
 
-The examples above use Datadog's `FlagsClient` API directly. If you prefer to drive feature flags through the [OpenFeature](https://openfeature.dev/) standard API, Datadog ships an OpenFeature bridge for iOS at [dd-openfeature-provider-swift](https://github.com/DataDog/dd-openfeature-provider-swift). Use the bridge's `DatadogProvider` in production, and for code-controlled flag values in tests, substitute an in-memory provider.
+The examples above use Datadog's `FlagsClient` API directly. Use `FlagsClient` for production workloads. If you are prototyping against the [OpenFeature](https://openfeature.dev/) bridge or writing tests around the OpenFeature API, substitute an in-memory provider for code-controlled flag values.
 
 You can test against a dedicated Datadog test environment with the real `DatadogProvider`, or swap it for an in-memory `FeatureProvider` to control flag values directly in test code. This section shows the in-memory approach, which keeps tests hermetic and offline. The OpenFeature Swift SDK does not ship an `InMemoryProvider`, so tests use a small custom `FeatureProvider` instead.
 

content/en/feature_flags/client/javascript.md

@@ -45,13 +45,16 @@ pnpm add @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core
 
 ## Initialize the provider
 
-Create a `DatadogProvider` instance with your Datadog credentials. To create a client token, see [Client tokens][2].
+Create a `DatadogProvider` instance with your Datadog credentials. `applicationId`, `clientToken`, `site`, and `env` are required. To create a client token, see [Client tokens][2].
+
+Note: Browser Feature Flags are currently not supported on GovCloud sites.
 
 ```javascript
 import { DatadogProvider } from '@datadog/openfeature-browser';
 import { OpenFeature } from '@openfeature/web-sdk';
 
 const provider = new DatadogProvider({
+  // Required client-side Datadog credentials
   applicationId: '<APPLICATION_ID>',
   clientToken: '<CLIENT_TOKEN>',
   site: '{{< region-param key="dd_site" code="true" >}}',
@@ -63,6 +66,8 @@ const provider = new DatadogProvider({
 
 Define who or what the flag evaluation applies to using an evaluation context. The evaluation context includes user or session information used to determine which flag variations should be returned. Reference these attributes in your targeting rules to control who sees each variant.
 
+<div class="alert alert-warning">Datadog Feature Flags requires evaluation context attributes to be flat primitive values: strings, numbers, and Booleans. Do not pass nested objects or arrays; they are not supported and can cause exposure data to be dropped.</div>
+
 {{< code-block lang="javascript" >}}
 const evaluationContext = {
   targetingKey: 'user-123',
@@ -199,6 +204,21 @@ await OpenFeature.setContext({
 });
 {{< /code-block >}}
 
+## Configure browser provider options
+
+The web provider also supports these optional settings:
+
+| Option | Default | Use |
+| --- | --- | --- |
+| `enableExposureLogging` | `true` | Send exposure events to the exposures intake. |
+| `enableFlagEvaluationTracking` | `true` | Send aggregated evaluation telemetry. |
+| `enableRumFeatureFlagTracking` | `true` | Add flag evaluations to RUM events. This is the setting that can affect RUM usage. |
+| `flagEvaluationTrackingInterval` | `10000` ms | Flush interval for evaluation telemetry. |
+| `initialFlagsConfiguration` | `{}` | Bootstrap with precomputed flags. |
+| `flaggingProxy` | unset | Fetch flags through a proxy instead of `site`. |
+| `customHeaders` | unset | Add headers to flag-fetch requests. |
+| `overwriteRequestHeaders` | `false` | Replace default request headers with `customHeaders`. |
+
 ## Testing
 
 You can test against a dedicated Datadog test environment with the real `DatadogProvider`, or swap it for OpenFeature's `InMemoryProvider` to control flag values directly in test code. This section shows the in-memory approach, which keeps tests hermetic and offline. `InMemoryProvider` is exported directly from `@openfeature/web-sdk`, so no additional dependency is required.
@@ -249,4 +269,3 @@ The Web SDK flag shape requires `variants`, `defaultVariant`, and `disabled`. Om
 
 [1]: https://openfeature.dev/
 [2]: /account_management/api-app-keys/#client-tokens
-