Skip to main content
The HTML snippet is the simplest way to add Sparklytics to any website. The script is less than 5 KB gzipped, works without cookies, and automatically tracks pageviews and SPA navigation.

​
Installation

1

Get your website ID

In the Sparklytics dashboard, create a new website and copy the Website ID.
2

Add the script tag

Add the following script before the closing </body> tag on every page:
<script defer src="https://analytics.example.com/s.js" data-website-id="YOUR_WEBSITE_ID"></script>
Replace https://analytics.example.com with your Sparklytics server URL.
3

Verify tracking

Visit your website and check the Sparklytics dashboard. Pageviews should appear within seconds.

​
Configuration Options

Customize the script behavior using data-* attributes: 
<script 
  defer 
  src="https://analytics.example.com/s.js" 
  data-website-id="abc123"
></script>

​
Available Attributes

AttributeValuesDescription
data-website-idRequiredYour website ID from the dashboard
data-api-hostURLOverride API endpoint (default: same origin)
data-exclude-hash"true"Skip tracking hash-only URL changes
data-respect-dnt"false"Ignore DNT/GPC signals (default: respects them)
data-disabled"true"Disable tracking (useful for dev/staging)
data-track-links"true" / "outbound"Track all links or external links only
data-track-scroll-depth"true" / "25,50,75,100"Track scroll milestones
data-track-forms"true"Track form submissions

​
Tracking Custom Events

Use the global window.sparklytics API to track custom events: 
// Track a button click
window.sparklytics?.track('signup_click', { 
  plan: 'pro',
  source: 'hero_cta' 
})

// Track a purchase
window.sparklytics?.track('purchase', {
  product_id: '12345',
  price: 49.99,
  currency: 'USD'
})

// Track without additional data
window.sparklytics?.track('newsletter_signup')
Event names are limited to 50 characters and event data must be less than 4 KB when serialized to JSON.

​
Visitor Identification

By default, Sparklytics generates a privacy-friendly visitor ID based on IP + user agent (rotated daily). You can override this with a stable identifier: 
// After user logs in
window.sparklytics?.identify('user-123')
Custom visitor IDs are stored in localStorage under the key sparklytics_visitor_id and persist across sessions. Maximum length: 64 characters.

​
UTM Parameter Tracking

The snippet automatically captures and persists UTM parameters from the URL:
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content
UTM values are stored in sessionStorage and attached to all events in the same session.

​
SPA Support

The script automatically tracks navigation in single-page applications by:
  1. Intercepting history.pushState and history.replaceState
  2. Listening to popstate events
  3. Sending a new pageview when the URL changes
Works out-of-the-box with React Router, Vue Router, Next.js Pages Router, and other client-side routing libraries.

​
Privacy Features

​
Do Not Track (DNT) Respect

By default, the script respects browser privacy signals:
  • navigator.doNotTrack === '1'
  • navigator.globalPrivacyControl === true
To disable this behavior (not recommended): 
<script 
  defer 
  src="https://analytics.example.com/s.js" 
  data-website-id="abc123"
  data-respect-dnt="false"
></script>

​
No Cookies

Sparklytics never sets cookies. All tracking is cookieless and does not require consent banners in most jurisdictions.

​
Example: Complete Setup

Here’s a production-ready configuration with all features enabled: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome</h1>
  <button onclick="handleSignup()">Sign Up</button>

  <script 
    defer 
    src="https://analytics.example.com/s.js" 
    data-website-id="abc123"
    data-track-links="outbound"
    data-track-scroll-depth="25,50,75,100"
    data-track-forms="true"
  ></script>

  <script>
    function handleSignup() {
      // Track custom event
      window.sparklytics?.track('signup_click', { 
        plan: 'free',
        button_location: 'hero' 
      })

      // ... your signup logic
    }
  </script>
</body>
</html>

​
Next Steps

Next.js SDK

First-class integration for Next.js with automatic route tracking

Custom Integration

Build a custom integration using the API directly

Build docs developers (and LLMs) love

Get started for freeTalk to us