Events & properties
Named events, automatic vs custom, property enrichment, and where they appear.
Event
An event is a named fact that something happened, optionally with a property bag.
Examples shipped by the SDK (automatic):
$pageview, $click, $form_submitted, $rageclick, $deadclick, $web_vitals
Examples you send (custom):
signed_up, checkout_completed, feature_flag_evaluated
Browser delivery uses tracker.customEvent(name, properties?), which batches to POST /api/ingestion/customEvent/batch (see Custom events).
Properties
Properties are key/value fields on an event (plan: "pro", path: "/pricing"). Prefer JSON-serializable primitives.
Sources of properties
| Source | Controlled by | Examples |
|---|---|---|
| You (custom) | customEvent second argument | plan, price, source |
| Autocapture | Automatic tracking options | tag, text, path, href |
| Automatic enrichment | enableAutomaticProperties (default on) | device_type, browser, os, utm_*, referrer, viewport |
| User traits | identifyUser / setUserProperty | email, name, plan (on the user, not every event) |
| Denylist | propertyDenylist | Keys excluded from automatic enrichment |
Automatic device/location fields come from the SDK property detector (device_type, browser, browser_version, os, screen_resolution, timezone, language, URL/UTM/referrer fields, etc.).
Automatic vs custom
| Kind | Source | Where you notice them |
|---|---|---|
| Automatic | SDK defaults / autocapture | Dashboard Pages/Events, Replay activity, behavioral Issues |
| Custom | Your customEvent calls | Dashboard Custom tab, Funnels, Replay Custom tab |
Naming rules that save pain
- Use one convention (
snake_caseor stabledot.case) and keep it. - Do not rename events after funnels depend on them.
- Put identity in
identifyUser, not only on events. - Avoid colliding with SDK
$…reserved names unless intentional. - Keep property values small — huge strings may be trimmed or drop batches near the 1MB chunk limit on the events path.
Batching & delivery (custom)
| Behavior | Value |
|---|---|
| Debounce flush | 100 ms |
| Max batch size | 50 events |
| Primary endpoint | POST /api/ingestion/customEvent/batch |
| Min-duration hold | Default 5s (minimumDurationMilliseconds) |