Events and properties

Every event and property name ClickClacks sets or reserves, and what each one means. Names starting with $ belong to ClickClacks; everything else is yours.

Updated Sep 26, 2026

Events

Event	Sent by	Meaning
`$pageview`	Tracker	A page load, or a URL change in a single-page app.
`$click`	Tracker	A click, recorded on the nearest link or button. Off when the source’s click autocapture is off.
`$scroll`	Tracker	How far down a page the visitor got, sent when they leave it.
`$identify`	Tracker, server API	An `identify` call: carries `distinct_id` and the traits. Free: not counted toward your monthly events.
`$agent_run, $agent_step`	Server API	Runs and steps of your own AI agents, for Traces. They follow a fixed schema.

Your own events can have any name of 1–128 characters that doesn’t start with $. See Custom events.

Page and interaction

Sent by the tracker with autocaptured events.

Property	Set by	Meaning
`path`	Tracker	Page path and query string, sensitive parameters removed, never the fragment. Shown as “Page”.
`referrer`	Tracker	First pageview of a page load: the referring URL, scrubbed. See visit values.
`$carried_from`	Tracker	First pageview after a link from another listed domain: that domain.
`target_tag`	Tracker	`$click`: the element’s tag name.
`target_id`	Tracker	`$click`: the element’s id, when it has one.
`target_classes`	Tracker	`$click`: up to its first two class names.
`target_text`	Tracker	`$click` on a link or button: up to 40 characters of its text. Never inside form fields or masked areas.
`sel`	Tracker	`$click`: a short CSS selector for the element, at most 64 characters.
`x_pct, y_px`	Tracker	`$click`: position, as a percentage of the page width and pixels from the top.
`max_y_px, doc_h`	Tracker	`$scroll`: the lowest point seen and the page height, in pixels.
`vw`	Tracker	`$click`, `$scroll`: the viewport width in pixels.

Identity

Who an event belongs to, beyond the anonymous browser and session IDs every event carries.

Property	Set by	Meaning
`$distinct_id`	Tracker, server API	Your user ID, on every event sent after `identify` (or with `distinct_id` from the server).
`distinct_id`	Tracker, server API	On `$identify` events: the ID being identified.

Device and location

Added by ClickClacks as events arrive. Values you send under these names from the browser are removed first.

Property	Set by	Meaning
`$country`	ClickClacks	Two-letter country code, from Cloudflare’s network. Absent when unknown. Server events can send it.
`$browser`	ClickClacks	`Chrome`, `Safari`, `Firefox`, `Edge` or `Other`, from the user agent.
`$os`	ClickClacks	`macOS`, `Windows`, `iOS`, `Android`, `Linux` or `Other`.
`$device`	ClickClacks	`desktop`, `mobile` or `tablet`. iPads are counted as tablets.
`$source_id`	ClickClacks	The source the event came in through. Shown as “Source”.
`$ingest_host`	ClickClacks	The hostname the event was received on: `app.clickclacks.io` or your custom domain.
`$ip`	ClickClacks	The visitor’s IP address, only when the source has Record IP address on.

Campaign and referrer

Property	Set by	Meaning
`utm_source, utm_medium, utm_campaign, utm_term, utm_content`	ClickClacks	Read from the query string in `path` (or `$current_url` on server events), up to 200 characters each. A value the event already carries wins.
`$click_id`	ClickClacks	Which ad click IDs were present, such as `gclid,fbclid`. Their values are never kept.

Visit values in reports

In reports, Referrer and the UTM properties mean the visit’s value, on every event of the visit: the referrer the session landed with (empty for a direct visit, shown as “Direct / none”) and the first non-empty UTM value. So a funnel split by utm_campaign credits the campaign that brought the visit, even for events on later pages. The value each event carried itself is still there, under Advanced, as “Referrer (this event)” and “UTM source (this event)” ($event_referrer, $event_utm_source and so on).

Server API properties

The server API accepts these $ keys on its items, and refuses any other.

Property	Set by	Meaning
`$user_agent`	You	Read for `$browser`, `$os`, `$device` and bot filtering, then discarded.
`$current_url`	You	The page URL the event relates to. Campaign properties are read from it.
`$ip`	You	Kept only when the source records IP addresses.
`$country`	You	Two letters, any case.
`$revenue, $currency`	You	An amount (up to 6 decimals) and a three-letter currency code. Always together.
`$groups`	You	Group membership, such as `{ "company": "cmp_311" }`, up to 5 entries. Stored now; group analytics is coming soon.
`$lib, $lib_version`	ClickClacks	The library that sent the event, read from a `User-Agent` of `clickclacks-<name>/<version>`, such as the Node SDK’s.

Reserved names

Event names starting with $ are refused from your code, in the browser and the server API.
From the browser, $country, $browser, $os, $device, $source_id, $ingest_host, $ip and $event_id are removed from what you send, and set by ClickClacks where they apply.
On the server API, any $ property not listed above is refused with reserved_property, and the ones ClickClacks sets itself are removed.
Describe your own events and properties in Lexicon, so every picker in the app shows what they mean.