Merge pull request #354 from DataDog/leo.romanovsky/rum-user-evaluation-context

feat(browser): include RUM user in evaluation context

Author: leoromanovsky

packages/browser/README.md

@@ -90,6 +90,29 @@ console.log(result.value) // Flag value
 console.log(result.reason) // Evaluation reason
 ```
 
+### RUM User Context
+
+When RUM integration is enabled (the default), the provider includes flat primitive properties returned by
+`DD_RUM.getUser()` in the OpenFeature evaluation context. The RUM user ID is used as the targeting key, while fields
+set explicitly through `OpenFeature.setContext()` take precedence.
+
+Initialize the RUM user before registering the provider:
+
+```javascript
+DD_RUM.setUser({
+  id: 'user-123',
+  email: 'user@example.com',
+  company_name: 'Example, Inc.',
+})
+
+await OpenFeature.setProviderAndWait(new DatadogProvider(configuration))
+```
+
+If the RUM user changes after provider initialization, call
+`await OpenFeature.setContext(OpenFeature.getContext())` to reconcile the provider with the latest user while
+preserving explicitly configured OpenFeature properties. Nested RUM user properties are not included in the
+evaluation context.
+
 ## End-user license agreement
 
 https://www.datadoghq.com/legal/eula

packages/browser/src/domain/configuration.ts

@@ -47,7 +47,8 @@ export interface FlaggingInitConfiguration extends InitConfiguration {
   enableFlagEvaluationTracking?: boolean
 
   /**
-   * Whether to include feature flag assignment details in RUM events (default: true)
+   * Whether to enable RUM integration (default: true). This includes feature flag assignment details in RUM events
+   * and flat primitive RUM user properties in the OpenFeature evaluation context.
    * See: https://docs.datadoghq.com/real_user_monitoring/feature_flag_tracking/
    */
   enableRumFeatureFlagTracking?: boolean

packages/browser/src/openfeature/exposures.ts

@@ -2,14 +2,18 @@ import type { Context, RawError } from '@datadog/browser-core'
 import { addTelemetryDebug, createPageMayExitObservable } from '@datadog/browser-core'
 import { type AssignmentCache, createExposureEvent, type ExposureEventWithTimestamp } from '@datadog/flagging-core'
 import { timeStampNow } from '@datadog/js-core/time'
-import type { EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
+import type { EvaluationContext, EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
 import type { FlaggingConfiguration } from '../domain/configuration'
 import { startExposuresBatch } from '../transport/startExposuresBatch'
 
 /**
  * Create hook for exposure logging.
  */
-export function createExposureLoggingHook(configuration: FlaggingConfiguration, exposureCache: AssignmentCache): Hook {
+export function createExposureLoggingHook(
+  configuration: FlaggingConfiguration,
+  exposureCache: AssignmentCache,
+  getEvaluationContext: (context: EvaluationContext) => EvaluationContext = (context) => context
+): Hook {
   const pageMayExitObservable = createPageMayExitObservable(configuration)
   const exposuresBatch = startExposuresBatch(
     configuration,
@@ -22,7 +26,8 @@ export function createExposureLoggingHook(configuration: FlaggingConfiguration,
   return {
     after: (hookContext: HookContext, details: EvaluationDetails<FlagValue>) => {
       const timestamp = timeStampNow()
-      const exposureEvent = createExposureEvent(hookContext.context, details)
+      const evaluationContext = getEvaluationContext(hookContext.context)
+      const exposureEvent = createExposureEvent(evaluationContext, details)
       if (!exposureEvent) {
         return
       }

packages/browser/src/openfeature/flagEvaluations.ts

@@ -9,10 +9,13 @@ import {
   Observable,
 } from '@datadog/browser-core'
 import { FlagEvaluationAggregator, type FlagEvaluationEvent } from '@datadog/flagging-core'
-import type { EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
+import type { EvaluationContext, EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
 import type { FlaggingConfiguration } from '../domain/configuration'
 
-export function createFlagEvalEVPHook(configuration: FlaggingConfiguration): Hook {
+export function createFlagEvalEVPHook(
+  configuration: FlaggingConfiguration,
+  getEvaluationContext: (context: EvaluationContext) => EvaluationContext = (context) => context
+): Hook {
   const pageMayExitObservable = createPageMayExitObservable(configuration)
   const flagEvaluationBatch = createBatch({
     encoder: createIdentityEncoder(),
@@ -63,7 +66,7 @@ export function createFlagEvalEVPHook(configuration: FlaggingConfiguration): Hoo
   return {
     after: (hookContext: HookContext, details: EvaluationDetails<FlagValue>) => {
       try {
-        aggregator.addEvaluation(hookContext.context, details)
+        aggregator.addEvaluation(getEvaluationContext(hookContext.context), details)
       } catch (error) {
         addTelemetryDebug('Error adding evaluation to aggregator', {
           'error.message': error instanceof Error ? error.message : String(error),

packages/browser/src/openfeature/provider.ts

@@ -26,7 +26,7 @@ import {
 import { evaluate } from '../evaluation'
 import { createExposureLoggingHook } from './exposures'
 import { createFlagEvalEVPHook } from './flagEvaluations'
-import { createRumTrackingHook } from './rumIntegration'
+import { createRumTrackingHook, enrichEvaluationContextWithRumUser } from './rumIntegration'
 
 /**
  * @deprecated Use FlaggingInitConfiguration instead
@@ -64,6 +64,18 @@ export class DatadogProvider implements Provider {
   /** Provider-level configuration */
   private readonly configuration?: FlaggingConfiguration
 
+  /** Controls both directions of the provider's RUM integration. */
+  private readonly isRumIntegrationEnabled: boolean
+
+  // TODO: Migrate this manual context plumbing to a provider `before` hook once
+  // @openfeature/web-sdk supports returned EvaluationContext values for web hooks.
+  // Watch upstream packages/web/src/hooks/hook.ts for the before return changing from `void`,
+  // and packages/web/src/client/internal/open-feature-client.ts for `beforeHooks` merging that
+  // result before calling the resolver and subsequent hooks. Return this stored context, not a
+  // fresh RUM lookup, so targeting, flag configuration, and telemetry stay on the same identity.
+  /** Effective context associated with the active flags configuration. */
+  private evaluationContext: EvaluationContext = {}
+
   status: ProviderStatus
 
   private flagsConfiguration: FlagsConfiguration = {}
@@ -98,15 +110,15 @@ export class DatadogProvider implements Provider {
     this.hooks = []
     this.events = new OpenFeatureEventEmitter()
 
-    const isRumFeatureFlagTrackingEnabled = options.enableRumFeatureFlagTracking ?? true
-    if (isRumFeatureFlagTrackingEnabled) {
+    this.isRumIntegrationEnabled = options.enableRumFeatureFlagTracking ?? true
+    if (this.isRumIntegrationEnabled) {
       this.hooks.push(createRumTrackingHook())
     }
 
     // Add EVP flag evaluation hook.
     const isEvaluationTrackingEnabled = options.enableFlagEvaluationTracking ?? true
     if (isEvaluationTrackingEnabled && this.configuration) {
-      this.hooks.push(createFlagEvalEVPHook(this.configuration))
+      this.hooks.push(createFlagEvalEVPHook(this.configuration, () => this.evaluationContext))
     }
 
     // Add proper exposure logging hook (creates batch internally)
@@ -116,7 +128,7 @@ export class DatadogProvider implements Provider {
         chromeStorage: chromeStorageIfAvailable(),
         storageKeySuffix: 'dd-of-browser',
       })
-      this.hooks.push(createExposureLoggingHook(this.configuration, this.exposureCache))
+      this.hooks.push(createExposureLoggingHook(this.configuration, this.exposureCache, () => this.evaluationContext))
     }
 
     if (hasIndexedDB()) {
@@ -137,6 +149,8 @@ export class DatadogProvider implements Provider {
   }
 
   private setContext(context: EvaluationContext): Promise<void> {
+    const evaluationContext = this.isRumIntegrationEnabled ? enrichEvaluationContextWithRumUser(context) : context
+
     if (this.status === ProviderStatus.NOT_READY) {
       // we're initializing, no status changes necessary
     } else {
@@ -155,7 +169,7 @@ export class DatadogProvider implements Provider {
     // Important: OF SDK awaits for all onContextChange calls to exit
     // before marking the provider as ready. Make sure to respect
     // `signal`, so we don't block OF SDK unnecessarily.
-    this.latestContextUpdate = this.retrieveFlagsConfiguration(context, { signal })
+    this.latestContextUpdate = this.retrieveFlagsConfiguration(evaluationContext, { signal })
       .then((result) =>
         // New configuration might require clearing exposure
         // cache. One example of this is updating experiment
@@ -184,6 +198,7 @@ export class DatadogProvider implements Provider {
           // scheduling).
 
           this.flagsConfiguration = config
+          this.evaluationContext = evaluationContext
           this.status = fromCache ? ProviderStatus.STALE : ProviderStatus.READY
           this.events.emit(ProviderEvents.ConfigurationChanged)
 
@@ -268,34 +283,34 @@ export class DatadogProvider implements Provider {
   resolveBooleanEvaluation(
     flagKey: string,
     defaultValue: boolean,
-    context: EvaluationContext,
+    _context: EvaluationContext,
     _logger: Logger
   ): ResolutionDetails<boolean> {
-    return evaluate(this.flagsConfiguration, 'boolean', flagKey, defaultValue, context)
+    return evaluate(this.flagsConfiguration, 'boolean', flagKey, defaultValue, this.evaluationContext)
   }
 
   resolveStringEvaluation(
     flagKey: string,
     defaultValue: string,
-    context: EvaluationContext,
+    _context: EvaluationContext,
     _logger: Logger
   ): ResolutionDetails<string> {
-    return evaluate(this.flagsConfiguration, 'string', flagKey, defaultValue, context)
+    return evaluate(this.flagsConfiguration, 'string', flagKey, defaultValue, this.evaluationContext)
   }
 
   resolveNumberEvaluation(
     flagKey: string,
     defaultValue: number,
-    context: EvaluationContext,
+    _context: EvaluationContext,
     _logger: Logger
   ): ResolutionDetails<number> {
-    return evaluate(this.flagsConfiguration, 'number', flagKey, defaultValue, context)
+    return evaluate(this.flagsConfiguration, 'number', flagKey, defaultValue, this.evaluationContext)
   }
 
   resolveObjectEvaluation<T extends JsonValue>(
     flagKey: string,
     defaultValue: T,
-    context: EvaluationContext,
+    _context: EvaluationContext,
     _logger: Logger
   ): ResolutionDetails<T> {
     // type safety: OpenFeature interface requires us to return a
@@ -304,6 +319,12 @@ export class DatadogProvider implements Provider {
     // type-sound way because there's no runtime information passed to
     // learn what type the user expects. So it's up to the user to
     // make sure they pass the appropriate type.
-    return evaluate(this.flagsConfiguration, 'object', flagKey, defaultValue, context) as ResolutionDetails<T>
+    return evaluate(
+      this.flagsConfiguration,
+      'object',
+      flagKey,
+      defaultValue,
+      this.evaluationContext
+    ) as ResolutionDetails<T>
   }
 }

packages/browser/src/openfeature/rumIntegration.ts

@@ -1,9 +1,41 @@
-import { getGlobalObject } from '@datadog/browser-core'
-import type { EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
+import { type Context, getGlobalObject } from '@datadog/browser-core'
+import type { EvaluationContext, EvaluationDetails, FlagValue, Hook, HookContext } from '@openfeature/web-sdk'
 
 export interface DDRum {
   // biome-ignore lint/suspicious/noExplicitAny: DD RUM interface
   addFeatureFlagEvaluation: (flagKey: string, value: any) => void
+  getUser?: () => Context
+}
+
+export function enrichEvaluationContextWithRumUser(context: EvaluationContext): EvaluationContext {
+  try {
+    const globalObject = getGlobalObject<{ DD_RUM?: DDRum }>()
+    const user = globalObject.DD_RUM?.getUser?.()
+    if (!user) {
+      return context
+    }
+
+    const { id, ...attributes } = user
+    const rumUserContext: EvaluationContext = {}
+
+    if (typeof id === 'string') {
+      rumUserContext.targetingKey = id
+    }
+
+    for (const [key, value] of Object.entries(attributes)) {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        rumUserContext[key] = value
+      }
+    }
+
+    return {
+      ...rumUserContext,
+      // RUM provides defaults; context explicitly supplied through OpenFeature remains authoritative.
+      ...context,
+    }
+  } catch {
+    return context
+  }
 }
 
 export function createRumTrackingHook(): Hook {