Docs
Custom events
Track the actions that matter — signups, purchases, button clicks — not just pageviews. Custom events reuse the same script and the same endpoint.
What is a custom event
A pageview is recorded automatically whenever a page loads or the URL changes. A custom event is anything else you decide matters: a signup, a checkout, a CTA click. Each one has a name and an optional set of properties.
How it works
The script exposes a global lumen function. Call it with a name and, optionally, a plain object of properties:
lumen("Signup", { plan: "pro" });The call is fire-and-forget. The script adds the usual context (URL, title, referrer, viewport, language, timestamp, and server-derived device/browser/OS) and sends it through the same ingest endpoint as a pageview.
Add properties
Properties are stored with the event so you can add context — plan, price, variant, location. Values can be strings, numbers or booleans.
lumen("Purchase", {
plan: "pro",
seats: 3,
currency: "USD",
});Guard the call
If your code might run before the script loads — a bundler, a component, or server-side rendering — use optional chaining:
window.lumen?.("Signup", { plan: "pro" });Calling an undefined global throws and can break the surrounding code. The guard makes the call a harmless no-op when tracking is blocked or not ready.
What is tracked automatically
These already work without extra code, so don't send them yourself:
- pageview — initial load and SPA navigation.
- scroll — 25/50/75/100% depth.
- outbound — clicks on external links.
- download — clicks on file links.
- leave — tab close, with session duration.
Limits and good names
The event name is trimmed and capped at 64 characters. The whole payload must stay under about 16 KB. Keep names stable and readable (Signup Completed) so they group correctly in the dashboard.
Custom events count as events toward your plan's monthly meter, alongside pageviews.
Do not send personal data
Properties are stored verbatim. Never put emails, names, phone numbers or anything else that identifies a person in an event name or property value.