Custom properties

What custom properties are

Properties are key/value details you attach to an event, so one event name can carry the context that makes it useful. A single Signup event can record which plan was chosen; a Purchase event can record the method and a pricing variant. The Properties section then breaks any event down by a property key, one row per value.

Properties are not set up in the dashboard, and there is no form for adding one. A property exists once an event carries it, which means it is created by the code that sends the event. The Properties section is the report over whatever has arrived. For how that fits with events, goals and funnels, see how the pieces fit together.

Send a property

Pass a props object when you send the event. Values can be strings, numbers or booleans:

// One property
numative("Signup", { props: { plan: "growth" } })

// Several, including a number and a boolean
numative("Purchase", {
  props: { plan: "growth", method: "card", trial: false },
  revenue: { amount: 19.99, currency: "USD" },
})

A few limits apply (at most 30 properties per event, keys and values truncated at 300 characters, nested objects dropped). The full rules live in Custom events.

Read the Properties report

1. 1

   Open the Properties section

   Property keys are discovered automatically from the events in your selected date range, so there is nothing to declare up front. Send a property once and it appears in the picker.

2. 2

   Pick a key

   Choose a key (say plan) and the table lists every value seen for it, with visitors, events and revenue per value.

3. 3

   Filter the whole dashboard by a value

   Any property value can become a dashboard filter, so you can send the entire dashboard (traffic, sources, funnels, goals) through, for example, plan = growth. See Filters and segments.

Worked example

With the Purchase event above, the Properties section keyed on plan reads like this:

Switch the key to method to see card versus invoice, or filter to plan = enterprise and every other card on the dashboard follows.

Good keys to send

• Plan or tier on signups and purchases, to split revenue and conversion by pricing.
• Method or provider on purchases (card, PayPal, invoice).
• Variant or experiment to compare A/B outcomes on the same event.