Documentation

Everything you need to set up and use HushStats.

Quick Start

1. Create an account

Sign up for free — no credit card required.

2. Add your site

Go to your dashboard and click "Add Site". Enter your domain (e.g. example.com).

3. Install the tracking script

Copy the script tag from your site settings and paste it into the <head> of your website: 

<script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>

4. View your analytics

Data appears within seconds. Visit your site, then check the dashboard.

Tracking Script Reference

Basic installation

<script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>

Place this in the <head> of every page. If you use a shared layout or template, you only need to add it once.

How it works

  • The script is under 1 KB gzipped and loads asynchronously — it won't slow your site down.
  • It sends a single GET request per pageview to hushstats.com/api/collect.
  • No cookies are set. No localStorage is used. No fingerprinting occurs.
  • Unique visitors are estimated using a privacy-safe method based on the If-Modified-Since header — no personal data is stored.
  • The script automatically captures: page URL, referrer, country (from IP, which is not stored), browser, device type, and screen size.

Single-page apps (SPA)

The tracker automatically detects pushState navigation. Works out of the box with React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, and other SPA frameworks.

Excluding traffic

To exclude your own visits during development, add localStorage.setItem('hushstats_ignore', '1') in your browser console. The tracker will skip sending data for that browser.

Content Security Policy

If your site uses a CSP, add these directives: 

script-src https://hushstats.com; connect-src https://hushstats.com;

Framework Guides

HTML / Static Sites

Add the script tag to your HTML <head>.

<head>
  <script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>
</head>

Next.js

Add to app/layout.tsx or pages/_app.tsx:

import Script from 'next/script'

<Script
  defer
  src="https://hushstats.com/tracker.js"
  data-site-id="YOUR_SITE_ID"
  strategy="afterInteractive"
/>

Astro

Add to your base layout's <head>:

<head>
  <script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>
</head>

WordPress

Add to your theme's functions.php:

function hushstats_script() {
  echo '<script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>';
}
add_action('wp_head', 'hushstats_script');

Vue / Nuxt

In Nuxt, add to nuxt.config.ts:

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { src: 'https://hushstats.com/tracker.js', defer: true, 'data-site-id': 'YOUR_SITE_ID' }
      ]
    }
  }
})

SvelteKit

Add to src/app.html:

<head>
  <script defer src="https://hushstats.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>
</head>

Gatsby

Add to gatsby-ssr.js:

export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
      key="hushstats"
      defer
      src="https://hushstats.com/tracker.js"
      data-site-id="YOUR_SITE_ID"
    />,
  ]);
};

Dashboard

Your dashboard shows analytics for each site you've added:

Overview

  • Smart Insights — AI-powered analysis comparing current period to previous period, surfacing traffic trends, bounce rate changes, new top pages, and more
  • Visitors & Pageviews — Estimated unique visitors and total page loads
  • Bounce rate — Percentage of single-page visits
  • Avg. Visit Duration — How long visitors spend on your site
  • Real-time visitors — Live count of people on your site right now
  • Time chart — Pageviews over time (hourly or daily) with annotation markers

Pages tab

  • Top pages — Most visited pages by total views
  • Entry pages — Landing pages where visitors first arrive
  • Page Performance Scores — Each page scored 0-100 based on popularity, engagement (bounce rate), and depth (time on page)

Sources tab

  • Referrers — Where your traffic comes from
  • UTM Sources & Campaigns — Track marketing campaigns with UTM parameters

Geo & Tech tab

  • Countries — Geographic distribution of visitors
  • Browsers, OS, Devices — What your visitors are using
  • Screen Sizes — Viewport breakdown of your audience

Events tab

  • Custom events — Track button clicks, signups, and other actions
  • Outbound links — Auto-tracked external link clicks
  • File downloads — Auto-tracked .pdf, .zip, .dmg, etc. downloads
  • 404 errors — Auto-detected broken pages on your site

Performance tab

  • Core Web Vitals — LCP (loading speed), CLS (visual stability), INP (interactivity) with Good/Needs Work/Poor ratings
  • Scroll Depth — See how far visitors scroll — 25%, 50%, 75%, or 100%
  • Public Stats Badge — Embeddable SVG badge showing live visitor count for your README or website

Use the time range selector to view data for today, 7 days, 30 days, or 90 days. Add annotations to mark launches, campaigns, or other important events on your timeline.

Custom Events

Sending custom events

Track button clicks, signups, purchases, or any custom action: 

// Track a custom event
window.hushstats.event('signup', 'pro-plan');

// Track a button click
document.querySelector('#cta').addEventListener('click', () => {
  window.hushstats.event('click', 'hero-cta');
});

Automatic event tracking

The tracker automatically captures these events without any code:

  • Outbound links — Clicks on links to external domains
  • File downloads — Clicks on .pdf, .zip, .dmg, .exe, .doc, .xls, .ppt, .csv links
  • 404 errors — Pages that include a <meta name="hushstats-status" content="404"> tag

404 error tracking setup

Add this meta tag to your 404 error page: 

<meta name="hushstats-status" content="404">

Timeline Annotations

Mark important events on your analytics timeline — product launches, blog posts, marketing campaigns, or outages. Annotations appear as badges below your time series chart, making it easy to correlate traffic changes with real-world events.

To add an annotation, expand the "+ Add annotation" section below your chart, pick a date, write a short note (max 280 characters), and click Add.

Billing

Billing is handled through Stripe. You can upgrade, downgrade, or cancel anytime from your dashboard.

  • Upgrading — Takes effect immediately. You're charged a prorated amount.
  • Downgrading — Takes effect at the end of your current billing period.
  • Canceling — Your plan remains active until the end of the billing period, then reverts to Free.

Privacy & Compliance

HushStats is designed to be compliant with privacy regulations by default:

  • GDPR — No personal data is collected. No consent banner required.
  • CCPA — No personal information is sold or shared.
  • PECR — No cookies or similar technologies are used.

We don't collect IP addresses, don't set cookies, don't use fingerprinting, and don't build individual user profiles. The data we collect (page URL, referrer, country, browser, device) is aggregate by nature and cannot be used to identify individuals.

Support

Need help? Email us at hello@hushstats.com. Pro and Business customers get priority response times.