Custom event properties

Add typed custom event properties (strings, numbers, booleans and arrays) to events and pageviews, see how keys are normalized and query them with prop filters.

# Custom event properties

> Add typed custom event properties (strings, numbers, booleans and arrays) to events and pageviews, see how keys are normalized and query them with prop filters.

Properties are key-value pairs sent with an event or pageview:

```js
privatus.track('Download', { file_type: 'pdf', size_mb: 2.4, gated: false, tags: ['guide', 'pricing'] })
```

## Types

| Type | Example | Notes |
|---|---|---|
| String | `'pro'` | Up to 500 characters. Longer values are cut |
| Number | `49.99`, `3` | Must be finite. Sum, average, median and p90 are available in the Events explorer. A number sent as a string (`'3'`) is a string and is left out of those |
| Boolean | `true` | |
| Array of strings | `['a', 'b']` | Up to 30 items of up to 500 characters. Non-string items are dropped |

`null`, `undefined`, objects and nested arrays are dropped. Dates: send an
ISO 8601 string (`'2026-09-29'`).

An event keeps its first 30 properties. See [Limits](/docs/events#limits).

## Keys

Keys are normalized before storage: lowercased, any character outside
`a-z 0-9 _` becomes `_`, repeated underscores are collapsed, underscores at
the start and end are removed, and the key is cut to 64 characters.
`Plan Name` becomes `plan_name`, `userType` becomes `usertype`. A key with
nothing left (`'---'`) is dropped. Use `snake_case` to avoid surprises.

## Reserved keys

`revenue` and `currency` are taken out of the properties and stored as the
event's [revenue](/docs/events/revenue).

## Properties on every hit

```js
privatus.props({ logged_in: true, theme: 'dark' })
```

adds properties to every later pageview and event on the page load. Or
set [`data-props`](/docs/tracker/attributes) to the name of a global
function that returns them. It is called for every hit, and properties
passed to `privatus.track()` win over it.

Properties on pageviews are stored, and the
[Experiments report](/docs/features/experiments) reads them. `prop:<key>`
breakdowns and filters look at custom events only.

## Privacy

The [PII scrubber](/docs/privacy/pii-scrubbing) (on by default for every
site) runs on string values, including the strings in a list: emails, UUIDs, long hex ids, tokens and long
digit runs are replaced with placeholders such as `[redacted-email]`.
Property keys and event names are not scrubbed.
It's a safety net, not a license: never send names, emails, user ids or
free text typed by visitors.

## Querying properties

Use `prop:<key>` (the normalized key) as a dimension anywhere the API or
dashboard accepts one:

```text
/sites/pa_7Q2K9XH3AB/breakdown/prop:plan.json?filters=[["event","is","Signup"]]
```

or as a filter: `["prop:plan", "is", "pro"]`, which keeps the visits with
a custom event that carries that value. Number properties also take `gt`,
`lt` and `between`. See [Filters](/docs/api/filters).

查看 Markdown

Properties are key-value pairs sent with an event or pageview:

privatus.track('Download', { file_type: 'pdf', size_mb: 2.4, gated: false, tags: ['guide', 'pricing'] })

Types#

Type	Example	Notes
String	`'pro'`	Up to 500 characters. Longer values are cut
Number	`49.99`, `3`	Must be finite. Sum, average, median and p90 are available in the Events explorer. A number sent as a string (`'3'`) is a string and is left out of those
Boolean	`true`
Array of strings	`['a', 'b']`	Up to 30 items of up to 500 characters. Non-string items are dropped

null, undefined, objects and nested arrays are dropped. Dates: send an ISO 8601 string ('2026-09-29').

An event keeps its first 30 properties. See Limits.

Keys#

Keys are normalized before storage: lowercased, any character outside a-z 0-9 _ becomes _, repeated underscores are collapsed, underscores at the start and end are removed, and the key is cut to 64 characters. Plan Name becomes plan_name, userType becomes usertype. A key with nothing left ('---') is dropped. Use snake_case to avoid surprises.

Reserved keys#

revenue and currency are taken out of the properties and stored as the event's revenue.

Properties on every hit#

privatus.props({ logged_in: true, theme: 'dark' })

adds properties to every later pageview and event on the page load. Or set data-props to the name of a global function that returns them. It is called for every hit, and properties passed to privatus.track() win over it.

Properties on pageviews are stored, and the Experiments report reads them. prop:<key> breakdowns and filters look at custom events only.

Privacy#

The PII scrubber (on by default for every site) runs on string values, including the strings in a list: emails, UUIDs, long hex ids, tokens and long digit runs are replaced with placeholders such as [redacted-email]. Property keys and event names are not scrubbed. It's a safety net, not a license: never send names, emails, user ids or free text typed by visitors.

Querying properties#

Use prop:<key> (the normalized key) as a dimension anywhere the API or dashboard accepts one:

text

/sites/pa_7Q2K9XH3AB/breakdown/prop:plan.json?filters=[["event","is","Signup"]]

or as a filter: ["prop:plan", "is", "pro"], which keeps the visits with a custom event that carries that value. Number properties also take gt, lt and between. See Filters.