WebmasterID logoWebmasterID

Docs

Events reference

Every event the WebmasterID tracker can record, what it contains, and what it deliberately does not contain.

Last updated: v1.5.2 · 2026-05-10

The browser tracker records a small, fixed vocabulary of events. Some are recorded automatically (every page view, every outbound link click, every download click). Others fire only when you tag an element declaratively — that is the v0.9 design choice that keeps the tracker lightweight and operator-controlled.

Automatic events

These fire without any tagging — they're built into the tracker.

page_view

  • Fires once per real navigation.
  • Captures: url, pathname, referrer (when the browser provides one), the five canonical UTM parameters, the document title, the browser language string, and the screen width.
  • Anonymised at ingest: source IP is anonymised before storage (IPv4 last octet zeroed, IPv6 truncated to /48). Raw IPs never reach the database.
  • Visible on the dashboard at /events and rolled up on Overview.

outbound_click

  • Fires when the visitor clicks an <a> whose href resolves to a different host than the current page.
  • Captures: the destination URL.
  • If the link also carries data-wmid-cta, the CTA id rides along on the same event so you can correlate which CTA drove the outbound click.

download

  • Fires when the visitor clicks a link whose href ends in a known downloadable extension (PDF, ZIP, CSV, etc.).
  • Captures: the asset URL.
  • If tagged with data-wmid-cta, the CTA id rides along.

bot_visit (server-side classification)

  • NOT a browser event. The ingest API classifies the request's User-Agent at write time and routes recognised bots into a separate bot_visits table.
  • Eight bot categories (v1.0): ai_crawler, search_crawler, social_preview_bot, seo_tool_bot, uptime_monitor, security_scanner, automation_tool, unknown_bot.
  • Bots are NEVER mixed into human metrics. The dashboard's /bot-intelligence surface visualises bot activity separately from human events.

Declarative / tagged events

These fire only when you mark an element with a known data-wmid-* attribute. That keeps the tracker out of guessing-business and gives you stable, semantic event ids you control.

cta_click

Tag the element with data-wmid-cta="<id>".

<a href="/pricing" data-wmid-cta="hero-pricing">View pricing</a>
<button data-wmid-cta="install-snippet-copy">Copy snippet</button>
  • The CTA id is the value you'll see on /events. Use stable, semantic ids (hero-pricing, pricing-get-started).
  • Aliases are accepted: data-cta-id and data-wmid-event-id resolve to the same field.
  • See /docs/cta-tracking for the full pattern.

form_submit

Tag the <form> with data-wmid-form="<id>".

<form data-wmid-form="contact" action="/api/contact" method="POST">
  ...
</form>
  • Captures the form id only. WebmasterID never serialises form field values.

signup / purchase (declarative)

Use data-wmid-event="signup" or data-wmid-event="purchase" on the element whose click should record the event. Strict allowlist — arbitrary event names are silently ignored.

<button data-wmid-event="signup" data-wmid-cta="hero-signup">
  Start free trial
</button>

<button
  data-wmid-event="purchase"
  data-wmid-value="29.00"
  data-wmid-currency="USD"
  data-wmid-product="pro_monthly"
  data-wmid-plan="pro"
>
  Subscribe — $29/month
</button>
  • Optional purchase extras: data-wmid-value (numeric, 0..1e9), data-wmid-currency (max 8 chars), data-wmid-product / data-wmid-plan / data-wmid-source (max 128 chars each).
  • The declarative event always wins over URL-based classification (so a tagged outbound link that's really a signup CTA fires signup, not outbound_click).
  • One event per click. The tracker dedupes within a 750 ms window.

Server-side events

The schema also accepts a small set of server-side event names (signup, download, app_install_click, lead_submit, template_download, tool_usage, conversion, purchase) for future server-to-server ingestion. That path requires server-side secret material that lives only on your server and never ships to the browser.

What is NEVER collected

  • No third-party cookies.
  • No localStorage tracking, no persistent visitor IDs.
  • No fingerprinting (canvas, audio, fonts, device entropy).
  • No session replay, no DOM/input recordings.
  • No raw IPs in the database.
  • No advertising audience exports.
  • No gclid, no fbclid. Strict utm_*-only attribution.

DNT / GPC

Requests carrying DNT: 1 or the Sec-GPC: 1 header are honoured at ingest: the request returns HTTP 204 with no work performed.

Related