Custom Events & Autocapture

VeloStats makes it effortless to track custom user interactions—such as signup button clicks, checkout steps, pricing toggles, outbound link clicks, and file downloads—without writing complex tracking code.

Note: Viewing Custom Events analytics in the dashboard requires a paid plan (Starter, Pro, or Enterprise).

1. Automatic Capture (Zero Code Required)

Out of the box, velo.js automatically intercepts clicks on <a> links across your website and records two built-in event types:

• outbound_link: Triggered whenever a visitor clicks an external link pointing to a different hostname than your current site. The full destination URL is recorded as the event target.
• file_download: Triggered whenever a visitor clicks a link ending in a common document, media, or archive extension: .pdf, .zip, .mp4, .mp3, .csv, .docx, .xlsx, .pptx, .gz, .exe, .dmg, .rar, .7z, .tar, .doc, .xls, .ppt, .mov, .wav.

No configuration is needed for outbound links or file downloads—they appear automatically in your Analytics > Custom Events view.

2. Declarative HTML Attributes (data-velo-event)

The easiest way to track clicks on buttons, links, or any interactive DOM element is by adding the data-velo-event attribute directly in your HTML.

Basic Event

<button data-velo-event="signup_click">
  Start Free Trial
</button>

When a user clicks the button (or any child element inside it, such as an icon or <span>), VeloStats dispatches a signup_click event.

Attaching Custom Properties (data-velo-prop-*)

You can attach custom key-value metadata to any declarative event using data-velo-prop-* attributes. Attribute names after data-velo-prop- are automatically normalized to lowercase hyphenated keys:

<button
  data-velo-event="upgrade_plan"
  data-velo-prop-tier="pro"
  data-velo-prop-billing-cycle="annual"
>
  Choose Pro Plan
</button>

This sends the event upgrade_plan with properties:

{
  "tier": "pro",
  "billing-cycle": "annual"
}

3. JavaScript API (window.velo)

For dynamic workflows—such as form submissions, multi-step checkouts, modal views, or async API callbacks—use the global window.velo function.

Tracking Custom Events

Call window.velo('track', eventName, properties):

// Simple event
window.velo('track', 'newsletter_subscribed');

// Event with custom metadata properties
window.velo('track', 'checkout_completed', {
  plan: 'starter',
  currency: 'USD',
  value: 19,
  coupon_applied: true
});

Safe Early Queuing (Before Script Load)

Because velo.js loads with defer, if you need to trigger events immediately during page initialization before the script has finished loading, add this tiny queue snippet in your <head>:

<script>
  window.velo = window.velo || function() {
    (window.velo.q = window.velo.q || []).push(arguments);
  };
</script>

Any calls made to window.velo('track', ...) before velo.js initializes will be queued and flushed automatically.

Manual Pageview Tracking

VeloStats automatically tracks Single Page Application (SPA) route changes via the browser History API (pushState, replaceState, and popstate). However, if you set data-auto-track="false" on your <script> tag to control pageviews manually, you can trigger a pageview at any time:

window.velo('page');

Validation & Payload Limits

To ensure fast ingestion and protect your analytics database, custom events enforce the following validation rules: