Custom events

Beyond automatic pageviews, you can send custom events to track any user interaction. Tracked events appear in your dashboard under the Custom Events card on the Overview page.

Syntax

OpenAnalytics.track(eventName, properties)

Parameter	Type	Description
`eventName`	string	A human-readable name for the event (e.g. "Signup", "Add to Cart").
`properties`	object (optional)	Key-value pairs with additional context. Stored as JSON.

Note

Call OpenAnalytics.track only after the script has loaded. If you call it immediately on page load, wrap it in a DOMContentLoaded listener or check that window.OpenAnalytics exists first.

Event examples

Button click

<button onclick="OpenAnalytics?.track('CTA Clicked', { button: 'hero' })">
  Get Started
</button>

Form submission

document.querySelector("#signup-form").addEventListener("submit", () => {
  OpenAnalytics?.track("Signup Form Submitted");
});

React — event on button click

function UpgradeButton() {
  function handleClick() {
    OpenAnalytics?.track("Upgrade Clicked", { plan: "pro", source: "banner" });
    // ... open checkout
  }

  return <button onClick={handleClick}>Upgrade to Pro</button>;
}

E-commerce — add to cart

OpenAnalytics?.track("Add to Cart", {
  product_id: "sku-1234",
  product_name: "Wireless Headphones",
  price: 79.99,
  currency: "USD",
});

Video play

document.querySelector("#hero-video").addEventListener("play", () => {
  OpenAnalytics?.track("Video Played", { video: "hero-demo" });
});

Declarative click tracking

Track clicks without writing JavaScript:

<button
  data-oa-event="signup"
  data-oa-event-plan="pro"
>
  Sign up
</button>

Extra attributes use the prefix data-oa-event-; hyphens in the name become underscores in the payload (e.g. data-oa-event-plan → plan).

Identify logged-in users

Set a distinct_id to associate events with a logged-in user. In fingerprint mode it is stored in sessionStorage; in cookie mode (data-use-cookies="true") it is stored in the oa_did cookie.

// After login
OpenAnalytics.identify("user_12345");

// After logout
OpenAnalytics.identify(null);