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

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

// attach identity + traits to the current visitor
orwel.identify({ email: '[e-mail]', 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:

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

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.

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

Semantic event catalog

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

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.