Custom events

Latest Dynatrace
How-to guide
1-min read
Published Jan 12, 2025

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

Allowed properties:

Properties prefixed with event_properties.*

Property limits:

Maximum of 50 custom properties per event.
String properties are limited to 5000 characters (exceeding characters are truncated).

Field naming rules:

Field names must contain only alphabetic characters, numbers, underscores, and dots.
Field name maximum length: 100 characters (including the event_properties. prefix).
Each dot must be followed by an alphabetic character.
Each underscore must be followed by an alphabetic character or number.
Values must be primitive types (string, number, boolean).
Cannot contain functions, undefined, Infinity, or NaN as values (they're replaced with null).

Valid examples:

event_properties.checkout_step
event_properties.cart_value
event_properties.user_tier

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.

Most fields and namespaces can't be modified in any way (added, removed or overridden), while others are open for modification.

Open for modification and can be added

event_properties.*—custom event properties.
session_properties.*—session properties (only on session property events).

Open for modification only

url.full—full URL for HTTP request events.
exception.stack_trace—stack trace for exception events.

Read-only fields

All other reserved fields and namespaces cannot be modified.

Attempting to modify read-only fields will have no effect. The original values are preserved.

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);

Important considerations

Execution order—if multiple event modifiers are added, they are executed in the order they were added.
Returning null—returning null discards the event and prevents future modifier functions from being executed.
Performance—event modifiers should be efficient as they are called for every event.
Field naming—fields added in modifiers must follow the property requirements defined in Send custom events for event_properties.* fields and Send session property events for session_properties.* fields, including naming rules, length limits, and allowed characters.
Reserved fields—certain reserved fields and namespaces cannot be modified. Attempts to modify them will be ignored.
Error handling—if a modifier throws an exception, it will be logged but won't prevent other modifiers from executing.

Configuration—agent configuration.