Tracker JavaScript API reference

Once loaded, the tracker exposes window.privatus (or the name in data-namespace).

privatus.track(name, props?, callback?)#

Sends a custom event.

privatus.track('Signup', { plan: 'pro', seats: 3 })
privatus.track('Purchase', { revenue: 49.99, currency: 'EUR', sku: 'A1' })

• name: up to 120 characters, any language. Trimmed and Unicode normalized (NFC), and anything longer is cut. Case is kept.
• props: up to 30 properties of type string (cut at 500 characters), number, boolean or array of strings (up to 30 items). Other values, including null and nested objects, are dropped. Keys are lowercased, characters other than a-z, 0-9 and _ become _, and keys are cut at 64 characters. revenue and currency are reserved. See Properties and Revenue.
• callback: called once the request has completed, or straight away if nothing is sent (opted out, excluded, debug mode). It's called after the first attempt and never waits for a retry. The tracker adds no timeout of its own, so add one when you navigate away:

link.addEventListener('click', (e) => {
  e.preventDefault()
  let done = false
  const go = () => { if (!done) { done = true; location.href = link.href } }
  privatus.track('Outbound click', { domain: link.hostname }, go)
  setTimeout(go, 300)
})

Requests are sent with keepalive, so in most cases you don't need to wait at all: the hit survives the navigation.

You can pass the callback as the second argument when there are no properties: privatus.track('Logout', done).

privatus.pageview(options?)#

Sends a pageview for the current URL, even if the path hasn't changed.

privatus.pageview()
privatus.pageview({ props: { variant: 'b' } })

• options.props: properties for this pageview only. This is the only option.
• The URL is always location.href (after exclusions, masks, canonical and hash handling). To record a different path, change the URL first with history.pushState, or use a mask.

Use it with manual mode or for virtual pageviews such as steps of a wizard that change the URL.

privatus.props(object)#

Adds properties to every later pageview and event on this page load. Calls merge. Set a key to null to stop recording it (the server drops null values). Properties passed to track() or pageview() win over these for that one hit.

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

Properties live in memory only and are gone on the next full page load.

privatus.optOut(), privatus.optIn(), privatus.isOptedOut()#

Stop or resume tracking in this browser. See Opt-out.

privatus.ready(fn)#

Runs fn straight away, because privatus.ready only exists once the tracker has loaded. It is useful with the queue stub, where the call is queued until pa.js arrives.

privatus.ready(() => console.log('Privatus Analytics is loaded'))

Queue stub#

pa.js loads with defer, so it isn't available to inline scripts that run earlier. Put this stub before the tracker tag. Calls made before the tracker loads are queued and replayed in order.

<script>
  window.privatus = window.privatus || { q: [] };
  ['track', 'pageview', 'props', 'optOut', 'optIn', 'ready'].forEach(function (m) {
    window.privatus[m] = window.privatus[m] || function () {
      window.privatus.q.push([m, Array.prototype.slice.call(arguments)]);
    };
  });
</script>
<script defer src="https://privatusstats.com/js/pa.js" data-site="pa_YOURSITEID" data-modules="engage,auto,vitals,clicks,ask"></script>

The queue format is window.<namespace>.q = [[method, [args…]], …]. isOptedOut() returns a value, so it can't be queued. Call it after ready().

If you use a custom data-namespace, use the same name in the stub.

Events without JavaScript#

Any element with a data-privatus-event attribute sends that event when it is clicked (a <form> when it is submitted), with data-privatus-prop-* attributes as properties. See HTML attributes.

TypeScript#

Add these declarations to your project (for example in privatus.d.ts) to get types for window.privatus:

declare global {
  interface Window {
    privatus?: {
      track(name: string, props?: Record<string, string | number | boolean | string[] | null>, callback?: () => void): void
      pageview(options?: { props?: Record<string, unknown> }): void
      props(props: Record<string, unknown>): void
      optOut(): void
      optIn(): void
      isOptedOut(): boolean
      ready(fn: () => void): void
    }
  }
}