> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/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)
orwel.conversion('signup', { source: 'landing' });

// per-session state (utm, 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/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 theme={null}
orwel.init({
  apiKey: 'orwel_pk_...',
  autoMonitor: true,        // errors, performance, web-vitals
  autoEventDetection: true, // page_view / click / scroll / element_visible
});
```

## Custom events & the catalog

Orwel is **flexible by default**: send any event code that fits your product (`deal_created`, `invoice_stamped`) and it's captured. On top of that sits a **curated semantic catalog** — a shared taxonomy of standard events (below) that powers the behavioral engine, benchmarks, and prebuilt insights.

<Tip>
  Event codes are `lowercase_snake_case`, ≤ 50 characters, letters / numbers / underscores. Keep them verb-based and stable (`quote_sent`, not `QuoteSent2`).
</Tip>

## Semantic event catalog

The standard events Orwel understands out of the box, by category. You can always send custom codes alongside these.

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