Custom events

Three ways to track events: data attributes, no-code rules in the dashboard, and the JavaScript API.

Three ways in

A custom event is a named thing a visitor did: a signup click, a checkout, a download. There are three ways to produce one, and they are the same event once it arrives. Pick whichever fits how you work.

An HTML attribute

Mark an element and every click counts. No code, no dashboard step.

A no-code rule

Define it in the dashboard. No deploy at all; live on the next pageview.

The JavaScript API

oa.track() for anything conditional or programmatic.

1. The attribute: data-oa-event

Mark any element and every click on it counts, under the name you wrote:

anywhere in your HTMLhtml

<button data-oa-event="signup_click">Sign up</button>

The name is letters or digits first, then letters, digits, _ . : -, up to 64 characters. An invalid name sends nothing, silently.
A click anywhere inside the marked element counts once; when marked elements nest, the innermost one wins.
On a <form> the attribute fires on submit instead of click.
A middle-click on a marked link counts too, the same as cmd or ctrl click: opening your CTA in a new tab is still following it.

Add properties with data-oa-prop-* on the same element, so one event name can answer both how many and which:

one name, two placementshtml

<a href="/signup" data-oa-event="signup" data-oa-prop-section="hero">Get started</a>
<a href="/signup" data-oa-event="signup" data-oa-prop-section="pricing">Get started</a>

Write property keys in kebab-case

HTML lowercases attribute names, so data-oa-prop-buttonLabel silently becomes the key buttonlabel. Properties are read from the marked element only, never from parents or children.

2. No-code rules

Under your site's Custom events tab you can define a rule (click, submit, or URL pattern) that produces an event without touching your site at all. Rules can read an element's text, an allowlisted attribute, the page path or a query parameter, and never the value of an input, at any layer. Publish the rule and it is live for the next pageview; no deploy.

If a rule and an attribute would name the same click identically, the rule wins and exactly one event fires.

3. The JavaScript API

anywhere after the snippetjs

oa.track("plan_selected", { plan: "growth" });

// a conversion is a custom event that marks an outcome;
// with an order_id it also ties revenue to the visit
oa.conversion("purchase", { order_id: "cs_live_a1B2c3" });

Properties: up to 32 per event, keys up to 40 characters, string values up to 256.
Keys starting with oa_ are reserved and dropped, and so are keys that name a secret (token, session, email and friends).
Values are redacted in the browser before sending: an email address or a card-shaped number becomes [redacted]. Do not rely on it, but a template mistake is not a leak.
Nothing needs declaring first. There is no schema step; the event and its properties appear in the dashboard when they first fire.

Do not double-count

Two instruments, same name, same element bills twice

A custom event counts as one event, like a pageview (the full matrix is on usage and billing). The one case to avoid is describing the same click twice yourself: an attribute plus an oa.track() of the same name on the same element bills twice. Pick one. A dashboard rule with the same name is safe; the rule wins and one event fires.

Reading them

Events appear in the dashboard's custom events breakdown with their count, when they last fired, a sample page path and a sample property bag, so you can tell what a name actually carries without leaving the list. Attaching a display name is optional labelling under Custom events; nothing depends on it.