@dynatrace/rum-javascript-sdk 1.333.15 → 1.335.1

package/docs/1-overview.md

@@ -18,6 +18,7 @@ This package provides two main API approaches for interacting with the Dynatrace
 - **Synchronous API**: Safe wrapper functions that gracefully handle cases where the RUM JavaScript is not available
 - **Asynchronous API**: Promise-based functions that wait for the RUM JavaScript to become available
 - **User Actions API**: Manual control over user action creation and lifecycle (see [User Actions API](./4-useractions.md))
+- **Interactions API**: Report custom user interaction events (see [Interactions API](./5-interactions.md))
 - **TypeScript Support**: Comprehensive type definitions for all RUM API functions
 - **Testing Framework**: Playwright-based utilities for testing RUM integration
 
@@ -195,6 +196,32 @@ const yourError = new Error("Your Error Message");
 sendExceptionEvent(yourError, { "event_properties.component": "myExampleComponent" });
 ```
 
+### Interactions API (`@dynatrace/rum-javascript-sdk/api/interactions`)
+
+#### `sendKeyPressEvent(fields, elementOrEvent?): void`
+
+Sends a user interaction event to report custom keyboard shortcuts or key combinations.
+Only available if the User Interaction module is enabled.
+
+**Parameters:**
+
+- `fields: SendUserInteractionFields` - Must be a JSON-serializable object with a `keys` array (at least one key).
+  Optional `ui_element.custom_name` and `event_properties.*` entries are allowed.
+- `elementOrEvent?: Element | KeyboardEvent` - Optional Element or KeyboardEvent to auto-capture UI element fields.
+
+**Example:**
+```typescript
+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"
+});
+```
+
+For detailed documentation and examples, see [Interactions API](./5-interactions.md).
+
 ### Asynchronous API (`@dynatrace/rum-javascript-sdk/promises`)
 
 The asynchronous API provides Promise-based functions that wait for the Dynatrace RUM JavaScript to become available. These functions will throw a `DynatraceError` if the RUM JavaScript is not available within the specified timeout. This is useful for scenarios where you don't want to
@@ -285,6 +312,20 @@ Only available if the Errors module is enabled.
 - `error: Error` - The error object to report. Must be an instance of the standard JavaScript `Error` class.
 - `fields: ApiCreatedEventPropertiesEvent` - Optional Event properties object. Must be serializable JSON with properties prefixed with `event_properties.`, plus optional `duration` and `start_time` properties.
 
+### Interactions API (`@dynatrace/rum-javascript-sdk/api/promises/interactions`)
+
+#### `sendKeyPressEvent(fields, elementOrEvent?, timeout?): Promise<void>`
+
+Async wrapper for sending a user interaction event, with automatic waiting for RUM JavaScript availability.
+Only available if the User Interaction module is enabled.
+
+**Parameters:**
+
+- `fields: SendUserInteractionFields` - Must be a JSON-serializable object with a `keys` array (at least one key).
+  Optional `ui_element.custom_name` and `event_properties.*` entries are allowed.
+- `elementOrEvent?: Element | KeyboardEvent` - Optional Element or KeyboardEvent to auto-capture UI element fields.
+- `timeout?: number` - Timeout in milliseconds to wait for RUM JavaScript (default: 10,000)
+
 ### User Actions API
 
 Both synchronous and asynchronous wrappers are available for the User Actions API. For detailed documentation and examples, see [User Actions API](./4-useractions.md).

package/docs/2-testing.md

@@ -372,10 +372,10 @@ The snapshot files contain JSON-formatted event data with ignored fields replace
 
 #### Updating Snapshots
 
-To update snapshots when event structures change intentionally, run Playwright with the `--update-snapshots` flag:
+To update snapshots when event structures change intentionally, run Playwright with the `--update-snapshots=all` flag:
 
 ```bash
-npx playwright test --update-snapshots
+npx playwright test --update-snapshots=all
 ```
 
 #### Default Ignored Fields
@@ -417,7 +417,7 @@ When a snapshot comparison fails, the error message includes:
 3. Instructions for updating the snapshot
 
 Common causes of snapshot failures:
-- **New fields added to events**: Update the snapshot with `--update-snapshots`
+- **New fields added to events**: Update the snapshot with `--update-snapshots=all`
 - **Volatile field values**: Add the field to `ignoredFields` to replace values with `[IGNORED]`
 - **Varying field presence**: Add the field to `removedFields` (use `fieldname.*` wildcard to remove all fields with that prefix)
 - **Unwanted events**: Add an event pattern to `ignoreEvents` to filter them out

package/docs/3-types.md

@@ -48,3 +48,4 @@ if (window.dynatrace) {
 ```
 
 Refer to the [User Actions API](./4-useractions.md) for details about `dynatrace.userActions`.
+Refer to the [Interactions API](./5-interactions.md) for details about `dynatrace.interactions`.

package/docs/4-useractions.md

@@ -136,7 +136,7 @@ By default, user actions are automatically closed when Dynatrace detects that th
 :::caution
 Calling `finish()` is reliable in this case because `performSomeWork()` is synchronous. If it was awaited, there is no
 guarantee that the action would still be open when `finish()` is called, leading to unreliable action durations. See
-(User action with manual control)[#user-action-with-manual-control] below.
+[User action with manual control](#user-action-with-manual-control) below.
 :::
 
 ### User action with manual control

package/docs/5-interactions.md

@@ -0,0 +1,60 @@
+---
+title: Interactions API
+---
+# 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](./1-overview.md):
+
+### Direct API (via `dynatrace.interactions`)
+
+```typescript
+dynatrace?.interactions?.sendKeyPressEvent({
+    keys: ["A"]
+});
+```
+
+### Safe Wrapper API (recommended)
+
+```typescript
+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"
+});
+```
+
+### Async API
+
+```typescript
+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"]
+});
+```
+
+## sendKeyPressEvent
+
+`sendKeyPressEvent(fields, elementOrEvent?)` reports a custom key_press interaction.
+
+- `fields` must be a JSON-serializable object with a non-empty `keys` array.
+- Use `UserInteractionSpecialKey` enum values for modifier and special keys (ctrl, cmd, shift, alt, esc, enter, tab, space).
+- Optional `ui_element.custom_name` and `event_properties.*` entries are allowed.
+- `elementOrEvent` may be an [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) or [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent) to derive UI element fields. If omitted, no UI element fields are added.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynatrace/rum-javascript-sdk",
-  "version": "1.333.15",
+  "version": "1.335.1",
   "description": "JavaScript API for Real User Monitoring (RUM)",
   "sideEffects": false,
   "type": "module",
@@ -13,12 +13,18 @@
       "api/user-actions": [
         "./dist/api/user-actions.d.ts"
       ],
+      "api/interactions": [
+        "./dist/api/interactions.d.ts"
+      ],
       "api/promises": [
         "./dist/api/promises/index.d.ts"
       ],
       "api/promises/user-actions": [
         "./dist/api/promises/user-actions.d.ts"
       ],
+      "api/promises/interactions": [
+        "./dist/api/promises/interactions.d.ts"
+      ],
       "test": [
         "./dist/testing/index.d.ts"
       ],
@@ -63,11 +69,21 @@
       "import": "./dist/api/user-actions.js",
       "default": "./dist/api/user-actions.js"
     },
+    "./api/interactions": {
+      "types": "./dist/api/interactions.d.ts",
+      "import": "./dist/api/interactions.js",
+      "default": "./dist/api/interactions.js"
+    },
     "./api/promises/user-actions": {
       "types": "./dist/api/promises/user-actions.d.ts",
       "import": "./dist/api/promises/user-actions.js",
       "default": "./dist/api/promises/user-actions.js"
     },
+    "./api/promises/interactions": {
+      "types": "./dist/api/promises/interactions.d.ts",
+      "import": "./dist/api/promises/interactions.js",
+      "default": "./dist/api/promises/interactions.js"
+    },
     "./api/promises": {
       "types": "./dist/api/promises/index.d.ts",
       "import": "./dist/api/promises/index.js",
@@ -134,8 +150,8 @@
     "@vitest/coverage-v8": "4.1.0-beta.1",
     "@vitest/ui": "4.1.0-beta.1",
     "eslint": "9.38.0",
-    "jsdom": "27.0.1",
-    "knip": "5.27.0",
+    "jsdom": "28.0.0",
+    "knip": "5.85.0",
     "typedoc": "0.28.10",
     "typedoc-plugin-mdn-links": "5.0.3",
     "typescript": "5.8.2",