Guides/Custom Events

Custom Events

Go beyond page views. Track the specific interactions that matter for your business — button clicks, form submissions, purchases, video plays, and any action your users take.

JavaScriptTrackingAnalytics

Quick Start

Everything you need in two lines.

JavaScript

// 1. Simple event — just a name
siteTooling.track('button_click');

// 2. Event with context — name + properties object
siteTooling.track('cta_clicked', {
  button_text: 'Start Free Trial',
  location:    'hero_section',
  plan:         'pro'
});

Requires the tracking snippet

The siteTooling object is provided by the embed script installed on your site. Custom events won't work without it.

Why Properties Matter

Without properties, you'll only see event counts — not what was clicked or where. This is the #1 cause of "Unknown" labels in your dashboard.

Without properties

// Only a name — no context
siteTooling.track('button_click');

Dashboard shows: Button Click — Unknown Button — Unknown Location

With properties

siteTooling.track('button_click', {
  button_text: 'Get Started',
  location:    'hero_section'
});

Dashboard shows: Button Click — "Get Started" — Hero Section

Standard Properties

These property names are recognized by the dashboard and displayed with proper labels and icons. You can add any custom properties too — they'll appear in the expanded event detail view.

Property	Type	Used for	Example
`button_text`	string	Button & CTA clicks	'Start Free Trial'
`location`	string	Any click event	'hero_section'
`form_name`	string	Form submissions	'contact'
`product_name`	string	E-commerce events	'Pro Plan'
`value`	number	Revenue / purchase amount	149.99
`currency`	string	Purchase / revenue events	'USD'
`order_id`	string	Purchase confirmation	'ORD-12345'
`category`	string	Product / content grouping	'electronics'
`label`	string	Generic display label	'Summer Sale Banner'
`plan`	string	Signup / upgrade events	'pro'

Event Naming Conventions

Consistent naming makes your analytics readable and queryable. Follow the noun_verb pattern.

Category	❌ Avoid	✅ Prefer
Button clicks	Click, clicked, btnClick	button_click, cta_clicked
Forms	form, formSubmit, submit	form_submitted, contact_submitted
Purchases	buy, paid, order	purchase_completed, order_placed
Signups	signup, SignUp, newUser	signup_completed, account_created
Media	video, play, watch	video_play, video_completed
Downloads	download, dl, fileClick	file_download, pdf_downloaded

Implementation Examples

Copy-paste examples for the most common use cases.

CTA Button Clickbutton_click event

// Track any CTA button with full context
document.querySelector('.cta-button')
  .addEventListener('click', (e) => {
    siteTooling.track('button_click', {
      button_text: e.target.innerText,   // what the button says
      location:    'hero_section',        // where it is on the page
      page:        window.location.pathname // current page
    });
  });

Auto-instrument All Buttonsbulk tracking

// Add data attributes to HTML: <button data-track="hero_cta" data-location="header">
document.querySelectorAll('[data-track]')
  .forEach(el => {
    el.addEventListener('click', () => {
      siteTooling.track('button_click', {
        button_text: el.dataset.track,
        location:    el.dataset.location || 'unknown',
        label:       el.innerText.trim()
      });
    });
  });

Navigation Link Clicksnav_click event

document.querySelectorAll('nav a')
  .forEach(link => {
    link.addEventListener('click', () => {
      siteTooling.track('nav_click', {
        label:       link.innerText.trim(),
        destination: link.href,
        location:    'main_nav'
      });
    });
  });

Best Practices

Follow these principles to keep your analytics clean and actionable.

Do

✓ Use snake_case for all event names
✓ Always include location on click events
✓ Always include button_text on button clicks
✓ Always include form_name on form events
✓ Track meaningful conversions, not noise
✓ Test in dev before deploying to prod
✓ Use a useTracking() composable to keep code DRY

Don't

✗ Track every mouse movement or keypress
✗ Include PII (email, name, phone, address)
✗ Mix camelCase and snake_case names
✗ Fire events inside render loops
✗ Create events without properties
✗ Track sensitive form field values
✗ Use vague names like "click" or "action"

Debugging & Verification

Confirm your events are firing correctly before relying on the data.

1. Browser Console Verification

// Open DevTools → Console, then run:
window.siteTooling  // should be an object, not undefined

// Test fire an event:
siteTooling.track('test_event', { source: 'manual_test' });

// Check the Network tab for a request to /api/track

2. Dashboard Verification

Go to your SiteTooling dashboard → Custom Events tab
Filter by Today or use the live stream toggle
Trigger the action on your site
The event should appear within a few seconds
Expand the event row to verify all properties are present

3. Common Issues

Issue

"siteTooling is not defined"

The embed script hasn't loaded yet. Make sure the script tag is in your <head> or before your event code.

Issue

Events appear but show "Unknown" labels

You're tracking without properties. Add button_text, location, and form_name as appropriate.

Issue

Events fire multiple times per action

You're attaching listeners inside a render loop. Move event listener setup to a one-time DOMContentLoaded or component mount callback.

Issue

No events showing in dashboard

Check the Network tab for blocked requests (ad blockers, CSP headers). Try in an incognito window with extensions disabled.