Custom Event Goals

Custom event goals track user actions that don't involve page navigation — button clicks, video plays, form submissions, file downloads, and any interaction you want to measure. They provide granular insight into user behavior beyond pageviews.

What are Custom Events?

Custom events let you track in-page interactions using JavaScript. Unlike pageview goals that trigger on URL visits, custom events fire when users perform specific actions:

• Button clicks: CTA buttons, add-to-cart, social shares
• Form submissions: AJAX forms, multi-step wizards
• Video engagement: Play, pause, completion events
• Downloads: PDF, ebook, software downloads
• Interactions: Tab switches, modal opens, scroll depth

Custom events require adding tracking code to your site, but offer precise control over what you measure.

How to Track Custom Events

Client-Side Tracking (JavaScript)

First, ensure the Ovyxa script is installed:

<script async src="https://ingest.ovyxa.com/js/script.js" data-domain="YOUR_DOMAIN"></script>

Then track events using the global ovyxa() function:

// Basic event
window.ovyxa('event', 'SignupCompleted')

// Event with properties
window.ovyxa('event', 'PurchaseCompleted', {
  plan: 'pro',
  amount: '99.00',
  currency: 'EUR'
})

Example: Track button click

<button onclick="window.ovyxa('event', 'CTAClicked', { location: 'hero' })">
  Get Started
</button>

Example: Track form submission

document.querySelector('#signup-form').addEventListener('submit', function(e) {
  e.preventDefault()

  // Track the event
  window.ovyxa('event', 'SignupFormSubmitted', {
    source: 'homepage',
    plan: document.querySelector('#plan').value
  })

  // Submit the form
  this.submit()
})

Server-Side Tracking (API)

For backend events (webhook confirmations, payment processing, cron jobs), use the Events API:

// Node.js example
await fetch('https://api.ovyxa.com/api/v1/events/custom', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    site_id: 'your-site-id',
    event_name: 'SubscriptionRenewed',
    url: 'https://example.com/dashboard',
    props: {
      plan: 'annual',
      amount: '990.00',
      customer_id: 'cus_abc123'
    }
  })
})

# Python example
import requests

requests.post('https://api.ovyxa.com/api/v1/events/custom',
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  json={
    'site_id': 'your-site-id',
    'event_name': 'PaymentFailed',
    'url': 'https://example.com/billing',
    'props': {
      'reason': 'insufficient_funds',
      'plan': 'pro'
    }
  }
)

Creating a Custom Event Goal

Once your events are being sent, convert them into goals:

1. Send Events First: Deploy your tracking code and verify events appear in the Ovyxa Events tab
2. Navigate to Goals: Go to Settings → Goals in your dashboard
3. Create Goal: Click "Create Goal"
4. Select Type: Choose "Custom Event Goal"
5. Enter Event Name: Type the exact event name (e.g., SignupCompleted)
6. Display Name: Give it a friendly label (e.g., "User Signups")
7. Save: Click "Save Goal"

The goal is now active and will aggregate all events matching that name.

Event Properties

Add context to events with custom properties (metadata):

window.ovyxa('event', 'VideoPlayed', {
  video_title: 'Product Demo',
  duration: '3:45',
  category: 'tutorial'
})

Property limitations:

• Maximum 10 properties per event
• Property names: alphanumeric + underscores (no spaces)
• Property values: strings, numbers, booleans
• Total payload: < 5 KB

Use cases for properties:

• Segmentation (Phase 2): Filter conversions by plan type, category, price tier
• Attribution: Track which campaign variant drove conversions
• Analysis: Export event properties for deeper analysis

Common Custom Events

E-commerce

// Add to cart
window.ovyxa('event', 'AddToCart', {
  product_id: '12345',
  price: '49.99',
  category: 'electronics'
})

// Purchase
window.ovyxa('event', 'Purchase', {
  order_id: 'ORD-2024-001',
  amount: '149.97',
  items: '3'
})

SaaS Application

// User signup
window.ovyxa('event', 'SignupCompleted', {
  plan: 'trial',
  source: 'landing_page'
})

// Feature usage
window.ovyxa('event', 'FeatureUsed', {
  feature_name: 'export_csv',
  user_plan: 'pro'
})

// Upgrade
window.ovyxa('event', 'PlanUpgraded', {
  from_plan: 'free',
  to_plan: 'pro'
})

Content & Media

// File download
window.ovyxa('event', 'FileDownloaded', {
  file_type: 'pdf',
  file_name: 'whitepaper-2025.pdf'
})

// Video engagement
window.ovyxa('event', 'VideoCompleted', {
  video_id: 'intro_tour',
  watch_time: '180'
})

// Newsletter signup
window.ovyxa('event', 'NewsletterSignup', {
  source: 'footer',
  list: 'weekly_digest'
})

Best Practices

Use consistent naming: Stick to a convention like PascalCase or snake_case for event names

Be specific but concise: SignupCompleted is better than event1 or UserHasCompletedTheSignupProcessSuccessfully

Track the outcome, not the attempt: Fire events on successful completion, not button clicks that might fail

Add meaningful properties: Include context that helps you analyze performance

Test thoroughly: Verify events fire correctly in your browser's network tab before deploying

Document your events: Maintain a list of event names and their purposes for your team

Troubleshooting

Event not appearing in dashboard?

• Check browser console for JavaScript errors
• Verify window.ovyxa is defined (script loaded)
• Confirm data-domain attribute matches your site domain
• Check network tab for successful POST to /e endpoint

Events firing multiple times?

• Remove duplicate event listeners
• Use once: true option for event listeners
• Check for accidental event propagation

Server-side events not tracking?

• Verify API key has correct permissions
• Check site_id matches your dashboard
• Ensure event_name is provided
• Review API response for error messages

Next Steps

Now that you're tracking custom events, learn how to analyze conversions to optimize your funnel and improve ROI. Or explore pageview goals for simpler URL-based tracking.