Skip to content

Custom properties

Custom properties are key/value pairs attached to an event. They turn a single event name into a richer signal. Instead of Plan Selected alone, you get Plan Selected with plan=pro, billing=annual, currency=usd.

Use them whenever one event covers several variants you want to compare. One event with three properties beats three near-duplicate event names.

Make sure s.js is installed on the page. See Install the tracking script.

Three ways to attach properties

1. JavaScript API

Pass a plain object as the second argument to window.statable.t():

window.statable.t('Sign Up', {
  plan: 'pro',
  user_id: '12345',
  campaign: 'spring-sale'
})

Values can be strings, numbers, or booleans. Nested objects and arrays aren't supported. Flatten before sending.

2. HTML data-attributes on the element

Add any number of data-statable-{key} attributes alongside data-statable-event on the same element. When the click fires, the SDK reads every data-statable-* attribute (except data-statable-event itself) and attaches its value as a property:

<button
  data-statable-event="Sign Up"
  data-statable-plan="pro"
  data-statable-source="footer">
  Start Pro plan
</button>

That fires the event Sign Up with plan=pro and source=footer.

Stick to single-word, lowercase keys

The SDK lowercases property keys read from element attributes. data-statable-plan becomes plan, data-statable-source becomes source. Multi-word kebab keys like data-statable-user-id flatten to userid (no separator, all lowercase). Surprising, and a frequent source of dashboard mismatches. Prefer one-word keys, or use the JavaScript API where you control the exact key shape.

3. Default properties on the script tag

Attach properties to every event from the page by adding data-statable-{key} directly to the <script> tag. The SDK reads them once at load and merges them into every pageview:

<script defer
  src="https://statable.com/js/YOUR_SITE_ID/s.js"
  data-statable-app-version="2.4.1"
  data-statable-environment="production"></script>

Property keys on the script tag keep their hyphens

Unlike attributes on a clicked element, properties read from the <script> tag preserve the raw attribute suffix. So data-statable-app-version arrives as app-version (kebab-case). Single-word keys (data-statable-version, data-statable-env) behave the same everywhere.

4. data-before-send hook (pageviews only)

For dynamic pageview enrichment (values that depend on auth state, A/B buckets, or runtime config), define a global function and reference it from the script tag with data-before-send:

<script>
  window.enrichProps = function (props) {
    props.logged_in = Boolean(window.currentUser)
    props.experiment = window.abTestBucket || 'control'
    return props
  }
</script>

<script defer
  src="https://statable.com/js/YOUR_SITE_ID/s.js"
  data-before-send="enrichProps"></script>

The function receives the current properties object, mutates or replaces it, and returns the new value. The hook only runs for pageviews. Custom events triggered by window.statable.t() or data-statable-event clicks bypass it. To enrich custom events dynamically, build the props object in JavaScript and pass it to window.statable.t() directly.

Naming conventions

  • Use lowercase, single-word keys: plan, source, userid, cohort. They map identically across all three input methods.
  • Keep keys stable. Renaming creates a new property in the dashboard; the old one stays until it ages out.
  • Keep strings short. Truncate IDs and URLs on your side if needed.
  • Don't put PII in properties. No email addresses, full names, or IP-equivalents. Use a hashed or anonymous ID if you need to correlate users.

Viewing properties

Properties are auto-discovered. Fire an event with a new key and it becomes filterable in the dashboard within minutes. Every property surfaces as a filter named prop_<key>. For example, prop_plan = pro scopes every widget to sessions where any event carried plan=pro. Combine property filters with other filters to slice by source, device, or country at the same time.

Limits

  • Each plan has a ceiling on distinct property keys per site. See your billing page for the current limit.
  • Boolean values are stored as strings in reports. Filter on "true" / "false", not unquoted values.

Next steps

Ready to take control of your web analytics? Try Statable free for 30 days — no credit card required, full feature access, GDPR-compliant by default. Start your free trial or view a live demo.