> ## Documentation Index
> Fetch the complete documentation index at: https://www.orwel.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Tracking

> Capture user behavior automatically or with a single call, and the semantic catalog behind it.

An **event** is a single thing a visitor did: a page view, a click, a form submit, a purchase. Orwel captures events two ways: **automatically** (page views, clicks, scrolls, errors) and **explicitly** with a one-line call. Every event is tied to a visitor and a session.

## The four primitives

```typescript theme={null}
// a named event with any properties
orwel.track('quote_created', { amount: 1200, currency: 'MXN' });

// attach identity + traits to the current visitor
orwel.identify({ email: 'user@acme.com', plan: 'pro' });

// a conversion / lead (its own record, attributed to the visitor)
await orwel.conversion('signup', { email, source: 'landing' });

// per-session state (current screen, cart value...)
orwel.session({ currentScreen: 'checkout', cartTotal: 99.9 });
```

## Automatic capture

With `autoEventDetection` and `autoMonitor` enabled at init, the SDK captures common signals with no extra code:

> [card] Navigation & interaction
>
> `page_view`, `click`, `scroll`, `hover`, `search`, `select_content`, including SPA route changes.

> [card] Technical & performance
>
> `js_error`, `network_request_failed`, console errors, plus navigation and resource timings attached to the session.

> [!TIP]
>
> Elements with a `data-orwel-section` attribute are also tracked automatically: total visible time, max visibility %, and interaction count are rolled up into `session.sectionEngagements` (no extra events).

```typescript theme={null}
orwel.init({
  apiKey: 'orwel_...',
  autoMonitor: true,        // errors, performance, web-vitals
  autoEventDetection: true, // page_view / click / scroll / element_visible
});
```

## Custom events & the catalog

Every `track()` code must exist in your workspace catalog, otherwise the ingest rejects it with `Event not found: <code>` (HTTP 400 on a single event, or a partial 207 inside a batch). The catalog has two parts:

* The **Orwel catalog**: a few hundred standard codes (the most common ones are listed below) that every workspace can send.
* Your **custom codes** (`deal_created`, `invoice_stamped`): add them as a custom event in a journey or feature in [Journeys and features setup](https://www.orwel.io/docs/guides/journeys-and-features.md). They are registered for your workspace when you save.

Conversion codes are not gated: any valid code works with `conversion()`.

> [!TIP]
>
> Event codes are `lowercase_snake_case`, up to 50 characters, letters, numbers and underscores. Keep them verb-based and stable (`quote_sent`, not `QuoteSent2`).

## Semantic event catalog

Common standard events, by category. The full catalog, with search by domain and vertical, is in the event picker of Journeys and features setup.

> [accordion] Navigation
>
> | Code | Description |
> | - | - |
> | `page_view` | User loaded a page (auto on SPA route changes). |
> | `click` | User clicked on an element. |
> | `scroll` | User scrolled through the page. |
> | `time_on_screen` | Time an element or screen stayed visible. |
> | `element_visible` | An element became visible to the user. |
> | `hover` | User hovered over an element. |
> | `search` | User performed a search query. |
> | `view_search_results` | User saw the search results page. |
> | `select_content` | User selected a piece of content. |

> [accordion] Auth
>
> | Code | Description |
> | - | - |
> | `login` | User logged into their account. |
> | `logout` | User logged out of their account. |
> | `signup` | User created a new account. |
> | `complete_profile` | User completed their profile information. |
> | `verify_email` | User verified their email address. |
> | `join_group` | User joined a group or community. |

> [accordion] Form
>
> | Code | Description |
> | - | - |
> | `form_focus` | User focused on a form input field. |
> | `form_input` | User entered data in a form field. |
> | `form_change` | User changed a form field value. |
> | `form_submit_attempt` | User attempted to submit the form. |
> | `form_submit_success` | Form submitted successfully. |
> | `form_submit_error` | Form failed to submit (validation or API error). |
> | `form_abandon` | User started the form but left before submitting. |

> [accordion] Conversion
>
> | Code | Description |
> | - | - |
> | `generate_lead` | A new lead was generated. **(high-value)** |
> | `waitlist` | New user registered to a waitlist. **(high-value)** |
> | `conversion_custom` | A custom conversion event occurred. |
> | `milestone_reached` | User reached a specific milestone. |
> | `share` | User shared content externally. |
> | `view_promotion` | User viewed a promotion. |
> | `select_promotion` | User selected a promotion. |

> [accordion] Ecommerce
>
> | Code | Description |
> | - | - |
> | `view_item` | User viewed a specific product. |
> | `view_item_list` | User viewed a list of products. |
> | `select_item` | User selected an item from a list. |
> | `add_to_cart` | User added a product to the cart. |
> | `remove_from_cart` | User removed a product from the cart. |
> | `view_cart` | User viewed their shopping cart. |
> | `begin_checkout` | User started the checkout process. |
> | `checkout_progress` | User proceeded to the next checkout step. |
> | `set_checkout_option` | User selected a checkout option (e.g. shipping). |
> | `add_shipping_info` | User entered shipping information. |
> | `add_payment_info` | User provided payment details. |
> | `purchase` | User completed a purchase. **(high-value)** |
> | `refund` | A refund was issued for a purchase. |

> [accordion] Communication
>
> | Code | Description |
> | - | - |
> | `chat_opened` | User opened a chat window. |
> | `chat_message_sent` | User sent a message in chat. |

> [accordion] Media
>
> | Code | Description |
> | - | - |
> | `video_play` | User started a video. |
> | `video_progress` | User reached a certain point in a video. |
> | `video_complete` | User finished watching a video. |
> | `audio_play` | User started an audio file. |

> [accordion] Notification
>
> | Code | Description |
> | - | - |
> | `notification_received` | A push notification was received. |
> | `notification_clicked` | User clicked on a notification. |

> [accordion] Feedback
>
> | Code | Description |
> | - | - |
> | `feedback_submitted` | User submitted feedback. **(high-value)** |
> | `survey_submitted` | User submitted a survey. **(high-value)** |

> [accordion] Gamification
>
> | Code | Description |
> | - | - |
> | `earn_virtual_currency` | User earned virtual currency. |
> | `spend_virtual_currency` | User spent virtual currency. |

> [accordion] Technical
>
> | Code | Description |
> | - | - |
> | `js_error` | A JavaScript error occurred on the client. |
> | `exception` | An exception or error occurred in the app. |
> | `network_request_failed` | A network request failed. |
> | `timing_complete` | A timed operation completed. |
> | `file_download` | User downloaded a file. |

## Next steps

> [card] [Feature Tracking](https://www.orwel.io/docs/sdk/feature-tracking.md)
>
> Map events to product features and measure adoption.

> [card] [Conversions](https://www.orwel.io/docs/sdk/conversions.md)
>
> Capture leads and goals, attributed across sessions.

> [card] [SDK Reference](https://www.orwel.io/docs/sdk/reference.md)
>
> Every method and option.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.