Features

Tracking features, script tag options, JS API, live dashboard, and SPA support.

Script Tag

Basic embed — add to any HTML page:

<script async src="https://your-host/ea.js" data-site="my-site"></script>

Script Attributes

All behavioral tracking is enabled by default. Use data-no-* attributes to selectively disable features.

Selective Opt-Out

<script async src="https://your-host/ea.js"
  data-site="my-site"
  data-no-hover
  data-no-vitals></script>

HTML Element Markup

Annotate elements to track specific interactions:

Click Tracking

Enabled by default. Disable with data-no-clicks on the script tag.

<button data-echelon-click="signup-cta">Sign Up</button>

Hover Tracking

Enabled by default. Fires after 1 second of hover. Disable with data-no-hover on the script tag.

<div data-echelon-hover="pricing-card">...</div>

Form Tracking

Enabled by default. Tracks three levels of form interaction. Disable with data-no-forms on the script tag.

Optionally label forms for easier identification in the dashboard:

<form data-echelon-form="contact-form">...</form>

Custom Data Attributes

Any data-echelon-* attribute on annotated elements is included in event data (max 8 keys, max 256 chars per value).

<button data-echelon-click="buy"
  data-echelon-product="widget"
  data-echelon-price="9.99">Buy Now</button>

JavaScript API

Send custom events programmatically:

window.echelon.track("event_name", {
  key: "value",
  another: "prop"
});

Limits: max 16 properties, key max 64 chars, value max 512 chars.

Auto-Tracked Events

These fire automatically — no configuration needed:

SPA Support

The tracker automatically patches pushState, replaceState, and listens for popstate events. When the route changes, a new pageview beacon fires automatically. No configuration needed for React Router, Vue Router, SvelteKit, Fresh, or any other SPA framework.

🧭 "Did you know the tracker automatically detects route changes in React, Vue, Svelte, and Fresh without any configuration? Just add the script tag and pageviews fire on every navigation." -🦭

UTM Campaign Tracking

Echelon tracks all five standard UTM parameters. Attribution is session-scoped and persisted across page loads.

Supported Parameters

How It Works

1. Visitor arrives with UTM parameters in the URL:
   https://example.com/pricing?utm_campaign=spring-2026&utm_source=newsletter&utm_medium=email
2. Tracker extracts all five UTM params and stores them in sessionStorage (key: _eutm).
3. Every pageview beacon (/b.gif) includes the UTM parameters for the rest of the session — even when the visitor navigates to pages without UTM in the URL.
4. SPA navigation: On route changes (pushState/replaceState), the tracker re-reads URL params. If the new URL has a utm_campaign, it updates the session. Otherwise, the stored values persist.
5. Server validates: The beacon endpoint checks utm_campaign against a whitelist of active campaigns (refreshed every 60 seconds from the database). Unknown campaigns are silently dropped — only registered, active campaigns record UTM data.

Setting Up Campaigns

Campaigns must be registered before they appear in stats. Create them via the admin dashboard or the API:

Admin Dashboard

Navigate to /admin/campaigns and fill in the form:

• ID — URL-safe slug (alphanumeric, ., _, -), e.g. spring-2026
• Name — Human-readable label, e.g. Spring Launch 2026
• UTM Campaign — Exact value that will appear in URLs, e.g. spring-2026
• Site ID — Scope to a specific site (defaults to default)

API

POST /api/campaigns
Authorization: Bearer <token>

{
  "id": "spring-2026",
  "name": "Spring Launch 2026",
  "utm_campaign": "spring-2026",
  "site_id": "default"
}

Campaign Lifecycle

Change status via PATCH /api/campaigns/:id with { "status": "paused" }, or use the buttons on the campaign detail page.

Campaign Stats

The campaign detail page (and GET /api/stats/campaigns?id=X) shows:

• Summary — Total views and unique visitors for the campaign
• By Source — Breakdown by utm_source (views + visitors)
• By Medium — Breakdown by utm_medium
• By Content — Breakdown by utm_content
• By Term — Breakdown by utm_term
• Daily Trend — Views per day over the selected period
• Top Landing Pages — Pages visitors entered through

All stats exclude bot traffic (bot_score ≥ 50). Default lookback is 30 days (max 90).

https://example.com/sale?utm_campaign=spring-2026&utm_source=newsletter&utm_medium=email&utm_content=hero-cta

📊 "Tip: The campaign whitelist prevents spam traffic from polluting your stats. If a crawler hits your URL with a random utm_campaign, it gets quietly dropped because there's no matching active campaign." -🦭

A/B Experiments

Run split tests to measure the impact of changes. Echelon tracks impressions, conversions, and calculates statistical significance automatically.

How It Works

1. Create an experiment with variants and a conversion metric (event type to measure)
2. Your application assigns visitors to variants and sends events with experiment attribution
3. Echelon counts unique sessions per variant (impressions) and sessions that triggered the metric event (conversions)
4. Statistical significance is calculated automatically using a two-proportion z-test

Creating an Experiment

Admin Dashboard

Navigate to /admin/experiments and fill in the form:

• Experiment ID — URL-safe slug, e.g. checkout-v2
• Name — Human-readable label, e.g. Checkout Redesign
• Description — Optional context
• Metric Event Type — The event type that counts as a conversion, e.g. purchase, signup, click
• Allocation % — Percentage of traffic enrolled in the experiment (1–100, default 100)
• Variants — At least 2, up to 20. Each has an ID, name, weight, and a control flag

API

POST /api/experiments
Authorization: Bearer <token>

{
  "experiment_id": "checkout-v2",
  "name": "Checkout Redesign",
  "description": "Test new checkout flow vs original",
  "metric_event_type": "purchase",
  "allocation_percent": 100,
  "variants": [
    { "variant_id": "control", "name": "Original", "weight": 50, "is_control": true },
    { "variant_id": "redesign", "name": "New Flow", "weight": 50 }
  ]
}

Variant Weights

Weights are relative, not percentages. Two variants with weights 50/50 each get 50% of traffic. Weights of 1/1 or 100/100 produce the same split. Three variants with weights 2/1/1 get 50%/25%/25%.

Your application is responsible for reading the weights and assigning visitors to variants (e.g. using a hash of the visitor ID modulo total weight). Echelon stores the weights but does not perform assignment — this keeps the system flexible for any frontend framework.

Sending Experiment Events

Include experiment_id and variant_id in your event data. Use the JavaScript API:

// Track an impression (user saw the variant)
window.echelon.track("page_view", {
  experiment_id: "checkout-v2",
  variant_id: "redesign"
});

// Track a conversion (user completed the goal)
window.echelon.track("purchase", {
  experiment_id: "checkout-v2",
  variant_id: "redesign"
});

Both fields are stored in the semantic_events table. Echelon counts:

• Impressions — Unique sessions that sent any event for the experiment+variant
• Conversions — Unique sessions that sent the metric_event_type event for the experiment+variant

Experiment Lifecycle

Change status via PATCH /api/experiments/:id with { "status": "active" }.

Reading Results

The experiment detail page (and GET /api/stats/experiments?experiment_id=X) shows per-variant:

Statistical Significance

Echelon uses a two-proportion z-test to determine if differences between variants are statistically significant:

1. Calculate pooled proportion: p = (conversions_control + conversions_variant) / (impressions_control + impressions_variant)
2. Calculate standard error: SE = √(p × (1-p) × (1/n1 + 1/n2))
3. Calculate z-score: z = |rate_variant - rate_control| / SE

Minimum data: At least 100 impressions per variant are required before significance is calculated. Below this threshold, results show "Insufficient data".

🧪 "Wait for at least 95% significance before declaring a winner. Early results often flip as more data comes in." -🦭

Cookieless by Default

Without data-cookie, visitors are identified by a daily-rotating HMAC-SHA256 hash of IP + User-Agent + site ID + date. This produces a 16-character hex identifier that:

• Resets every day — no cross-day tracking
• Cannot be reversed to recover the original IP
• Requires no cookie consent (GDPR/ePrivacy compliant)

Add data-cookie to enable a persistent visitor cookie for returning visitor tracking.

Admin Dashboard

The admin UI at /admin/ provides a full-featured analytics dashboard:

• Persistent site selector and date range picker in navigation
• Overview with KPIs, daily trends, top pages, devices, countries, referrers
• Realtime visitor monitoring
• Visitor views listing — filterable, sortable, paginated
• Bot management — suspicious visitors, exclude/include controls
• A/B experiments — create, manage, view conversion uplift
• UTM campaigns — track and break down by source, medium, content
• Performance metrics — CI/CD benchmark tracking with trends
• Configurable timezone display for all admin timestamps

Future Plans

No roadmap exists. This project is built for personal use. It might get worked on, it might not. If you find it interesting you're welcome to fork it, open pull requests, or contribute — just work within the AGPL-3.0 license.

Known ideas on the horizon:

• MariaDB/PostgreSQL support if SQLite ever becomes a bottleneck. It probably won't.
• Ad system integration — Google AdSense, Meta Ads, and other ad platform tracking may be integrated at a later date to correlate ad spend with analytics data.
• MCP write tools — The MCP server is currently read-only by design. Write tools (campaign/experiment management) may be added in a future version.