Custom Events & Properties

Sending custom events

The Abner tracking script exposes a global window.abner() function that you can call to send custom events. The first argument is the event name, and the optional second argument is an object of custom properties.

window.abner('event-name', { key: 'value' })

The event name is a string that identifies the action. This is the name you'll later filter and aggregate on — for example with filter.event_name on the REST API or the filters argument to MCP query_metrics.

Examples

Tracking a signup button click

Attach an event listener to your signup button and fire a custom event when it is clicked:

document.getElementById('signup-btn').addEventListener('click', function() {
  window.abner('Signup')
})

Tracking a form submission

Fire an event when a form is submitted, and include the form's plan selection as a custom property:

document.getElementById('signup-form').addEventListener('submit', function() {
  window.abner('Form Submit', { plan: 'pro' })
})

Tracking a purchase

Send a custom event with revenue and product information after a successful checkout:

window.abner('Purchase', {
  product: 'Annual Plan',
  revenue: 299,
  currency: 'USD'
})

Revenue tracking

You can include a revenue property (or any numeric property) on a custom event, the same as any other custom property:

window.abner('Purchase', { revenue: 49.99 })

Query this data back out via the REST API (e.g. GET /api/v1/breakdown/event_name?filter.event_name=Purchase) or MCP query_metrics. There is no dashboard goal card — aggregation happens in your query.

Custom properties via data attributes

You can attach custom properties to every pageview by adding data-props-* attributes to the Abner script tag. These properties are automatically included with each pageview event, without any additional JavaScript.

<script
  defer
  data-site="YOUR_SITE_ID"
  data-props-author="John"
  data-props-section="blog"
  src="https://www.abner.app/abner.js"
></script>

In this example, every pageview will include author: "John" and section: "blog" as custom properties. This is useful for static sites where you want to tag pages by category, author, or any other dimension without writing JavaScript.

Custom properties via the JavaScript API

For dynamic properties that vary per event, pass an object as the second argument to window.abner():

window.abner('Download', {
  file: 'whitepaper.pdf',
  format: 'pdf',
  size: '2.4MB'
})

Property values can be strings, numbers, or booleans. Each property key-value pair is stored and made available for querying via the REST API and MCP server.

Viewing custom event data

Abner's web dashboard is deliberately minimal — a site list and per-site last-24h visitors/pageviews. Custom event data (and any properties attached to it) is queried via the REST API or the MCP server, not viewed in a dashboard UI.

For example, to see how many Signup events occurred, call MCP query_metrics with events as the metric and filters: {"event_name": "Signup"}, or use GET /api/v1/metrics?filter.event_name=Signup on the REST API.

Filtering by custom properties

Custom event properties aren't a separate filterable dimension in the metrics vocabulary, but you can still narrow queries by event name — for example, filter by filter.event_name=Signup combined with dimensions like country or browser to see where those events came from.

Limitations

Keep the following limits in mind when using custom events and properties:

Events that exceed these limits will be silently dropped. Ensure your event names and property keys are concise and consistent across your codebase.