# Events and properties

> Reference for every event and property ClickClacks sets or reserves: $pageview, $click, $scroll and $identify, identity, device, location and campaign properties, visit-level referrer and UTM, and the $ properties the server API accepts.

- Canonical URL: https://clickclacks.io/docs/properties
- Section: Reference
- Last updated: 2026-09-26

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

## Events {#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](https://clickclacks.io/docs/events.md).

## Page and interaction {#page}

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](https://clickclacks.io/docs/properties.md#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 {#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 {#device}

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 {#campaign}

| 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 {#visit-values}

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 {#server}

The [server API](https://clickclacks.io/docs/api.md#properties) 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 {#reserved}

- 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.