Track events

EventObserver

The EventObserver component provides automatic click tracking for conversion analytics. It uses event delegation to monitor clicks on elements with the data-ddi-event attribute and sends events to the analytics system.

Features:

• Automatic tracking - No need to manually add event listeners to each trackable element
• Event delegation - Efficiently handles clicks using a single listener on the document
• Simple setup - Just add the component once and use data attributes on clickable elements
• Analytics integration - Automatically sends event data to @dynamic-type/analytics
• Scroll depth tracking - Automatically includes scroll position (0-1) with each event
• External link handling - Ensures tracking completes before external navigation (300ms max delay)
• Smart link detection - Handles download links, mailto:, and special protocols without delay

Basic Usage

---
import { EventObserver } from '@dynamic-type/ddi';
---

<!-- Add the observer component once per page -->
<EventObserver />

<!-- Add tracking to any clickable element -->
<button data-ddi-event="newsletter-signup" data-ddi-attribute="demo-page">
    Subscribe to Newsletter
</button>

<a href="/contact" data-ddi-event="contact-page-visit">
    Contact Us
</a>

Tracking Different Events

You can track various types of user interactions by setting different event names:

<!-- Button clicks -->
<button data-ddi-event="cta-primary">
    Get Started
</button>

<!-- Link clicks -->
<a href="/pricing" data-ddi-event="pricing-page-view">
    View Pricing
</a>

<!-- Form submissions -->
<button type="submit" data-ddi-event="form-submit">
    Submit Form
</button>

<!-- Download links -->
<a href="/whitepaper.pdf" data-ddi-event="whitepaper-download">
    Download Whitepaper
</a>

Attributes

• data-ddi-event - The event name to track when the element is clicked (required)
• data-ddi-attribute - Optional additional context or categorization for the event

Tracked Data

Each event automatically includes:

• name - The value from data-ddi-event
• attribute - The value from data-ddi-attribute (if present)
• scrollPosition - Current scroll depth as a number between 0 (top) and 1 (bottom)
• pathName - Current page path

How It Works

The EventObserver:

1. Sets up a delegated click listener on the document
2. Checks if clicked elements have the data-ddi-event attribute
3. Extracts the event name and optional attribute
4. Calculates the current scroll position
5. For external page links: prevents default navigation, tracks the event (with 300ms timeout), then navigates programmatically
6. For all other cases (internal links, download links, buttons, special protocols): tracks immediately and allows normal behavior
7. Sends the event data to the analytics system via trackEvent()

External Link Handling

External page links (different hostname) are handled specially to ensure tracking completes:

• Navigation is delayed by up to 300ms to allow tracking to complete
• If tracking fails or times out, navigation proceeds anyway
• Exceptions: Download links, mailto:, tel:, and javascript: protocols are never delayed