Well-Known Events
Standard event names with typed property schemas, validated by SDKs and the backend at ingestion time. Using well-known events gives you TypeScript types, schema validation, and built-in dashboard templates.
Custom event names (any other string) are accepted without validation.
Event index
| Event | Category | Description |
|---|---|---|
page_view | Navigation | Page or screen view |
click | Engagement | Element click |
scroll | Engagement | Scroll depth milestone |
form_submit | Engagement | Form submission |
form_field | Engagement | Form field interaction |
rage_click | UX | Repeated clicks on non-responsive element |
dead_click | UX | Click with no response |
signup | Identity | User registration completed |
login | Identity | User sign-in |
search | Engagement | Search query submitted |
product_viewed | Commerce | Product detail view |
add_to_cart | Commerce | Item added to cart |
remove_from_cart | Commerce | Item removed from cart |
checkout_started | Commerce | Checkout flow initiated |
purchase | Commerce | Completed purchase |
Schemas
page_view
Auto-tracked by the Web SDK on navigation and SPA route changes.
| Property | Type | Required | Description |
|---|---|---|---|
$url | string | Auto | Current page URL (auto-property) |
$referrer | string | Auto | Document referrer |
$title | string | No | Page title |
click
Auto-tracked on element clicks.
| Property | Type | Required | Description |
|---|---|---|---|
tag | string | No | HTML tag name (e.g. button, a) |
text | string | No | Element text content |
href | string | No | Link href if applicable |
selector | string | No | CSS selector path |
scroll
Auto-tracked at depth milestones.
| Property | Type | Required | Description |
|---|---|---|---|
depth | number | Yes | Scroll depth percentage (25, 50, 75, 100) |
signup
| Property | Type | Required | Description |
|---|---|---|---|
method | string | No | Signup method (e.g. email, google, github) |
plan | string | No | Initial plan selected |
login
| Property | Type | Required | Description |
|---|---|---|---|
method | string | No | Sign-in method |
search
| Property | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query text |
results_count | number | No | Number of results returned |
product_viewed
| Property | Type | Required | Description |
|---|---|---|---|
product_id | string | Yes | Product SKU or ID |
product_name | string | No | Display name |
price | number | No | Product price |
category | string | No | Product category |
add_to_cart
| Property | Type | Required | Description |
|---|---|---|---|
product_id | string | Yes | Product SKU or ID |
quantity | number | No | Quantity added (default 1) |
price | number | No | Unit price at time of add |
remove_from_cart
| Property | Type | Required | Description |
|---|---|---|---|
product_id | string | Yes | Product SKU or ID |
quantity | number | No | Quantity removed |
checkout_started
| Property | Type | Required | Description |
|---|---|---|---|
cart_value | number | No | Total cart value |
item_count | number | No | Number of items in cart |
purchase
| Property | Type | Required | Description |
|---|---|---|---|
revenue | number | Yes | Transaction amount (use number, not string) |
currency | string | Yes | ISO 4217 currency code (e.g. USD, EUR) |
order_id | string | Yes | Unique order identifier |
item_count | number | No | Number of items purchased |
track('purchase', {
revenue: 29.99,
currency: 'USD',
order_id: 'ord-456',
item_count: 2
}, { immediate: true })form_submit
| Property | Type | Required | Description |
|---|---|---|---|
form_id | string | No | Form identifier |
form_name | string | No | Form name attribute |
form_field
| Property | Type | Required | Description |
|---|---|---|---|
form_id | string | No | Form identifier |
field_name | string | No | Field name |
interaction | string | No | focus, blur, or change |
rage_click / dead_click
Auto-tracked by frustration detection.
| Property | Type | Required | Description |
|---|---|---|---|
tag | string | No | Target element tag |
selector | string | No | CSS selector |
click_count | number | No | Number of rapid clicks (rage_click only) |
Validation errors
Sending invalid properties on well-known events returns invalid_argument:
{
"code": "invalid_argument",
"message": "validation error",
"details": [
{ "field": "events[0].properties.revenue", "description": "value must be number, got string" }
]
}Custom events skip validation entirely.
TypeScript types
The Web SDK generates TypeScript types from protobuf schemas:
import type { PurchaseEvent } from '@poluruprvn/pug-web'
track('purchase', {
revenue: 29.99,
currency: 'USD',
order_id: 'ord-456'
} satisfies PurchaseEvent)Regenerate when protos change: node gen-well-known-events.mjs
Source of truth
Schemas are defined in protobuf in the cotton repo. This page will be auto-generated from proto in a future docs pipeline.