Events

Events are the foundation of Kitbase analytics. Every interaction you want to measure -- a page view, a button click, a purchase, an error -- is represented as an event.

What Are Events

An event is a record of something that happened in your application at a specific point in time. Events are sent to the Kitbase server, enriched with contextual data, and stored for analysis. You can view, filter, and break down events in the dashboard.

Event Structure

Every event contains the following fields:

Field	Type	Description
event	string	The name of the event (e.g., "Purchase Completed", "screen_view")
channel	string	A category that groups related events (e.g., "payments", "users", "errors")
tags	object	Key-value metadata attached to the event (string, number, or boolean values)
timestamp	string	ISO 8601 timestamp of when the event occurred
user_id	string	The identified user who performed the action (set after identify())
anonymous_id	string	The auto-generated UUID for anonymous tracking
session_id	string	The session during which the event occurred

Additional optional fields include icon, notify, and description for display and notification purposes.

Types of Events

Auto-Tracked Events

These events are captured automatically by the SDK without any code on your part. They are sent to the __analytics channel.

Event	Trigger	Description
session_start	A new session begins	Captures referrer, UTM parameters, and device info
screen_view	A page is loaded or a route changes	Captures page path, title, and referrer
outbound_link	A user clicks a link to an external domain	Captures the destination URL and link text
scroll_depth	The user scrolls past defined thresholds	Captures the maximum scroll percentage
click	A user clicks a tracked element	Captured via data attributes (see below)

Auto-tracked events can be individually enabled or disabled in the SDK configuration. See Autocapture for the full reference.

Custom Events

Custom events are tracked explicitly using the track() method. Use them for anything specific to your business logic.

await kitbase.track({
  channel: 'payments',
  event: 'New Subscription',
  user_id: 'user-123',
  notify: true,
  tags: {
    plan: 'premium',
    amount: 9.99,
  },
});

See Track Events for the complete API and examples.

Data Attribute Events

Track user interactions directly from HTML without writing JavaScript. Add data attributes to any element:

Attribute	Trigger	Description
data-kb-track-click	Element is clicked	Sends a click event with the attribute value as the event name
data-kb-track-visibility	Element enters the viewport	Sends a visibility event when the element becomes visible

<button data-kb-track-click="CTA Clicked">Get Started</button>

<section data-kb-track-visibility="Pricing Section Viewed">
  <!-- pricing content -->
</section>

Revenue Events

Track monetary values with the dedicated trackRevenue() method. Revenue events are aggregated in the dashboard for financial reporting.

await kitbase.trackRevenue({
  amount: 99.99,
  currency: 'USD',
  orderId: 'order-123',
  productId: 'prod-456',
  tags: { plan: 'premium' },
});

Channels

Channels are categories that organize your events into logical groups. They make it easy to filter and navigate events in the dashboard.

Channel	Purpose
__analytics	System channel for auto-tracked events (page views, sessions, outbound links)
payments	Financial events such as subscriptions, purchases, and refunds
users	User lifecycle events like signups, logins, and profile updates
errors	Application errors, exceptions, and failure conditions
Custom channels	Any channel name relevant to your domain (e.g., "notifications", "api", "features")

Channel Naming

Use lowercase, plural nouns for channel names. This keeps your events organized and consistent across your codebase.

Tags

Tags are key-value pairs that attach rich metadata to your events. They allow you to slice and filter event data across any dimension you need.

User-Defined Tags

You set these when calling track(). They support three value types:

Type	Example
string	plan: 'premium'
number	amount: 99.99
boolean	is_first_purchase: true

tags: {
  plan: 'premium',
  amount: 99.99,
  is_first_purchase: true,
}

Server-Enriched Tags

The server automatically adds tags prefixed with __ based on the incoming request. These are stored as first-class dimensions and are available as filters in the dashboard.

Tag	Description
__browser	Browser name
__browser_version	Browser version
__os	Operating system
__os_version	OS version
__device	Device type (desktop, mobile, tablet)
__brand	Device manufacturer
__model	Device model
__country	Country (from IP geolocation)
__region	Region or state
__city	City
__path	Page path
__referrer	Referrer URL
__utm_source	UTM source parameter
__utm_medium	UTM medium parameter
__utm_campaign	UTM campaign parameter

Super Properties

Super properties are tags that are automatically included in every event you send. Set them once and they persist for the duration of the session (or until cleared).

kitbase.setSuperProperties({
  app_version: '2.1.0',
  environment: 'production',
});

// Now every track() call includes app_version and environment

See Track Events — Super Properties for more on super properties.

Viewing Events

The Kitbase dashboard provides several ways to explore your event data.

Event Timeline

View a chronological stream of events with configurable time intervals (hourly, daily, weekly, monthly). The timeline chart shows event volume over time and updates as you apply filters.

Event Breakdown

Break down event counts by any dimension -- event name, browser, country, device type, page path, referrer, UTM parameters, and more. Use breakdowns to understand the composition of your traffic.

Event Detail View

Click on any individual event to see its full detail, including:

• Event name and channel
• Timestamp
• User ID and anonymous ID
• Session ID
• All user-defined tags
• All server-enriched tags

Filtering

Narrow down the event list using the filter bar:

• Date range -- Select a time window
• Channel -- Filter by event channel
• Event name -- Show only specific events
• User -- Search by user ID or anonymous ID
• Dimensions -- Filter by browser, country, device, OS, referrer, UTM parameters, and more

Notifications

When you set notify: true on a tracked event, Kitbase sends a real-time alert. Use notifications for high-value or critical events.

await kitbase.track({
  channel: 'payments',
  event: 'Payment Failed',
  user_id: 'user-123',
  icon: '🔴',
  notify: true,
  tags: {
    amount: 99.99,
    error: 'card_declined',
  },
});

Good candidates for notifications:

• New signups and subscriptions
• Failed payments
• Critical application errors
• Security events (e.g., login from a new device)