# Custom events

> Count the things visitors do on your site, such as a signup or a click on a button, with one attribute or one line of JavaScript.

This page shows how to count what visitors do on your site, not only which pages they open. After reading it you can send an event from a button or from your own code, attach details to it, and find it in the dashboard.

## What an event is

A page view is recorded for you. A custom event is anything else you decide to count: a signup, a download, a click on "Add to cart". You give it a name, and Clear Saga counts how often it happened and how many visitors did it.

Both scripts send custom events, the light one and the full one. The script is the only supported way to send an event: there is no separate address for your server to post events to.

Every stored hit uses one unit of your monthly allowance. A page view is one, a custom event is one, a hit for a missing page is one, and so is a web vitals sample. A hit that is filtered out, such as a bot or a visit you excluded, is never stored and uses nothing. [Plans, usage and limits](/docs/plans-and-usage) has the details.

## Send an event

There are two ways, and you can mix them on one site.

**From a click**

```html
<button data-clearsaga-event="Newsletter signup" data-clearsaga-event-source="footer">Subscribe</button>
```

**From JavaScript**

```js
window.clearsaga?.track('Purchase completed', { plan: 'pro' })
```

**The attribute.** Add `data-clearsaga-event` to any element, with the name of the event as its value. A click on the element, or on anything inside it, sends the event. No JavaScript is needed, which makes this the easy choice in a site builder.

**The call.** Call `track` on `window.clearsaga` with the name of the event. Use this when the moment you care about is not a click, such as a form that was accepted by your server. The `?.` in the sample keeps your page working when a content blocker removed the script.

One visitor can have 120 hits recorded in a minute. Further hits in that minute are dropped, which no person browsing a site comes near.

Nothing is sent for a visitor who is left out: a browser with Global Privacy Control or Do Not Track switched on, or one where you opted out yourself. The call does nothing in that case and never raises an error.

## Names

- A name is at most 64 characters. A longer one is cut.
- Capital letters count. `Signup` and `signup` are two different events, so pick one spelling and keep it.
- Some names are kept for the script itself and are ignored when you send them: `pageview`, `404`, and any name that starts with `clearsaga:`.

## Properties

A property is a detail that travels with an event, such as which plan was bought or where on the page the button sat.

On an element, every attribute that starts with `data-clearsaga-event-` becomes a property. The rest of the attribute name is the name of the property, and a hyphen followed by a letter becomes a capital: an attribute ending in `plan-name` gives the property `planName`. From JavaScript, pass an object as the second argument, as the sample above does.

The limits:

- The first 16 properties of an event are looked at. The rest are dropped.
- A property name longer than 48 characters is dropped.
- A value is text, a number, or true or false. Anything else, such as a list, is dropped. Text is cut at 200 characters.
- A property that looks like personal data is dropped: a name such as `email`, `phone` or `password`, or a value shaped like an email address.

Only the offending property goes. The event itself is always kept.

## Calling before the script has loaded

The tag loads the script without holding up your page, so code that runs very early can call `track` before the script is there. To keep those calls, put this line before the tag:

```html
<script>window.clearsaga=window.clearsaga||{q:[],track:function(){this.q.push(arguments)}}</script>
```

It records the calls, and the script sends them once it has loaded. Events are also held back until the first page view of the page has gone out, so an event never arrives before the visit it belongs to. Up to 50 calls are held this way.

## Count a section that was seen

The full script can send an event the first time a part of a page has been on screen, with no click at all. Mark the section:

```html
<section data-clearsaga-scroll="viewed_pricing" data-clearsaga-scroll-threshold="0.6" data-clearsaga-scroll-delay="1000">...</section>
```

- `data-clearsaga-scroll` holds the name of the event. Here a name may only use lower-case letters, digits, underscores, colons and hyphens.
- `data-clearsaga-scroll-threshold` is the share of the section that must be visible, from 0.1 to 1. Left out, it is 0.5, which is half. A section taller than the screen counts once it fills that share of the screen.
- `data-clearsaga-scroll-delay` is how long it must stay visible, in milliseconds, up to 10 seconds. Left out, the event is sent at once.

Each marked element sends its event once. In an app that draws the section again after a change of page, it can be sent again. This is not scroll depth: no percentage or position is collected, only the event. The light script ignores these attributes, so load the full script for them. [Add the tracker](/docs/tracker) shows its tag.

## Where events show up

Open **Events** in the sidebar of a site. It has two views.

**Activity log** lists single hits, newest first, in these tabs: All, Views, Events and Properties. Events holds your custom events. Properties holds the ones that carried properties, with how often each value occurred. Select the name of an event to narrow the log to it. "Load more" adds 50 rows at a time.

**Insights** shows how your events develop. Its tiles count the events, the different event names and the visitors who sent at least one. "Events over time" draws the 5 most frequent events as a line each and sums the rest into one. "Trending events" compares every event with the period before, so you see which ones are growing.

The Overview has an Events card as well, and you can filter the dashboard by an event name, as [filters and saved segments](/docs/filters-and-segments) explains. A person who opens a shared dashboard link sees that card and never the log of single hits.

Once an event is flowing you can mark it as a [conversion goal](/docs/conversion-goals) or use it as a step in a [funnel](/docs/funnels).

**Next:** [Conversion goals](/docs/conversion-goals), [Funnels](/docs/funnels), [Script options](/docs/script-options)