@datadog/mobile-react-native 3.9.0 → 3.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/DatadogSDKReactNative.podspec +7 -7
  2. package/android/build.gradle +9 -8
  3. package/android/src/main/kotlin/com/datadog/reactnative/DdFlagsImplementation.kt +6 -3
  4. package/android/src/main/kotlin/com/datadog/reactnative/DdRumImplementation.kt +10 -0
  5. package/android/src/main/kotlin/com/datadog/reactnative/DdSdkImplementation.kt +16 -8
  6. package/android/src/main/kotlin/com/datadog/reactnative/FrameRateProvider.kt +11 -6
  7. package/android/src/main/kotlin/com/datadog/reactnative/SdkVersion.kt +1 -1
  8. package/android/src/newarch/kotlin/com/datadog/reactnative/DdRum.kt +10 -0
  9. package/android/src/oldarchCommon/kotlin/com/datadog/reactnative/DdRum.kt +10 -0
  10. package/android/src/test/kotlin/com/datadog/reactnative/DdFlagsImplementationTest.kt +19 -0
  11. package/android/src/test/kotlin/com/datadog/reactnative/DdRumTest.kt +9 -0
  12. package/android/src/test/kotlin/com/datadog/reactnative/DdSdkTest.kt +131 -0
  13. package/android/src/test/kotlin/com/datadog/tools/unit/MockRumMonitor.kt +3 -3
  14. package/datadog-configuration.schema.json +11 -0
  15. package/ios/Sources/DdRum.mm +13 -1
  16. package/ios/Sources/DdRumImplementation.swift +6 -0
  17. package/ios/Sources/DdSdkConfiguration.swift +13 -0
  18. package/ios/Sources/DdSdkImplementation.swift +4 -3
  19. package/ios/Sources/DdSdkNativeInitialization.swift +26 -8
  20. package/ios/Sources/JSRefreshRateListener.swift +6 -2
  21. package/ios/Sources/RNDdSdkConfiguration.swift +9 -0
  22. package/ios/Sources/SdkVersion.swift +1 -1
  23. package/jest/mock.js +3 -0
  24. package/lib/commonjs/DdSdkReactNative.js +1 -1
  25. package/lib/commonjs/config/FileBasedConfiguration.js +3 -1
  26. package/lib/commonjs/config/FileBasedConfiguration.js.map +1 -1
  27. package/lib/commonjs/config/async/AutoInstrumentationConfiguration.js +3 -0
  28. package/lib/commonjs/config/async/AutoInstrumentationConfiguration.js.map +1 -1
  29. package/lib/commonjs/config/features/RumConfiguration.js +8 -0
  30. package/lib/commonjs/config/features/RumConfiguration.js.map +1 -1
  31. package/lib/commonjs/flags/FlagsClient.js +81 -8
  32. package/lib/commonjs/flags/FlagsClient.js.map +1 -1
  33. package/lib/commonjs/flags/configuration/precomputed.js +2 -3
  34. package/lib/commonjs/flags/configuration/precomputed.js.map +1 -1
  35. package/lib/commonjs/flags/internal.js.map +1 -1
  36. package/lib/commonjs/rum/DdRum.js +4 -0
  37. package/lib/commonjs/rum/DdRum.js.map +1 -1
  38. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/FetchProxy.js +2 -2
  39. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/FetchProxy.js.map +1 -1
  40. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/XHRProxy.js +1 -1
  41. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/XHRProxy.js.map +1 -1
  42. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.js +7 -1
  43. package/lib/commonjs/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.js.map +1 -1
  44. package/lib/commonjs/rum/types.js.map +1 -1
  45. package/lib/commonjs/sdk/AccountInfoSingleton/AccountInfoSingleton.js +1 -0
  46. package/lib/commonjs/sdk/AccountInfoSingleton/AccountInfoSingleton.js.map +1 -1
  47. package/lib/commonjs/sdk/UserInfoSingleton/UserInfoSingleton.js +1 -0
  48. package/lib/commonjs/sdk/UserInfoSingleton/UserInfoSingleton.js.map +1 -1
  49. package/lib/commonjs/specs/NativeDdRum.js.map +1 -1
  50. package/lib/commonjs/version.js +1 -1
  51. package/lib/commonjs/version.js.map +1 -1
  52. package/lib/module/DdSdkReactNative.js +1 -1
  53. package/lib/module/config/FileBasedConfiguration.js +3 -1
  54. package/lib/module/config/FileBasedConfiguration.js.map +1 -1
  55. package/lib/module/config/async/AutoInstrumentationConfiguration.js +3 -0
  56. package/lib/module/config/async/AutoInstrumentationConfiguration.js.map +1 -1
  57. package/lib/module/config/features/RumConfiguration.js +8 -0
  58. package/lib/module/config/features/RumConfiguration.js.map +1 -1
  59. package/lib/module/flags/FlagsClient.js +81 -8
  60. package/lib/module/flags/FlagsClient.js.map +1 -1
  61. package/lib/module/flags/configuration/precomputed.js +2 -3
  62. package/lib/module/flags/configuration/precomputed.js.map +1 -1
  63. package/lib/module/flags/internal.js.map +1 -1
  64. package/lib/module/rum/DdRum.js +4 -0
  65. package/lib/module/rum/DdRum.js.map +1 -1
  66. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/FetchProxy.js +3 -3
  67. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/FetchProxy.js.map +1 -1
  68. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/XHRProxy.js +2 -2
  69. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/XHRProxy.js.map +1 -1
  70. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.js +5 -0
  71. package/lib/module/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.js.map +1 -1
  72. package/lib/module/rum/types.js.map +1 -1
  73. package/lib/module/sdk/AccountInfoSingleton/AccountInfoSingleton.js +2 -1
  74. package/lib/module/sdk/AccountInfoSingleton/AccountInfoSingleton.js.map +1 -1
  75. package/lib/module/sdk/UserInfoSingleton/UserInfoSingleton.js +2 -1
  76. package/lib/module/sdk/UserInfoSingleton/UserInfoSingleton.js.map +1 -1
  77. package/lib/module/specs/NativeDdRum.js.map +1 -1
  78. package/lib/module/version.js +1 -1
  79. package/lib/module/version.js.map +1 -1
  80. package/lib/typescript/config/FileBasedConfiguration.d.ts.map +1 -1
  81. package/lib/typescript/config/FileBasedConfiguration.type.d.ts +2 -0
  82. package/lib/typescript/config/FileBasedConfiguration.type.d.ts.map +1 -1
  83. package/lib/typescript/config/async/AutoInstrumentationConfiguration.d.ts +4 -0
  84. package/lib/typescript/config/async/AutoInstrumentationConfiguration.d.ts.map +1 -1
  85. package/lib/typescript/config/async/PartialInitializationConfiguration.d.ts +2 -0
  86. package/lib/typescript/config/async/PartialInitializationConfiguration.d.ts.map +1 -1
  87. package/lib/typescript/config/features/RumConfiguration.d.ts +4 -0
  88. package/lib/typescript/config/features/RumConfiguration.d.ts.map +1 -1
  89. package/lib/typescript/config/features/RumConfiguration.type.d.ts +21 -0
  90. package/lib/typescript/config/features/RumConfiguration.type.d.ts.map +1 -1
  91. package/lib/typescript/config/features/RumConfigurationNative.d.ts +2 -0
  92. package/lib/typescript/config/features/RumConfigurationNative.d.ts.map +1 -1
  93. package/lib/typescript/flags/FlagsClient.d.ts +38 -1
  94. package/lib/typescript/flags/FlagsClient.d.ts.map +1 -1
  95. package/lib/typescript/flags/internal.d.ts +1 -0
  96. package/lib/typescript/flags/internal.d.ts.map +1 -1
  97. package/lib/typescript/flags/types.d.ts +1 -1
  98. package/lib/typescript/flags/types.d.ts.map +1 -1
  99. package/lib/typescript/rum/DdRum.d.ts +1 -0
  100. package/lib/typescript/rum/DdRum.d.ts.map +1 -1
  101. package/lib/typescript/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.d.ts +2 -0
  102. package/lib/typescript/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.d.ts.map +1 -1
  103. package/lib/typescript/rum/types.d.ts +6 -0
  104. package/lib/typescript/rum/types.d.ts.map +1 -1
  105. package/lib/typescript/sdk/AccountInfoSingleton/AccountInfoSingleton.d.ts.map +1 -1
  106. package/lib/typescript/sdk/UserInfoSingleton/UserInfoSingleton.d.ts.map +1 -1
  107. package/lib/typescript/specs/NativeDdRum.d.ts +6 -0
  108. package/lib/typescript/specs/NativeDdRum.d.ts.map +1 -1
  109. package/lib/typescript/version.d.ts +1 -1
  110. package/lib/typescript/version.d.ts.map +1 -1
  111. package/package.json +2 -2
  112. package/src/DdSdkReactNative.tsx +1 -1
  113. package/src/__tests__/DdSdkReactNative.test.tsx +133 -0
  114. package/src/__tests__/DdSdkReactNativeConfiguration.test.ts +12 -0
  115. package/src/config/FileBasedConfiguration.ts +6 -1
  116. package/src/config/FileBasedConfiguration.type.ts +2 -0
  117. package/src/config/__tests__/FileBasedConfiguration.test.ts +79 -0
  118. package/src/config/__tests__/__fixtures__/configuration-all-fields.json +2 -0
  119. package/src/config/async/AutoInstrumentationConfiguration.ts +9 -0
  120. package/src/config/async/PartialInitializationConfiguration.ts +2 -0
  121. package/src/config/features/RumConfiguration.ts +10 -0
  122. package/src/config/features/RumConfiguration.type.ts +23 -0
  123. package/src/config/features/RumConfigurationNative.ts +2 -0
  124. package/src/flags/FlagsClient.ts +128 -19
  125. package/src/flags/__tests__/FlagsClient.test.ts +167 -0
  126. package/src/flags/configuration/precomputed.ts +2 -3
  127. package/src/flags/internal.ts +2 -0
  128. package/src/flags/types.ts +2 -0
  129. package/src/rum/DdRum.ts +10 -0
  130. package/src/rum/__tests__/DdRum.test.ts +10 -0
  131. package/src/rum/instrumentation/interactionTracking/__tests__/DdBabelInteractionTracking.test.ts +104 -1
  132. package/src/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/FetchProxy.ts +3 -3
  133. package/src/rum/instrumentation/resourceTracking/requestProxy/FetchProxy/__tests__/FetchProxy.test.ts +29 -0
  134. package/src/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/XHRProxy.ts +2 -2
  135. package/src/rum/instrumentation/resourceTracking/requestProxy/XHRProxy/__tests__/XHRProxy.test.ts +40 -0
  136. package/src/rum/instrumentation/resourceTracking/requestProxy/common/RequestContext.ts +9 -0
  137. package/src/rum/types.ts +7 -0
  138. package/src/sdk/AccountInfoSingleton/AccountInfoSingleton.ts +2 -1
  139. package/src/sdk/AccountInfoSingleton/__tests__/AccountInfoSingleton.test.ts +59 -0
  140. package/src/sdk/DatadogProvider/__tests__/initialization.test.tsx +165 -0
  141. package/src/sdk/UserInfoSingleton/UserInfoSingleton.ts +2 -1
  142. package/src/sdk/UserInfoSingleton/__tests__/UserInfoSingleton.test.ts +55 -0
  143. package/src/specs/NativeDdRum.ts +7 -0
  144. package/src/version.ts +1 -1
@@ -59,6 +59,10 @@ describe('FileBasedConfiguration', () => {
59
59
  "longTaskThresholdMs": 44,
60
60
  "nativeCrashReportEnabled": true,
61
61
  "nativeInteractionTracking": true,
62
+ "nativeIosResourceTracking": true,
63
+ "nativeIosResourceTrackingDisallowList": [
64
+ "https://3p.example.com/*",
65
+ ],
62
66
  "nativeLongTaskThresholdMs": 789,
63
67
  "nativeViewTracking": true,
64
68
  "resourceEventMapper": null,
@@ -172,6 +176,8 @@ describe('FileBasedConfiguration', () => {
172
176
  "longTaskThresholdMs": 44,
173
177
  "nativeCrashReportEnabled": false,
174
178
  "nativeInteractionTracking": false,
179
+ "nativeIosResourceTracking": undefined,
180
+ "nativeIosResourceTrackingDisallowList": undefined,
175
181
  "nativeLongTaskThresholdMs": 200,
176
182
  "nativeViewTracking": false,
177
183
  "resourceEventMapper": null,
@@ -237,6 +243,8 @@ describe('FileBasedConfiguration', () => {
237
243
  "longTaskThresholdMs": 0,
238
244
  "nativeCrashReportEnabled": false,
239
245
  "nativeInteractionTracking": false,
246
+ "nativeIosResourceTracking": undefined,
247
+ "nativeIosResourceTrackingDisallowList": undefined,
240
248
  "nativeLongTaskThresholdMs": 200,
241
249
  "nativeViewTracking": false,
242
250
  "resourceEventMapper": null,
@@ -267,6 +275,77 @@ describe('FileBasedConfiguration', () => {
267
275
  `);
268
276
  });
269
277
 
278
+ it('leaves nativeIosResourceTracking undefined when not set', () => {
279
+ const config = new FileBasedConfiguration({
280
+ configuration: {
281
+ env: 'fake-env',
282
+ clientToken: 'fake-client-token',
283
+ rumConfiguration: {
284
+ applicationId: 'fake-app-id'
285
+ }
286
+ }
287
+ });
288
+ expect(config.rumConfiguration).toHaveProperty(
289
+ 'nativeIosResourceTracking',
290
+ undefined
291
+ );
292
+ });
293
+
294
+ it.each([true, false])(
295
+ 'passes nativeIosResourceTracking through when set to %s',
296
+ value => {
297
+ const config = new FileBasedConfiguration({
298
+ configuration: {
299
+ env: 'fake-env',
300
+ clientToken: 'fake-client-token',
301
+ rumConfiguration: {
302
+ applicationId: 'fake-app-id',
303
+ nativeIosResourceTracking: value
304
+ }
305
+ }
306
+ });
307
+ expect(config.rumConfiguration?.nativeIosResourceTracking).toBe(
308
+ value
309
+ );
310
+ }
311
+ );
312
+
313
+ it('leaves nativeIosResourceTrackingDisallowList undefined when not set', () => {
314
+ const config = new FileBasedConfiguration({
315
+ configuration: {
316
+ env: 'fake-env',
317
+ clientToken: 'fake-client-token',
318
+ rumConfiguration: {
319
+ applicationId: 'fake-app-id'
320
+ }
321
+ }
322
+ });
323
+ expect(config.rumConfiguration).toHaveProperty(
324
+ 'nativeIosResourceTrackingDisallowList',
325
+ undefined
326
+ );
327
+ });
328
+
329
+ it('passes nativeIosResourceTrackingDisallowList through when set', () => {
330
+ const disallowList = [
331
+ 'https://3p.example.com/*',
332
+ 'https://cdn.example.com/a'
333
+ ];
334
+ const config = new FileBasedConfiguration({
335
+ configuration: {
336
+ env: 'fake-env',
337
+ clientToken: 'fake-client-token',
338
+ rumConfiguration: {
339
+ applicationId: 'fake-app-id',
340
+ nativeIosResourceTrackingDisallowList: disallowList
341
+ }
342
+ }
343
+ });
344
+ expect(
345
+ config.rumConfiguration?.nativeIosResourceTrackingDisallowList
346
+ ).toEqual(disallowList);
347
+ });
348
+
270
349
  it('applies event mappers to configuration when provided', () => {
271
350
  const actionEventMapper = () => null;
272
351
  const errorEventMapper = () => null;
@@ -28,6 +28,8 @@
28
28
  "initialResourceThreshold": 456,
29
29
  "nativeViewTracking": true,
30
30
  "nativeInteractionTracking": true,
31
+ "nativeIosResourceTracking": true,
32
+ "nativeIosResourceTrackingDisallowList": ["https://3p.example.com/*"],
31
33
  "nativeLongTaskThresholdMs": 789,
32
34
  "nativeCrashReportEnabled": true,
33
35
  "trackBackgroundEvents": true,
@@ -28,6 +28,8 @@ export type AutoInstrumentationConfiguration = {
28
28
  readonly nativeCrashReportEnabled?: boolean;
29
29
  readonly nativeLongTaskThresholdMs?: number;
30
30
  readonly nativeViewTracking?: boolean;
31
+ readonly nativeIosResourceTracking?: boolean;
32
+ readonly nativeIosResourceTrackingDisallowList?: string[];
31
33
  readonly actionEventMapper?: ActionEventMapper | null;
32
34
  readonly errorEventMapper?: ErrorEventMapper | null;
33
35
  readonly resourceEventMapper?: ResourceEventMapper | null;
@@ -53,6 +55,8 @@ export type AutoInstrumentationParameters = {
53
55
  readonly nativeCrashReportEnabled?: boolean;
54
56
  readonly nativeLongTaskThresholdMs?: number;
55
57
  readonly nativeViewTracking?: boolean;
58
+ readonly nativeIosResourceTracking?: boolean;
59
+ readonly nativeIosResourceTrackingDisallowList?: string[];
56
60
  readonly actionEventMapper: ActionEventMapper | null;
57
61
  readonly errorEventMapper: ErrorEventMapper | null;
58
62
  readonly resourceEventMapper: ResourceEventMapper | null;
@@ -117,6 +121,11 @@ export const addDefaultValuesToAutoInstrumentationConfiguration = (
117
121
  nativeViewTracking:
118
122
  features.rumConfiguration.nativeViewTracking ??
119
123
  RUM_DEFAULTS.nativeViewTracking,
124
+ // No default on purpose: undefined means legacy iOS behavior
125
+ nativeIosResourceTracking:
126
+ features.rumConfiguration.nativeIosResourceTracking,
127
+ nativeIosResourceTrackingDisallowList:
128
+ features.rumConfiguration.nativeIosResourceTrackingDisallowList,
120
129
  firstPartyHosts:
121
130
  features.rumConfiguration.firstPartyHosts ||
122
131
  RUM_DEFAULTS.getFirstPartyHosts()
@@ -36,6 +36,8 @@ export type PartialInitializationConfiguration = {
36
36
  readonly nativeCrashReportEnabled?: boolean;
37
37
  readonly nativeViewTracking?: boolean;
38
38
  readonly nativeInteractionTracking?: boolean;
39
+ readonly nativeIosResourceTracking?: boolean;
40
+ readonly nativeIosResourceTrackingDisallowList?: string[];
39
41
  readonly longTaskThresholdMs?: number | false;
40
42
  readonly vitalsUpdateFrequency?: VitalsUpdateFrequency;
41
43
  readonly trackFrustrations?: boolean;
@@ -26,6 +26,8 @@ const DEFAULTS = {
26
26
  nativeCrashReportEnabled: false,
27
27
  nativeInteractionTracking: false,
28
28
  nativeLongTaskThresholdMs: 200,
29
+ nativeIosResourceTracking: undefined,
30
+ nativeIosResourceTrackingDisallowList: undefined,
29
31
  nativeViewTracking: false,
30
32
  resourceEventMapper: null,
31
33
  resourceTraceSampleRate: 100.0,
@@ -85,6 +87,14 @@ export class RumConfiguration implements RumConfigurationType {
85
87
  public nativeLongTaskThresholdMs: number =
86
88
  DEFAULTS.nativeLongTaskThresholdMs;
87
89
 
90
+ // Native Resource Tracking (iOS only); undefined means legacy behavior
91
+ public nativeIosResourceTracking?: boolean =
92
+ DEFAULTS.nativeIosResourceTracking;
93
+
94
+ // URL patterns excluded from native iOS resource tracking; undefined means [] on iOS
95
+ public nativeIosResourceTrackingDisallowList?: string[] =
96
+ DEFAULTS.nativeIosResourceTrackingDisallowList;
97
+
88
98
  // Native View Tracking enabled
89
99
  public nativeViewTracking: boolean = DEFAULTS.nativeViewTracking;
90
100
 
@@ -109,6 +109,29 @@ export interface RumConfigurationOptions {
109
109
  */
110
110
  nativeViewTracking?: boolean;
111
111
 
112
+ /**
113
+ * Controls automatic native network (URLSession) resource tracking. iOS only: has no effect on Android.
114
+ * - `undefined` (default): legacy behavior, enables iOS network tracking if `firstPartyHosts` is defined.
115
+ * - `true`: enables iOS network tracking (with trace headers for `firstPartyHosts`, if defined).
116
+ * - `false`: disables iOS network tracking.
117
+ */
118
+ nativeIosResourceTracking?: boolean;
119
+
120
+ /**
121
+ * URL patterns excluded from automatic native iOS network (URLSession) resource tracking.
122
+ * iOS only: has no effect on Android.
123
+ * - Patterns are matched against the full URL: plain strings match exactly, `*` matches any characters.
124
+ * - Patterns without any literal characters (e.g. `"*"`) are ignored.
125
+ * - Matching requests also get no trace headers injected and no APM span.
126
+ *
127
+ * Only takes effect when native iOS resource tracking is enabled (see `nativeIosResourceTracking`);
128
+ * it never enables tracking by itself. If set while tracking is disabled, the native SDK logs
129
+ * a warning (subject to `verbosity`).
130
+ *
131
+ * Default: `[]` (no URLs excluded).
132
+ */
133
+ nativeIosResourceTrackingDisallowList?: string[];
134
+
112
135
  /**
113
136
  * Custom mapper to transform RUM resource events.
114
137
  */
@@ -15,6 +15,8 @@ export type RumNativeConfiguration = {
15
15
  readonly nativeLongTaskThresholdMs: number;
16
16
  readonly nativeViewTracking: boolean;
17
17
  readonly nativeInteractionTracking: boolean;
18
+ readonly nativeIosResourceTracking: boolean | undefined;
19
+ readonly nativeIosResourceTrackingDisallowList: string[] | undefined;
18
20
  readonly trackNonFatalAnrs: boolean | undefined;
19
21
  readonly appHangThreshold: number | undefined;
20
22
  readonly trackWatchdogTerminations: boolean | undefined;
@@ -24,11 +24,13 @@ import type { JsonValue, EvaluationContext, FlagDetails } from './types';
24
24
  * Error codes an offline configuration result can carry:
25
25
  * - `INVALID_CONTEXT`: the active context does not match the precomputed snapshot.
26
26
  * - `PROVIDER_NOT_READY`: an offline operation ran with no configuration loaded.
27
+ * - `PARSE_ERROR`: the offline evaluator cannot parse the supplied configuration.
27
28
  * - `GENERAL`: the loaded configuration is unusable (malformed/unsupported/undecodable).
28
29
  */
29
30
  export type ConfigurationErrorCode =
30
31
  | 'INVALID_CONTEXT'
31
32
  | 'PROVIDER_NOT_READY'
33
+ | 'PARSE_ERROR'
32
34
  | 'GENERAL';
33
35
 
34
36
  /**
@@ -63,6 +65,22 @@ type LoadedConfigurationState =
63
65
  flags: Map<string, FlagCacheEntry>;
64
66
  };
65
67
 
68
+ /** @internal JavaScript evaluation supplied by the OpenFeature package; tracking stays native. */
69
+ interface OfflineFlagsEvaluator {
70
+ reconcile(
71
+ context: EvaluationContext | undefined,
72
+ hasTargetingKey?: boolean
73
+ ): ConfigurationResult;
74
+ evaluate<T>(
75
+ key: string,
76
+ defaultValue: T,
77
+ type: 'boolean' | 'string' | 'number' | 'object'
78
+ ): {
79
+ details: FlagDetails<T>;
80
+ exposure?: { flag: FlagCacheEntry; context: EvaluationContext };
81
+ };
82
+ }
83
+
66
84
  export class FlagsClient {
67
85
  // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
68
86
  private nativeFlags: DdNativeFlagsType = require('../specs/NativeDdFlags')
@@ -77,6 +95,10 @@ export class FlagsClient {
77
95
  // is never mistaken for an app-set override (which would spuriously fail a later replacement).
78
96
  private externalContext: EvaluationContext | undefined = undefined;
79
97
 
98
+ // Rules distinguish a missing subject from an explicitly anonymous ('') subject. Keep that
99
+ // information alongside the normalized context, without changing native/precomputed semantics.
100
+ private externalContextHasTargetingKey: boolean | undefined = undefined;
101
+
80
102
  // The effective context evaluation and exposure tracking run against: the external override
81
103
  // when set, otherwise the loaded configuration's embedded context.
82
104
  private evaluationContext: EvaluationContext | undefined = undefined;
@@ -91,6 +113,9 @@ export class FlagsClient {
91
113
  // The decoded outcome of the last loaded offline configuration (see the type).
92
114
  private loadedConfiguration: LoadedConfigurationState = { kind: 'none' };
93
115
 
116
+ // Owned by the named client (not the provider instance), preserving shared-client behavior.
117
+ private offlineEvaluator: OfflineFlagsEvaluator | undefined;
118
+
94
119
  // Internal serving status. `'none'` = online path (serve `flagsCache`); `'ready'` = serve
95
120
  // the offline snapshot; `'error'` = serve coded defaults with `configurationError`.
96
121
  private configurationStatus: 'none' | 'ready' | 'error' = 'none';
@@ -137,17 +162,19 @@ export class FlagsClient {
137
162
  // client for both online and offline is unsupported (give the offline provider its own
138
163
  // `clientName`), so warn when an offline configuration is discarded here. Online-only clients
139
164
  // have no overlay, so this does not touch their keep-last-known-flags-on-failure behavior.
140
- if (this.loadedConfiguration.kind !== 'none') {
165
+ if (this.loadedConfiguration.kind !== 'none' || this.offlineEvaluator) {
141
166
  InternalLog.log(
142
167
  `An offline configuration was loaded for '${this.clientName}' but an online fetch was requested; discarding it and serving default values on failure. Use a separate client for the offline provider.`,
143
168
  SdkVerbosity.WARN
144
169
  );
145
170
  this.loadedConfiguration = { kind: 'none' };
171
+ this.offlineEvaluator = undefined;
146
172
  this.configurationStatus = 'none';
147
173
  this.configurationError = undefined;
148
174
  this.flagsCache = new Map();
149
175
  this.evaluationContext = undefined;
150
176
  this.externalContext = undefined;
177
+ this.externalContextHasTargetingKey = undefined;
151
178
  }
152
179
 
153
180
  try {
@@ -158,6 +185,7 @@ export class FlagsClient {
158
185
  );
159
186
 
160
187
  this.externalContext = processedContext;
188
+ this.externalContextHasTargetingKey = true;
161
189
  this.evaluationContext = processedContext;
162
190
  this.flagsCache = new Map(Object.entries(result));
163
191
 
@@ -165,6 +193,7 @@ export class FlagsClient {
165
193
  // prior offline error status (e.g. PROVIDER_NOT_READY from an offline op with no
166
194
  // configuration loaded) can't keep serving coded defaults over the fetched flags.
167
195
  this.loadedConfiguration = { kind: 'none' };
196
+ this.offlineEvaluator = undefined;
168
197
  this.configurationStatus = 'none';
169
198
  this.configurationError = undefined;
170
199
  } catch (error) {
@@ -196,8 +225,25 @@ export class FlagsClient {
196
225
  */
197
226
  setEvaluationContextWithoutFetching = (
198
227
  context: EvaluationContext
228
+ ): ConfigurationResult => {
229
+ return this.__ddSetOfflineEvaluationContext(
230
+ context,
231
+ typeof context.targetingKey === 'string'
232
+ );
233
+ };
234
+
235
+ /**
236
+ * Preserve subject presence before the OpenFeature adapter normalizes a missing key to ''.
237
+ * The context still follows native/precomputed normalization; only the offline evaluator
238
+ * receives the presence bit. Stored on the named client so aliases and replacements share it.
239
+ * @internal Used only by the matching-version OpenFeature integration.
240
+ */
241
+ __ddSetOfflineEvaluationContext = (
242
+ context: EvaluationContext,
243
+ hasTargetingKey: boolean
199
244
  ): ConfigurationResult => {
200
245
  this.externalContext = processEvaluationContext(context);
246
+ this.externalContextHasTargetingKey = hasTargetingKey;
201
247
 
202
248
  return this.reconcile();
203
249
  };
@@ -213,6 +259,7 @@ export class FlagsClient {
213
259
  */
214
260
  resetEvaluationContextWithoutFetching = (): ConfigurationResult => {
215
261
  this.externalContext = undefined;
262
+ this.externalContextHasTargetingKey = undefined;
216
263
 
217
264
  return this.reconcile();
218
265
  };
@@ -239,11 +286,36 @@ export class FlagsClient {
239
286
  setConfiguration = (
240
287
  configuration: ParsedFlagsConfiguration
241
288
  ): ConfigurationResult => {
289
+ this.offlineEvaluator = undefined;
242
290
  this.loadedConfiguration = this.loadConfiguration(configuration);
243
291
 
244
292
  return this.reconcile();
245
293
  };
246
294
 
295
+ /**
296
+ * Install a JavaScript evaluator for this named client's offline configuration.
297
+ * The factory receives the SDK's existing compatibility helpers, so the provider can reuse
298
+ * precomputed validation/context normalization without depending on private module paths.
299
+ * All client getters use the delegate; successful evaluations still use native tracking.
300
+ * An online fetch or a direct setConfiguration replaces this overlay, just as before.
301
+ * @internal Used only by the matching-version OpenFeature integration.
302
+ */
303
+ __ddSetOfflineEvaluator = (
304
+ create: (helpers: {
305
+ decodePrecomputedFlags: typeof decodePrecomputedFlags;
306
+ normalizeWireContext: typeof normalizeWireContext;
307
+ }) => OfflineFlagsEvaluator
308
+ ): ConfigurationResult => {
309
+ this.offlineEvaluator = create({
310
+ decodePrecomputedFlags,
311
+ normalizeWireContext
312
+ });
313
+ this.loadedConfiguration = { kind: 'none' };
314
+ this.flagsCache = new Map();
315
+ this.evaluationContext = undefined;
316
+ return this.reconcile();
317
+ };
318
+
247
319
  /**
248
320
  * Decode a supplied configuration into a {@link LoadedConfigurationState} **once**, capturing
249
321
  * whether the load itself is valid (independent of the active context). Later context changes
@@ -294,6 +366,24 @@ export class FlagsClient {
294
366
  * can never promote an invalid (or absent) load to `ready`.
295
367
  */
296
368
  private reconcile = (): ConfigurationResult => {
369
+ if (this.offlineEvaluator) {
370
+ const result = this.offlineEvaluator.reconcile(
371
+ this.externalContext,
372
+ this.externalContextHasTargetingKey
373
+ );
374
+ if (result.status === 'error') {
375
+ return this.enterError(
376
+ result.errorCode,
377
+ result.errorCode === 'PARSE_ERROR'
378
+ ? `The offline configuration for '${this.clientName}' cannot be parsed.`
379
+ : `The offline configuration for '${this.clientName}' cannot serve the current context.`
380
+ );
381
+ }
382
+ this.configurationStatus = 'ready';
383
+ this.configurationError = undefined;
384
+ return result;
385
+ }
386
+
297
387
  const loaded = this.loadedConfiguration;
298
388
 
299
389
  // No offline configuration engaged: an offline operation with nothing loaded is not ready.
@@ -367,23 +457,30 @@ export class FlagsClient {
367
457
  };
368
458
 
369
459
  private track = (flag: FlagCacheEntry, context: EvaluationContext) => {
370
- // A non-blocking call; don't await this.
371
- this.nativeFlags
372
- .trackEvaluation(
373
- this.clientName,
374
- flag.key,
375
- flag,
376
- context.targetingKey,
377
- context.attributes ?? {}
378
- )
379
- .catch(error => {
380
- if (error instanceof Error) {
381
- InternalLog.log(
382
- `Error tracking flag evaluation: ${error.message}`,
383
- SdkVerbosity.WARN
384
- );
385
- }
386
- });
460
+ // A non-blocking call; don't await this. A tracking failure, synchronous or not, must
461
+ // never change the evaluation result.
462
+ try {
463
+ this.nativeFlags
464
+ .trackEvaluation(
465
+ this.clientName,
466
+ flag.key,
467
+ flag,
468
+ context.targetingKey,
469
+ context.attributes ?? {}
470
+ )
471
+ .catch(this.logTrackingError);
472
+ } catch (error) {
473
+ this.logTrackingError(error);
474
+ }
475
+ };
476
+
477
+ private logTrackingError = (error: unknown) => {
478
+ if (error instanceof Error) {
479
+ InternalLog.log(
480
+ `Error tracking flag evaluation: ${error.message}`,
481
+ SdkVerbosity.WARN
482
+ );
483
+ }
387
484
  };
388
485
 
389
486
  private getDetails = <T>(
@@ -391,8 +488,20 @@ export class FlagsClient {
391
488
  defaultValue: T,
392
489
  type: 'boolean' | 'string' | 'number' | 'object'
393
490
  ): FlagDetails<T> => {
491
+ if (this.offlineEvaluator) {
492
+ const { details, exposure } = this.offlineEvaluator.evaluate(
493
+ key,
494
+ defaultValue,
495
+ type
496
+ );
497
+ if (!details.errorCode && exposure) {
498
+ this.track(exposure.flag, exposure.context);
499
+ }
500
+ return details;
501
+ }
502
+
394
503
  // An offline configuration that cannot be served against the active context surfaces the
395
- // precise error code (INVALID_CONTEXT / GENERAL / PROVIDER_NOT_READY) with the coded
504
+ // precise error code (INVALID_CONTEXT / PARSE_ERROR / GENERAL / PROVIDER_NOT_READY) with the coded
396
505
  // default. The OpenFeature provider maps this to a PROVIDER_ERROR / ERROR state.
397
506
  if (this.configurationStatus === 'error' && this.configurationError) {
398
507
  return {
@@ -82,6 +82,144 @@ describe('FlagsClient', () => {
82
82
  await DdFlags.enable();
83
83
  });
84
84
 
85
+ describe('offline evaluator subject presence', () => {
86
+ const evaluator = () => ({
87
+ reconcile: jest.fn(() => ({ status: 'ready' as const })),
88
+ evaluate: jest.fn()
89
+ });
90
+
91
+ it('preserves presence on the named client across evaluator/direct configuration replacement', () => {
92
+ const client = DdFlags.getClient('presence');
93
+ const initial = evaluator();
94
+ client.__ddSetOfflineEvaluator(() => initial);
95
+ expect(initial.reconcile).toHaveBeenLastCalledWith(
96
+ undefined,
97
+ undefined
98
+ );
99
+ const anonymous = {
100
+ targetingKey: '',
101
+ attributes: { country: 'CA' }
102
+ };
103
+ client.__ddSetOfflineEvaluationContext(anonymous, false);
104
+ expect(initial.reconcile).toHaveBeenLastCalledWith(
105
+ anonymous,
106
+ false
107
+ );
108
+
109
+ client.setConfiguration(configurationFromString('invalid'));
110
+ const replacement = evaluator();
111
+ DdFlags.getClient('presence').__ddSetOfflineEvaluator(
112
+ () => replacement
113
+ );
114
+ expect(replacement.reconcile).toHaveBeenLastCalledWith(
115
+ anonymous,
116
+ false
117
+ );
118
+ client.setEvaluationContextWithoutFetching(anonymous);
119
+ expect(replacement.reconcile).toHaveBeenLastCalledWith(
120
+ anonymous,
121
+ true
122
+ );
123
+ client.resetEvaluationContextWithoutFetching();
124
+ expect(replacement.reconcile).toHaveBeenLastCalledWith(
125
+ undefined,
126
+ undefined
127
+ );
128
+ expect(
129
+ NativeModules.DdFlags.setEvaluationContext
130
+ ).not.toHaveBeenCalled();
131
+ });
132
+
133
+ it('keeps online normalization authoritative and clears stale offline presence', async () => {
134
+ const client = DdFlags.getClient('presence-online');
135
+ client.__ddSetOfflineEvaluator(evaluator);
136
+ client.__ddSetOfflineEvaluationContext({ targetingKey: '' }, false);
137
+ await client.setEvaluationContext({
138
+ targetingKey: '',
139
+ attributes: {}
140
+ });
141
+ expect(
142
+ NativeModules.DdFlags.setEvaluationContext
143
+ ).toHaveBeenCalledWith('presence-online', '', {});
144
+ const replacement = evaluator();
145
+ client.__ddSetOfflineEvaluator(() => replacement);
146
+ expect(replacement.reconcile).toHaveBeenLastCalledWith(
147
+ { targetingKey: '', attributes: {} },
148
+ true
149
+ );
150
+ });
151
+
152
+ it('clears offline presence when an online fetch discards the overlay and fails', async () => {
153
+ const client = DdFlags.getClient('presence-failed-fetch');
154
+ client.__ddSetOfflineEvaluator(evaluator);
155
+ client.__ddSetOfflineEvaluationContext({ targetingKey: '' }, false);
156
+ NativeModules.DdFlags.setEvaluationContext.mockRejectedValueOnce(
157
+ new Error('fetch failed')
158
+ );
159
+ await expect(
160
+ client.setEvaluationContext({ targetingKey: 'user' })
161
+ ).rejects.toThrow('fetch failed');
162
+ const replacement = evaluator();
163
+ client.__ddSetOfflineEvaluator(() => replacement);
164
+ expect(replacement.reconcile).toHaveBeenLastCalledWith(
165
+ undefined,
166
+ undefined
167
+ );
168
+ });
169
+ });
170
+
171
+ describe('offline evaluator tracking', () => {
172
+ it('tracks only successful delegate results, using the flag and context the delegate selected', () => {
173
+ const client = DdFlags.getClient('delegate-tracking');
174
+ const flag = {
175
+ key: 'flag',
176
+ value: true,
177
+ allocationKey: 'allocation',
178
+ variationKey: 'on',
179
+ variationType: 'boolean',
180
+ variationValue: 'true',
181
+ reason: 'TARGETING_MATCH',
182
+ doLog: true,
183
+ extraLogging: {},
184
+ serialId: '7'
185
+ };
186
+ const context = {
187
+ targetingKey: 'user',
188
+ attributes: { country: 'US' }
189
+ };
190
+ let errorCode: 'TYPE_MISMATCH' | undefined = 'TYPE_MISMATCH';
191
+ client.__ddSetOfflineEvaluator(() => ({
192
+ reconcile: () => ({ status: 'ready' as const }),
193
+ evaluate: <T>(key: string, defaultValue: T) => ({
194
+ details: {
195
+ key,
196
+ value: defaultValue,
197
+ reason: errorCode ? 'ERROR' : 'TARGETING_MATCH',
198
+ errorCode
199
+ },
200
+ exposure: { flag, context }
201
+ })
202
+ }));
203
+ expect(client.getBooleanDetails('flag', false).errorCode).toBe(
204
+ 'TYPE_MISMATCH'
205
+ );
206
+ expect(
207
+ NativeModules.DdFlags.trackEvaluation
208
+ ).not.toHaveBeenCalled();
209
+ errorCode = undefined;
210
+ client.getBooleanDetails('flag', false);
211
+ expect(NativeModules.DdFlags.trackEvaluation).toHaveBeenCalledWith(
212
+ 'delegate-tracking',
213
+ 'flag',
214
+ flag,
215
+ 'user',
216
+ {
217
+ country: 'US'
218
+ }
219
+ );
220
+ });
221
+ });
222
+
85
223
  describe('setEvaluationContext', () => {
86
224
  it('should set the evaluation context', async () => {
87
225
  const flagsClient = DdFlags.getClient();
@@ -191,6 +329,35 @@ describe('FlagsClient', () => {
191
329
  });
192
330
  });
193
331
 
332
+ it('returns the flag details when native tracking throws synchronously', async () => {
333
+ const flagsClient = DdFlags.getClient();
334
+ await flagsClient.setEvaluationContext({
335
+ targetingKey: 'test-user-1',
336
+ attributes: { country: 'US' }
337
+ });
338
+ jest.spyOn(
339
+ NativeModules.DdFlags,
340
+ 'trackEvaluation'
341
+ ).mockImplementationOnce(() => {
342
+ throw new Error('native bridge unavailable');
343
+ });
344
+
345
+ const details = flagsClient.getBooleanDetails(
346
+ 'test-boolean-flag',
347
+ false
348
+ );
349
+
350
+ expect(details).toMatchObject({
351
+ value: true,
352
+ variant: 'true',
353
+ reason: 'STATIC'
354
+ });
355
+ expect(InternalLog.log).toHaveBeenCalledWith(
356
+ 'Error tracking flag evaluation: native bridge unavailable',
357
+ SdkVerbosity.WARN
358
+ );
359
+ });
360
+
194
361
  it('should return PROVIDER_NOT_READY if evaluation context is not set', () => {
195
362
  const flagsClient = DdFlags.getClient();
196
363
  // Skip `setEvaluationContext` call here.
@@ -152,9 +152,8 @@ const toFlagCacheEntry = (
152
152
  return null;
153
153
  }
154
154
 
155
- // `serialId` is intentionally not propagated: `FlagCacheEntry` has no slot for it
156
- // and the native CDN-fetched snapshot omits it too, so dropping it keeps
157
- // offline/online parity.
155
+ // The released decoder's payload omits serialId. The OpenFeature offline adapter adds it from
156
+ // the evaluator's metadata, for both precomputed and rules flags.
158
157
  return {
159
158
  key,
160
159
  value: variationValue,