Custom events

Beyond automatic pageviews, MetriXs tracks custom events — anything you want to measure: button clicks, form submissions, video plays, signups, purchases. Custom events carry their own properties you can attach, and the dashboard breaks them down for you.

Sending custom events

Fire a custom event from your site with the global metrixs() function (available once the tracker script has loaded):

// A custom event with properties
metrixs('Signup', { props: { plan: 'pro', location: 'hero' } })

Option	Type	Default	Description
`name`	`string`	—	The event name. Use `'pageview'` for a manual pageview.
`props`	`object`	`{}`	Custom properties to attach to the event.
`url`	`string`	`location.href`	Override the page URL recorded for this event (useful for SPA route changes).
`interactive`	`boolean`	`true`	Set to `false` for passive signals that should not count as a real interaction (so they don’t lower bounce rate). The built-in scroll-depth/engagement events use this.
`callback`	`function`	—	Called after the event is sent.

// Non-interactive signal — extends visit duration without affecting bounce rate
metrixs('scroll_to_bottom', { props: { article: 'gdpr' }, interactive: false })

Custom events that fire during a visit also extend its measured duration, because duration is calculated as the time between the first pageview and the last event. See Visit duration for why this matters.

Auto-tracked events

The tracker automatically captures three event types — no setup required:

Event name	When it fires	Property
`Outbound Link: Click`	A visitor clicks a link to an external domain	`url`
`File Download`	A visitor clicks a link to a file (pdf, zip, mp4, docx, …)	`url`
`404`	A 404 page — only if the page sets `<meta name="metrixs:404" content="true">`	`path`

These appear in the dashboard in their own Auto-tracked Events card, separate from your user-defined events, so your custom events stay clean.

The lite tracker (tracker.lite.js) omits auto-tracking — pageviews only. Use the full tracker.js if you want outbound links, downloads, and 404s captured.

Viewing custom events in the dashboard

The dashboard shows two cards (only when the site has custom events — they hide otherwise, so there’s no clutter on sites that don’t use them):

Custom Events — your user-defined events.
Auto-tracked Events — outbound links, file downloads, and 404s.

Each row shows the event name and how many times it fired, with a bar scaled to the top event. Click a row to expand it inline and see its property breakdown — every property key with its top values and counts.

Clicking a property value (for example plan = pro) filters the whole dashboard to that segment, just like clicking a page or a country. Remove the filter from the filter bar at the top.

How properties are stored

Custom event properties are stored in ClickHouse as parallel meta.key / meta.value arrays (one row per event). The dashboard discovers the property keys per event with a dedicated POST /api/v2/event-props endpoint (the main query builder can’t enumerate unknown keys), then reads each value via the event:props:<key> dimension. Property keys are whitelisted to ^[a-zA-Z0-9_-]+$ — stick to letters, numbers, dashes, and underscores.