Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(analytics): tracker JS + snippet generator (Phase 3)

Juan Denisb61e1d5c184f
diff --git a/backend/tests/test_analytics_extension.py b/backend/tests/test_analytics_extension.py
index de7b77bb..8725a18b 100644
--- a/backend/tests/test_analytics_extension.py
+++ b/backend/tests/test_analytics_extension.py
@@ -689,3 +689,51 @@ def test_rollup_job_handler_never_raises(app):
_mk_plugin_row()
out = jobs_mod.rollup(job=None)
assert 'rows' in out or 'error' in out or 'sites_dates' in out
+
+
+# --------------------------------------------------------------------------- #
+# Phase 3: tracker JS artifact + snippet
+# --------------------------------------------------------------------------- #
+def test_tracker_min_artifact_exists_and_bounded():
+ path = os.path.join(EXT_DIR, 'backend', 'tracker', 'sk.min.js')
+ assert os.path.exists(path), 'run scripts/build-analytics-tracker.mjs'
+ body = open(path, encoding='utf-8').read()
+ assert len(body.encode('utf-8')) < 4096 # <4 KB budget
+ assert '/*' not in body and '*/' not in body # comments stripped
+ assert 'sendBeacon' in body and 'data-site-key' in body
+
+
+def test_tracker_js_serves_real_build(app, analytics_client):
+ bp_mod._TRACKER_CACHE['js'] = None # bypass any placeholder cached earlier
+ resp = analytics_client.get('/api/v1/analytics/tracker.js')
+ assert resp.status_code == 200
+ body = resp.get_data(as_text=True)
+ assert 'placeholder' not in body
+ assert 'sendBeacon' in body
+
+
+def test_snippet_endpoint(app, analytics_client):
+ viewer = _auth(_mk_viewer())
+ site = _mk_site()
+ r = analytics_client.get(f'/api/v1/analytics/sites/{site.id}/snippet',
+ headers=viewer)
+ assert r.status_code == 200
+ body = r.get_json()
+ assert body['site_key'] == site.site_key
+ assert '/api/v1/analytics/tracker.js' in body['tracker_url']
+ assert f'data-site-key="{site.site_key}"' in body['snippet']
+ assert body['snippet'].startswith('<script defer')
+
+
+def test_snippet_outlinks_flag(app, analytics_client):
+ viewer = _auth(_mk_viewer())
+ site = _mk_site()
+ r = analytics_client.get(
+ f'/api/v1/analytics/sites/{site.id}/snippet?outlinks=true', headers=viewer)
+ assert 'data-outlinks="true"' in r.get_json()['snippet']
+
+
+def test_snippet_missing_site_404(app, analytics_client):
+ viewer = _auth(_mk_viewer())
+ r = analytics_client.get('/api/v1/analytics/sites/9999/snippet', headers=viewer)
+ assert r.status_code == 404
diff --git a/builtin-extensions/serverkit-analytics/backend/analytics.py b/builtin-extensions/serverkit-analytics/backend/analytics.py
index 234a633d..4a506351 100644
--- a/builtin-extensions/serverkit-analytics/backend/analytics.py
+++ b/builtin-extensions/serverkit-analytics/backend/analytics.py
@@ -258,6 +258,37 @@ def rotate_key(site_id):
return jsonify(site.to_dict()), 200
+def _panel_base_url():
+ """Best public base URL for the tracker script, preferring a configured
+ public URL over the request host so a copied snippet works off-panel."""
+ from flask import current_app as _app
+ configured = (_app.config.get('SERVERKIT_PUBLIC_URL')
+ or _app.config.get('PUBLIC_URL') or '').strip()
+ if configured:
+ return configured.rstrip('/')
+ return (request.host_url or '').rstrip('/')
+
+
+@analytics_bp.route('/sites/<int:site_id>/snippet', methods=['GET'])
+@viewer_required
+def site_snippet(site_id):
+ """Return the ready-to-paste tracker snippet for a site."""
+ site, err = _site_or_404(site_id)
+ if err:
+ return err
+ tracker_url = f'{_panel_base_url()}/api/v1/analytics/tracker.js'
+ outlinks = str(request.args.get('outlinks', '')).lower() in ('1', 'true', 'yes')
+ attrs = f' src="{tracker_url}" data-site-key="{site.site_key}"'
+ if outlinks:
+ attrs += ' data-outlinks="true"'
+ snippet = f'<script defer{attrs}></script>'
+ return jsonify({
+ 'snippet': snippet,
+ 'tracker_url': tracker_url,
+ 'site_key': site.site_key,
+ }), 200
+
+
# --------------------------------------------------------------------------- #
# report queries (JWT: viewer)
# --------------------------------------------------------------------------- #
diff --git a/builtin-extensions/serverkit-analytics/backend/tracker/sk.js b/builtin-extensions/serverkit-analytics/backend/tracker/sk.js
new file mode 100644
index 00000000..26d24580
--- /dev/null
+++ b/builtin-extensions/serverkit-analytics/backend/tracker/sk.js
@@ -0,0 +1,151 @@
+/* serverkit-analytics tracker (sk.js) — privacy-first, cookieless.
+ Source of truth. Build the served artifact with:
+ node scripts/build-analytics-tracker.mjs
+ which strips comments + trims whitespace into sk.min.js (served by the
+ backend at GET /api/v1/analytics/tracker.js).
+
+ No cookies. No localStorage. No fingerprinting. No third-party calls.
+ Sends one small JSON beacon per pageview via navigator.sendBeacon (text/plain
+ so no CORS preflight), honoring Do Not Track. Fails silently on any error so a
+ disabled/removed panel never breaks the tracked site. */
+(function () {
+ var d = document;
+ var s = d.currentScript;
+ if (!s) { return; }
+
+ var siteKey = s.getAttribute('data-site-key');
+ if (!siteKey) { return; }
+
+ /* Derive the collect endpoint from this script's own URL. */
+ var src = s.src || '';
+ var endpoint = src.replace(/tracker\.js(\?.*)?$/, 'collect');
+ if (endpoint === src) { return; }
+
+ /* Opt-in behaviors via data-* attributes. */
+ var trackOutlinks = s.getAttribute('data-outlinks') === 'true';
+ var honorDnt = s.getAttribute('data-respect-dnt') !== 'false';
+
+ function dntOn() {
+ var v = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
+ return v === '1' || v === 'yes';
+ }
+ if (honorDnt && dntOn()) { return; }
+
+ function screenClass() {
+ var w = window.innerWidth || d.documentElement.clientWidth || 0;
+ if (w < 576) { return 'xs'; }
+ if (w < 768) { return 'sm'; }
+ if (w < 992) { return 'md'; }
+ if (w < 1200) { return 'lg'; }
+ return 'xl';
+ }
+
+ function externalReferrer() {
+ var r = d.referrer;
+ if (!r) { return ''; }
+ try {
+ var u = new URL(r);
+ if (u.host === location.host) { return ''; }
+ return r;
+ } catch (e) { return ''; }
+ }
+
+ function loadMs() {
+ try {
+ var nav = performance.getEntriesByType('navigation')[0];
+ if (nav && nav.duration) { return Math.round(nav.duration); }
+ var t = performance.timing;
+ if (t && t.loadEventEnd && t.navigationStart) {
+ return Math.max(0, t.loadEventEnd - t.navigationStart);
+ }
+ } catch (e) { }
+ return null;
+ }
+
+ function post(body) {
+ var payload = JSON.stringify(body);
+ try {
+ if (navigator.sendBeacon) {
+ var blob = new Blob([payload], { type: 'text/plain' });
+ if (navigator.sendBeacon(endpoint, blob)) { return; }
+ }
+ } catch (e) { }
+ try {
+ fetch(endpoint, {
+ method: 'POST', body: payload, keepalive: true,
+ headers: { 'Content-Type': 'text/plain' }, credentials: 'omit'
+ });
+ } catch (e) { }
+ }
+
+ var firstView = true;
+ function send(type, extra) {
+ var body = {
+ k: siteKey,
+ t: type,
+ p: location.pathname,
+ r: externalReferrer(),
+ s: screenClass(),
+ l: (navigator.language || '').slice(0, 16)
+ };
+ if (type === 'pageview' && firstView) {
+ body.ms = loadMs();
+ firstView = false;
+ }
+ if (extra) {
+ for (var key in extra) {
+ if (Object.prototype.hasOwnProperty.call(extra, key)) {
+ body[key] = extra[key];
+ }
+ }
+ }
+ post(body);
+ }
+
+ function pageview() { send('pageview'); }
+
+ /* SPA navigations: patch history + listen for popstate; fire on path change. */
+ var lastPath = location.pathname;
+ function onNav() {
+ if (location.pathname !== lastPath) {
+ lastPath = location.pathname;
+ pageview();
+ }
+ }
+ function patch(name) {
+ var orig = history[name];
+ if (typeof orig !== 'function') { return; }
+ history[name] = function () {
+ var ret = orig.apply(this, arguments);
+ setTimeout(onNav, 0);
+ return ret;
+ };
+ }
+ patch('pushState');
+ patch('replaceState');
+ window.addEventListener('popstate', onNav);
+
+ /* Optional outbound + download click tracking. */
+ var DOWNLOAD_RE = /\.(zip|rar|7z|gz|tar|pdf|docx?|xlsx?|pptx?|csv|dmg|exe|pkg|apk|mp3|mp4|mov|avi|iso)(\?|$)/i;
+ if (trackOutlinks) {
+ d.addEventListener('click', function (ev) {
+ var a = ev.target && ev.target.closest ? ev.target.closest('a') : null;
+ if (!a || !a.href) { return; }
+ try {
+ var u = new URL(a.href);
+ if (u.host !== location.host) {
+ send('outlink', { n: u.host });
+ } else if (DOWNLOAD_RE.test(u.pathname)) {
+ send('download', { n: u.pathname.slice(0, 128) });
+ }
+ } catch (e) { }
+ }, true);
+ }
+
+ /* First pageview: wait for load so the timing metric is available. */
+ if (d.readyState === 'complete') {
+ pageview();
+ } else {
+ window.addEventListener('load', pageview);
+ }
+})();
diff --git a/builtin-extensions/serverkit-analytics/backend/tracker/sk.min.js b/builtin-extensions/serverkit-analytics/backend/tracker/sk.min.js
new file mode 100644
index 00000000..f51f1d64
--- /dev/null
+++ b/builtin-extensions/serverkit-analytics/backend/tracker/sk.min.js
@@ -0,0 +1,123 @@
+(function () {
+var d = document;
+var s = d.currentScript;
+if (!s) { return; }
+var siteKey = s.getAttribute('data-site-key');
+if (!siteKey) { return; }
+var src = s.src || '';
+var endpoint = src.replace(/tracker\.js(\?.*)?$/, 'collect');
+if (endpoint === src) { return; }
+var trackOutlinks = s.getAttribute('data-outlinks') === 'true';
+var honorDnt = s.getAttribute('data-respect-dnt') !== 'false';
+function dntOn() {
+var v = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
+return v === '1' || v === 'yes';
+}
+if (honorDnt && dntOn()) { return; }
+function screenClass() {
+var w = window.innerWidth || d.documentElement.clientWidth || 0;
+if (w < 576) { return 'xs'; }
+if (w < 768) { return 'sm'; }
+if (w < 992) { return 'md'; }
+if (w < 1200) { return 'lg'; }
+return 'xl';
+}
+function externalReferrer() {
+var r = d.referrer;
+if (!r) { return ''; }
+try {
+var u = new URL(r);
+if (u.host === location.host) { return ''; }
+return r;
+} catch (e) { return ''; }
+}
+function loadMs() {
+try {
+var nav = performance.getEntriesByType('navigation')[0];
+if (nav && nav.duration) { return Math.round(nav.duration); }
+var t = performance.timing;
+if (t && t.loadEventEnd && t.navigationStart) {
+return Math.max(0, t.loadEventEnd - t.navigationStart);
+}
+} catch (e) { }
+return null;
+}
+function post(body) {
+var payload = JSON.stringify(body);
+try {
+if (navigator.sendBeacon) {
+var blob = new Blob([payload], { type: 'text/plain' });
+if (navigator.sendBeacon(endpoint, blob)) { return; }
+}
+} catch (e) { }
+try {
+fetch(endpoint, {
+method: 'POST', body: payload, keepalive: true,
+headers: { 'Content-Type': 'text/plain' }, credentials: 'omit'
+});
+} catch (e) { }
+}
+var firstView = true;
+function send(type, extra) {
+var body = {
+k: siteKey,
+t: type,
+p: location.pathname,
+r: externalReferrer(),
+s: screenClass(),
+l: (navigator.language || '').slice(0, 16)
+};
+if (type === 'pageview' && firstView) {
+body.ms = loadMs();
+firstView = false;
+}
+if (extra) {
+for (var key in extra) {
+if (Object.prototype.hasOwnProperty.call(extra, key)) {
+body[key] = extra[key];
+}
+}
+}
+post(body);
+}
+function pageview() { send('pageview'); }
+var lastPath = location.pathname;
+function onNav() {
+if (location.pathname !== lastPath) {
+lastPath = location.pathname;
+pageview();
+}
+}
+function patch(name) {
+var orig = history[name];
+if (typeof orig !== 'function') { return; }
+history[name] = function () {
+var ret = orig.apply(this, arguments);
+setTimeout(onNav, 0);
+return ret;
+};
+}
+patch('pushState');
+patch('replaceState');
+window.addEventListener('popstate', onNav);
+var DOWNLOAD_RE = /\.(zip|rar|7z|gz|tar|pdf|docx?|xlsx?|pptx?|csv|dmg|exe|pkg|apk|mp3|mp4|mov|avi|iso)(\?|$)/i;
+if (trackOutlinks) {
+d.addEventListener('click', function (ev) {
+var a = ev.target && ev.target.closest ? ev.target.closest('a') : null;
+if (!a || !a.href) { return; }
+try {
+var u = new URL(a.href);
+if (u.host !== location.host) {
+send('outlink', { n: u.host });
+} else if (DOWNLOAD_RE.test(u.pathname)) {
+send('download', { n: u.pathname.slice(0, 128) });
+}
+} catch (e) { }
+}, true);
+}
+if (d.readyState === 'complete') {
+pageview();
+} else {
+window.addEventListener('load', pageview);
+}
+})();
diff --git a/builtin-extensions/serverkit-analytics/dev/test-tracker.html b/builtin-extensions/serverkit-analytics/dev/test-tracker.html
new file mode 100644
index 00000000..3b279865
--- /dev/null
+++ b/builtin-extensions/serverkit-analytics/dev/test-tracker.html
@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>serverkit-analytics tracker — manual test</title>
+ <style>
+ body { font: 15px/1.5 system-ui, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 16px; }
+ fieldset { border: 1px solid #ccc; border-radius: 8px; margin: 16px 0; padding: 12px 16px; }
+ label { display: block; margin: 8px 0 4px; font-weight: 600; }
+ input { width: 100%; padding: 8px; box-sizing: border-box; }
+ button { padding: 8px 14px; margin: 6px 6px 0 0; cursor: pointer; }
+ code { background: #f4f4f4; padding: 1px 5px; border-radius: 4px; }
+ #log { white-space: pre-wrap; background: #111; color: #6f6; padding: 12px; border-radius: 8px; min-height: 80px; }
+ </style>
+</head>
+<body>
+ <h1>serverkit-analytics — tracker smoke test</h1>
+ <p>Loads <code>tracker.js</code> from a dev panel and lets you fire pageviews,
+ SPA navigations, and outbound/download clicks. Open the browser Network tab
+ to watch the beacons to <code>/api/v1/analytics/collect</code>.</p>
+
+ <fieldset>
+ <label for="base">Panel base URL</label>
+ <input id="base" value="http://localhost:47927" />
+ <label for="key">Site key (from Sites tab / POST /sites)</label>
+ <input id="key" placeholder="paste the site_key" />
+ <button id="load">Load tracker</button>
+ </fieldset>
+
+ <fieldset>
+ <strong>Simulate activity</strong><br />
+ <button id="spa">SPA navigate (pushState → /virtual/<random>)</button>
+ <button id="manual">Manual pageview beacon</button>
+ <a id="out" href="https://example.com/" target="_blank" rel="noopener">Outbound link</a>
+ <a id="dl" href="/files/report.pdf">Download-style link</a>
+ </fieldset>
+
+ <label>Event log</label>
+ <div id="log"></div>
+
+ <script>
+ var logEl = document.getElementById('log');
+ function log(m) { logEl.textContent += m + '\n'; }
+
+ document.getElementById('load').addEventListener('click', function () {
+ var base = document.getElementById('base').value.replace(/\/$/, '');
+ var key = document.getElementById('key').value.trim();
+ if (!key) { log('! enter a site key first'); return; }
+ var s = document.createElement('script');
+ s.defer = true;
+ s.src = base + '/api/v1/analytics/tracker.js';
+ s.setAttribute('data-site-key', key);
+ s.setAttribute('data-outlinks', 'true');
+ s.onload = function () { log('tracker.js loaded from ' + s.src); };
+ s.onerror = function () { log('! failed to load tracker.js (panel up? extension enabled?)'); };
+ document.head.appendChild(s);
+ });
+
+ document.getElementById('spa').addEventListener('click', function () {
+ var p = '/virtual/' + Math.floor(Math.random() * 1e6);
+ history.pushState({}, '', p);
+ log('pushState -> ' + p + ' (tracker should send a pageview)');
+ });
+
+ document.getElementById('manual').addEventListener('click', function () {
+ window.dispatchEvent(new Event('load'));
+ log('dispatched load (fires first pageview if not already sent)');
+ });
+ </script>
+</body>
+</html>
diff --git a/scripts/build-analytics-tracker.mjs b/scripts/build-analytics-tracker.mjs
new file mode 100644
index 00000000..9ed6361f
--- /dev/null
+++ b/scripts/build-analytics-tracker.mjs
@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Build the serverkit-analytics tracker artifact.
+ *
+ * node scripts/build-analytics-tracker.mjs # build sk.min.js
+ * node scripts/build-analytics-tracker.mjs --check # fail (exit 1) on drift
+ *
+ * Reads the readable source
+ * builtin-extensions/serverkit-analytics/backend/tracker/sk.js
+ * and writes the served artifact
+ * builtin-extensions/serverkit-analytics/backend/tracker/sk.min.js
+ * (the backend serves it at GET /api/v1/analytics/tracker.js).
+ *
+ * Dependency-free, conservative minification: strip block comments, drop
+ * full-line `//` comments, trim per-line whitespace, drop blank lines. Newlines
+ * between statements are KEPT so ASI can't break. The source is authored to make
+ * this safe (no block-comment tokens inside strings/regex, no inline `//`).
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const DIR = path.join(ROOT, 'builtin-extensions', 'serverkit-analytics',
+ 'backend', 'tracker');
+const SRC = path.join(DIR, 'sk.js');
+const OUT = path.join(DIR, 'sk.min.js');
+
+const CHECK = process.argv.includes('--check');
+
+function minify(src) {
+ // Remove /* ... */ block comments (source avoids these tokens elsewhere).
+ let out = src.replace(/\/\*[\s\S]*?\*\//g, '');
+ const lines = out.split('\n')
+ .map((l) => l.trim())
+ .filter((l) => l.length && !l.startsWith('//'));
+ return lines.join('\n') + '\n';
+}
+
+async function main() {
+ const src = await fs.readFile(SRC, 'utf8');
+ const built = minify(src);
+
+ if (built.includes('/*') || built.includes('*/')) {
+ console.error('Refusing to write: comment tokens survived minification.');
+ process.exit(1);
+ }
+ const bytes = Buffer.byteLength(built, 'utf8');
+
+ if (CHECK) {
+ let current = null;
+ try { current = await fs.readFile(OUT, 'utf8'); } catch { /* missing */ }
+ if (current !== built) {
+ console.error('Tracker artifact drift: sk.min.js is out of date.\n'
+ + 'Run: node scripts/build-analytics-tracker.mjs and commit it.');
+ process.exit(1);
+ }
+ console.log(`sk.min.js in sync (${bytes} bytes).`);
+ return;
+ }
+
+ await fs.writeFile(OUT, built);
+ console.log(`Built sk.min.js (${bytes} bytes, ${(bytes / 1024).toFixed(1)} KB).`);
+ if (bytes > 4096) {
+ console.warn('Warning: tracker exceeds the 4 KB budget.');
+ }
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });