Web Analytics Script Installation

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

The VitalSentinel Web Analytics script provides privacy-focused web analytics with automatic e-commerce tracking. It's lightweight (~11KB gzipped) and designed to respect user privacy while giving you valuable insights.

Basic Installation

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

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

Find your tracking ID in Domain Settings → Web Analytics.

Configuration Options

Customize the script behavior using data-* attributes:

Attribute	Type	Default	Description
`data-key`	string	required	Your unique tracking ID
`data-storage`	string	"none"	Storage consent: "none", "session", "persistent"
`data-cookie-domain`	string	(current host)	Cookie scope for multi-property/subdomain setups
`data-debug`	boolean	false	Enable console logging
`data-hash-user-id`	boolean	false	Hash user IDs with SHA-256
`data-spa`	string	"auto"	SPA detection: "true", "false", "auto"

The data-storage attribute (and the matching grantConsent() API) controls how the script remembers visitors. Pick the lowest level that meets your needs - lower levels collect less personal data and require less consent under GDPR.

Level	What it stores	Best for
none (default)	Nothing - no cookies, no localStorage. Each pageview is treated independently. Visitor counts use anonymous in-memory session IDs that reset on refresh.	Privacy-first sites that want to avoid the cookie banner entirely
session	Session-only storage that's cleared when the browser tab closes. Lets the script connect multiple pageviews into a single session, but doesn't recognize returning visitors.	Sites that want session-based metrics (pages per session, session duration) without persistent tracking
persistent	Long-lived storage that survives across browser sessions. Enables returning-visitor recognition and `identify()` for known users.	Apps that need to attribute behavior to logged-in users across visits

If you serve content across multiple subdomains (e.g. www.example.com and app.example.com) and use session or persistent storage, set data-cookie-domain="example.com" so the same visitor is recognized across both. With the default scoping, each subdomain would track visitors separately.

<script
  src="https://analytics.vitalsentinel.com/analytics.js"
  data-key="abc123"
  data-storage="session"
  data-cookie-domain="example.com"
  async
></script>

Example with Options

<script
  src="https://analytics.vitalsentinel.com/analytics.js"
  data-key="abc123"
  data-storage="session"
  data-debug="true"
  async
></script>

What Data is Collected

Page Views

URL and page title
Referrer information
Time on page
Scroll depth

Session Data

Session ID (anonymous)
Visitor ID (based on consent level)
Pages per session
Session duration

Traffic Attribution

UTM parameters (source, medium, campaign, term, content)
Referrer domain classification
Traffic source type (direct, organic, social, referral, paid, email)
First-touch attribution

User Behavior

Scroll depth tracking (25%, 50%, 75%, 90%, 100%)
Time on page (active and total)
Rage click detection (3+ clicks in 1 second within 100px)
Outbound link clicks
Site search queries

Device Information

Screen resolution and window dimensions
Device pixel ratio
Touch capability
Connection type and network info
Language and timezone

E-commerce Auto-Tracking

The Web Analytics script automatically detects and tracks e-commerce events on popular platforms.

Supported Platforms

Shopify
WooCommerce
Magento
Squarespace

Events Tracked

Event	Description
`product_view`	Visitor views a product page
`add_to_cart`	Item added to cart
`view_cart`	Cart page viewed
`begin_checkout`	Checkout started
`purchase`	Order completed

Data Captured

For each e-commerce event:

Product ID and SKU
Product name and category
Price and quantity
Cart total
Order ID (for purchases)

E-commerce tracking is automatic. No additional configuration needed for supported platforms.

Platform-Specific Installation

WordPress

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

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

See Platform Guides for the wp_enqueue_script alternative.

Shopify

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

E-commerce tracking will work automatically.

WooCommerce

Install the script in your theme. E-commerce events will be tracked automatically by detecting WooCommerce elements.

Next.js

In your root layout (app/layout.tsx):

import Script from 'next/script';

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

SPA Support

Automatic Detection

The script automatically detects SPA navigation via:

History API (pushState, replaceState)
Popstate events
Hash change events
Navigation API (modern browsers)

Manual Configuration

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

Manual Page View Tracking

For complete control:

window.VitalSentinelAnalytics.trackPageView({
  path: '/new-page',
  title: 'New Page Title'
});

API Methods

All methods are available via window.VitalSentinelAnalytics (or the shorter alias window.VSAnalytics).

Track Custom Events

window.VitalSentinelAnalytics.track('signup', {
  plan: 'premium',
  source: 'homepage'
});

Track Page Views

window.VitalSentinelAnalytics.trackPageView({
  path: '/virtual-page',
  title: 'Virtual Page'
});

Identify Users

// Requires persistent consent
window.VitalSentinelAnalytics.identify('user-123', {
  email: 'user@example.com',
  plan: 'pro',
  signupDate: '2024-01-15'
});

Set Global Properties

// Added to all subsequent events
window.VitalSentinelAnalytics.setGlobalProperties({
  environment: 'production',
  appVersion: '2.1.0'
});

// Grant consent (enables storage)
window.VitalSentinelAnalytics.grantConsent('persistent');

// Revoke consent (clears storage)
window.VitalSentinelAnalytics.revokeConsent();

// Check current level
const level = window.VitalSentinelAnalytics.getConsentLevel();
// Returns: 'none', 'session', or 'persistent'

Opt Out/In

// Stop all tracking
window.VitalSentinelAnalytics.optOut();

// Resume tracking
window.VitalSentinelAnalytics.optIn();

Force Flush

// Send all queued events immediately
window.VitalSentinelAnalytics.flush();

Debug Info

const debug = window.VitalSentinelAnalytics.getDebug();
console.log(debug);
// Returns: {
//   initialized: boolean,
//   optedOut: boolean,
//   consent: string,
//   sessionId: string,
//   visitorId: string,
//   identifiedUserId: string | null,
//   ecommercePlatform: string,
//   queueLength: number,
//   config: object
// }

Data Attribute Event Tracking

Track events without JavaScript using data attributes:

<button
  data-vs-event="button_click"
  data-vs-button-id="cta-header"
  data-vs-button-text="Sign Up"
>
  Sign Up Now
</button>

<a
  href="/pricing"
  data-vs-event="link_click"
  data-vs-link-type="navigation"
>
  View Pricing
</a>

When clicked, these automatically send events with the specified properties.

Storage Levels

The Web Analytics script supports three consent levels:

Level	Storage	Behavior
`none` (default)	None	IDs regenerate on page refresh, no persistence
`session`	sessionStorage	IDs persist within browser session (30-min timeout)
`persistent`	localStorage + cookies	Cross-session tracking with explicit consent

Default Privacy

By default (data-storage="none"):

No cookies are set
No localStorage/sessionStorage is used
Visitor IDs regenerate on each page load
Fully GDPR compliant without consent

When a user accepts cookies:

// After user consents to analytics
window.VitalSentinelAnalytics.grantConsent('persistent');

Listen for consent events from your cookie banner and call grantConsent:

window.addEventListener('cookie-consent-granted', () => {
  window.VitalSentinelAnalytics.grantConsent('persistent');
});

Or dispatch the built-in consent event (the script listens for this automatically):

// When user consents
window.dispatchEvent(new CustomEvent('vs-analytics-consent', {
  detail: { level: 'persistent' }
}));

User ID Hashing

For additional privacy, hash user IDs:

<script
  src="https://analytics.vitalsentinel.com/analytics.js"
  data-key="YOUR_TRACKING_ID"
  data-hash-user-id="true"
  async
></script>

User IDs passed to identify() will be hashed with SHA-256 before sending.

Do Not Track

The script respects the browser's Do Not Track setting:

if (navigator.doNotTrack === '1') {
  // Tracking is automatically disabled
}

Bot Detection

The script automatically detects and filters:

Known bot user agents
Headless browsers
Automated testing tools

Bot traffic is excluded from your analytics.

Troubleshooting

No Page Views Appearing

Check browser console for errors
Verify tracking ID is correct
Ensure script is loading (Network tab)
Check if an ad blocker is active

E-commerce Not Tracking

Verify you're using a supported platform (Shopify, WooCommerce, Magento, Squarespace)
Check that product pages have the expected structure
Enable debug mode (data-debug="true") to see detection in console logs

Debug Mode

Enable debug logging:

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

Check browser console for [VitalSentinel Analytics] messages.

Duplicate Page Views

For SPAs, ensure you're not manually calling trackPageView() when automatic detection is enabled. Either:

Use data-spa="false" and track manually, or
Use data-spa="true" and let auto-detection handle it

Browser Compatibility

The Web Analytics script supports:

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

Older browsers will gracefully degrade without causing errors.

Web Analytics Script Installation

Web Analytics

Engagement Analytics

Data & Privacy

Troubleshooting

On this page