Tracking Snippet

The self-hosted Statalog tracking script works identically to the Cloud version, with one difference: the script is served from your own domain instead of app.statalog.com.

The snippet

Place this snippet in the <head> of every page you want to track, replacing yourdomain.com with your actual Statalog installation domain and ST-XXXXXX with your site ID:

<script async src="https://yourdomain.com/st.js" data-site="ST-XXXXXX"></script>

The async attribute means the script loads in the background and does not block page rendering. The data-site attribute tells the script which site to attribute pageviews to.

Finding your site ID

Your site ID is displayed in two places:

  1. Dashboard header — shown in the URL when you are viewing your site's dashboard, e.g. https://yourdomain.com/sites/ST-XXXXXX/dashboard
  2. Account → Websites → [site name] → Tracking Snippet — the full snippet with your site ID pre-filled is shown here

The site ID format is ST- followed by six alphanumeric characters.

How the tracker works

When the script loads, it sends a POST request to /api/collect on your Statalog domain, passing the current page URL, referrer, screen width, and timestamp. The server records the pageview asynchronously and returns immediately — the tracker has no visible impact on page load time.

The script itself is approximately 3 KB (minified and gzip-compressed). It is served with a one-hour cache header so repeat visitors load it from their browser cache.

Noscript fallback (pixel endpoint)

For visitors who have JavaScript disabled, a one-pixel image fallback can capture basic pageview data. Add this inside a <noscript> tag immediately after the main script tag:

<noscript>
  <img src="https://yourdomain.com/api/pixel?site_id=ST-XXXXXX&url=/your-page" 
       width="1" height="1" alt="" style="display:none" />
</noscript>

The pixel endpoint records a minimal pageview (URL and timestamp only — no referrer or device data, since JavaScript is not available). The url parameter should match the canonical URL of the current page.

Verifying tracking is working

Network tab method: Open your browser DevTools, navigate to the Network tab, and reload the page. Look for a request to /api/collect on your Statalog domain. It should return HTTP 200. If it returns 404, the web server is not routing the API request to Statalog. If it returns 422, check that the data-site attribute contains a valid site ID.

Health check endpoint: Your Statalog installation exposes a health endpoint at:

https://yourdomain.com/api/health

It returns {"status": "ok"} if the application, database, and ClickHouse connections are all healthy. A non-200 response or an error field in the JSON body indicates a configuration problem.

Live view: Go to your Statalog dashboard and open the Live tab. Open your website in another browser tab. A visitor count of at least 1 should appear within a few seconds.

CORS

The /api/collect endpoint accepts cross-origin requests from any domain by default. This is intentional — the tracker runs on your visitors' browsers, which are on your website's domain, not your Statalog domain. No additional CORS configuration is needed.

Content Security Policy (CSP)

If your website sends a Content-Security-Policy header, you need to explicitly allow the Statalog script to load and the collect endpoint to be reached.

Add your Statalog domain to the relevant directives:

Content-Security-Policy:
  script-src 'self' https://yourdomain.com;
  connect-src 'self' https://yourdomain.com;

If you use a <meta> CSP tag instead of a header, the same directive values apply. Without these additions, browsers will block the script from loading or block the /api/collect request, and no pageviews will be recorded.

Excluding your own visits

To exclude your own visits from analytics while developing or testing, you can use the built-in exclusion mechanism. Open your browser's JavaScript console on any page with the tracking snippet and run:

localStorage.setItem('statalog_ignore', '1');

The tracker checks for this key on every load and skips sending the pageview if it is set. To re-enable tracking for your browser:

localStorage.removeItem('statalog_ignore');

This exclusion is per-browser — it does not affect other visitors.