Track events with HTML attributes

Track clicks and form submissions as custom events without writing JavaScript, using data-privatus-event and data-privatus-prop HTML attributes on any element.

# Track events with HTML attributes

> Track clicks and form submissions as custom events without writing JavaScript, using data-privatus-event and data-privatus-prop HTML attributes on any element.

Add `data-privatus-event` to any element to send an event when it's
clicked:

```html
<a href="/pricing" data-privatus-event="Pricing CTA">See pricing</a>
<button data-privatus-event="Play video" data-privatus-prop-video="intro">Play</button>
```

## Properties

Every `data-privatus-prop-<key>` attribute becomes a property. Dashes in the
key become underscores:

```html
<a href="/signup" data-privatus-event="Signup CTA"
   data-privatus-prop-plan="pro"
   data-privatus-prop-button-location="hero">Start free</a>
```

sends `Signup CTA` with `{ plan: 'pro', button_location: 'hero' }`.
Attribute values are always strings, so a number written in an attribute is
stored as text and gets no sum or average. Send numbers and
[revenue](/docs/events/revenue) with `privatus.track()` instead.

## Attributes

| Attribute | Where | What it does |
|---|---|---|
| `data-privatus-event="Name"` | Any element | Sends the custom event `Name` when the element, or anything inside it, is clicked |
| `data-privatus-event="Name"` | A `<form>` | Sends `Name` when the form is submitted, not when it is clicked |
| `data-privatus-prop-<key>="value"` | The same element | Adds the property `<key>` with a string value. Only attributes on the element that has `data-privatus-event` are read |

The same [limits](/docs/events#limits) apply as for `privatus.track()`.

## Forms

On a `<form>`, the event fires when the form is **submitted**. Clicks
inside the form don't trigger the form's event (a button inside it can
still carry its own `data-privatus-event`):

```html
<form action="/contact" method="post" data-privatus-event="Contact form" data-privatus-prop-topic="sales">
  …
</form>
```

Form fields are never read or sent. Only the attributes you write become
properties.

## How it works

The tracker listens for clicks and submits on the whole document (in the
capture phase), finds the nearest ancestor with `data-privatus-event`, and
sends the event. It works for elements added later, too.

- Clicking a child element (an icon inside a button) counts for the
  element with the attribute.
- A link or form that has `data-privatus-event` itself is skipped by the
  [`auto` module](/docs/tracker/modules#auto-automatic-events), so a
  tracked outbound link isn't counted twice. Put the attribute on the
  `<a>` or `<form>`: when it sits on a wrapper around a link, `auto` still
  sends its own event for the link.
- The global properties set with `privatus.props()` are added to the
  event.
- Links navigate as usual. The request uses `keepalive` so it survives the
  navigation.

## Click maps

`data-privatus-click` is a different attribute. It sends no event: it
makes an element a click target for the `clicks` module. With a value
(`data-privatus-click="buy-pro"`) the value is the element's name in the
click map, sent in place of its CSS selector. Without one, the module
records the element's CSS selector (tag, id and classes). See
[Click maps](/docs/features/click-maps#name-your-elements).

Voir en Markdown

Add data-privatus-event to any element to send an event when it's clicked:

html

<a href="/pricing" data-privatus-event="Pricing CTA">See pricing</a>
<button data-privatus-event="Play video" data-privatus-prop-video="intro">Play</button>

Properties#

Every data-privatus-prop-<key> attribute becomes a property. Dashes in the key become underscores:

html

<a href="/signup" data-privatus-event="Signup CTA"
   data-privatus-prop-plan="pro"
   data-privatus-prop-button-location="hero">Start free</a>

sends Signup CTA with { plan: 'pro', button_location: 'hero' }. Attribute values are always strings, so a number written in an attribute is stored as text and gets no sum or average. Send numbers and revenue with privatus.track() instead.

Attributes#

Attribute	Where	What it does
`data-privatus-event="Name"`	Any element	Sends the custom event `Name` when the element, or anything inside it, is clicked
`data-privatus-event="Name"`	A `<form>`	Sends `Name` when the form is submitted, not when it is clicked
`data-privatus-prop-<key>="value"`	The same element	Adds the property `<key>` with a string value. Only attributes on the element that has `data-privatus-event` are read

The same limits apply as for privatus.track().

Forms#

On a <form>, the event fires when the form is submitted. Clicks inside the form don't trigger the form's event (a button inside it can still carry its own data-privatus-event):

html

<form action="/contact" method="post" data-privatus-event="Contact form" data-privatus-prop-topic="sales">
  …
</form>

Form fields are never read or sent. Only the attributes you write become properties.

How it works#

The tracker listens for clicks and submits on the whole document (in the capture phase), finds the nearest ancestor with data-privatus-event, and sends the event. It works for elements added later, too.

Clicking a child element (an icon inside a button) counts for the element with the attribute.
A link or form that has data-privatus-event itself is skipped by the auto module, so a tracked outbound link isn't counted twice. Put the attribute on the <a> or <form>: when it sits on a wrapper around a link, auto still sends its own event for the link.
The global properties set with privatus.props() are added to the event.
Links navigate as usual. The request uses keepalive so it survives the navigation.

Click maps#

data-privatus-click is a different attribute. It sends no event: it makes an element a click target for the clicks module. With a value (data-privatus-click="buy-pro") the value is the element's name in the click map, sent in place of its CSS selector. Without one, the module records the element's CSS selector (tag, id and classes). See Click maps.