@dynatrace/react-native-plugin 2.335.1 → 2.337.2

package/types.d.ts

@@ -516,6 +516,24 @@ declare enum LogLevel {
     Info = 1
 }
 
+/**
+ * Interface which is containing the additional properties available for instrumentation.
+ */
+interface IDynatraceProperties {
+    /**
+     * This string is changing the name of the action. So it is possible to override the action naming.
+     */
+    dtActionName?: string;
+    /**
+     * If true is passed the auto instrumentation will skip the action creation. We allow both string
+     * and boolean.
+     */
+    dtActionIgnore?: boolean | 'true' | 'false';
+}
+
+type ActionNamePreference = 'any' | 'text' | 'icon';
+type ActionNameAlgorithm = 'depth-first' | 'breadth-first';
+
 /**
  * Configuration interface for Dynatrace agent startup.
  * Use this interface when configuring the agent programmatically instead of using auto-startup.
@@ -588,6 +606,26 @@ interface IConfiguration {
      * Defaults to `false` if not specified.
      */
     readonly actionNamePrivacy: boolean;
+    /**
+     * Controls which type of child element is preferred when searching the component tree for the
+     * name of an `onPress` action.
+     *
+     * - `'text'`: Prefers text content and falls back to any match.
+     * - `'icon'`: Prefers `ReactNative.Image` or custom Icons and falls back to any match.
+     * - `'any'`: Accepts the first match regardless of type (text, image, or icon).
+     *
+     * Defaults to `'any'` if not specified.
+     */
+    readonly actionNamePreference: ActionNamePreference;
+    /**
+     * Controls the traversal algorithm used when searching the component tree for the name of an `onPress` action.
+     *
+     * - `'depth-first'`: Follows the first child branch fully before trying siblings.
+     * - `'breadth-first'`: Visits all siblings at a level before going deeper, returning the shallowest match first.
+     *
+     * Defaults to `'depth-first'` if not specified.
+     */
+    readonly actionNameAlgorithm: ActionNameAlgorithm;
     /**
      * The bundle name used as a prefix for internal action IDs. Optional.
      */
@@ -651,6 +689,12 @@ interface IEventModifier {
  */
 type EventProperty = string | number | boolean;
 
+type TraceparentHeader = `${string}-${string}-${string}-${string}`;
+interface TraceContext {
+    traceparent: TraceparentHeader;
+    tracestate: string;
+}
+
 /**
  * Base interface for all events.
  */
@@ -800,7 +844,7 @@ interface IHttpRequestEventData extends IBaseEvent {
      *
      * @see https://docs.dynatrace.com/docs/shortlink/react-native-web-request-performance#manual-http-request-reporting
      */
-    withTraceparentHeader(traceparentHeader: TraceparentHeader): this;
+    withTraceparentHeader(traceparentHeader: TraceparentHeader | undefined): this;
     /**
      * Adds a custom event property to the request event.
      * @param key The property key. See property requirements below.
@@ -832,7 +876,6 @@ interface IHttpRequestEventData extends IBaseEvent {
     addEventProperty(key: `event_properties.${string}`, value: EventProperty): this;
 }
 
-type TraceparentHeader = `00-${string}-${string}-0${'0' | '1'}`;
 type AllowedRequestMethods = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH' | 'get' | 'head' | 'post' | 'put' | 'delete' | 'connect' | 'options' | 'trace' | 'patch';
 type Url = `http://${string}` | `https://${string}`;
 type EventPropertyKey = `event_properties.${string}`;
@@ -875,9 +918,10 @@ declare class HttpRequestEventData implements IHttpRequestEventData {
     withError(error: Error): this;
     withBytesSent(bytesSent: number): this;
     withBytesReceived(bytesReceived: number): this;
-    withTraceparentHeader(traceparentHeader: TraceparentHeader): this;
+    withTraceparentHeader(traceparentHeader: TraceparentHeader | undefined): this;
     addEventProperty(key: EventPropertyKey, value: EventProperty): this;
     toJSON(): JSONObject | null;
+    private getTraceContextHint;
     private hasValidMandatoryAttributes;
     private isInvalidUrl;
     private sanitizeStatusCode;
@@ -885,8 +929,6 @@ declare class HttpRequestEventData implements IHttpRequestEventData {
     private sanitizeBytesSent;
     private sanitizeBytesReceived;
     private isStatusCodeError;
-    private parseTraceparent;
-    private allZeros;
 }
 
 /**
@@ -1220,26 +1262,92 @@ interface IDynatrace$1 {
     /**
      * Sends an HTTP request event for network activity monitoring.
      *
-     * @param {HttpRequestEventData} httpRequestEvent Event object containing the HTTP request details
+     * @param {HttpRequestEventData} httpRequestEvent Event object containing the HTTP request details.
+     *
+     * The {@link HttpRequestEventData} class supports the following builder methods:
+     * - `withDuration(duration)` — Override the request duration in milliseconds.
+     * - `withStatusCode(statusCode)` — Set the HTTP response status code.
+     * - `withReasonPhrase(reasonPhrase)` — Set the HTTP response reason phrase.
+     * - `withError(error)` — Attach an `Error` object for failed requests.
+     * - `withBytesSent(bytesSent)` — Set the number of bytes sent in the request body.
+     * - `withBytesReceived(bytesReceived)` — Set the number of bytes received in the response body.
+     * - `withTraceparentHeader(traceparentHeader)` — Attach a W3C traceparent header for distributed tracing.
+     * - `addEventProperty(key, value)` — Add a custom event property (key must start with `event_properties.`).
      *
      * @example
      * ```ts
      * import { Dynatrace, HttpRequestEventData } from '@dynatrace/react-native-plugin';
      *
-     * // Basic HTTP request event
-     * const requestEvent = new HttpRequestEventData('https://api.example.com/users', 'GET');
-     * Dynatrace.sendHttpRequestEvent(requestEvent);
+     * const traceContext = Dynatrace.generateTraceContext();
+     * const body = JSON.stringify({ query: 'search term' });
+     *
+     * try {
+     *   const response = await fetch('https://api.example.com/data', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json', ...traceContext },
+     *     body,
+     *   });
+     *
+     *   const responseBody = await response.text();
      *
-     * // HTTP request with additional details
-     * const detailedRequest = new HttpRequestEventData('https://api.example.com/data', 'POST')
-     *   .withStatusCode(200)
-     *   .addEventProperty('event_properties.headers.content_type', 'application/json');
-     * Dynatrace.sendHttpRequestEvent(detailedRequest);
+     *   const requestEvent = new HttpRequestEventData('https://api.example.com/data', 'POST')
+     *     .withStatusCode(response.status)
+     *     .withReasonPhrase(response.statusText)
+     *     .withDuration(340)
+     *     .withBytesSent(new Blob([body]).size)
+     *     .withBytesReceived(new Blob([responseBody]).size)
+     *     .withTraceparentHeader(traceContext?.traceparent)
+     *     .addEventProperty('event_properties.endpoint', '/data')
+     *     .addEventProperty('event_properties.payload_type', 'json');
+     *
+     *   Dynatrace.sendHttpRequestEvent(requestEvent);
+     * } catch (error) {
+     *   const requestEvent = new HttpRequestEventData('https://api.example.com/data', 'POST')
+     *     .withError(error instanceof Error ? error : new Error(String(error)))
+     *     .withTraceparentHeader(traceContext?.traceparent)
+     *     .addEventProperty('event_properties.endpoint', '/data')
+     *     .addEventProperty('event_properties.payload_type', 'json');
+     *
+     *   Dynatrace.sendHttpRequestEvent(requestEvent);
+     * }
      * ```
      *
      * @see https://docs.dynatrace.com/docs/shortlink/react-native-web-request-performance#manual-http-request-reporting
      */
     sendHttpRequestEvent(httpRequestEvent: HttpRequestEventData): void;
+    /**
+     * Generates a W3C trace context for distributed tracing.
+     *
+     * Creates a {@link TraceContext} containing traceparent and tracestate headers
+     * for distributed tracing. If existing headers are provided, they will be
+     * reused according to the W3C Trace Context specification.
+     *
+     * @param traceparent Optional existing W3C traceparent header value.
+     * @param tracestate Optional existing W3C tracestate header value.
+     * @returns A {@link TraceContext} with traceparent and tracestate values, or `undefined` if:
+     * - The agent is not started
+     * - The agent configuration is not yet available
+     *
+     * @example
+     * ```ts
+     * import { Dynatrace } from '@dynatrace/react-native-plugin';
+     *
+     * // Generate new trace context
+     * const traceContext = Dynatrace.generateTraceContext();
+     *
+     * const response = await fetch('https://api.example.com/data', {
+     *   headers: {
+     *     ...traceContext,
+     *   },
+     * });
+     *
+     * // Or reuse existing trace context from an incoming request
+     * // const existingTraceparent = req.headers['traceparent'];
+     * // const existingTracestate = req.headers['tracestate'];
+     * // const traceContext = Dynatrace.generateTraceContext(existingTraceparent, existingTracestate);
+     * ```
+     */
+    generateTraceContext(traceparent?: TraceparentHeader, tracestate?: string): TraceContext | undefined;
 }
 
 /**
@@ -1706,6 +1814,8 @@ declare class ManualStartupConfiguration implements IConfiguration {
     readonly logLevel: LogLevel;
     readonly lifecycleUpdate: boolean;
     readonly actionNamePrivacy: boolean;
+    readonly actionNamePreference: ActionNamePreference;
+    readonly actionNameAlgorithm: ActionNameAlgorithm;
     readonly bundleName?: string;
     readonly errorHandler: boolean;
     readonly reportFatalErrorAsCrash: boolean;
@@ -1727,7 +1837,7 @@ declare class ManualStartupConfiguration implements IConfiguration {
      *
      * @deprecated Use ConfigurationBuilder and IConfiguration instead
      */
-    constructor(beaconUrl: string, applicationId: string, reportCrash?: boolean, logLevel?: LogLevel, lifecycleUpdate?: boolean, userOptIn?: boolean, actionNamePrivacy?: boolean, bundleName?: string, bundleVersion?: string);
+    constructor(beaconUrl: string, applicationId: string, reportCrash?: boolean, logLevel?: LogLevel, lifecycleUpdate?: boolean, userOptIn?: boolean, actionNamePrivacy?: boolean, actionNamePreference?: ActionNamePreference, actionNameAlgorithm?: ActionNameAlgorithm, bundleName?: string, bundleVersion?: string);
     toString(): string;
 }
 
@@ -1744,6 +1854,8 @@ declare class ConfigurationBuilder {
     private lifecycleUpdate;
     private userOptIn;
     private actionNamePrivacy;
+    private actionNamePreference;
+    private actionNameAlgorithm;
     private bundleName;
     private bundleVersion;
     private autoStartup;
@@ -1781,7 +1893,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withCrashReporting(reportCrash: boolean): ConfigurationBuilder;
+    withCrashReporting(reportCrash: boolean): this;
     /**
      * Configures the React Native error handler. Defaults to `true`.
      *
@@ -1799,7 +1911,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withErrorHandler(errorHandler: boolean): ConfigurationBuilder;
+    withErrorHandler(errorHandler: boolean): this;
     /**
      * Configures how fatal errors are reported. Defaults to `true`.
      *
@@ -1818,7 +1930,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withReportFatalErrorAsCrash(reportFatalErrorAsCrash: boolean): ConfigurationBuilder;
+    withReportFatalErrorAsCrash(reportFatalErrorAsCrash: boolean): this;
     /**
      * Configures the log level for the Dynatrace plugin. Defaults to `LogLevel.Info`.
      *
@@ -1837,7 +1949,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withLogLevel(logLevel: LogLevel): ConfigurationBuilder;
+    withLogLevel(logLevel: LogLevel): this;
     /**
      * Configures tracking of component update cycles in lifecycle actions. Defaults to `false`.
      *
@@ -1856,7 +1968,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withLifecycleUpdate(lifecycleUpdate: boolean): ConfigurationBuilder;
+    withLifecycleUpdate(lifecycleUpdate: boolean): this;
     /**
      * Configures privacy mode and user opt-in. Defaults to `false`.
      *
@@ -1875,7 +1987,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withUserOptIn(userOptIn: boolean): ConfigurationBuilder;
+    withUserOptIn(userOptIn: boolean): this;
     /**
      * Configures action name privacy for Touchables and Buttons. Defaults to `false`.
      *
@@ -1895,7 +2007,49 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withActionNamePrivacy(actionNamePrivacy: boolean): ConfigurationBuilder;
+    withActionNamePrivacy(actionNamePrivacy: boolean): this;
+    /**
+     * Configures the preferred child element type for resolving `onPress` action names. Defaults to `'any'`.
+     *
+     * @param {ActionNamePreference} actionNamePreference The preferred child element type.
+     * - `'text'`: Prefers text content and falls back to any match.
+     * - `'icon'`: Prefers `ReactNative.Image` or custom Icons and falls back to any match.
+     * - `'any'`: Accepts the first match regardless of type (text, image, or icon).
+     * @returns {ConfigurationBuilder} The builder instance for method chaining
+     *
+     * @example
+     * ```ts
+     * import { ConfigurationBuilder, Dynatrace } from '@dynatrace/react-native-plugin';
+     *
+     * const config = new ConfigurationBuilder('beaconUrl', 'applicationId')
+     *   .withActionNamePreference('text'); // Prioritize text labels for action names
+     * await Dynatrace.start(config.buildConfiguration());
+     * ```
+     *
+     * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#how-does-dynatrace-determine-the-user-action-name
+     */
+    withActionNamePreference(actionNamePreference: ActionNamePreference): this;
+    /**
+     * Configures the traversal algorithm for searching the component tree for `onPress` action names.
+     * Defaults to `'depth-first'`.
+     *
+     * @param {ActionNameAlgorithm} actionNameAlgorithm The traversal algorithm to use.
+     * - `'depth-first'`: Follows the first child branch fully before trying siblings.
+     * - `'breadth-first'`: Visits all siblings at a level before going deeper, returning the shallowest match first.
+     * @returns {ConfigurationBuilder} The builder instance for method chaining
+     *
+     * @example
+     * ```ts
+     * import { ConfigurationBuilder, Dynatrace } from '@dynatrace/react-native-plugin';
+     *
+     * const config = new ConfigurationBuilder('beaconUrl', 'applicationId')
+     *   .withActionNameAlgorithm('breadth-first'); // Prioritize shallowest matches in the component tree
+     * await Dynatrace.start(config.buildConfiguration());
+     * ```
+     *
+     * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#how-does-dynatrace-determine-the-user-action-name
+     */
+    withActionNameAlgorithm(actionNameAlgorithm: ActionNameAlgorithm): this;
     /**
      * Configures the bundle name used as a prefix for internal action IDs.
      *
@@ -1913,7 +2067,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withBundleName(bundleName: string): ConfigurationBuilder;
+    withBundleName(bundleName: string): this;
     /**
      * Configures the bundle version for events. This is mandatory for proper crash reporting.
      *
@@ -1932,7 +2086,7 @@ declare class ConfigurationBuilder {
      *
      * @see https://www.npmjs.com/package/@dynatrace/react-native-plugin#plugin-startup
      */
-    withBundleVersion(bundleVersion: string): ConfigurationBuilder;
+    withBundleVersion(bundleVersion: string): this;
     /**
      * Builds the configuration object for Dynatrace agent startup.
      *
@@ -2192,21 +2346,6 @@ declare class DynatraceWebRequestTiming implements IDynatraceWebRequestTiming {
     getRequestTagHeader(): string;
 }
 
-/**
- * Interface which is containing the additional properties available for instrumentation.
- */
-interface IDynatraceProperties {
-    /**
-     * This string is changing the name of the action. So it is possible to override the action naming.
-     */
-    dtActionName?: string;
-    /**
-     * If true is passed the auto instrumentation will skip the action creation. We allow both string
-     * and boolean.
-     */
-    dtActionIgnore?: boolean | 'true' | 'false';
-}
-
 declare module 'react' {
     namespace JSX {
         interface IntrinsicAttributes extends IDynatraceProperties {