# Web Analytics Script Installation
The VitalSentinel Web Analytics script provides privacy-focused web analytics with automatic e-commerce tracking. It's lightweight (\~11KB gzipped) and respects user privacy while still giving you the insights you need.
## Basic Installation [#basic-installation]
Add this script to the `` section of your HTML:
```html
```
Find your tracking ID in **Domain Settings** → **Web Analytics**.
## Configuration Options [#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 | "false" | SPA route-change tracking: "true", "false", "auto" |
### Storage Consent Levels Explained [#storage-consent-levels-explained]
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 |
### Cookie Domain for Subdomains [#cookie-domain-for-subdomains]
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.
```html
```
### Example with Options [#example-with-options]
```html
```
## What Data is Collected [#what-data-is-collected]
### Page Views [#page-views]
* URL and page title
* Referrer information
* Time on page
* Scroll depth
### Session Data [#session-data]
* Session ID (anonymous)
* Visitor ID (based on consent level)
* Pages per session
* Session duration
### Traffic Attribution [#traffic-attribution]
* UTM parameters (source, medium, campaign, term, content)
* Referrer domain classification
* Traffic source type, classified server-side (direct, search, social, referral, email, newsletter, paid, paid search, paid social, AI search, internal)
* First-touch attribution
### User Behavior [#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
* File downloads
* Site search queries
### Device Information [#device-information]
* Screen resolution and window dimensions
* Device pixel ratio
* Touch capability
* Connection type and network info
* Language and timezone
## E-commerce Auto-Tracking [#e-commerce-auto-tracking]
The Web Analytics script automatically detects and tracks e-commerce events on popular platforms.
### Supported Platforms [#supported-platforms]
* **Shopify**
* **WooCommerce**
* **Magento**
* **Squarespace**
### Events Tracked [#events-tracked]
| Event | Description |
| ------------------ | ---------------------------- |
| `product_view` | Visitor views a product page |
| `add_to_cart` | Item added to cart |
| `remove_from_cart` | Item removed from cart |
| `view_cart` | Cart page viewed |
| `begin_checkout` | Checkout started |
| `purchase` | Order completed |
### Data Captured [#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 is needed for supported platforms.
## Platform-Specific Installation [#platform-specific-installation]
### WordPress [#wordpress]
Use a header scripts plugin, or add it to your theme's `functions.php`:
```php
function vitalsentinel_analytics_script() {
?>
`
E-commerce tracking will work automatically.
### WooCommerce [#woocommerce]
Install the script in your theme. E-commerce events will be tracked automatically by detecting WooCommerce elements.
### Next.js [#nextjs]
In your root layout (`app/layout.tsx`):
```jsx
import Script from 'next/script';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
## SPA Support [#spa-support]
SPA (single-page app) route tracking is **opt-in**. By default (`data-spa="false"`) the script records only the initial page load. To track client-side route changes, set `data-spa="true"`.
### Enabling SPA Tracking [#enabling-spa-tracking]
```html
```
With SPA tracking enabled, the script detects navigation via:
* History API (pushState, replaceState)
* Popstate events
* Hash change events
* Navigation API (modern browsers)
`data-spa="auto"` enables a legacy heuristic that tries to detect SPAs automatically. It is opt-in only, because it can misfire on server-rendered sites that ship framework-like markers.
### Manual Page View Tracking [#manual-page-view-tracking]
For complete control:
```javascript
window.VitalSentinelAnalytics.trackPageView({
path: '/new-page',
title: 'New Page Title'
});
```
## API Methods [#api-methods]
All methods are available via `window.VitalSentinelAnalytics` (or the shorter alias `window.VSAnalytics`).
### Track Custom Events [#track-custom-events]
```javascript
window.VitalSentinelAnalytics.track('signup', {
plan: 'premium',
source: 'homepage'
});
```
### Track Page Views [#track-page-views]
```javascript
window.VitalSentinelAnalytics.trackPageView({
path: '/virtual-page',
title: 'Virtual Page'
});
```
### Identify Users [#identify-users]
```javascript
// Requires persistent consent
window.VitalSentinelAnalytics.identify('user-123', {
email: 'user@example.com',
plan: 'pro',
signupDate: '2024-01-15'
});
```
### Set Global Properties [#set-global-properties]
```javascript
// Added to all subsequent events
window.VitalSentinelAnalytics.setGlobalProperties({
environment: 'production',
appVersion: '2.1.0'
});
```
### Consent Management [#consent-management]
```javascript
// 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 [#opt-outin]
```javascript
// Stop all tracking
window.VitalSentinelAnalytics.optOut();
// Resume tracking
window.VitalSentinelAnalytics.optIn();
```
### Force Flush [#force-flush]
```javascript
// Send all queued events immediately
window.VitalSentinelAnalytics.flush();
```
### Debug Info [#debug-info]
```javascript
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 [#data-attribute-event-tracking]
Track events without JavaScript using data attributes:
```html
View Pricing
```
When clicked, these automatically send events with the specified properties.
## Privacy & Consent [#privacy--consent]
### Storage Levels [#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 [#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
### Granting Consent [#granting-consent]
When a user accepts cookies:
```javascript
// After user consents to analytics
window.VitalSentinelAnalytics.grantConsent('persistent');
```
### Cookie Consent Integration [#cookie-consent-integration]
Listen for consent events from your cookie banner and call grantConsent:
```javascript
window.addEventListener('cookie-consent-granted', () => {
window.VitalSentinelAnalytics.grantConsent('persistent');
});
```
Or dispatch the built-in consent event (the script listens for this automatically):
```javascript
// When user consents
window.dispatchEvent(new CustomEvent('vs-analytics-consent', {
detail: { level: 'persistent' }
}));
```
### User ID Hashing [#user-id-hashing]
For additional privacy, hash user IDs:
```html
```
User IDs passed to `identify()` will be hashed with SHA-256 before sending.
### Do Not Track [#do-not-track]
The script respects the browser's Do Not Track setting:
```javascript
if (navigator.doNotTrack === '1') {
// Tracking is automatically disabled
}
```
## Bot Detection [#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 [#troubleshooting]
### No Page Views Appearing [#no-page-views-appearing]
1. Check browser console for errors
2. Verify tracking ID is correct
3. Ensure script is loading (Network tab)
4. Check if an ad blocker is active
### E-commerce Not Tracking [#e-commerce-not-tracking]
1. Verify you're using a supported platform (Shopify, WooCommerce, Magento, Squarespace)
2. Check that product pages have the expected structure
3. Enable debug mode (`data-debug="true"`) to see detection in console logs
### Debug Mode [#debug-mode]
Enable debug logging:
```html
```
Check browser console for `[VitalSentinel Analytics]` messages.
### Duplicate Page Views [#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 [#browser-compatibility]
The Web Analytics script supports:
* Chrome/Edge 90+
* Firefox 89+
* Safari 15+
* Opera 76+
Older browsers will gracefully degrade without causing errors.
## Related [#related]
Explore the analytics dashboard and available reports
Deep dive into scroll depth, rage clicks, and user behavior
Details on data collection, storage, and GDPR compliance
Solutions to common installation and tracking issues