Try it free

Customize web frontend monitoring using the JavaScript API

  • Latest Dynatrace
  • Reference
  • 1-min read

This page describes the API provided by the RUM JavaScript. For the API to retrieve the RUM JavaScript for manual insertion, refer to RUM manual insertion tags API.

Dynatrace RUM includes a powerful JavaScript API that lets you customize and enhance web frontend monitoring for your applications. On top of everything the RUM JavaScript captures automatically, the API lets you report your own events, enrich sessions with additional context, take manual control of user actions, and build automated tests around the data your application sends. Read on to learn about its capabilities, the on-page JavaScript API, the npm package, and the companion Playwright testing framework.

Capabilities

The JavaScript API is called from your own application code and offers the following capabilities.

  • Send custom events: Report events with your own properties using sendEvent.
  • Enrich sessions with properties: Attach data that applies to the whole session—for example, the subscription tier—with sendSessionPropertyEvent.
  • Identify users: Associate the current session with a user identifier using identifyUser.
  • Report exceptions: Send custom exception/error events using sendExceptionEvent so internally handled failures still surface in monitoring.
  • Modify events before they are sent: Register an event modifier with addEventModifier to adjust or filter RUM events on the fly.
  • Manually control user actions: Create custom user actions, rename them, attach additional context, adjust timing, subscribe to user-action lifecycle events, and disable automatic detection when it interferes with your application. All are available through the dynatrace.userActions namespace.
  • Report custom key combinations: Use interactions.sendKeyPressEvent to report key press interactions that aren't automatically detected by standard key press capturing.

JavaScript API documentation

The API comes with comprehensive reference documentation covering everything above in detail, with API signatures, TypeScript types, practical use cases, and copy-paste examples to help you get started quickly.

The online reference always reflects the latest version of the @dynatrace/rum-javascript-sdk npm package. For older versions, use the Markdown docs in the package's docs/ directory.

Choose between the on-page API and the npm package

There are two ways to work with the API. Both expose the same capabilities but differ in how you call them.

The on-page API and the npm package let you customize and enrich monitoring once the RUM JavaScript is on the page—they don't replace its addition via automatic injection or manual insertion; see Initial setup for web frontends.

The on-page JavaScript API

The on-page JavaScript API is provided by the dynatrace global object that the RUM JavaScript exposes directly on your page. Use it for quick, in-page instrumentation, or if you don't have—or don't want—a build step.

The @dynatrace/rum-javascript-sdk npm package

The @dynatrace/rum-javascript-sdk npm package is a typed, safe wrapper around the same API for applications built with a bundler and TypeScript. It makes the on-page API easier and safer to call.

Reach for the SDK instead of the on-page API if:

  • You want compile-time safety and autocomplete from the bundled TypeScript types.
  • You want calls to degrade gracefully when the RUM JavaScript hasn't loaded, or to wait for and handle its availability—for example, when you can't load the RUM JavaScript until the user consents. The SDK provides two approaches for this: synchronous and asynchronous.
  • You want to test your instrumentation in CI with the Playwright framework; see Test your instrumentation with Playwright.

The following table summarizes the key differences.

On-page JavaScript APInpm package

How you access it

The dynatrace global object the RUM JavaScript puts on the page

An import statement in your bundled application

Best for

Quick in-page snippets and apps without a build step

Applications built with a bundler and TypeScript

Type safety

None, since dynatrace is a plain global

Full TypeScript type definitions included

When the RUM JavaScript isn't loaded

You must guard every call yourself (dynatrace?.…)

The synchronous API is a safe no-op; the asynchronous (/promises) API waits for the RUM JavaScript and throws an error on timeout

Test your instrumentation with Playwright

The API ships a companion Playwright testing framework, @dynatrace/rum-javascript-sdk-playwright, so you can verify in CI that your application sends exactly the RUM events you expect.

It provides a Playwright fixture that connects to your Dynatrace environment, injects the correct RUM JavaScript for your application, and exposes expect-style assertions on the events the RUM JavaScript sends:

import { test, expect } from "@dynatrace/rum-javascript-sdk-playwright";


test("reports the component event", async ({ page, dynatraceTesting }) => {
  await page.goto("https://your-app.example.com");
  await page.getByText("Explore data").first().click();


  await dynatraceTesting.expectToHaveSentEvent(
    expect.objectContaining({ "event_properties.component_rendered": "Data" })
  );
});

Setup requires an API token with the Read RUM manual insertion tags permission, your environment URL, and your application ID. For a full walkthrough, see Dynatrace RUM JavaScript Testing Framework for Playwright.

Related tags
Digital Experience