Event Tracking

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

View as Markdown Open in Claude Open in ChatGPT

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:

Navigation & interaction

page_view, click, scroll, hover, search, select_content, including SPA route changes.

Technical & performance

js_error, network_request_failed, console errors, plus navigation and resource timings attached to the session.

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

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. They are registered for your workspace when you save.

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

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.

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.

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.

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.

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.

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.

Communication

Code	Description
`chat_opened`	User opened a chat window.
`chat_message_sent`	User sent a message in chat.

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.

Notification

Code	Description
`notification_received`	A push notification was received.
`notification_clicked`	User clicked on a notification.

Feedback

Code	Description
`feedback_submitted`	User submitted feedback. (high-value)
`survey_submitted`	User submitted a survey. (high-value)

Gamification

Code	Description
`earn_virtual_currency`	User earned virtual currency.
`spend_virtual_currency`	User spent virtual currency.

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

Feature Tracking

Map events to product features and measure adoption.

Conversions

Capture leads and goals, attributed across sessions.

SDK Reference

Every method and option.