This guide walks you through setting up Real User Monitoring (RUM) with JavaScript in the browser. These instructions can also be found on the Installation page in your Middleware Account.

Install

If you are installing RUM in the browser with Next.js, skip to the Next.js section.

Step 1: Create Application Reference

Navigate to the Installation page in your Middleware Account. In the Real User Monitoring section, select Create New Application and provide the application name, origin(s) and Trace Propogation Target(s) to whitelist. Multiple origins can be listed as a comma-separated list.

Step 2: Import Javascript CDN

Add the following script tag to the head section of your index.html file. The tag can be copied directly from the Installation page upon completing Step 1.

HTML

<script src="https://cdnjs.middleware.io/browser/libs/0.0.1/middleware-rum.min.js" type="text/javascript"></script>

Step 3: Initialize the SDK

Add the following lines in your index.html file below the script tag entered in Step 2. We recommend copying directly from the Installation page; select the appropriate Application from the list and copy the code snippet. The window.Middleware attribute is set in the script from Step 2. In the example below, env and recording are optional. recording: "1" is the default value and records the entire user session. To track only browser traces and errors set recording: "0".

JavaScript

<script>
    if (window.Middleware){
        Middleware.track({
            serviceName: "service_name",
            accountKey: "account_key",
            target:"https://<UID>.middleware.io",
            env: "production",
            recording: "1"
        })
    }
</script>

Step 4: Add User Information [Optional]

To gather user details add key-value pairs, as shown below. Any user metadata can be defined as a key-value pair.

JavaScript

if(window.Middleware){
...
defaultAttributes: { 
    name: 'John Doe', 
    email: '[email protected]', 
    user_type: 'admin', // it can be key value pairs
}
}

If you need to define attributes post initialization of the SDK, utilize the Middleware.setAttributes method, as exemplified in the following example.

The .setAttributes method must be called after the .track method in Step 3.

JavaScript

<script>
if(window.Middleware){
        Middleware.setAttributes({
            name: 'John Doe',
            email: '[email protected]',
            user_type: 'admin',
        })
    }
</script>

Once RUM is configured, metrics should begin appearing on the RUM Dashboard in Middleware within a few minutes. For more information on the RUM Dashboards see here.

Step 5: Add Custom Logs [Optional]

Use these functions to keep track of different types of issues in your system, making it easier to monitor and fix problems.

JavaScript

<script>
if(window.Middleware){
    Middleware.error("Your error message")
    Middleware.error(new Error("Your error message"))
    Middleware.info("info message")
    Middleware.warn("warn message")
    Middleware.debug("debug message")
    }
</script>

Connect RUM to Tracing

RUM Tracing allows you to gain insight into the specific actions of your users. You can watch time-stamped videos of user’s website interactions, pinpoint performance bottlenecks across your platform, and identify the major causes of customer drop off. The following installation uses OpenTelemetry B3 Propagator heads. Learn more about B3 Propagation here.

You must have a Middleware APM Agent installed in order to use the tracing feature. Install a Middleware APM here.

Step 1: Modify Middleware SDK

Add tracePropagationTargets to your SDK from Step 3 of the RUM Installation. The tracePropagationTargets value must be in regex format.

The Middleware JavaScript client is by default configured with b3 headers. You can change your headers by adding tracePropagationFormat to change the headers to w3c or all.

JavaScript

<script>
    if (window.Middleware){
        Middleware.track({
            serviceName: "service_name",
            accountKey: "account_key",
            target: "https://<UID>.middleware.io",
            env: "production",
            recording: "1",
            tracePropagationTargets: [/localhost:3000/i, /api.domain.com/i],
            tracePropagationFormat: "w3c"
        })
    }
</script>

Step 2: Modify APM SDK

In order to enable Trace Propagation, some languages require the OTEL_PROPAGATORS=b3 environment variable. Those languages are called out in the table below. All other langugages will work with the standard APM install.

Access RUM From Trace List

To access your Session Replay data, navigate to the APM section, select the Trace List tab and choose a trace to view your data.

For more information about using RUM, head to the RUM Workflow page.

Supported APMs


Language	Supported	APM Version	Environment Variable
Cloudflare	✖️	✖️	✖️
Go	✅	`>= 1.1.100`	✖️
Java	✅	✖️	✅
.NET	✅	✖️	✅
Next.js	✅	✖️	✖️
Node.js	✅	`>= 1.2.5`	✖️
PHP	✖️	✖️	✖️
Python	✅	`>= 0.3.2`	✖️
Ruby	✅	`>= 2.1.0`	✅
Vercel	✅	✖️	✖️

API Reference

Function	Returns	Parameters
`debug(log)`	undefined	log (string): The debug message to be logged
`info(log)`	undefined	log (string): The informational message to be logged
`warn(log)`	undefined	log (string): The warning message to be logged
`error(log)`	undefined	log (Object): An Error object
`track(config)`	undefined	config (object): Configuration object
`setAttributes(config)`	undefined	config (object): Configuration object used to set attributes after the initial configuration with `.track()`

Configuration Object

Property	Type	Required	Default	Description
`projectName`	`string`	✅	URL of the application	Main application identifier, encapsulating application instances like `dev`, `staging`, and `prod`
`serviceName`	`string`	✅		Associates application instances with traces as a subcategory of the project
`accountKey`	`string`	✅		Generated from `Installation -> JavaScript -> Create New Application`
`target`	`string`	✅		Target URL for the application using RUM - Required `http(s)://` prepend
`env`	`string`	✖️	`"prod"`	Arbitrary string for filtering applications
`recording`	`string`	✖️	`"1"`	Toggle used to enable/disable video recording - `"1"` enables video recording and `"2"` disables video recording
`tracePropagationTargets`	`Array\<RegExp\>`	✖️		Targets for trace propagation - URL’s of back-end serve as array of regular expression literals (`http(s)://` must be omitted)
`tracePropagationFormat`	`string`	✖️	`"b3"`	Trace propogation format
`defaultAttributes`	`Object\<string, string>`	✖️		Key value pairs used to filter sessions/traces - `name` and `email` filter RUM sessions, while all other keys are arbitrary strings for trace filtering
`ignoreUrls`	`Array`	✖️		URL’s that will be ignored

Troubleshooting

Browser Cookies

The RUM Browser SDK uses cookies to remember a single user session across different pages on your website. These are first-party cookies and stay within your domain; they won’t be used to track users across different sites.


Cookie Name	Details
`_mwRumSessionId_x`	This cookie collects all the actions from a user’s visit across different pages. This cookie includes the current session ID, whether the session has been excluded as a result of sampling, and the session expiration date. Each time a user interacts with the website, an extra 15 minutes is added to the cookie’s timer, ensuring the session remains active, with a maximum duration of 4 hours.

Script Integration Issues

If you are experiencing exceptions and errors while integrating the RUM browser SDK, consider moving Middleware packages and scripts earlier in the execution of your application code to avoid collisions with your website’s code.Make sure you have added the following Middleware script with the setTimeout function:

JavaScript

setTimeout(() => {
    if(window.Middleware) {
        Middleware.track({
            serviceName: "sample-service",
            projectName: "sample-project",
            accountKey: "REDACTED",
            target: "<target-url>"
        })
    }
}, 10000)

Unable to See Session Recording

Check if the origin URL (from where the session recording takes place) is correct.Check your network tab in your developer console if any adblockers or extensions are stopping Middleware requests.

Unhandled Promise Rejection: TypeError: Failed to fetch

This error can be ignored, as it does not impact the Middleware RUM Browser SDK. This issue commonly occurs when an API call is being executed and a user refreshes the page.

Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.

Middleware Docs

Browser RUM - Getting Started

Install

Step 1: Create Application Reference

Step 2: Import Javascript CDN

Step 3: Initialize the SDK

Step 4: Add User Information [Optional]

Step 5: Add Custom Logs [Optional]

Connect RUM to Tracing

Access RUM From Trace List

Supported APMs

API Reference

Configuration Object

Troubleshooting

​Install

​Step 1: Create Application Reference

​Step 2: Import Javascript CDN

​Step 3: Initialize the SDK

​Step 4: Add User Information [Optional]

​Step 5: Add Custom Logs [Optional]

​Connect RUM to Tracing

​Access RUM From Trace List

​Supported APMs

​API Reference

​Configuration Object

​Troubleshooting

Install

Step 1: Create Application Reference

Step 2: Import Javascript CDN

Step 3: Initialize the SDK

Step 4: Add User Information [Optional]

Step 5: Add Custom Logs [Optional]

Connect RUM to Tracing

Access RUM From Trace List

Supported APMs

API Reference

Configuration Object

Troubleshooting