Documentation

Everything you need to set up and use INSG.

Quick Start

1. Create an account

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://sbda.io/t/YOUR_SITE_ID.js"></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://sbda.io/t/YOUR_SITE_ID.js"></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 loads asynchronously and includes all modules enabled by default when using the dynamic tracker URL /t/YOUR_SITE_ID.js — it won't slow your site down.
It sends a lightweight request per pageview to the edge, plus small event beacons as visitors interact (scroll, click, etc.).
No cookies are set. No fingerprinting occurs. No directly identifying data is stored — no names, emails, IP addresses, or persistent identifiers.
Unique visitors are counted using a one-way hash of the visitor's IP address, User-Agent, and a daily rotating salt. The hash is irreversible — the original IP cannot be recovered. The salt rotates every 24 hours, making cross-day tracking impossible by design. No IP addresses or persistent identifiers are ever stored.
The tracker automatically captures: page URL, referrer, country (geo-IP resolved at the edge by the SBDA engine — the IP itself is never stored), browser, device type, and screen size.
Bot traffic is automatically filtered — the SBDA engine drops known crawlers, scrapers, headless browsers, and monitoring services server-side before any data is stored. AI bots (GPTBot, ClaudeBot, etc.) are tracked separately as their own channel.

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('insg_ignore', '1') in your browser console. The tracker reads this flag but never writes to localStorage or any other client storage. When the flag is set, the tracker will skip sending data for that browser.

Content Security Policy

If your site uses a CSP, add these directives:

script-src https://sbda.io; img-src https://sbda.io;

Framework Guides

HTML / Static Sites

Add the script tag to your HTML <head>.

<head>
  <script defer src="https://sbda.io/t/YOUR_SITE_ID.js"></script>
</head>

Next.js

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

import Script from 'next/script'

<Script
  defer
  src="https://sbda.io/t/YOUR_SITE_ID.js"
  strategy="afterInteractive"
/>

Astro

Add to your base layout's <head>:

<head>
  <script defer src="https://sbda.io/t/YOUR_SITE_ID.js"></script>
</head>

WordPress

Use the INSG WordPress plugin for zero-config installation with WooCommerce auto-detection, heatmap proxy, and automatic updates.

Vue / Nuxt

In Nuxt, add to nuxt.config.ts:

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { src: 'https://sbda.io/t/YOUR_SITE_ID.js', defer: true }
      ]
    }
  }
})

SvelteKit

Add to src/app.html:

<head>
  <script defer src="https://sbda.io/t/YOUR_SITE_ID.js"></script>
</head>

Gatsby

Add to gatsby-ssr.js:

export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
      key="insg"
      defer
      src="https://sbda.io/t/YOUR_SITE_ID.js"
    />,
  ]);
};

Dashboard

Your dashboard organizes analytics across six tabs:

Overview

Top revenue leaks, highest-confidence diagnoses surfaced by the SBDA engine, and the next fixes your team should make.

Revenue Leaks

All active findings ranked by the SBDA engine's combined impact and confidence score.

Behavior

Evidence-first behavior analysis by the SBDA engine: click heatmaps, rage/dead click detection, scroll depth, reading speed classification, and more.

Diagnosis

SBDA diagnostic reasoning — the engine evaluates each finding against behavioral evidence, performs contradiction checks, and computes confidence scores.

Actions

Recommended fixes generated by the SBDA engine, grouped by effort and likely payoff.

Technology

Browser, device, Web Vitals, JS errors, network quality, and active hours.

Interactive filtering

Click on any page, referrer, country, browser, or device in the lists to filter the entire dashboard by that value. Active filters appear as blue pills at the top — click the X to remove.

CSV export

Click "Export CSV" in the top bar to download your analytics data as a CSV file. The export includes time series, top pages, referrers, countries, and browsers.

Public dashboards

Share a read-only version of your analytics with anyone. Toggle the "Public Dashboard" switch and share the link. Public dashboards show all stats but don't allow annotation editing or configuration changes.

Stats badge

Embed a live visitor count SVG badge on your website or GitHub README.

What the Tracker Captures Automatically

The tracker handles all of this out of the box — no extra JavaScript, no configuration. Just add the script tag and everything works:

Core (always on)

Pageviews & visitors — Every page load, with referrer, UTM parameters, and screen size
Session tracking — Session grouping is handled entirely server-side using the daily visitor hash. No session token, cookie, or persistent ID is stored in the browser. The hash resets at midnight UTC.
Attention & duration — Time spent on page, adjusted for tab switches
SPA navigation — Detects pushState/popstate for React, Vue, Svelte, etc.
UTM attribution — The tracker captures UTM parameters and the SBDA engine stores first-touch attribution automatically

Interaction modules (automatic)

Outbound links — Clicks on links to external domains
File downloads — Clicks on .pdf, .zip, .dmg, .exe, .doc, .xls, .csv, and more
Rage clicks — The SBDA engine detects frustrated click patterns that indicate something isn't working
Dead clicks — The SBDA engine detects clicks that go nowhere, revealing broken or misleading UI elements
Copy tracking — When visitors copy text from your pages

Engagement modules (automatic)

Scroll depth — 25%, 50%, 75%, 100% milestones
Scroll hesitation — The SBDA engine detects points where visitors lose momentum or get confused
Reading speed — The SBDA engine classifies visitors as readers, skimmers, or scanners based on their engagement patterns

Performance modules (automatic)

Core Web Vitals — LCP, CLS, INP sent automatically on page exit

Advanced modules (automatic)

Hover aggregates — Tracks which elements visitors hover over and for how long
CTA visibility — Measures how long call-to-action elements are visible in the viewport
Keyboard interactions — Detects Tab navigation, Enter presses, and keyboard shortcut usage
JS error counts — Captures unhandled JavaScript errors per page without storing stack traces
Network hints — Records connection type and effective bandwidth for performance correlation
Mobile insights — Touch gesture patterns, orientation changes, and viewport resize events
Click heatmap — Aggregated click coordinates for visual heatmap overlays
Product page intelligence — The SBDA engine detects product pages and analyzes add-to-cart, variant selection, and image gallery interactions

404 detection (one meta tag)

The only thing that requires any setup. Add this meta tag to your 404 error page:

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

Custom events (optional JS)

For tracking business-specific actions like signups or purchases, the tracker exposes a simple API. This is the only part that requires writing JavaScript:

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

// Track a purchase
window.insg.event('purchase', JSON.stringify({plan: 'pro', price: 10}));

Custom events appear in the Events tab on your dashboard.

Revenue attribution (optional, 2 lines)

To connect Stripe revenue to traffic sources, pass attribution data to your checkout:

const attribution = window.insg.getAttribution();
// Pass as metadata to your Stripe checkout session

The tracker captures UTM parameters and the SBDA engine stores first-touch attribution data. You just retrieve it at checkout time.

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

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

GDPR — No directly identifying data is stored — no names, emails, IP addresses, or persistent identifiers. No consent banner required because we don't use cookies or client-side storage.
CCPA — No personal information is sold or shared.
PECR — No cookies or similar technologies are used.

IP addresses are processed transiently in server memory, combined with the visitor's User-Agent and a daily rotating salt, then fed into a one-way hash function. The resulting anonymous identifier is used for visitor counting. The IP is never stored, logged, or recoverable from the hash output. The salt rotates every 24 hours, preventing cross-day tracking. We don't set cookies, don't use fingerprinting, and don't build individual user profiles. The data we store (page URL, referrer, country, browser, device) is aggregate by nature and cannot be used to identify individuals.

Cart Rescue Nudge Pro

Cart Rescue Nudge automatically detects hesitant shoppers and offers a one-time discount to convert them. Available on the Pro plan (accessible during the 30-day trial).

How it works: INSG's behavioral tracker watches for shoppers who visit their cart 3+ times in a session, combined with hesitation signals like scroll pauses, rage clicks, or extended dwell time on the cart page. When the threshold is met and anti-gaming gates pass (randomized probability, daily store cap, one-per-visitor limit), a non-intrusive banner slides up with a unique discount code.

Discount codes: Codes are created on-demand via the Shopify Admin API — not pre-created when you enable the feature. Each code is single-use, time-limited (configurable 15–120 minutes), and capped at 5–25% off. Expired codes are automatically deleted so they don't clutter your Shopify Discounts page.

Settings you control: Discount percentage (5–25%), show probability (10–50%), daily limit (10–500 nudges/day), code expiry time (15–120 minutes), and the banner message text.

Conversion tracking: INSG tracks the full funnel — nudge shown, code clicked/copied, purchase completed with the code. Revenue recovered and conversion rate are displayed in the Nudge Performance panel.

Privacy: Zero personal data is used. The visitor is identified by the same anonymous daily-rotating hash used for all INSG analytics. No emails, names, or account data. Fully GDPR/CCPA compliant.

Support

Need help? Email us at hello@insg.io. Standard and Pro customers get priority response times.