Custom Events

Pageview tracking tells you which pages your visitors load. Custom events let you track what visitors do on those pages — clicking a button, submitting a form, completing a purchase, downloading a file, or any other meaningful interaction.

What custom events are

A custom event is a named signal you send to Statalog from your own JavaScript or via an HTML attribute. Events appear in the Analytics → Events section of your dashboard with a count of how many times each event occurred in the selected date range.

Events are useful when:

  • A conversion happens without a page navigation (e.g. a modal form submission)
  • You want to track micro-interactions (e.g. "Add to cart" clicks before checkout)
  • You want to attach metadata to an action (e.g. the plan a user selected, or the revenue of a purchase)

The JavaScript API

The tracker exposes a global statalog() function as soon as the script loads. To fire an event, call it with 'event' as the first argument and the event name as the second:

statalog('event', 'Sign Up')

Sending properties with an event

You can attach optional properties to any event as a plain object. Properties can be strings, numbers, or booleans:

statalog('event', 'Purchase', {
  revenue: 49.00,
  plan: 'pro',
  trial: false
})

Properties appear as filterable dimensions in the Events report. For example, you could filter the Purchase event to show only plan: pro purchases.

Common event examples

// Track a file download
document.querySelector('.download-btn').addEventListener('click', function () {
  statalog('event', 'File Download', { filename: 'whitepaper.pdf' })
})

// Track a form submission
document.querySelector('#contact-form').addEventListener('submit', function () {
  statalog('event', 'Contact Form Submitted')
})

// Track a video play
videoElement.addEventListener('play', function () {
  statalog('event', 'Video Play', { title: 'Product Demo' })
})

Waiting for the tracker to load

If you call statalog() before the script has loaded, the call will be queued automatically — the tracker initialises the queue on the first call. In most cases you do not need to worry about timing, but if you are firing events very early in the page lifecycle you can wrap the call in a check:

if (typeof statalog === 'function') {
  statalog('event', 'Early Action')
}

The data-event HTML attribute

For simple click tracking, you do not need to write any JavaScript. Add a data-event attribute to any HTML element, and the tracker will automatically fire an event with that name when the element is clicked:

<button data-event="Sign Up">Get started</button>

<a href="/pricing" data-event="View Pricing">See plans</a>

The data-event attribute works on any focusable or clickable element. It is the fastest way to instrument UI elements without touching your application code.

Event naming rules

  • Event names are case-sensitive. Sign Up and sign up are recorded as two separate events.
  • Maximum event name length is 100 characters.
  • Avoid leading or trailing whitespace in event names.
  • Property keys follow the same rules: case-sensitive, max 100 characters.
  • Property values can be strings (max 500 characters), numbers, or booleans.

Viewing events in the dashboard

Events appear under Analytics → Events. The report shows:

  • The event name
  • Total count of occurrences in the selected date range
  • Unique visitor count (how many distinct visitors triggered the event)
  • A breakdown of any properties attached to the event

Click an event name to drill into its properties and see the distribution of values.

Frequently asked questions

Are events retroactive? No. Events are recorded at the moment they are fired. If you add a data-event attribute to a button today, Statalog will count clicks from today forward — it has no record of clicks that happened before the attribute was added.

What is the difference between events and goals? Goals are URL-based: Statalog monitors the URL of every pageview and marks a conversion when a URL matches your goal pattern. Events are JavaScript-triggered: your code (or the data-event attribute) explicitly tells Statalog that something happened. Use goals for page-load conversions (e.g. a /thank-you page after signup) and events for in-page interactions that do not cause navigation.

Can I send events server-side? Server-side event ingestion via the Statalog API is available on the Pro and Enterprise Cloud plans. See the API reference for details.

Is there a limit on the number of events? There is no limit on distinct event names. On the Cloud edition, event volume counts toward your monthly pageview quota — each event record is counted the same as a pageview.