Custom events

Latest Dynatrace
How-to guide
1-min read

The New RUM Experience introduces a set of advanced APIs that allow you to send custom events, modify event data, track exceptions, monitor HTTP requests, and manage view contexts in your React Native application. These APIs provide more granular control over the data captured by Dynatrace and are designed for the next generation RUM capabilities.

Event and session properties

Configure event and session properties

Before you can send event or session properties from your application, you must first define them in the Dynatrace web UI. Any properties that are not pre-configured will be discarded.

To define a new property

In Experience Vitals, select the frontend for which you want to add the property.
Select the Settings tab, then choose Event and session properties.
Select Add under either Defined event properties or Defined session properties, depending on the type of property you want to create.
In the Field name box, enter a name for your property (for example, cart.total_value).
Optional To make the field name case-insensitive, turn on Field name validation should be case-insensitive.
From the Datatype list, select the appropriate data type for your property: string, boolean, or number.

Dynatrace automatically prefixes your field name with event_properties. or session_properties. based on the property type you selected. For example, a field name of cart.total_value will become event_properties.cart.total_value.

Send custom events

Use sendEvent() to report custom events with properties using the EventData class. Property keys must be prefixed with event_properties..

import { Dynatrace, EventData } from '@dynatrace/react-native-plugin';

// Send a custom event with properties
Dynatrace.sendEvent(new EventData()
  .addEventProperty("event_properties.button_clicked", "login_button")
  .addEventProperty("event_properties.user_type", "premium")
  .addEventProperty("event_properties.attempt_count", 3)
  .withDuration(250)
);

Property requirements

For naming rules and general limits, see Event and session properties.

React Native specifics:

Maximum of 50 custom properties per event.
String properties are limited to 5000 characters (exceeding characters are truncated).
Values cannot contain functions, undefined, Infinity, or NaN (they're replaced with null).

Send session property events

For information on sending session properties, see User and session management.

Event modifiers

Event modifiers allow you to intercept and modify events before they're sent to Dynatrace. Use them to add common properties, filter sensitive data, or enrich events with additional context. Event modifiers apply to all event types, including custom events, session properties, exceptions, and HTTP events.

If multiple event modifiers are added, they are executed in the order they were added.

Add an event modifier

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';

// Create an event modifier
const myModifier: IEventModifier = {
  modifyEvent(event) {
    // Add common properties to all events
    event["event_properties.app_build"] = "1.2.3";
    event["event_properties.environment"] = "production";

    return event;
  }
};

// Add the modifier
Dynatrace.addEventModifier(myModifier);

Filter events

Return null to discard an event:

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';

const filterModifier: IEventModifier = {
  modifyEvent(event) {
    // Discard events from test users
    if (event["event_properties.is_test_user"] === true) {
      return null;
    }

    return event;
  }
};

Dynatrace.addEventModifier(filterModifier);

Redact sensitive data

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';

const redactionModifier: IEventModifier = {
  modifyEvent(event) {
    // Redact email addresses from custom properties
    if (event["event_properties.user_email"]) {
      event["event_properties.user_email"] = "[REDACTED]";
    }

    return event;
  }
};

Dynatrace.addEventModifier(redactionModifier);

Remove event modifiers

import { Dynatrace } from '@dynatrace/react-native-plugin';

// Remove the modifier when no longer needed
Dynatrace.removeEventModifier(myModifier);

Modifiers are executed in the order they were added
Returning null from a modifier discards the event and prevents subsequent modifiers from executing
Modifiers should be efficient as they're called for every event

Modifier limitations

Event modifiers have restrictions on which fields can be modified to ensure data integrity.

Modifiable fields

The following fields can be modified or added:

event_properties.*—event properties.
session_properties.*—session properties (only on session property events).
url.full—complete request URL.
exception.stack_trace—exception stack traces.

All other fields are read-only and can't be modified. The original values are preserved.

Important considerations

Thread safety—modifiers may be called from any thread; ensure your code is thread-safe.
Performance—keep modifiers efficient; they run for every event.

Modifier examples

Add feature flags

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';

const featureFlags = {
  checkout_v2: true,
  new_payment_flow: false,
  enhanced_search: true
};

const featureFlagModifier: IEventModifier = {
  modifyEvent(event) {
    for (const [key, value] of Object.entries(featureFlags)) {
      event[`event_properties.ff_${key}`] = value;
    }
    return event;
  }
};

Dynatrace.addEventModifier(featureFlagModifier);

Conditional event enrichment

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';

const enrichmentModifier: IEventModifier = {
  modifyEvent(event) {
    // Add experiment tracking to checkout events
    if (event["event_properties.checkout_step"]) {
      event["event_properties.experiment_id"] = "checkout_flow_v2";
      event["event_properties.variant"] = "treatment_a";
    }

    return event;
  }
};

Dynatrace.addEventModifier(enrichmentModifier);

Environment-specific enrichment

import { Dynatrace, IEventModifier } from '@dynatrace/react-native-plugin';
import { Platform } from 'react-native';

const environmentModifier: IEventModifier = {
  modifyEvent(event) {
    // Add environment context
    event["event_properties.build_type"] = __DEV__ ? "debug" : "release";
    event["event_properties.platform"] = Platform.OS;

    return event;
  }
};

Dynatrace.addEventModifier(environmentModifier);

Web request performance—HTTP event modifiers.
Error and crash reporting—exception events.
Configuration—agent configuration.