# 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
// 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:

<CardGroup cols={2}>
  <Card title="Navigation & interaction" icon="arrow-pointer">
    `page_view`, `click`, `scroll`, `hover`, `search`, `select_content`, including SPA route changes.
  </Card>
  <Card title="Technical & performance" icon="gauge-high">
    `js_error`, `network_request_failed`, console errors, plus navigation and resource timings attached to the session.
  </Card>
</CardGroup>

<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).
</Tip>

```typescript
orwel.init({
  apiKey: 'orwel_pk_...',
  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](/docs/guides/journeys-and-features). 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`).
</Tip>

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

<AccordionGroup>
  <Accordion title="Navigation" icon="compass">
    | 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>

  <Accordion title="Auth" icon="user-lock">
    | 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>

  <Accordion title="Form" icon="rectangle-list">
    | 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>

  <Accordion title="Conversion" icon="bullseye-arrow">
    | 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>

  <Accordion title="Ecommerce" icon="cart-shopping">
    | 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>

  <Accordion title="Communication" icon="comments">
    | Code | Description |
    | --- | --- |
    | `chat_opened` | User opened a chat window. |
    | `chat_message_sent` | User sent a message in chat. |
  </Accordion>

  <Accordion title="Media" icon="play">
    | 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>

  <Accordion title="Notification" icon="bell">
    | Code | Description |
    | --- | --- |
    | `notification_received` | A push notification was received. |
    | `notification_clicked` | User clicked on a notification. |
  </Accordion>

  <Accordion title="Feedback" icon="comment-dots">
    | Code | Description |
    | --- | --- |
    | `feedback_submitted` | User submitted feedback. **(high-value)** |
    | `survey_submitted` | User submitted a survey. **(high-value)** |
  </Accordion>

  <Accordion title="Gamification" icon="trophy">
    | Code | Description |
    | --- | --- |
    | `earn_virtual_currency` | User earned virtual currency. |
    | `spend_virtual_currency` | User spent virtual currency. |
  </Accordion>

  <Accordion title="Technical" icon="bug">
    | 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. |
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Feature Tracking" icon="puzzle-piece" href="/sdk/feature-tracking">
    Map events to product features and measure adoption.
  </Card>
  <Card title="Conversions" icon="bullseye" href="/sdk/conversions">
    Capture leads and goals, attributed across sessions.
  </Card>
  <Card title="SDK Reference" icon="book" href="/sdk/reference">
    Every method and option.
  </Card>
</CardGroup>