Getting started

Snippet Installation

The Pulsecadence snippet uses the browser's native PerformanceObserver API to collect Core Web Vitals. This guide covers async loading, CSP configuration, SPA lifecycle integration, and advanced options.

Standard installation

Add the snippet to the <head> of every monitored page. The async attribute ensures it does not block parsing:

<script
  async
  src="https://cdn.pulsecadence.com/v1/pcd.js"
  data-project-key="YOUR_PROJECT_KEY"
></script>

Placement recommendations

  • Place the snippet tag as early as possible in <head>, before any render-blocking scripts, to ensure the PerformanceObserver is registered before LCP candidates are rendered.
  • Do not place in <body> — scripts loaded in body will miss early LCP candidates.
  • If your CMS or tag manager delays script loading, use the manual API (see below) to ensure timely initialization.

Content Security Policy

Add these directives to your CSP to allow the snippet to load and send data:

script-src 'self' https://cdn.pulsecadence.com;
connect-src 'self' https://ingest.pulsecadence.com;

If you use nonce-based CSP, you can add the nonce to the script tag:

<script
  async
  nonce="YOUR_NONCE"
  src="https://cdn.pulsecadence.com/v1/pcd.js"
  data-project-key="YOUR_PROJECT_KEY"
></script>

SPA route change tracking

Pulsecadence automatically detects SPA route changes via History API patching. Each route change starts a new LCP observation window. No configuration required for React Router, Vue Router, or Next.js App Router.

For custom routers or non-standard navigation patterns, you can manually fire a route change event:

// Fire when a route change completes
window.PulseCadence && window.PulseCadence.pageview({
  path: window.location.pathname
});

Sampling

By default, Pulsecadence captures 100% of sessions. For very high-traffic sites on the Hobby tier, you can configure a sampling rate using the data-sample-rate attribute:

<script
  async
  src="https://cdn.pulsecadence.com/v1/pcd.js"
  data-project-key="YOUR_PROJECT_KEY"
  data-sample-rate="0.5"
></script>

A sample rate of 0.5 captures 50% of sessions. p75 calculations remain statistically valid down to approximately 10% sampling for sites with 10,000+ daily sessions.

Advanced: manual initialization

If you need to control initialization (e.g. after consent is granted), use the defer pattern:

// Load after user consent or other async condition
function loadPulsecadence() {
  var s = document.createElement('script');
  s.src = 'https://cdn.pulsecadence.com/v1/pcd.js';
  s.setAttribute('data-project-key', 'YOUR_PROJECT_KEY');
  document.head.appendChild(s);
}

// Call when ready
if (userHasConsented()) {
  loadPulsecadence();
}

Custom session metadata

Attach custom key-value metadata to sessions for segmentation in the dashboard:

window.PulseCadenceConfig = {
  meta: {
    plan: 'enterprise',
    experiment: 'checkout-v2',
    user_segment: 'returning'
  }
};

Place this block before the snippet tag. Custom metadata values appear as filterable dimensions in the segmentation view.