VitalSentinel
Installation

RUM Script Installation

Complete guide to installing and configuring the VitalSentinel Real User Monitoring script.

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

Basic Installation

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>

Find your tracking ID in Domain Settings → Real User Monitoring (RUM).

Configuration Options

Customize the script behavior using data-* attributes:

AttributeTypeDefaultDescription
data-keystringrequiredYour unique tracking ID
data-sample-ratenumber1.0Sampling rate (0.0-1.0)
data-debugbooleanfalseEnable console logging
data-engagementbooleantrueTrack scroll/time on page
data-mask-textbooleanfalseRedact text content
data-mask-selectorsbooleanfalseRedact CSS selectors
data-filter-query-paramsbooleanfalseRemove query parameters

Example with Options

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

What Data is Collected

Core Web Vitals

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
  • DNS lookup time
  • TCP connection time
  • Request/response time
  • DOM load time
  • Full page load time

User Engagement

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 Tracking

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

Device Information

  • Screen size and device pixel ratio
  • Device memory and CPU cores
  • Network connection type (2G, 3G, 4G, 5G)
  • Touch capability

Platform-Specific Installation

WordPress

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.

Shopify

  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.js

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)

Add to public/index.html:

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

Vue.js

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

Nuxt.js

In nuxt.config.js:

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

SPA Support

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 Methods

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

Track Custom Events

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

Mark Points in Time

// Mark when a critical element loads
window.VitalSentinelRUM.mark('hero-loaded');

// Measure time between marks
window.VitalSentinelRUM.measure('hero-time', 'navigationStart', 'hero-loaded');

Add Custom Data

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

Event Hooks

// 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);
});

Force Send Data

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

Get Debug Info

const debug = window.VitalSentinelRUM.getDebug();
console.log(debug);
// Returns: {
//   sessionId: string,
//   eventQueue: number,
//   marks: Array,
//   customData: Array,
//   hooks: string[],
//   navigationCount: number
// }

Command Queue

You can queue commands before the script loads:

<script>
  window.VitalSentinelRUM = window.VitalSentinelRUM || {
    cmd: function(c) {
      this._q = this._q || [];
      this._q.push(c);
    }
  };

  // Queue commands before script loads
  window.VitalSentinelRUM.cmd(['mark', 'app-start']);
  window.VitalSentinelRUM.cmd(['trackCustomEvent', 'page_intent', { category: 'pricing' }]);
</script>

Privacy & Consent

Privacy by Default

The RUM script is designed with privacy in mind:

  • No persistent cookies by default
  • No cross-site tracking
  • Session IDs regenerate on page refresh (no persistent identifiers)
  • URL sanitization available via data-filter-query-params

Privacy Options

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 - Redacts text content in engagement events
  • data-mask-selectors - Masks CSS selectors in click/form tracking
  • data-filter-query-params - Removes query parameters from tracked URLs

Opt-Out Support

Respect user preferences:

// Check Do Not Track
if (navigator.doNotTrack === '1') {
  // Don't load the script
}

GDPR Compliance

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

  1. Delay loading until consent is given
  2. Use sampling (data-sample-rate) to reduce data collection
  3. Enable privacy options (data-mask-text, data-mask-selectors, data-filter-query-params)

Troubleshooting

Script Not Loading

  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 Appearing

  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 Mode

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 Compatibility

The RUM script supports:

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

Older browsers will gracefully degrade without causing errors.

RUM Monitoring

Learn about the metrics and insights available from RUM data

Performance Thresholds

Understand what good, needs improvement, and poor metrics look like

Data & Privacy

Details on data collection, storage, and GDPR compliance

Troubleshooting

Solutions to common installation and tracking issues

Adding a Domain

Learn how to add domains to VitalSentinel and configure monitoring settings.

Web Analytics Script Installation

Complete guide to installing and configuring the VitalSentinel Web Analytics script.

On this page

Basic InstallationConfiguration OptionsExample with OptionsWhat Data is CollectedCore Web VitalsNavigation TimingUser EngagementError TrackingDevice InformationPlatform-Specific InstallationWordPressShopifyNext.jsReact (Create React App)Vue.jsNuxt.jsSPA SupportAPI MethodsTrack Custom EventsMark Points in TimeAdd Custom DataEvent HooksForce Send DataGet Debug InfoCommand QueuePrivacy & ConsentPrivacy by DefaultPrivacy OptionsOpt-Out SupportGDPR ComplianceTroubleshootingScript Not LoadingNo Data AppearingDebug ModeBrowser CompatibilityRelated