A JavaScript API for interacting with the Dynatrace Real User Monitoring (RUM) JavaScript. This package provides both synchronous and asynchronous wrappers for the Dynatrace RUM API, along with TypeScript support.
npm install @dynatrace/rum-javascript-sdk
This package provides two main API approaches for interacting with the Dynatrace RUM JavaScript, as well as types:
import { sendEvent, identifyUser } from '@dynatrace/rum-javascript-sdk/api';
// Send a custom event - safely handles cases where RUM JavaScript is not loaded
sendEvent({
'event_properties.component_name': 'UserProfile',
'event_properties.action': 'view'
});
// Identify the current user
identifyUser('user@example.com');
import { sendEvent, identifyUser } from '@dynatrace/rum-javascript-sdk/api/promises';
try {
// Wait for RUM JavaScript to be available (with 10s timeout by default)
await sendEvent({
'event_properties.component_name': 'UserProfile',
'event_properties.action': 'view'
});
await identifyUser('user@example.com');
} catch (error) {
console.error('RUM JavaScript not available:', error);
}
Use isEnabled() to check whether RUM JavaScript is currently active — reflecting the current opt-in mode
and consent state — before running code that only makes sense when monitoring is on.
The synchronous wrapper returns false when RUM JavaScript is not available.
import { isEnabled } from '@dynatrace/rum-javascript-sdk/api';
// Skip expensive instrumentation setup when monitoring is off
if (isEnabled()) {
runExpensiveProfilingSetup();
}
@dynatrace/rum-javascript-sdk/api)The synchronous API provides safe wrapper functions that gracefully handle cases where the Dynatrace RUM JavaScript is not available. These functions execute as no-ops if the JavaScript is not loaded, making them safe to use in any environment.
See the SDK API reference for the full list of available functions.
@dynatrace/rum-javascript-sdk/api/interactions)Report custom user interaction events via API.Interactions. See Interactions API for detailed documentation and examples.
@dynatrace/rum-javascript-sdk/api/promises)The SDK.promises namespace provides Promise-based functions that wait for the Dynatrace RUM JavaScript to become available. These functions throw a SDK.DynatraceError if the RUM JavaScript is not available within the specified timeout. This is useful for scenarios where you don't want to enable the RUM JavaScript before the user gives their consent.
Each function mirrors its synchronous counterpart with an additional timeout parameter (default: SDK.promises.DEFAULT_AGENT_TIMEOUT).
Manual control over user action creation and lifecycle via API.UserActions. Both synchronous and asynchronous wrappers are available. See User Actions API for detailed documentation and examples.
The SDK.DynatraceError class is thrown by the asynchronous API when the RUM JavaScript is not available within the specified timeout.
The on-page RUM JavaScript agent publishes a public API version via the dynatrace.apiVersion property. The SDK reads this value to detect when it is out of sync with the agent:
Legacy agents that predate API versioning expose apiVersion as undefined. They are treated as fully compatible and behave exactly as before.
Known versions (an apiVersion the SDK recognizes) are used as-is.
Newer-than-SDK agents (an apiVersion higher than the SDK knows about) still work, but the SDK emits a one-time console warning so you know some newer features may not be available:
RUM JavaScript agent API version <N> is newer than the maximum supported by this SDK (<MAX>). Some features may not be available. Consider updating @dynatrace/rum-javascript-sdk.
The warning is logged at most once per page load, and is shared across both the synchronous and asynchronous (promises) entry points. To resolve it, update @dynatrace/rum-javascript-sdk to a version that matches the deployed agent.
In addition to the console warning, when the agent is newer than the SDK, the SDK reports the mismatch back to the agent so it surfaces in monitoring. If the on-page agent exposes the dynatrace.reportApiMismatch method, the SDK calls it with the detected mismatch details (reason, agentApiVersion, and sdkMaxKnownApiVersion). The agent records this as an internal self-monitoring event (surfaced in the RUM JavaScript health check), deduplicated to at most once per page load. Agents that predate this method — including earlier apiVersion: 1 builds — do not expose it; against those agents the SDK falls back to the console warning only. This method is feature-detected, so it never fails when the agent lacks it.
For detailed type information and usage examples, see Dynatrace Api Types.
import type {
ApiCreatedEventPropertiesEvent,
ApiCreatedSessionPropertiesEvent,
HealthCheckConfig,
JSONEvent,
EventContext
} from '@dynatrace/rum-javascript-sdk/types';
⚠️ Warning
@dynatrace/rum-javascript-sdk-playwright
Migration:
Install the new package as a dev dependency:
npm install --save-dev @dynatrace/rum-javascript-sdk-playwright
Update your imports:
// Before
import { test } from "@dynatrace/rum-javascript-sdk/test";
// After
import { test } from "@dynatrace/rum-javascript-sdk-playwright";
All APIs remain the same — only the import path changes.
See the Testing with Playwright documentation for setup and usage.
Use Synchronous API when:
Use Asynchronous API when:
Follow prefix custom event properties with event_properties. when calling sendEvent:
// ✅ Good - properties with prefix are accepted
sendEvent({
'event_properties.action': 'login',
'event_properties.method': 'oauth',
'event_properties.page_name': 'dashboard',
'event_properties.load_time': 1234
});
// ❌ Avoid - properties without prefix are ignored
sendEvent({
'action': 'click',
'data': 'some_value'
});
Use session properties for data that applies to the entire user session:
// Set once per session
sendSessionPropertyEvent({
'session_properties.subscription_type': 'premium',
'session_properties.region': 'europe',
'session_properties.app_version': '2.1.0'
});