Events & Properties

Overview

Events are the foundation of analytics in Trodo. Every user action you capture—from page views to custom product events—is stored as an event with associated properties.

Event Structure

Every event has this structure:

{
  // Required
  "event_name": "agent_run_completed",
  "distinct_id": "user_12345",
  "timestamp": "2024-01-15T10:30:00.000Z",
  
  // Auto-captured (default properties)
  "session_id": "sess_abc123",
  "current_url": "https://app.example.com/workflows",
  "browser_name": "Chrome",
  "country": "US",
  // ... more default properties
  
  // Custom (your properties)
  "properties": {
    "workflow_id": "weekly_report",
    "duration_seconds": 36,
    "outcome": "success"
  }
}

Event Types

Auto-Events

Captured automatically only when auto-events="true" (or Trodo.enableAutoEvents()). Examples of implemented names:

Event	Trigger (summary)
`page_view`	Load / route
`element_click`	Any click
`rage_click`	Rapid repeated clicks on the same element
`dead_click`	Click with no navigation or DOM change after a short window
`page_scroll`	Increasing scroll depth
`form_submit`	Form submit
`form_validation_error`	Native invalid field
`form_abandoned`	Started a form, left without submit
`media_play` / `media_pause`	Video or audio
`text_selection`	Text highlighted
`copy_action` / `context_menu`	Copy / right-click
`js_error` / `network_error`	Errors (when enabled)
`page_performance`	Core vitals-style summary after load
`exit_intent` / `page_summary`	Engagement / exit aggregates

See Auto-Events for the full catalog, script attributes, and JavaScript API. Custom properties on each event may also include group membership fields merged from set_group / add_group.

Custom Events

Tracked via SDK:

Trodo.track('agent_run_completed', {
  workflow_id: 'weekly_report',
  duration_seconds: 36,
  outcome: 'success'
});

Properties

Properties provide context to events. They come in several categories:

Default Properties

Auto-captured on every event:

Identifiers
Location
Device & Browser
Screen & Page
UTM & campaign

Property	Description
`team_id`	Your Trodo team
`session_id`	Current session
`distinct_id`	User identifier
`website_id`	Site identifier
`event_type`	auto or custom
`event_name`	Name of the event
`event_category`	Category grouping
`timestamp`	Event time (ISO 8601)

Property	Description
`country`	Country code (US, GB, etc.)
`city`	City name
`region`	State/province
`latitude`	Approximate latitude
`longitude`	Approximate longitude
`timezone`	User timezone

Property	Description
`browser_name`	Chrome, Firefox, Safari, etc.
`browser_version`	Browser version
`os`	Operating system
`os_version`	OS version
`device_type`	desktop, mobile, tablet
`language`	Browser language

Property	Description
`screen_height`	Screen height (px)
`screen_width`	Screen width (px)
`viewport_height`	Viewport height (px)
`viewport_width`	Viewport width (px)
`dpi`	Device pixel ratio
`current_url`	Full page URL
`page_title`	Page title
`uri`	URL pathname
`referrer`	Previous page URL
`initial_referrer`	First referrer in session

Property	Description
`utm_source`	Campaign source
`utm_medium`	Campaign medium
`utm_campaign`	Campaign name
`utm_term`	Campaign term
`utm_content`	Campaign content
`utm_id`	Campaign ID

Custom Properties

Add your own properties to events:

Trodo.track('subscription_upgraded', {
  // Strings
  plan: 'enterprise',
  billing_interval: 'annual',

  // Numbers
  seat_count: 25,
  mrr_delta_usd: 400,

  // Booleans
  is_self_serve: true,

  // Arrays
  enabled_integrations: ['slack', 'salesforce'],

  // Nested objects
  metadata: {
    previous_plan: 'pro',
    sales_assisted: false
  }
});

Event-Specific Properties

Auto event payloads vary by event_name. Examples: element_click (abbreviated):

{
  "click_coordinates": { "x": 120, "y": 340 },
  "page_x": 120,
  "page_y": 540,
  "scroll_x": 0,
  "scroll_y": 200,
  "document_height": 3200,
  "document_width": 1280,
  "double_click": false,
  "element_category": "button",
  "element_tag_name": "button",
  "element_id": "btn-run-workflow",
  "element_text": "Run workflow"
}

page_scroll:

{
  "scroll_depth": 72,
  "max_scroll_reached": 72,
  "scroll_position": 2100,
  "document_height": 3200
}

Property Data Types

Type	Example	Notes
String	`"enterprise"`	Max 255 chars for indexed fields
Number	`1500.50`	Integer or decimal
Boolean	`true` / `false`
Date	`"2024-01-15"`	ISO 8601 date
Datetime	`"2024-01-15T10:30:00Z"`	ISO 8601 with time
Array	`["slack", "email"]`	Homogeneous type recommended
Object	`{name: "...", value: 100}`	Nested properties

Best Practices

Event Naming

Use snake_case with clear action verbs:

// ✅ Good
'agent_run_completed'
'integration_connected'
'export_generated'
'onboarding_step_completed'

// ❌ Avoid
'AgentRunCompleted'  // PascalCase
'agent-run-done'     // kebab-case
'run'                // Too vague
'user clicked run'   // Spaces, unclear

Property Naming

// ✅ Good
{
  workflow_id: 'weekly_report',
  surface: 'in_app',
  duration_seconds: 36,
  retry_count: 0
}

// ❌ Avoid
{
  workflowId: 'weekly_report', // camelCase
  'Workflow Id': 'x',          // Spaces
  dur: 36,                     // Abbreviated
  retry: '0'                  // String for number
}

Property Values

// ✅ Good - Consistent, specific
{
  status: 'completed',
  plan_tier: 'enterprise',
  seat_count: 12,
  is_paid: true
}

// ❌ Avoid
{
  status: 'COMPLETED',
  planTier: 'enterprise',
  seat_count: '12',
  is_paid: 'yes'
}

High-Cardinality Properties

Avoid properties with unlimited unique values:

// ❌ High cardinality - avoid when possible
{
  raw_prompt: 'full unstructured text...',
  request_id: 'uuid-per-event'
}

// ✅ Better - categories, lengths, or IDs you control
{
  prompt_length_bucket: 'medium',
  template_id: 'onboarding_v2',
  // Use built-in timestamp instead of a duplicate ms field
}

Limits

Limit	Value
Event name length	255 characters
Property name length	255 characters
String property value	8,192 characters
Properties per event	255
Array items	255
Object nesting depth	5 levels

Next Steps

Track Events

Learn the track() method

Auto-Events

Automatic event names and configuration

Groups

Group keys, membership, and enrichment

Default Properties

Full property reference

INTRO

DATA IN

DATA MODEL

BEST PRACTICES

Events & Properties

Overview

Event Structure

Event Types

Auto-Events

Custom Events

Properties

Default Properties

Custom Properties

Event-Specific Properties

Property Data Types

Best Practices

Event Naming

Property Naming

Property Values

High-Cardinality Properties

Limits

Next Steps

Track Events

Auto-Events

Groups

Default Properties

INTRO

DATA IN

DATA MODEL

BEST PRACTICES

​Overview

​Event Structure

​Event Types

​Auto-Events

​Custom Events

​Properties

​Default Properties

​Custom Properties

​Event-Specific Properties

​Property Data Types

​Best Practices

​Event Naming

​Property Naming

​Property Values

​High-Cardinality Properties

​Limits

​Next Steps

Track Events

Auto-Events

Groups

Default Properties

Overview

Event Structure

Event Types

Auto-Events

Custom Events

Properties

Default Properties

Custom Properties

Event-Specific Properties

Property Data Types

Best Practices

Event Naming

Property Naming

Property Values

High-Cardinality Properties

Limits

Next Steps