Custom events

Beyond pageviews, you can record any action that matters — a signup, a checkout, a button click. The tracker exposes one global function:

window.satsu(name, props?);

name — a string naming the event (e.g. "signup"). Truncated to 128 characters.
props (optional) — a flat object of extra data. Values may be strings, numbers or booleans.

Examples

A simple event:

window.satsu("signup");

An event with properties:

window.satsu("signup", { plan: "pro", referrer: "changelog" });

Wire it to a click:

html

<button onclick="window.satsu('cta_click', { location: 'hero' })">
  Start free
</button>

Or in a framework, call it from your handler:

tsx

function CheckoutButton() {
  return (
    <button
      onClick={() => window.satsu("checkout_started", { plan: "pro" })}
    >
      Upgrade
    </button>
  );
}

TypeScript

The tracker attaches satsu to window at runtime. Declare it once so TypeScript knows the signature:

// satsu.d.ts
declare global {
  interface Window {
    satsu: (name: string, props?: Record<string, string | number | boolean>) => void;
  }
}
export {};

Rules and limits

Keep props flat. Nested objects and arrays aren't supported — one level of string / number / boolean values. The whole props payload is capped at ~2 KB.
Never put personal data in props. No emails, names, user IDs or anything that identifies a person. This is the core privacy promise, and props with PII will be rejected. Use props for context (plan, variant, source), not identity.
Events count toward your plan's monthly event limit — pageviews and custom events both count; heartbeats never do.
Calls before the tracker loads are safe to guard. If you might fire an event before the script has run, check first: window.satsu?.("event").

Turning events into conversions

A custom event on its own is a raw signal. To measure it as a conversion — with a conversion rate and breakdowns — create a goal that matches its name. See Goals & conversions.

Reserved events

Three event names are produced automatically by the tracker for engagement tracking: Outbound Link, File Download and Scroll Depth. You don't fire these yourself — they appear in your dashboard without any code. Avoid reusing these exact names for your own events.

Next: Goals & conversions →