Getting started

Install the script

One tag, on every page. Pageviews, route changes, outbound clicks, scroll depth and Core Web Vitals are recorded without anything else.

Updated All docs as one Markdown file

The tag

Add this to the head of every page, including the signed-in part of your app. The website id is on the install step of each website in the dashboard.

HTML
<script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>
Next.js, in app/layout.tsx
import Script from 'next/script'; <Script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" strategy="afterInteractive" />

Load it once. Every subdomain of the website is the same website, so app.example.com and example.com share one dashboard. Signed in, the Install tab of each website carries a brief for a coding agent with these values filled in, and the same snippets per platform.

The script is 17 kB, 6.5 kB gzipped, and has no dependencies. It is served from this host; if the site has a Content-Security-Policy, allow it in script-src and connect-src.

Where the tag goes, by framework

The only rule is that it loads once on every page. These are the usual places.

Next.js, pages router
// pages/_document.tsx import { Html, Head, Main, NextScript } from 'next/document'; export default function Document() { return ( <Html> <Head> <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" /> </Head> <body><Main /><NextScript /></body> </Html> ); }
Nuxt
// nuxt.config.ts export default defineNuxtConfig({ app: { head: { script: [{ src: 'https://geckostats.com/js/script.js', defer: true, 'data-website-id': '<website-id>' }] } }, });
SvelteKit
<!-- src/app.html --> <head> %sveltekit.head% <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script> </head>
Astro
--- // src/layouts/Layout.astro --- <head> <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script> </head>
Remix / React Router
// app/root.tsx <head> <Meta /> <Links /> <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" /> </head>
WordPress
// functions.php add_action('wp_head', function () { echo '<script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>'; });

Webflow, Framer, Squarespace, Shopify and the like: paste the tag into the site-wide head code setting. A page builder that only offers a body slot is fine too; defer means the tag runs after the page has parsed wherever it is.

Serving the script from your own domain

Some content blockers refuse any analytics host. The script sends events to the origin it was loaded from, so the whole thing can live behind your own domain with two rewrites, and nothing else changes:

Next.js rewrites
// next.config.ts async rewrites() { return [ { source: '/js/script.js', destination: 'https://geckostats.com/js/script.js' }, { source: '/api/event', destination: 'https://geckostats.com/api/event' }, ]; }
Then load it from your domain
<script defer data-website-id="<website-id>" src="/js/script.js"></script>

Any proxy that forwards those two paths does the same. Payments are unaffected either way: they arrive by webhook from the provider, not from the browser.

What it records on its own

  • Pageviews, including route changes in a single-page app: pushState, replaceState and popstate are all pageviews. Do not add pageview calls.
  • Outbound clicks: a link to another domain is recorded as the destination origin and path.
  • Scroll depth: the deepest point reached on each page, only ever counted upwards.
  • Core Web Vitals: LCP, CLS, INP and TTFB from the real visit, attached to the pageview.
  • Engaged time, sent as a heartbeat while the tab is active.

Personal data in a URL, such as ?email= on a payment return page, is stripped before the address leaves the browser.

Attributes

AttributeWhat it does
data-website-idRequired. Which website this is.
data-domainThe root domain when the script runs on a subdomain and you want the parent treated as the same place, such as data-domain="example.com" on app.example.com. Used for the cookie domain in cookie mode and to keep your own domains out of the referrers.
data-apiSend events somewhere other than this host. Rarely needed.
data-allow-localhostRecord visits from localhost. The script ignores them otherwise. For testing; remove it before committing.

Check it is working

Open the site with the browser's developer tools on the Network tab. A POST to https://geckostats.com/api/event answers 202, and the visit is on the dashboard within seconds, on the live globe first.

On localhost, nothing is sent unless the tag carries data-allow-localhost. The install step in the dashboard watches for the first event and says when it has arrived.