Custom Event Tracking

Track button clicks, form submissions, and custom user actions.

Why Track Custom Events?

Page views tell you which pages people visit, but custom events tell you what they do on those pages. Track actions like:

• Button clicks (Sign Up, Add to Cart, Download, etc.)
• Form submissions
• Video plays
• File downloads
• Scroll depth
• Feature usage in web apps

Method 1: Data Attributes (Recommended)

The easiest way to track events is with the data-narrowbeam-action-name attribute. Just add it to any clickable element:

<button data-narrowbeam-action-name="signup-clicked">
  Sign Up
</button>

More Examples

Download button:

<a
  href="/whitepaper.pdf"
  data-narrowbeam-action-name="whitepaper-download"
>
  Download Whitepaper
</a>

Add to cart:

<button
  data-narrowbeam-action-name="add-to-cart"
  onClick={handleAddToCart}
>
  Add to Cart
</button>

Method 2: JavaScript API

For more control or dynamic events, use the JavaScript API:

// Track an action
window.narrowbeam.trackAction('action-name')

// Also available with optional chaining
window.narrowbeam?.trackAction('action-name')

Real Examples

Form Submission:

const handleSubmit = async (e) => {
  e.preventDefault()

  // Track the form submission
  window.narrowbeam.trackAction('contact-form-submitted')

  // Submit the form
  await submitForm(formData)
}

Video Play:

const video = document.getElementById('promo-video')

video.addEventListener('play', () => {
  window.narrowbeam.trackAction('video-played')
})

Feature Usage:

const exportData = () => {
  window.narrowbeam.trackAction('data-exported')

  // Export logic
  downloadCSV(data)
}

Naming Best Practices

Choose clear, consistent action names that describe what happened:

Viewing Custom Events in Dashboard

Once you've added custom event tracking, you can view the data in your dashboard:

1. Go to your Narrowbeam dashboard
2. Create a new widget or view
3. Select Actions as the metric
4. Group by action_name to see all your custom events

Common Use Cases

Conversion Tracking

Track key conversion actions:

• signup-completed
• purchase-completed
• trial-started
• demo-requested

Content Engagement

Track how users engage with your content:

• video-played
• video-completed
• document-downloaded
• social-share-clicked

Product Features

Track feature usage in your SaaS app:

• export-data-clicked
• filter-applied
• report-generated
• settings-changed

Testing Your Events

To verify custom events are working:

1. Trigger the action on your website
2. Open browser console (F12)
3. Look for: Narrowbeam: Action tracked - your-action-name
4. Check the Network tab for successful POST to /api/audience
5. Verify in your dashboard that the action appears

Next Steps