# Custom events

Record named events from JavaScript or HTML attributes.

> [!NOTE]
> The [tracking script](https://docs.kogut.dev/web-apps/tracking-script/) sends custom events. kogut stores
> them, but the panel, API, and MCP tools do not expose them.

## JavaScript

`window.kogut.track(name, props)` sends an event. `props` is optional and accepts
strings, numbers, and booleans. The server stores values as strings.

```js
window.kogut?.track("signup", { plan: "pro", seats: 3, trial: true });
```

The optional chain skips calls before the script loads. Calls do nothing when tracking is
off, such as on local pages or before prerender activation.

```ts title="kogut.d.ts"
declare global {
	interface Window {
		kogut?: { track(name: string, props?: Record<string, string | number | boolean>): void };
	}
}
export {};
```

## HTML

A click on an element with `data-kogut-event`, or a child of that element, sends the
named event. Each `data-kogut-event-<key>` attribute supplies a string property.

```html
<button data-kogut-event="signup" data-kogut-event-plan="pro">Start with Pro</button>
```

## Outbound links

Clicks on HTTP or HTTPS links to another host send `outbound` with a `url` property,
without query strings or fragments. A tagged link sends its named event instead.

## Properties

Names have 1 to 100 characters. Events accept at most 10 properties, with keys of 1 to
50 characters and values of up to 200 characters. Numbers and booleans count after
conversion to strings. The server rejects events that exceed these limits.

The server redacts property values, but not names and keys. Do not send personal data:
send a plan or variant, not user ids or order numbers.