Docs

Events and identify

The tracker records pageviews, clicks and scroll depth on its own. Custom events and identify are one function call each.

Captured automatically

Once the script tag is on the page you get three events without writing any code. Their names start with $, which is reserved for ClickClacks.

Event	When	Properties
`$pageview`	When the page loads, and whenever the URL changes in a single-page app (`pushState`, `replaceState` and back/forward).	`path`. The first pageview of a load also carries `referrer`.
`$click`	On any click. The tracker records the nearest link or button that contains the click, or the clicked element if there isn’t one.	`path`, the element’s tag, id, first two classes and a short CSS selector, the click position, the viewport width, and up to 40 characters of link or button text.
`$scroll`	When the visitor leaves the page, switches tab, or navigates within a single-page app.	`path`, how far down the page they got, the page height and the viewport width.

On arrival, ClickClacks adds the country, browser, operating system and device type on the server. Click autocapture can be switched off for a source in the app; pageviews and scroll depth still arrive. Privacy covers what is left out of these events.

Custom events

Send anything that matters to your product (a sign-up, an upgrade, an export) with event, a name and an optional object of properties:

window.clickclacks('event', 'Signed up', {
  plan: 'pro',
  seats: 5,
})

The name is a string of 1 to 128 characters, and it can’t start with $.
Properties must be a plain object. Functions and undefined values are dropped.
Properties are capped at 2 KB of JSON. Over that, the event is still sent, without its properties.
A call that breaks these rules is ignored silently rather than throwing.

Properties belong to the event, not to the person. A plan sent with Signed up describes that sign-up, not the person’s current plan.

Identify people

Until you say otherwise, a visitor is anonymous: the tracker gives each browser a random ID. When someone signs in, call identify with your own ID for them:

// After sign-in, with your own user ID
window.clickclacks('identify', 'user_4821', {
  plan: 'pro',
  company: 'Acme',
})

The ID is a string of 1 to 128 characters. Use the stable ID your own system uses for the user.
It records an $identify event with the properties you pass (2 KB of JSON at most; over that, only the ID is kept).
The ID is saved in the browser, so every later event from that browser carries it, including after a reload, until you call reset.

On sign-out

// On sign-out
window.clickclacks('reset')

reset (also available as window.clickclacks.reset()) forgets the identified ID, drops any events not yet sent, and starts a new anonymous visitor and session. Tracking carries on. Call it on sign-out so the next person on a shared computer isn’t counted as the last one.

To stop tracking a visitor entirely, use optOut, described in Privacy.

Calling before the script loads

The script tag is async, so window.clickclacks doesn’t exist until it has loaded. It also never exists on a hostname missing from data-domains, because the tracker doesn’t start there.

When the tracker starts it replays any calls waiting in window.clickclacks.q, in order. So if your code might run first, define this small stub above the script tag, and calls made early are queued rather than lost:

// Before the ClickClacks script tag
window.clickclacks = window.clickclacks || function () {
  (window.clickclacks.q = window.clickclacks.q || []).push(arguments)
}

If you’d rather not add the stub, guard each call instead: window.clickclacks?.('event', 'Signed up').

How events are sent

Events are batched in the browser and sent every five seconds, as soon as 25 are waiting, and when the page is hidden or closed. If a batch fails, its events are kept and retried with the next one, so a brief network drop doesn’t lose them.