User action instrumentation

• Latest Dynatrace
• How-to guide
• Published Jul 10, 2026

A user action represents a significant operation within your app—it groups the requests, navigations, and errors that result from a single user interaction into one event. For a full conceptual overview of how user actions start, end, and what data they capture, see User actions. The sections below cover only React Native specific instrumentation details.

Automatic instrumentation

Automatic user actions are caused by User interactions with an action handler.

User action names

The general naming pattern is described in User actions. On React Native, the two parts of the name are resolved as follows:

Screen name: The current react-navigation route where the touch occurred, for example, /Home. If you set a custom view name via the API, that name is used instead.

Element name: The text content of the tapped element, for example, Checkout. For non-text elements, the accessibilityLabel property is used if set; otherwise, the component name is used. You can also override the name with the dtActionName property.

touch on Checkout on /Home

Action handler examples

An action handler is the app code bound to a User interaction that implements the behavior triggered by that interaction. Only user interactions that have an action handler attached can produce a user action.

React Native: The logic is executed in an onPress or onLongPress handler.

For a detailed explanation of action handlers, see User interactions.

Configure automatic instrumentation

Use Dynatrace.setAutomaticUserActionDetection(boolean) to enable or disable automatic user action detection at runtime. Automatic detection is enabled by default.

When you disable automatic detection, user interactions no longer trigger automatic user action creation. Manual user actions created with createUserAction are not affected.

Dynatrace.setAutomaticUserActionDetection(false)

Manual instrumentation

User actions triggered by the API let you track custom workflows that the agent cannot instrument automatically, such as multi-step business processes, background tasks, or interactions that span multiple screens.

Create a user action

Use Dynatrace.createUserAction(UserActionConfiguration) to start a user action triggered by the API. Pass a UserActionConfiguration with a custom name that describes the workflow you are tracking. Call complete() when the workflow finishes.

createUserAction always returns a user action, and invalid usage (for example, providing an empty custom name) is handled silently.

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

const userAction = Dynatrace.createUserAction(
    new UserActionConfiguration('Checkout Process')
)

// ... perform the workflow ...

userAction.complete()

Automatic completion

By default, you must call complete() explicitly. If your workflow triggers web requests and you want the user action to close automatically once all in-flight requests finish, pass true as the second argument to UserActionConfiguration.

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

const userAction = Dynatrace.createUserAction(
    new UserActionConfiguration('Checkout Process', true)
)

// The user action closes on its own once pending requests finish.
// You can still call complete() to close it earlier.

You can also change this behavior at any point during the user action's lifetime with setCompleteAutomatically(boolean).

Add event properties

Use addEventProperty to attach custom data to the user action. Property keys must be prefixed with event_properties.. Properties added after complete() is called are silently ignored.

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

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

const userAction = Dynatrace.createUserAction(
    new UserActionConfiguration('Checkout Process')
)

userAction.addEventProperty('event_properties.payment_method', 'credit_card')
userAction.addEventProperty('event_properties.cart_value', 149.99)
userAction.addEventProperty('event_properties.item_count', 3)

// ... perform the workflow ...

userAction.complete()

Example: E-commerce checkout flow

The following example tracks a checkout workflow as a single user action that spans multiple functions. The action is started in the button handler so that its start time matches the user's selection, kept as a module-level variable while the payment is processed, and closed—with outcome properties attached—in both the success and error paths.

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

let checkoutAction: UserAction | null = null

const completeCheckout = (orderId: string) => {
  checkoutAction?.addEventProperty("event_properties.order_id", orderId)
  checkoutAction?.addEventProperty("event_properties.checkout_successful", true)
  checkoutAction?.complete()
}

const cancelCheckout = (reason: string) => {
  checkoutAction?.addEventProperty("event_properties.checkout_successful", false)
  checkoutAction?.addEventProperty("event_properties.cancellation_reason", reason)
  checkoutAction?.complete()
}

const checkout = async (cart: Cart) => {
  checkoutAction = Dynatrace.createUserAction(new UserActionConfiguration('Checkout Process'))
  checkoutAction.addEventProperty("event_properties.cart_id", cart.id)
  checkoutAction.addEventProperty("event_properties.cart_count", cart.items.size)
  checkoutAction.addEventProperty("event_properties.cart_total", cart.total)
  checkoutAction.addEventProperty("event_properties.currency", cart.currency)
  try {
    const result = await processPayment(cart)
    completeCheckout(result.orderId)
  } catch (error: unknown) {
    if (error instanceof Error) {
      cancelCheckout(error instanceof Error ? error.message : 'unknown_error')
    } else {
      cancelCheckout('Unknown error')
    }
  }
}

const checkoutButton = () => {
  return <Button title="Checkout" onPress={() => checkout(currentCart)} />
}