Interactions API

This guide explains how to report custom interaction events that are not automatically detected.

What you can do

• Report custom keyboard shortcuts or key combinations via sendKeyPressEvent
• Attach ui_element.custom_name and event_properties.* fields
• Provide an Element or KeyboardEvent to capture UI element fields

Prerequisites

• New RUM Experience is enabled for your application

API approaches

You can use the Interactions API directly, or via its synchronous or asynchronous SDK functions, matching the pattern established in the RUM JavaScript SDK Overview:

Direct API (via dynatrace.interactions)

Access the API directly through the global dynatrace.interactions namespace:

dynatrace?.interactions?.sendKeyPressEvent({
    keys: ["A"]
});
Copy

Safe Wrapper API (recommended)

Use the safe wrapper from SDK.interactions (@dynatrace/rum-javascript-sdk/api/interactions):

import * as interactions from "@dynatrace/rum-javascript-sdk/api/interactions";
import { UserInteractionSpecialKey } from "@dynatrace/rum-javascript-sdk/types/rum-events";

interactions.sendKeyPressEvent({
    keys: [UserInteractionSpecialKey.CTRL, "S"],
    "event_properties.context": "editor"
});
Copy

Async API

Use the promise-based wrapper from SDK.promises.interactions (@dynatrace/rum-javascript-sdk/api/promises/interactions):

import { sendKeyPressEvent } from "@dynatrace/rum-javascript-sdk/api/promises/interactions";
import { UserInteractionSpecialKey } from "@dynatrace/rum-javascript-sdk/types/rum-events";

await sendKeyPressEvent({
    keys: [UserInteractionSpecialKey.CTRL, "S"]
});
Copy

UserInteractionSpecialKey

The Types.UserInteractionSpecialKey enum provides normalized string representations for specific KeyboardEvent.key values (e.g. " " → "space", "Control" → "ctrl", "Escape" → "esc", "ArrowUp" → "arrow_up").

Using this enum is optional — raw KeyboardEvent.key values are also accepted and normalized internally. The enum is a convenience for readability, especially when constructing key arrays manually without a real keyboard event.

import { UserInteractionSpecialKey } from "@dynatrace/rum-javascript-sdk/types/rum-events";

// Modifier + regular key
dynatrace.interactions?.sendKeyPressEvent({
    keys: [UserInteractionSpecialKey.CTRL, "S"]
});

// Single special key
dynatrace.interactions?.sendKeyPressEvent({
    keys: [UserInteractionSpecialKey.ESC]
});

// Regular key (passed as its KeyboardEvent.key value)
dynatrace.interactions?.sendKeyPressEvent({
    keys: ["a"]
});
Copy

sendKeyPressEvent

See the Interactions API reference for full parameter details. The function accepts a API.SendUserInteractionFields object with a non-empty keys array, and an optional Element or KeyboardEvent to derive UI element fields.

Safe wrapper: SDK.interactions • Async wrapper: SDK.promises.interactions