Install & Configure RUM


On this page

Real User Monitoring (RUM) requires adding a JavaScript snippet to your website. The snippet will collect performance data from real users visiting your site.

This guide explains how to install and configure Calibre RUM.

Prerequisites#

To use Calibre RUM, you will need:

  • A Calibre account with a plan that includes Real User Monitoring (RUM).
  • A website where you can add the RUM JavaScript snippet.

Enable RUM for your Site#

  1. Navigate to your Site in Calibre.
  2. In the left-hand side menu, click on Real User Monitoring → Settings.
  3. Add your website's full URL to Allowed Origins, for example https://example.com.
  4. Choose how many user sessions you want to collect (e.g., 15%, 100%).
  5. Click Save RUM Settings.
RUM Settings with Real User Monitoring enabled and the embed code shown, with install steps for HTML, Google Tag Manager, React, Shopify and WordPress.

Enabling RUM for a site

Install the RUM snippet#

  1. Open the snippet on the Site setup page, or in Real User Monitoring → Settings.
  2. Pick your setup: HTML, Google Tag Manager, React, Shopify or WordPress.
  3. Follow its step. Every page you want to monitor needs the snippet.
  4. Deploy your changes.

The HTML snippet in the <head> is the most accurate install. It loads before anything else, so it catches visitors who leave early. Use the sections below if you can’t edit your HTML directly.

Optimisation tools that delay or combine scripts also delay RUM. Exclude use.calibre.app from “delay JavaScript” and combine or minify settings, and turn off Cloudflare Rocket Loader for it.

If your site sends a Content Security Policy, allow use.calibre.app. See Content Security Policy.

Google Tag Manager#

  1. Add a Custom HTML tag with the code from RUM Settings.
  2. Trigger it on Initialization - All Pages. It fires earliest.
  3. Publish the container.
Custom HTML tag
<script>
  (function () {
    var script = document.createElement('script');
    script.type = 'module';
    script.crossOrigin = 'anonymous';
    script.integrity = 'VALID_INTEGRITY_HASH';
    script.setAttribute('data-calibre-rum-id', 'YOUR_RUM_ID');
    script.src = 'YOUR_RUM_SNIPPET_URL';
    document.head.appendChild(script);
  })();
</script>

GTM loads after the page, so visitors who leave early are missed and results lean faster than reality. The HTML snippet is more accurate.

Don’t add a History Change trigger. RUM tracks soft navigations itself. If you use Consent Mode, it may hold the tag back until consent is given.

React#

For Vite or Create React App, paste the HTML snippet into the <head> of index.html. It loads earliest.

If you can’t edit index.html, render this component once in your root component. It must run on the client.

CalibreRum.jsx
import { useEffect } from 'react'

export function CalibreRum() {
  useEffect(() => {
    if (document.querySelector('script[data-calibre-rum-id]')) return
    const script = document.createElement('script')
    script.type = 'module'
    script.crossOrigin = 'anonymous'
    script.integrity = 'VALID_INTEGRITY_HASH'
    script.dataset.calibreRumId = 'YOUR_RUM_ID'
    script.src = 'YOUR_RUM_SNIPPET_URL'
    document.head.appendChild(script)
  }, [])

  return null
}

Shopify#

  1. Go to Online Store → Themes.
  2. Open the … menu next to your theme and choose Edit code.
  3. Paste the HTML snippet into layout/theme.liquid, just before </head>.

Checkout and thank-you pages don’t use theme.liquid, so they aren’t measured. The snippet belongs to one theme. Add it again after switching themes.

To collect visits on your *.myshopify.com or theme preview domains, add them to Allowed Origins.

Customer Events and Web Pixels run in a sandbox and can’t measure Core Web Vitals. Use theme.liquid instead.

WordPress#

Add this to functions.php in a child theme. The priority of 1 puts it near the top of <head>.

functions.php
add_action('wp_head', function () { ?>
<script
  defer
  type="module"
  crossorigin="anonymous"
  integrity="VALID_INTEGRITY_HASH"
  data-calibre-rum-id="YOUR_RUM_ID"
  src="YOUR_RUM_SNIPPET_URL"
></script>
<?php }, 1);

If you can’t edit theme files, use a header plugin such as WPCode and paste the HTML snippet.

This applies to WP Rocket, LiteSpeed Cache, SiteGround Optimizer and Autoptimize.

Verify RUM Installation#

You can verify that the RUM snippet is working correctly by checking the Network tab in your browser's developer tools. You should see at least 2 requests from use.calibre.app:

  1. A GET request to use.calibre.app/index.js to load the RUM snippet. If no /t request follows, you may have been served the empty no-op script: check Allowed Origins and the Sampling Rate.
  2. A POST request to use.calibre.app/t that sends performance data.

/t will respond with OK if data is being successfully sent.

Verifying RUM installation in browser developer tools

Verifying RUM installation in browser developer tools

Reload your RUM Dashboard after a few minutes to see the collected data. Check the Live Sessions count to verify that data is being received. After a few hours, filter by Today to see the most recent data.

Expect to see data in the RUM Dashboard within a few minutes of verifying installation. If you are using a low sampling rate or do not have much traffic, it may take longer to see comprehensive data appear.

Configuration options#

Calibre RUM makes it easy to configure how data is collected, processed and stored.

To manage these settings, navigate to your Site → Real User Monitoring → Settings page. Settings are split across two tabs: Configuration (covered below) and Page Groupings.

Read on to learn about Allowed Origins, Geographic Monitoring, Sampling Rate, Data Retention, and Advanced Configuration.

The RUM Settings Configuration tab showing the embed code with install tabs for HTML, Google Tag Manager, React, Shopify and WordPress, then allowed origins and geographic monitoring.

The Configuration tab of RUM Settings.

Allowed Origins#

To ensure that RUM data is only collected from your website, you need to add your website's full URL, such as https://example.com, to the Allowed Origins field in the RUM settings. This prevents other unauthorised websites from sending data to your Calibre account.

If a website embeds the RUM snippet and is not in Allowed Origins, it receives an empty no-op script instead of RUM, and no data is collected.

Geographic Monitoring#

By default, Calibre RUM collects data from users worldwide. In all cases, Calibre’s RUM data collection is designed to respect user privacy and comply with relevant data protection regulations.

When data is collected, it is processed in the same region as the user. If the user is located in the European Economic Area (EEA) or European Union (EU), the data will be processed in accordance with GDPR requirements.

However, if you prefer to exclude data from users in the EEA or EU, you can enable the Exclude EEA/EU option in RUM Settings. When this option is enabled, users in these regions receive an empty script, and any data sent from them is rejected at the edge. See Excluding EEA/EU data entirely.

Learn more about RUM data collection and processing.

Sampling Rate#

You can choose how much data is collected by changing the Sampling Rate percentage.

If a user is sampled out, they receive an empty no-op script instead of RUM, and no data is collected from them. They keep that script for the rest of their session.

Sampling Rate is applied after EEA/EU exclusion, so you can use the two settings together.

Data Retention#

Depending on your pricing plan, you can specify a RUM data retention period of 3 — 24 months.

PlanRUM Data Retention Period
Trial3 months
Starter3 months
TeamUp to 12 months
CompanyUp to 24 months

After the retention period, your Site’s RUM data is deleted automatically and can’t be recovered.

Advanced configuration#

Override page path to mask sensitive information#

In some cases, you may want to mask parts of the page path to avoid tracking sensitive information.

You can do this by adding a data-path attribute to the <script> tag of the RUM snippet, or by calling Calibre.update({ path: "/new/path" });.

<script
  defer
  type="module"
  crossorigin="anonymous"
  src="YOUR_RUM_SNIPPET_URL"
  data-calibre-rum-id="YOUR_RUM_ID"
  integrity="VALID_INTEGRITY_HASH"
  data-path="/teams/:team/:site_id"
></script>

When a user visits /teams/calibre/calibre, the RUM snippet will report the page path as /teams/:team/:site_id, effectively masking the original path and preventing the original path from being sent to Calibre’s servers. This is helpful when you want to prevent storing sensitive information such as account identifiers or user IDs.

Element attribution#

By default, Calibre RUM attributes Core Web Vitals metrics to specific named elements on your pages.

For example, Largest Contentful Paint (LCP) will be automatically attributed using CSS selectors, pointing directly to the image that caused it (e.g.: header img.hero-image).

Segmenting CLS by Element Attribution. #heroImage is a custom attribution.

Segmenting CLS by Element Attribution. #heroImage is a custom attribution.

Custom element attribution labels#

You can also set custom attribution labels by adding a data-name or elementtiming attribute to the relevant HTML elements (usually <img>, <video>, or <button>).

Labels are lowercased, spaces and underscores become hyphens, other characters outside a–z and 0–9 are removed, and labels are truncated to 30 characters. e.g.: Product_Card 123 is reported as product-card-123. If an element has both attributes, elementtiming is used.

Custom Element Attribution
<img src="hero.jpg" data-name="hero-image" />
<img src="avatar.png" elementtiming="user-avatar" />
<button type="button" data-name="start-new-search-button">Start New Search</button>

While elementtiming is designed for the Element Timing API, Calibre RUM also recognises it for custom element attribution, so you get better quality element attribution out of the box.