Merge pull request #312 from flashcatcloud/doc-review/20260825-react-native

docs(rum): correct React Native SDK guidance

Author: Fiona2016

en/rum/sdk/react-native/advanced-config.mdx

@@ -4,7 +4,7 @@ description: "Configure sampling, tracking consent, event filtering, distributed
 keywords: ["RUM", "React Native SDK", "advanced configuration", "sampling", "tracking consent", "source map", "native crash", "symbolication", "dSYM", "mapping"]
 ---
 
-This page covers the advanced options of the React Native SDK. All options are set as properties on a `DdSdkReactNativeConfiguration` instance before calling `DdSdkReactNative.initialize(config)`.
+This page covers the advanced options of the React Native SDK. All eight constructor arguments are read-only; arguments 7 and 8 are the less obvious `trackingConsent` and `useAccessibilityLabel` options. Set the remaining advanced options as instance properties. Complete all configuration before calling `DdSdkReactNative.initialize(config)`.
 
 ## Sampling
 
@@ -14,6 +14,8 @@ config.resourceTracingSamplingRate = 20; // Distributed tracing sampling rate on
 config.telemetrySampleRate = 20;         // SDK internal telemetry sampling rate, default 20
 ```
 
+All three sampling rates accept values from `0` to `100`. `0` samples nothing and `100` samples everything.
+
 ## Tracking consent
 
 `TrackingConsent` controls whether data is collected and reported, for compliance requirements such as GDPR:
@@ -30,6 +32,7 @@ const config = new DdSdkReactNativeConfiguration(
   '<CLIENT_TOKEN>', 'production', '<APPLICATION_ID>',
   true, true, true,
   TrackingConsent.PENDING,
+  false, // argument 8: do not use accessibilityLabel as the action name
 );
 
 // Update after the user grants consent
@@ -46,7 +49,11 @@ config.errorEventMapper = (event) => {
   event.message = event.message.replace(/token=[^&\s]+/g, 'token=***');
   return event;
 };
-config.resourceEventMapper = (event) => event; // statusCode, kind, size, and context can be modified
+config.resourceEventMapper = (event) => {
+  // Resources only allow context changes; return null to drop the event
+  event.context = { ...event.context, sanitized: true };
+  return event;
+};
 config.actionEventMapper = (event) => event;
 config.logEventMapper = (event) => event;
 ```
@@ -96,7 +103,41 @@ import { WebView } from '@flashcatcloud/mobile-react-native-webview';
 />
 ```
 
-`allowedHosts` is the list of hosts allowed to be associated; subdomains are matched. The page loaded in the WebView must already integrate the <a href="/en/rum/sdk/web/sdk-integration">Flashduty Browser SDK</a>. The component is fully compatible with the props of `react-native-webview`.
+`allowedHosts` is the list of hosts allowed to be associated; subdomains are matched. The page loaded in the WebView must already integrate the <a href="/en/rum/sdk/web/sdk-integration">Flashduty Browser SDK</a>.
+
+The component passes through most `react-native-webview` props, but it controls the following props to inject the RUM bridge:
+
+- `nativeConfig`
+- `onMessage`
+- `injectedJavaScript`
+- `injectedJavaScriptBeforeContentLoaded`
+
+You can still provide your own `onMessage` handler and injected scripts: the component forwards non-RUM messages to your handler and executes the scripts after wrapping them. A custom `nativeConfig` is overwritten. Set `logUserCodeErrors={true}` to record errors from injected user code as logs; it defaults to `false`. Because Logs currently works only on Android, these errors are not reported from iOS.
+
+```tsx
+<WebView
+  source={{ uri: 'https://myapp.example' }}
+  allowedHosts={['myapp.example']}
+  logUserCodeErrors={true}
+  onMessage={(event) => console.log(event.nativeEvent.data)}
+/>
+```
+
+## Reporting through a proxy
+
+`proxyConfig` supports HTTP, HTTPS, and SOCKS proxies. HTTP and HTTPS proxies support Basic Authentication. SOCKS proxies do not support a username or password; the SDK logs a warning and ignores credentials when you provide them.
+
+```typescript
+import { ProxyConfiguration, ProxyType } from '@flashcatcloud/mobile-react-native';
+
+config.proxyConfig = new ProxyConfiguration(
+  ProxyType.HTTPS,
+  'proxy.example.com',
+  8443,
+  'username',
+  'password',
+);
+```
 
 ## Source map upload
 
@@ -224,26 +265,32 @@ A dSYM is matched to crash events by the binary's **UUID**, and every release bu
 </Tabs>
 
 <Warning>
-**Upload symbol files for both platforms separately.** Symbol files are matched by service, and without an explicit `serviceName` Android falls back to the `applicationId` while iOS falls back to the bundle identifier — one app becomes two services in the console, and the Android mapping file is never applied to an iOS crash or vice versa. Set `serviceName` explicitly so both platforms agree, and upload from each platform's release pipeline.
+**Upload symbol files for both platforms separately.** Symbol files are matched by service, and without an explicit `serviceName` Android falls back to the `applicationId` while iOS falls back to the bundle identifier. If those platform identifiers differ, one app becomes two services in the console, and the Android mapping file is never applied to an iOS crash or vice versa. Set `serviceName` explicitly so both platforms agree, and upload from each platform's release pipeline.
 </Warning>
 
 ## Other options
 
 | Option | Default | Description |
 |------|--------|------|
-| `serviceName` | Platform default | **Strongly recommended.** When unset, Android uses `applicationId` and iOS the bundle identifier, splitting the app into two services |
+| `serviceName` | Platform default | **Recommended.** When unset, Android uses `applicationId` and iOS the bundle identifier; the app is split into two services when those identifiers differ |
 | `nativeCrashReportEnabled` | false | Whether to collect native crashes |
-| `version` / `versionSuffix` | App version | Override the reported version / append a suffix; must match the version used for source map upload |
+| `version` / `versionSuffix` | App version | Override the reported version / append a suffix; only letters, numbers, `_`, `-`, `:`, `.`, and `/` are preserved, other characters become `_`, and the SDK adds `-` before the suffix; the result must match the source map upload version |
 | `verbosity` | undefined | SDK internal log level (`SdkVerbosity.DEBUG` / `INFO` / `WARN` / `ERROR`); use it when troubleshooting the integration |
+| `nativeViewTracking` | false | Enable native view tracking for a custom navigation system based on native views |
+| `nativeInteractionTracking` | false | Collect user interactions on native screens |
 | `trackBackgroundEvents` | false | Whether to collect events while no view is active; enabling it increases the session count |
-| `vitalsUpdateFrequency` | `VitalsUpdateFrequency.AVERAGE` | Collection frequency of native mobile vitals; set to `NEVER` to disable |
-| `nativeLongTaskThresholdMs` | 200 | Native main-thread long task threshold in milliseconds; `0` or `false` disables it |
-| `longTaskThresholdMs` | 0 (disabled) | JS-thread long task threshold in milliseconds; set 100 to 5000 to enable |
+| `vitalsUpdateFrequency` | `VitalsUpdateFrequency.AVERAGE` | Native mobile vital frequency: `FREQUENT`, `AVERAGE`, `RARE`, or `NEVER` |
+| `nativeLongTaskThresholdMs` | 200 | Native main-thread long task threshold in milliseconds; `0` / `false` disables it, and enabled values are clamped to 100–5000 |
+| `longTaskThresholdMs` | 0 (disabled) | JS-thread long task threshold in milliseconds; `0` / `false` disables it, and enabled values are clamped to 100–5000 |
 | `trackFrustrations` | true | Whether to derive frustration signals (such as error taps) from user actions |
 | `actionNameAttribute` | undefined | Which component prop to use as the name of automatically collected actions (for example `testID`); `dd-action-name` takes precedence |
-| `useAccessibilityLabel` | true | Whether to use `accessibilityLabel` as the action name |
+| `useAccessibilityLabel` | true | Whether to use `accessibilityLabel` as the action name; read-only constructor argument 8 |
+| `bundleLogsWithRum` | true | Whether to correlate Android logs with the current RUM session; Logs is a no-op on iOS |
 | `trackNonFatalAnrs` | Platform default | Whether to collect non-fatal ANRs; disabled by default on Android 30+, enabled on Android 29 and below |
 | `appHangThreshold` | undefined | iOS App Hang threshold in seconds; unset means disabled |
+| `initialResourceThreshold` | 0.1 seconds | Time window after a view starts in which resources are included in Time to Network-Settled (TNS) |
 | `trackWatchdogTerminations` | false | Whether to collect iOS watchdog terminations |
-| `uploadFrequency` / `batchSize` / `batchProcessingLevel` | `AVERAGE` / `MEDIUM` / `MEDIUM` | Upload frequency, batch size, and batches per upload cycle; trade off freshness against battery |
-| `proxyConfig` | undefined | Report through an HTTP / SOCKS proxy |
+| `uploadFrequency` | `UploadFrequency.AVERAGE` | Upload frequency: `FREQUENT` (about 1 second), `AVERAGE` (about 5 seconds), or `RARE` (about 10 seconds) |
+| `batchSize` | `BatchSize.MEDIUM` | Amount of data per batch: `SMALL`, `MEDIUM`, or `LARGE` |
+| `batchProcessingLevel` | `BatchProcessingLevel.MEDIUM` | Batches processed per upload cycle: `LOW` (1), `MEDIUM` (10), or `HIGH` (100) |
+| `proxyConfig` | undefined | Report through an HTTP, HTTPS, or SOCKS proxy; SOCKS does not support Basic Authentication |

en/rum/sdk/react-native/compatible.mdx

@@ -58,7 +58,7 @@ JavaScript class names begin with `Dd*` (`DdSdkReactNative`, `DdSdkReactNativeCo
 | Logs | `DdLogs` only sends logs on Android; it is a no-op on iOS and sends nothing |
 | Static resources | Only requests issued from JavaScript are collected; images, fonts, and other resources loaded by the native networking stack such as `<Image>` are **not collected**, and the console does not show static-resource panels for React Native applications |
 | Resource type | Every collected request is recorded as `xhr`, regardless of the response Content-Type |
-| Android app launch time | No app launch vital on Android yet; iOS reports cold / warm launch time |
+| Android app launch time | The React Native Android bridge does not yet report launch events; iOS reports cold / warm launch time |
 | Platform scope | iOS / Android only; React Native Web is not supported |
 | Minimum version | `0.1.1` or later is recommended; in `0.1.0` the Android release build fails when `FLASHCAT_API_KEY` is missing |
 

en/rum/sdk/react-native/data-collection.mdx

@@ -24,7 +24,7 @@ Every event carries the following context (collected by the native layer):
 - **Device**: device model, OS and version, screen size
 - **Session**: `session.id`, sampled by `sessionSamplingRate`
 - **Connectivity**: network type (when available)
-- **User**: `usr.id` / `usr.name` / `usr.email` set through `DdSdkReactNative.setUser`
+- **User**: `usr.id` / `usr.name` / `usr.email` set through `DdSdkReactNative.setUserInfo`
 - **Global attributes**: custom fields set through `DdSdkReactNative.setAttributes`
 
 ## Network request collection boundary
@@ -48,7 +48,7 @@ The console shows a Performance page for React Native applications. Native vital
 
 | Metric | Android | iOS | Description |
 |------|---------|-----|------|
-| App launch time | Not yet | Cold / warm launch | Android does not report launch time yet; the corresponding console card shows "No data" |
+| App launch time | Not yet | Cold / warm launch | The React Native Android bridge does not yet report the launch event; the corresponding console card shows "No data" |
 | Refresh rate | Supported | Supported | Rendering frame rate of the native UI thread |
 | **JS-thread frame rate** | Supported | Supported | React Native-specific; reflects whether application JS code is janky; shown on the console's Performance page |
 | CPU | Supported | Supported | CPU usage during the view |
@@ -82,7 +82,8 @@ DdRum.startResource('req-1', 'GET', 'https://api.example.com/orders');
 DdRum.stopResource('req-1', 200, 'xhr');
 
 // Report an error manually
-DdRum.addError('payment failed', ErrorSource.SOURCE, stack);
+const error = new Error('payment failed');
+DdRum.addError(error.message, ErrorSource.SOURCE, error.stack ?? '');
 
 // Attach global attributes (written to all subsequent events)
 DdSdkReactNative.setAttributes({ tenant: 'acme' });
@@ -91,6 +92,24 @@ DdSdkReactNative.setAttributes({ tenant: 'acme' });
 DdRum.addTiming('first_order_rendered');
 ```
 
+### View loading, sessions, and feature flags
+
+Use these APIs to add view loading state, control session boundaries, and associate feature flag values with the current RUM session:
+
+```typescript
+// Record loading time from startView until now; true overwrites an existing value
+DdRum.addViewLoadingTime(false);
+
+// Returns undefined when the SDK is not initialized or no session is available
+const sessionId = await DdRum.getCurrentSessionId();
+
+// Associate the feature flag value actually used in this session
+DdRum.addFeatureFlagEvaluation('checkout_redesign', 'variant-a');
+
+// End the current session; the next RUM event starts a new session
+await DdRum.stopSession();
+```
+
 ## Sampling and controls
 
 | Option | Default | Description |

en/rum/sdk/react-native/sdk-integration.mdx

@@ -60,16 +60,16 @@ const config = new DdSdkReactNativeConfiguration(
   TrackingConsent.GRANTED,
 );
 config.site = 'CN';
-config.serviceName = 'com.example.shopping'; // Required: keeps Android and iOS under one service
+config.serviceName = 'com.example.shopping'; // Recommended: keeps Android and iOS under one service
 config.nativeCrashReportEnabled = true; // Collect native Android / iOS crashes
 config.sessionSamplingRate = 100;
 
 DdSdkReactNative.initialize(config);
 ```
 
-<Warning>
-**`serviceName` must be set explicitly.** Without it, Android defaults to the `applicationId` and iOS to the bundle identifier, so one application is split into two services in the console: the same error appears once per service in the issue list, and filters and source map matching are separated as well.
-</Warning>
+<Tip>
+**Set `serviceName` explicitly for cross-platform consistency.** Without it, Android defaults to the `applicationId` and iOS to the bundle identifier. If those platform identifiers differ, one application is split into two services, separating issue lists, filters, and source map matching.
+</Tip>
 
 <Warning>
 Do not use server-side secrets in client code. `clientToken` is only used for client-side RUM data reporting, and `applicationId` is used to attribute RUM application data.
@@ -111,16 +111,43 @@ function App() {
 }
 ```
 
-Only one `NavigationContainer` can be tracked at a time; call `DdRumReactNavigationTracking.stopTrackingViews()` before switching containers.
+Only one `NavigationContainer` can be tracked at a time. Pass the previous container reference when you stop tracking before switching containers:
+
+```typescript
+DdRumReactNavigationTracking.stopTrackingViews(navigationRef.current);
+```
+
+The second argument to `startTrackingViews` can rename views. Return `null` to ignore a route. To use this control, replace the call inside `onReady` above with this one:
+
+```typescript
+DdRumReactNavigationTracking.startTrackingViews(
+  navigationRef.current,
+  (route, trackedName) =>
+    route.name === 'InternalDebug' ? null : `mobile/${trackedName}`,
+);
+```
+
+<Note>
+Returning `null` only skips the new view; it does not stop the previous RUM view. Later events on the ignored screen may still be attributed to that previous view. Use manual view tracking when you need an explicit view boundary.
+</Note>
 </Tab>
 <Tab title="react-native-navigation (Wix)">
 Call once at application startup:
 
 ```typescript
 import { DdRumReactNativeNavigationTracking } from '@flashcatcloud/mobile-react-native-navigation';
 
-DdRumReactNativeNavigationTracking.startTracking();
+DdRumReactNativeNavigationTracking.startTracking(
+  (_event, trackedName) =>
+    trackedName === 'InternalDebug' ? null : `mobile/${trackedName}`,
+);
 ```
+
+Call `DdRumReactNativeNavigationTracking.stopTracking()` when automatic tracking is no longer needed.
+
+<Note>
+Returning `null` only skips the new view; it does not stop the previous RUM view. Later events on the ignored screen may still be attributed to that previous view. Use manual view tracking when you need an explicit view boundary.
+</Note>
 </Tab>
 <Tab title="Manual">
 If you use neither library, start and stop views manually:
@@ -168,7 +195,7 @@ To correlate frontend requests with backend traces, configure `firstPartyHosts`;
 After sign-in, set the current user. The SDK writes the user fields into the `usr` object of subsequent RUM events. Always pass `id`: iOS ignores calls without an `id`.
 
 ```typescript
-DdSdkReactNative.setUser({
+DdSdkReactNative.setUserInfo({
   id: 'user-1001',
   name: 'Alice',
   email: 'alice@example.com',