[EX-3407] Send the serial ID on web SDK exposure events (#368)

* Send the serial ID on web SDK exposure events

The compiler changes a holdout into a usual allocation before an SDK
receives it. An exposure event therefore shows no holdout, and the serial
ID is the only link back to the holdout. The exposures worker already
accepts a serial_id field, and the precompute service already sends the
serial ID to the browser, but the SDK discards it.

Add an optional serial_id field to the exposure event, read it from the
evaluation metadata, and put the serial ID from the precomputed flag into
that metadata in the browser package.

A serial ID that is not a whole number of zero or more is not sent. The
intake discards the complete exposure event if the serial ID is less than
zero, so a bad value costs more than the field.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Update packages/core/src/configuration/exposureEvent.ts

Co-authored-by: Oleksii Shmalko <oleksii.shmalko@datadoghq.com>

* Narrow the serial ID by type only

The accepted review suggestion checked for null and undefined, which does
not compile: flagMetadata values are string, number, or boolean, so the
result cannot satisfy a numeric serial_id. Keep the type narrow, which is
what TypeScript needs, and drop the range and integer checks. The UFC layer
already validates the value, so the SDK does not repeat that work.

The tests that asserted a negative or fractional serial ID is dropped now
assert that it is sent unchanged. Two cases cover the narrow itself.

Author: danyal002

packages/browser/src/evaluation.ts

@@ -54,6 +54,7 @@ function evaluatePrecomputed<T extends FlagValueType>(
       allocationKey: flag.allocationKey,
       variationType: flag.variationType,
       doLog: flag.doLog,
+      ...(typeof flag.serialId === 'number' ? { __dd_split_serial_id: flag.serialId } : {}),
     } as PrecomputedFlagMetadata,
     reason: flag.reason,
   } as ResolutionDetails<FlagTypeToValue<T>>

packages/browser/test/evaluation.spec.ts

@@ -1,4 +1,4 @@
-import { configurationFromString } from '@datadog/flagging-core'
+import { configurationFromString, type FlagsConfiguration } from '@datadog/flagging-core'
 import type { ErrorCode } from '@openfeature/web-sdk'
 import { evaluate } from '../src/evaluation'
 import configurationWire from './data/precomputed-v1-wire.json'
@@ -78,4 +78,52 @@ describe('evaluate', () => {
       },
     })
   })
+
+  describe('serial id', () => {
+    const configurationWithSerialId = (serialId?: number | null): FlagsConfiguration => ({
+      precomputed: {
+        response: {
+          data: {
+            attributes: {
+              createdAt: '2026-08-17T00:00:00.000Z',
+              flags: {
+                'string-flag': {
+                  allocationKey: 'allocation-123',
+                  variationKey: 'variation-123',
+                  variationType: 'string',
+                  variationValue: 'red',
+                  reason: 'TARGETING_MATCH',
+                  doLog: true,
+                  extraLogging: {},
+                  ...(serialId === undefined ? {} : { serialId }),
+                },
+              },
+            },
+          },
+        },
+      },
+    })
+
+    it('carries the serial id from the precomputed flag onto the evaluation metadata', () => {
+      const result = evaluate(configurationWithSerialId(340132), 'string', 'string-flag', 'default', {})
+      expect(result.flagMetadata).toEqual({
+        allocationKey: 'allocation-123',
+        variationType: 'string',
+        doLog: true,
+        __dd_split_serial_id: 340132,
+      })
+    })
+
+    it('omits the serial id when the server sends null', () => {
+      const result = evaluate(configurationWithSerialId(null), 'string', 'string-flag', 'default', {})
+      expect(result.flagMetadata).not.toHaveProperty('__dd_split_serial_id')
+      expect(result.value).toBe('red')
+    })
+
+    it('omits the serial id when the server sends no such key', () => {
+      const result = evaluate(configurationWithSerialId(), 'string', 'string-flag', 'default', {})
+      expect(result.flagMetadata).not.toHaveProperty('__dd_split_serial_id')
+      expect(result.value).toBe('red')
+    })
+  })
 })

packages/browser/test/openfeature/exposures.spec.ts

@@ -445,6 +445,58 @@ describe('Exposures End-to-End', () => {
     }
   })
 
+  it('should send serial_id only for flags whose precomputed assignment carries one', async () => {
+    const responseWithSerialId = {
+      ...precomputedServerResponse,
+      data: {
+        ...precomputedServerResponse.data,
+        attributes: {
+          ...precomputedServerResponse.data.attributes,
+          flags: {
+            'string-flag': {
+              ...precomputedServerResponse.data.attributes.flags['string-flag'],
+              serialId: 340132,
+            },
+            'boolean-flag': precomputedServerResponse.data.attributes.flags['boolean-flag'],
+          },
+        },
+      },
+    }
+
+    fetchMock.mockImplementation((url: string) => {
+      if (url.includes('exposures')) {
+        return Promise.resolve({ ok: true, status: 200 })
+      }
+      if (url.includes('precompute-assignments')) {
+        return Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve(responseWithSerialId),
+        })
+      }
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+    })
+
+    await OpenFeature.setContext({ targetingKey: 'test-user-123' })
+    await OpenFeature.setProviderAndWait(
+      new DatadogProvider({
+        ...baseProviderConfig,
+        enableExposureLogging: true,
+      })
+    )
+
+    const client = OpenFeature.getClient()
+    client.getStringValue('string-flag', 'default')
+    client.getBooleanValue('boolean-flag', false)
+    triggerBatch()
+
+    const exposureEvents = parseExposureEvents(getExposuresCalls()[0][1].body)
+    expect(exposureEvents).toHaveLength(2)
+
+    const byFlagKey = new Map(exposureEvents.map((event) => [event.flag.key, event]))
+    expect(byFlagKey.get('string-flag').serial_id).toBe(340132)
+    expect(byFlagKey.get('boolean-flag')).not.toHaveProperty('serial_id')
+  })
+
   describe('exposure logging deduplication', () => {
     let providerConfig: FlaggingInitConfiguration
 

packages/core/src/configuration/configuration.ts

@@ -44,6 +44,7 @@ export type PrecomputedFlag<T extends FlagValueType = FlagValueType> = {
   variationValue: FlagTypeToValue<T>
   reason: ResolutionReason
   doLog: boolean
+  serialId?: number | null
   extraLogging: Record<string, unknown>
 }
 

packages/core/src/configuration/exposureEvent.ts

@@ -18,6 +18,7 @@ export function createExposureEvent<T extends FlagValue>(
   }
 
   const { targetingKey: id = '', ...attributes } = context
+  const serialId = details.flagMetadata?.__dd_split_serial_id
 
   return {
     allocation: {
@@ -29,6 +30,7 @@ export function createExposureEvent<T extends FlagValue>(
     variant: {
       key: variantKey,
     },
+    ...(typeof serialId === 'number' ? { serial_id: serialId } : {}),
     subject: {
       id,
       attributes,

packages/core/src/configuration/exposureEvent.types.ts

@@ -11,6 +11,7 @@ export interface ExposureEvent {
   variant: {
     key: string
   }
+  serial_id?: number
   subject: {
     id: string
     attributes: EvaluationContext

packages/core/test/configuration/exposureEvent.spec.ts

@@ -0,0 +1,75 @@
+import type { EvaluationContext, EvaluationDetails, FlagMetadata, FlagValue } from '@openfeature/core'
+import { createExposureEvent } from '../../src/configuration/exposureEvent'
+
+const context: EvaluationContext = { targetingKey: 'user-123', country: 'US' }
+
+function detailsWith(flagMetadata: FlagMetadata): EvaluationDetails<FlagValue> {
+  return {
+    flagKey: 'checkout-redesign',
+    value: 'red',
+    variant: 'treatment',
+    reason: 'SPLIT',
+    flagMetadata,
+  }
+}
+
+const baseMetadata: FlagMetadata = { doLog: true, allocationKey: 'allocation-123' }
+
+describe('createExposureEvent', () => {
+  it('should build the whole event, including serial_id, from the evaluation metadata', () => {
+    const event = createExposureEvent(context, detailsWith({ ...baseMetadata, __dd_split_serial_id: 340132 }))
+
+    expect(event).toEqual({
+      allocation: { key: 'allocation-123' },
+      flag: { key: 'checkout-redesign' },
+      variant: { key: 'treatment' },
+      serial_id: 340132,
+      subject: {
+        id: 'user-123',
+        attributes: { country: 'US' },
+      },
+    })
+  })
+
+  it('should not include serial_id when the metadata carries none', () => {
+    const event = createExposureEvent(context, detailsWith(baseMetadata))
+
+    expect(event).not.toHaveProperty('serial_id')
+    expect(event?.allocation.key).toBe('allocation-123')
+  })
+
+  it('should include a serial id of zero', () => {
+    const event = createExposureEvent(context, detailsWith({ ...baseMetadata, __dd_split_serial_id: 0 }))
+
+    expect(event).toHaveProperty('serial_id')
+    expect(event?.serial_id).toBe(0)
+  })
+
+  it.each<[number, string]>([
+    [-1, 'negative'],
+    [1.5, 'not an integer'],
+  ])('should send a serial id of %p (%s) without validating it', (serialId) => {
+    const event = createExposureEvent(context, detailsWith({ ...baseMetadata, __dd_split_serial_id: serialId }))
+
+    expect(event?.serial_id).toBe(serialId)
+  })
+
+  it.each<[string | boolean, string]>([
+    ['340132', 'a string'],
+    [true, 'a boolean'],
+  ])('should not include serial_id when the metadata value is %p (%s)', (serialId) => {
+    const event = createExposureEvent(context, detailsWith({ ...baseMetadata, __dd_split_serial_id: serialId }))
+
+    expect(event).not.toHaveProperty('serial_id')
+    expect(event?.flag.key).toBe('checkout-redesign')
+  })
+
+  it('should return undefined when doLog is false, whatever the serial id', () => {
+    const event = createExposureEvent(
+      context,
+      detailsWith({ doLog: false, allocationKey: 'allocation-123', __dd_split_serial_id: 340132 })
+    )
+
+    expect(event).toBeUndefined()
+  })
+})

packages/node-server/index.d.ts

@@ -415,6 +415,7 @@ interface ExposureEvent {
 	variant: {
 		key: string;
 	};
+	serial_id?: number;
 	subject: {
 		id: string;
 		attributes: EvaluationContext;