Custom Events

Send custom events from your site with track(): signups, purchases, CTA clicks, and actions beyond pageviews.

Custom events let you measure actions beyond pageviews: signups, purchases, feature usage, or any interaction that matters to your product.

Pageviews are tracked automatically once the tracker script is installed. Custom events are sent explicitly from your code with track().

Before you start

Add the Clics tracker script to your site (see Installation Guides
Install the npm package (recommended for TypeScript projects):

npm add @clicsdev/tracker

The script tag is required. The npm package only adds a typed track() helper. It does not replace the script.

What gets tracked

Type	How	Event name
Pageviews	Automatic on load and SPA navigation	`pageview`
Custom events	`track()` in your code	Any name you choose

Each event includes the page URL, referrer, UTM parameters, and your project ID. Properties you pass to track() are merged into the event payload.

`track(name, props?)`

Send a custom event from the browser.

import { track } from "@clicsdev/tracker";

track("signup");
track("purchase", { plan: "pro", billing: "annual" });
track("cta_click", { location: "hero", variant: "primary" });

Argument	Type	Description
`name`	`string`	Event name (e.g. `signup`, `purchase`)
`props`	`Record<string, unknown>`	Optional properties attached to the event

track() only works in the browser and requires the tracker script to be loaded first. If the script is missing, a warning is logged to the console and the event is not sent.

Naming conventions

Use short, lowercase names with underscores:

signup, login, purchase
cta_click, feature_used, trial_started

Keep names stable over time. goals and funnels match on the exact event name.

Property values should be strings, numbers, or booleans. Use consistent keys across events (e.g. always plan, not plan on one event and tier on another).

Examples

Button click

import { track } from "@clicsdev/tracker";

export function SignupButton() {
  return (
    <button
      type="button"
      onClick={() => track("signup", { plan: "pro" })}
    >
      Sign up
    </button>
  );
}

Form submission

function onSubmit(data: FormData) {
  track("contact_form", {
    topic: data.get("topic"),
    source: "pricing_page",
  });
}

After a successful checkout

track("purchase", {
  amount: 49,
  currency: "USD",
  plan: "pro",
});

Analyze events in the dashboard

There is no separate Events tab. Use the Events card on Overview (and AI Analytics) for top event names, filter Overview by Event, or inspect properties on a visit under Sessions. See Events for the full dashboard guide.

Use events in goals and funnels

Goals: create an event goal in Configure → Goals and set the event name to match your track() call. See Goals.
Funnels: add a funnel step that matches a custom event name. See Funnels.

Track custom events with Clics track() API

Custom Events