Skip to main content
Events are actions that users take on your website or app. DATALYR captures these events to build complete customer journeys and attribute conversions to marketing campaigns.

​
What is an Event

An event represents a single user action at a specific point in time. Every event includes: Event Name What happened (e.g., page_view, purchase, button_clicked) Timestamp When it happened (ISO 8601 format) User Identifier Who did it (visitor ID, user ID, or both) Properties Additional data about the event (e.g., product ID, price, page URL) Attribution Data Marketing source information (UTM parameters, click IDs, referrer)

​
Event Structure

Every event DATALYR captures has this structure: 
{
  "event_name": "purchase",
  "timestamp": "2025-09-29T10:30:45.123Z",
  "visitor_id": "anon_abc123...",
  "user_id": "user_456",
  "session_id": "sess_789",
  "properties": {
    "order_id": "ORDER_123",
    "revenue": 99.99,
    "currency": "USD",
    "items": [...]
  },
  "attribution": {
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale",
    "fbclid": "...",
    "source": "facebook",
    "medium": "cpc"
  },
  "device": {
    "user_agent": "...",
    "screen_width": 1920,
    "screen_height": 1080
  },
  "page": {
    "url": "https://example.com/checkout",
    "path": "/checkout",
    "referrer": "https://facebook.com"
  }
}

​
Event Types

​
Automatic Events

DATALYR automatically tracks these events without code: page_view Fired when a user views a page. Captured automatically on every page load. session_start Fired when a new session begins (first visit or after 30 minutes of inactivity). session_end Fired when a session ends (user closes tab or 30 minutes of inactivity).

​
Custom Events

Track specific user actions with custom events: Web: 
datalyr.track('button_clicked', {
  button_name: 'Sign Up',
  location: 'hero_section'
});
iOS: 
await DatalyrSDK.shared.track("Button Clicked", eventData: [
    "button_name": "Sign Up",
    "location": "hero_section"
])
React Native: 
await Datalyr.track('button_clicked', {
  button_name: 'Sign Up',
  location: 'hero_section'
});

​
Conversion Events

Special events that represent business goals: purchase User completes a purchase (e-commerce). signup User creates an account. lead User submits contact information. subscribe User subscribes to a service or newsletter. add_to_cart User adds item to shopping cart. begin_checkout User starts checkout process.

​
Event Properties

Properties add context to events. They can be anything relevant to the action:

​
Standard Properties

Revenue Events:
  • revenue or amount: Dollar amount
  • currency: Three-letter code (USD, EUR, GBP)
  • order_id: Unique order identifier
  • items: Array of products purchased
Product Events:
  • product_id: Product SKU or ID
  • product_name: Product name
  • product_category: Category or type
  • product_price: Unit price
  • quantity: Number of items
Page Events:
  • page_url: Full page URL
  • page_path: URL path only
  • page_title: Document title
  • referrer: Previous page URL
User Events:
  • email: User email address
  • name: User full name
  • user_id: Internal user identifier
  • plan: Subscription plan level

​
Custom Properties

Add any properties relevant to your business: 
datalyr.track('video_played', {
  video_title: 'Product Demo',
  video_duration: 120,
  video_category: 'tutorials',
  autoplay: false,
  video_provider: 'youtube'
});
Best Practices:
  • Use snake_case for property names
  • Keep property names descriptive
  • Use consistent naming across events
  • Don’t include sensitive data (passwords, SSNs)
  • Limit to 50 properties per event

​
Event Naming Conventions

Follow these conventions for consistent tracking:

​
Use snake_case

// Good
datalyr.track('button_clicked')
datalyr.track('form_submitted')

// Bad
datalyr.track('ButtonClicked')
datalyr.track('form-submitted')

​
Use past tense

// Good
datalyr.track('purchase_completed')
datalyr.track('video_played')

// Bad
datalyr.track('purchase')
datalyr.track('play_video')

​
Be specific

// Good
datalyr.track('checkout_started')
datalyr.track('newsletter_subscribed')

// Bad
datalyr.track('event')
datalyr.track('action')

​
Standard Event Names

Use these standard names for common events: E-commerce:
  • view_item: User views product
  • add_to_cart: Add item to cart
  • remove_from_cart: Remove from cart
  • begin_checkout: Start checkout
  • add_payment_info: Enter payment details
  • purchase: Complete purchase
Engagement:
  • button_clicked: Any button click
  • link_clicked: Link click
  • form_submitted: Form submission
  • search: Search query
  • share: Content shared
Content:
  • video_played: Video play
  • video_completed: Video finished
  • download: File download
  • scroll_depth: Scroll milestone

​
Event Priority

DATALYR processes events with different priorities:

​
Critical Events (Highest Priority)

Sent immediately, bypass batching:
  • purchase
  • signup
  • subscribe
  • lead
  • conversion

​
High Priority Events

Sent in small batches (1-3 events):
  • add_to_cart
  • begin_checkout
  • view_item
  • search

​
Standard Events

Batched for efficiency (up to 10 events):
  • page_view
  • button_clicked
  • scroll_depth
  • All other custom events

​
Event Processing

​
Client-Side Flow

  1. Event Captured User action triggers event (page view, button click, etc.)
  2. Properties Collected SDK gathers event properties, device info, page data
  3. Attribution Added UTM parameters, click IDs, and computed source/medium attached
  4. Queued Event added to batch queue (or sent immediately if critical)
  5. Sent to API Batch sent to ingest endpoint via POST request
  6. Confirmed Client receives 200 OK response

​
Server-Side Processing

  1. Event Received Ingest worker receives event batch
  2. Validated Schema validation, workspace verification
  3. Enriched Geo-IP data, device parsing, user agent parsing
  4. Attribution Computed Attribution models applied (first-click, last-click, hybrid)
  5. Stored Written to Tinybird data warehouse
  6. Indexed Made available for queries and reports

​
Event Deduplication

DATALYR automatically deduplicates events using: Event ID Unique identifier for each event (automatically generated or provided). Timestamp Window Events with same name, user, and timestamp within 1 second are deduplicated. Property Matching Events with identical properties within the time window are merged. Provide Event IDs for Server-Side Tracking: 
// Web
datalyr.track('purchase', {
  order_id: 'ORDER_123',
  revenue: 99.99
}, {
  event_id: 'evt_' + orderId // Prevent duplicates
});

// Server
await fetch('https://ingest.datalyr.com/events', {
  method: 'POST',
  body: JSON.stringify({
    workspaceId: 'ws_123',
    events: [{
      event_name: 'purchase',
      event_id: 'evt_ORDER_123', // Same ID = deduplicated
      properties: { ... }
    }]
  })
});

​
Offline Events

Events are queued when offline and sent when connection restores: Automatic Queue Events saved to localStorage when offline. Auto-Retry Queue processed when online status detected. Max Queue Size 100 events max (oldest dropped if exceeded). Manual Flush 
// Force send queued events
datalyr.flush();

​
Event Validation

Events are validated before sending: Required Fields:
  • event_name (string, 1-255 chars)
  • timestamp (ISO 8601 string or Unix milliseconds)
  • visitor_id or user_id (at least one required)
Property Limits:
  • Max 50 properties per event
  • Property names: 255 chars max
  • Property values: 10KB max
  • Total event size: 50KB max
Invalid events are dropped with error logged.

​
Next Steps

Visitor Identification

Learn how DATALYR identifies users

Identity Calls

Link users across devices

Properties and Metadata

Add context to events

Attribution Models

How conversions are attributed

​
Need Help?

Questions about events? Check our troubleshooting guide or contact support.