Tracking

The MikroAnalytics tracker is intentionally small. It exposes one global, window.mikro, and sends JSON to /api/collect.

Basic Script

<script defer src="https://analytics.example.com/m.js" data-site="site_marketing"></script>

Create the site in the dashboard first, then copy the generated snippet from the Sites view. The install check will show whether the first request was accepted or why it was ignored.

By default, the script:

• sends one pageview on load,
• tracks single-page app navigation through pushState, replaceState, and popstate,
• tracks clicks on elements with data-mikro-event,
• respects Do Not Track and Global Privacy Control signals.

Script Options

<script
  defer
  src="https://analytics.example.com/m.js"
  data-site="site_marketing"
  data-auto="true"
  data-spa="true"
  data-clicks="true"
  data-do-not-track="true"
></script>

Set data-auto="false" when you want to call window.mikro.pageview() yourself. Set data-spa="false" if the application already handles route analytics. Set data-clicks="false" to disable markup-based event tracking.

Custom Events

window.mikro.event("signup", { plan: "team" });

Event names are trimmed, normalized, and limited to 80 characters. Event properties accept strings, numbers, and booleans. Property keys are limited to safe characters, and values are truncated before storage.

Markup Events

<button data-mikro-event="signup_click" data-mikro-prop-plan="team">Start</button>

Every data-mikro-prop-* attribute becomes an event property. Use these for low-risk product actions such as CTA clicks, filter usage, exports, onboarding steps, and feature toggles.

Manual Pageviews

window.mikro.pageview();

The tracker ignores duplicate pageviews for the same path during a session. This keeps SPA route handling from double-counting common navigation flows.

Campaigns and Referrers

The tracker reads ref, utm_source, utm_medium, utm_campaign, utm_term, and utm_content from the current URL. MikroAnalytics stores those values as campaign aggregates, not as full visitor journeys.

Referrers default to origin-only storage. A referrer like https://search.example/results?q=private becomes https://search.example.

Sensitive Data

Do not send names, emails, account IDs, tokens, or customer-specific identifiers as event properties. MikroAnalytics blocks common sensitive property names by default, but the cleanest analytics setup is still to avoid sending them in the first place.

Server-Side Ingestion

The /api/collect endpoint is a plain JSON HTTP endpoint. Any client can call it — not just the browser tracker. This is useful when an internal backend (for example, a Storage API) wants to record product events such as file uploads, batch completions, or background job outcomes.

Protect server-side ingestion with an ingest token

For public browser-only sites, leave the site ingestToken empty. For server-side ingestion, set an ingestToken on the site so that /api/collect requires an x-mikroanalytics-token header matching it.

Create or update a site with an ingestToken using the admin bearer token:

curl \
  -X PUT \
  -H "Authorization: Bearer $MIKROANALYTICS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Storage API","domains":[],"allowedEventProperties":["bucket","status"],"ingestToken":"your-secret-token"}' \
  "https://analytics.example.com/api/sites/site_storage"

Then send events from the backend with the matching header:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-mikroanalytics-token: your-secret-token" \
  -d '{"site":"site_storage","kind":"event","event":"file_uploaded","host":"storage.internal","properties":{"bucket":"media"}}' \
  "https://analytics.example.com/api/collect"

Notes for backend integration

• Host allow-list: if the site has domains configured, the payload host must match one of them. For backends, either leave domains empty (accepts all hosts) or include the service’s host and send it in the host field.
• Privacy signals: do not send DNT: 1 or Sec-GPC: 1 headers — the server honors Do Not Track and Global Privacy Control and will ignore the request otherwise.
• Client dimensions: browser, os, and device are parsed from the request User-Agent. They will be empty or generic for server-side events, which is fine for custom product events but not meaningful as synthetic pageviews.
• Dashboard: the ingest-token field in the site configuration modal is password-style. When a token is already set, the field is blank and says “Token set — leave blank to keep”. Type a new value to replace it, or click “Clear” to remove it.