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/native-http)Manually report HTTP requests captured via Cordova HTTP plugins (or any native transport) that are not automatically instrumented, via API.NativeHttp. See Native HTTP 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 SDK checks the version of the on-page RUM JavaScript agent. Agents that match this SDK build or predate it work without any warning. An agent newer than this SDK build also works, but the SDK logs a console warning:
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 SDK logs this warning at most once per page load, and shares that limit across the synchronous and asynchronous (promises) entry points. To clear it, update @dynatrace/rum-javascript-sdk to a version that matches the deployed agent.
Newer agents also record the mismatch as an internal self-monitoring event, so it appears in the RUM JavaScript health check and not only in the console.
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'
});