RUM Script Installation

The VitalSentinel RUM (Real User Monitoring) script collects Core Web Vitals and performance metrics from your actual visitors. It's lightweight (~13KB gzipped) and non-blocking.

Basic InstallationCopy Anchor Link

Add this script to the <head> section of your HTML:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="YOUR_TRACKING_ID"
  async
></script>

Configuration OptionsCopy Anchor Link

Customize the script behavior using data-* attributes:

Example with OptionsCopy Anchor Link

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="abc123"
  data-sample-rate="0.5"
  data-debug="true"
  data-engagement="true"
  async
></script>

Tracking IDs and HostnamesCopy Anchor Link

RUM discards a hit whose page URL is served from a host that cannot be a public production site. A developer's localhost reload has no network in front of it and reports Core Web Vitals no real visitor could, and it spends your page-view allowance doing it.

Unless the host is itself a domain you have registered, these are discarded on arrival whatever the script does:

• localhost
• Any bare IP address, private or public, IPv4 or IPv6
• Hostnames on suffixes reserved for testing and local development, such as .localhost, .local, .test, .internal, .invalid and .example, and a few others used by local development tooling

Anything else is kept, including a host that is not the domain the tracking ID belongs to. Registering a host as its own domain is how you say you meant it, so a tracked domain is always accepted even when it takes one of the shapes above.

Non-Production HostsCopy Anchor Link

The script also has its own, wider gate in the browser. It declines to send at all from localhost, loopback and private addresses, reserved test TLDs, and staging, dev and test subdomains, so a developer's reload and a QA click-through never land in the same p75 as real visitors.

Set data-track-non-production="true" if production genuinely serves from such a hostname:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="abc123"
  data-track-non-production="true"
  async
></script>

What Data is CollectedCopy Anchor Link

Core Web VitalsCopy Anchor Link

The script automatically tracks all Core Web Vitals:

• LCP (Largest Contentful Paint) - Loading performance
• FCP (First Contentful Paint) - Initial render time
• CLS (Cumulative Layout Shift) - Visual stability
• INP (Interaction to Next Paint) - Interactivity
• TTFB (Time to First Byte) - Server response time

Navigation TimingCopy Anchor Link

• DNS lookup time
• TCP connection time
• Request/response time
• DOM load time
• Full page load time

User EngagementCopy Anchor Link

When enabled (default), tracks:

• Scroll depth milestones (25%, 50%, 75%, 90%, 100%)
• Time on page and active time
• Page visibility changes
• Click tracking and rage click detection
• Form engagement (focus, changes, submissions, abandonment)

Error TrackingCopy Anchor Link

• JavaScript errors with stack traces
• Unhandled promise rejections
• Resource loading failures (images, scripts, stylesheets)

Device InformationCopy Anchor Link

Collected in every mode:

• Window size, rounded to the nearest 50 pixels
• Country, browser, operating system, and device type, worked out on our servers from the request headers the browser sends on its own

Collected only when you declare consent (see Consent Mode):

• Screen size and device pixel ratio
• Device memory and CPU cores
• Effective network connection type (slow-2g, 2g, 3g, or 4g) and downlink estimate
• Touch capability

Platform-Specific InstallationCopy Anchor Link

WordPressCopy Anchor Link

Use a header scripts plugin, or add to your theme's functions.php:

function vitalsentinel_rum_script() {
    ?>
    <script src="https://rum.vitalsentinel.com/rum.js" data-key="YOUR_TRACKING_ID" async></script>
    <?php
}
add_action('wp_head', 'vitalsentinel_rum_script');

See Platform Guides for the wp_enqueue_script alternative.

ShopifyCopy Anchor Link

1. Go to Online Store → Themes
2. Click ... → Edit code on your active theme
3. Open theme.liquid in the Layout folder
4. Add the script before </head>

Next.jsCopy Anchor Link

Using the Script component in your root layout (app/layout.tsx):

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://rum.vitalsentinel.com/rum.js"
          data-key="YOUR_TRACKING_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

React (Create React App)Copy Anchor Link

Add to public/index.html:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="YOUR_TRACKING_ID"
  async
></script>

Vue.jsCopy Anchor Link

Add to public/index.html or your main template.

Nuxt.jsCopy Anchor Link

In nuxt.config.js:

export default {
  head: {
    script: [
      {
        src: 'https://rum.vitalsentinel.com/rum.js',
        'data-key': 'YOUR_TRACKING_ID',
        async: true
      }
    ]
  }
}

SPA SupportCopy Anchor Link

The RUM script automatically detects Single Page Application navigation using the History API. For manual control:

// Trigger navigation tracking manually
window.VitalSentinelRUM.startSoftNavigation();

This is useful for:

• Custom routing implementations
• Hash-based navigation
• Complex state transitions

API MethodsCopy Anchor Link

The script exposes methods for custom tracking via window.VitalSentinelRUM (or the shorter alias window.VSRUM):

Track Custom EventsCopy Anchor Link

window.VitalSentinelRUM.trackCustomEvent('purchase', {
  productId: '12345',
  value: 99.99,
  currency: 'USD'
});

Mark Points in TimeCopy Anchor Link

// Mark points in time
window.VitalSentinelRUM.mark('hero-start');
window.VitalSentinelRUM.mark('hero-loaded');

// Measure time between two marks
window.VitalSentinelRUM.measure('hero-time', { start: 'hero-start', end: 'hero-loaded' });

Add Custom DataCopy Anchor Link

// Add data to all subsequent events
window.VitalSentinelRUM.addData('userId', 'user-123');
window.VitalSentinelRUM.addData('plan', 'premium');

Event HooksCopy Anchor Link

// Listen to RUM events
window.VitalSentinelRUM.on('mark', (eventType, data) => {
  console.log('Mark created:', data.name, data.startTime);
});

window.VitalSentinelRUM.on('measure', (eventType, data) => {
  console.log('Measure recorded:', data.name, data.duration);
});

window.VitalSentinelRUM.on('soft_navigation', (eventType, data) => {
  console.log('SPA navigation:', data);
});

Grant or Withdraw ConsentCopy Anchor Link

grantConsent('persistent') and revokeConsent() change the consent mode at runtime from your consent banner. Both are queued, so they are safe to call before the script has finished loading. See Consent Mode.

Force Send DataCopy Anchor Link

// Send all queued events immediately
window.VitalSentinelRUM.forceFlush();

Get Debug InfoCopy Anchor Link

// Logs the current tracking state (session, sampling, queued events) for debugging
const debug = window.VitalSentinelRUM.getDebug();
console.log(debug);

Command QueueCopy Anchor Link

The script installs its own command queue as soon as it loads. Once the tag is on the page, queue commands with cmd():

// Queue commands with cmd()
window.VitalSentinelRUM.cmd(['mark', 'app-start']);

// trackCustomEvent isn't queueable - call it directly
window.VitalSentinelRUM.trackCustomEvent('page_intent', { category: 'pricing' });

Privacy & ConsentCopy Anchor Link

Privacy by DefaultCopy Anchor Link

The RUM script is designed with privacy in mind:

• No cookies, no local storage, and no session storage: the script writes nothing to your visitor's device
• No cross-site tracking
• Session IDs are random and regenerate on every page load
• URL sanitization available via data-filter-query-params
• Record identifiers are stripped from page paths before a URL is stored. A long number, a UUID, a hex string, or a long opaque token becomes :id or :uuid, so /orders/44172/invoice is stored as /orders/:id/invoice. The path shape survives, so those page views still group as one page. Dates, short segments, and word slugs are left alone.

Consent ModeCopy Anchor Link

The script writes nothing to your visitor's device in any mode. What the consent mode changes is what it is allowed to read from the browser.

No consent is the default. In this mode the script reads no device details beyond the window size, rounded to the nearest 50 pixels. It also checks a flag that identifies headless automation and the Do Not Track and Global Privacy Control settings, which it reads in order to honor them. Core Web Vitals, JavaScript errors, and user engagement are all still collected.

Consent given adds screen size, device pixel ratio, device memory, CPU cores, touch capability, and connection speed, so you can tell a slow page apart from a slow device or a weak network.

Declare the consented mode on the script tag:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="YOUR_TRACKING_ID"
  data-consent="granted"
  async
></script>

Or set it at runtime from your consent banner, which needs no page reload:

// Visitor accepted
window.VitalSentinelRUM.grantConsent('persistent');

// Visitor rejected, or withdrew a previous acceptance
window.VitalSentinelRUM.revokeConsent();

Withdrawal is prospective: events already queued are sent with the context they were collected under, and nothing has to be deleted from the device because the script never wrote anything to it.

Privacy OptionsCopy Anchor Link

Enable additional privacy features:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="YOUR_TRACKING_ID"
  data-mask-text="true"
  data-mask-selectors="true"
  data-filter-query-params="true"
  async
></script>

• data-mask-text - Suppresses the visible text recorded for the LCP, CLS, and INP attribution elements. Engagement events carry no element text, so this attribute does not change them
• data-mask-selectors - Suppresses the CSS selectors recorded for LCP, CLS, and INP attribution and for engagement events. Use it if your element IDs or class names carry record identifiers, such as #order-88213
• data-filter-query-params - Removes query parameters from tracked URLs

Do Not Track and Global Privacy ControlCopy Anchor Link

The script honors a Do Not Track or Global Privacy Control signal from the browser on its own, so you do not need to gate the tag on it:

• No device details beyond the window size are read, whatever consent mode you declared
• User engagement tracking does not run
• A grantConsent() call is ignored, so your consent banner cannot raise the mode for these visitors
• Core Web Vitals and page views are still measured, so the traffic does not disappear from your reports

GDPR ComplianceCopy Anchor Link

The RUM script is designed to be GDPR-friendly by default (no cookies, no local storage, no session storage). For additional compliance:

1. Choose a consent mode that matches what your banner has obtained (see Consent Mode)
2. Use sampling (data-sample-rate) to reduce data collection
3. Enable privacy options (data-mask-text, data-mask-selectors, data-filter-query-params)

Domain-Level ControlsCopy Anchor Link

One privacy control lives in the dashboard rather than the script tag. In Domain Settings → Web Analytics → Advanced settings, ticking Do not store page titles or site-search terms also applies to your RUM data: page titles are no longer stored, and site-search terms are stripped from the URLs recorded for RUM. It is applied when we receive the data, so there is no snippet change and no redeploy, and it reaches all traffic within about a minute.

TroubleshootingCopy Anchor Link

Script Not LoadingCopy Anchor Link

1. Check browser console for errors
2. Verify the tracking ID is correct
3. Ensure no ad blocker is blocking the script
4. Check Content Security Policy headers

No Data AppearingCopy Anchor Link

1. Wait 15-30 minutes for initial data
2. Check sample rate is greater than 0
3. Verify the domain matches your configured domain
4. Enable debug mode to see console logs

Debug ModeCopy Anchor Link

Enable debug logging:

<script
  src="https://rum.vitalsentinel.com/rum.js"
  data-key="YOUR_TRACKING_ID"
  data-debug="true"
  async
></script>

Then check your browser console for [VitalSentinel RUM] messages.

Browser CompatibilityCopy Anchor Link

The RUM script supports:

• Chrome/Edge 90+
• Firefox 89+
• Safari 15+
• Opera 76+

Older browsers will gracefully degrade without causing errors.

RelatedCopy Anchor Link