Custom Events

Overview

Signal auto-tracks pageviews, clicks, downloads, forms, scroll, and engagement. For everything else — purchases, signups, button clicks, feature usage — use custom events.

There are two ways to track custom events: JavaScript and HTML data attributes.

JavaScript API

Call signal() from anywhere in your code:

signal('event_name', { key: 'value' });

Examples

// User signs up
signal('signup', { plan: 'pro', source: 'homepage' });

// User makes a purchase
signal('purchase', { product: 'Widget Pro', price: 49.99, currency: 'USD' });

// User clicks a CTA
signal('click_cta', { location: 'hero', text: 'Start Free Trial' });

// User watches a video
signal('video_play', { title: 'Product Demo', duration: 120 });

// User submits a search
signal('search', { query: 'pricing', results: 5 });

Rules

• Event names can be any string. They are auto-normalized: User Signed Up, user_signed_up, and user-signed-up all become the same event.
• Properties are flat key-value pairs. Values can be strings or numbers.
• No reserved words — unlike some analytics tools, Signal has no restricted event names or property prefixes.

HTML Data Attributes

Track clicks without writing JavaScript. Add data-signal to any HTML element:

<button data-signal="click_signup" data-signal-plan="pro">
  Sign Up
</button>

When clicked, this fires a click_signup event with { plan: "pro" }.

Attribute Format

Attribute	Purpose	Example
data-signal	Event name (required)	data-signal="click_cta"
data-signal-{key}	Event property	data-signal-location="header"

More Examples

<!-- Track pricing plan selection -->
<div data-signal="select_plan" data-signal-plan="enterprise" data-signal-price="99">
  Enterprise Plan — $99/mo
</div>

<!-- Track download button -->
<a href="/whitepaper.pdf" data-signal="download_whitepaper" data-signal-title="2026 Report">
  Download Now
</a>

<!-- Track navigation -->
<nav>
  <a href="/pricing" data-signal="nav_click" data-signal-item="pricing">Pricing</a>
  <a href="/about" data-signal="nav_click" data-signal-item="about">About</a>
</nav>

AI-Assisted Setup

Building with Claude Code, Cursor, or Copilot? Ask the AI to add tracking for you:

"What events should I track on this checkout page?"

The AI will analyze your HTML, identify interactive elements, and write the signal() calls or data-signal attributes. For example, it might suggest:

// On the checkout page
signal('begin_checkout', { items: cart.length, total: cart.total });

// When payment succeeds
signal('purchase', { order_id: order.id, total: order.total, currency: 'USD' });

// When a coupon is applied
signal('apply_coupon', { code: couponCode, discount: discountAmount });

This is Signal's key advantage: you don't need to learn what to track. Ask the AI, and it writes the code.

Viewing Custom Events

Custom events appear in the Events tab of your Signal connection in Commander. Each event shows:

• Event name
• Properties
• Page URL where it happened
• Timestamp
• Visitor session

Best Practices

1. Use descriptive names — signup_completed is better than event1
2. Be consistent — pick a naming convention (e.g., noun_verb) and stick with it
3. Don't over-track — track actions that answer business questions, not every click
4. Let AI help — describe what you want to measure and let AI write the tracking code