Documentation

What a session is

A session is everything one visitor sends us between midnight and midnight, measured in your project’s timezone. Everything on this page happens inside that one day: after midnight the same visitor starts a fresh session that cannot be tied back to the previous one. Inside the day the identity holds across page loads, reloads and browser tabs, so someone who reads five pages is one session and not five. The identity is worked out on our servers from the request itself — the tracker sends no identifier, and no cookie, localStorage or sessionStorage is involved.

A session is not the same thing as a visit. A visit is one sitting: it ends after 30 minutes with nothing happening, and in any case at midnight. Somebody who looks at your site in the morning and again in the evening made two visits inside one session. Flows count visits; the visitor numbers everywhere else count sessions.

What holds a session together

• Moving around a single-page app: the session does not change. Navigating inside the app is the same visitor on the same day.
• Loading a new page: also the same session. A site made of ordinary separate pages is at no disadvantage here — somebody who loads twenty pages is one session, not twenty.

At midnight in your project’s timezone every session ends and a new one begins, and the two cannot be connected to each other afterwards, by us or by anyone else. You choose that timezone yourself: see Settings → General.

What sessions are used for

Every event carries its session as the visitor’s identity for that day. That is what lets the product:

• Put one person’s actions together, instead of treating every click as a stranger
• Report how many people rather than only how many clicks — the “unique sessions” number on the Overview and in your reports
• Follow somebody through the steps of a funnel, and from one page to the next in flows

Because a session lasts a day, a total over a week counts a visitor who came back every day seven times. That is deliberate, and it is the cost of not following anybody across days.

Session traits

You can attach traits to a session, and then read any report for just the visitors carrying one of them. A trait is a plain word, not a pair of key and value: plan:pro reads nicely to a person, but nothing in the product splits it at the colon. It is stored and matched whole. Set them on the script tag with data-traits, which takes a comma-separated list, or from your own code with window.tracker.setTraits(), which takes an array:

<!-- Via script tag -->
<script
  src="https://api.privatrak.com/tracker.js"
  data-api-key="your-public-key"
  data-traits="plan:pro,role:admin"
  defer
></script>

// Programmatically
window.tracker.setTraits(['plan:pro', 'role:admin']);

Traits are attached to whole batches of events, so everything recorded after you set them carries them. Nothing is kept in the browser, so every page load starts with no traits until your script tag or your code sets them again.

setTraits() replaces the whole list rather than adding to it. A second call with a single trait removes the ones set before it, so always pass the complete set the session should carry.

Traits are attached when a batch is sent, not at the moment each event happens. Batches go out about every five seconds, or as soon as ten events have piled up. A call to setTraits() therefore also covers the events still waiting to go.

Each distinct trait your tracker sends claims a slot in your project, and your plan sets how many slots there are. You can see the traits in use and free up a slot under Settings → Trait Keys.

What a session can and cannot tell you

• Nothing carries across a day: there is no way to tell that today’s visitor is yesterday’s visitor. Returning customers, week-long journeys and lifetime value are all out of reach, on purpose.
• Tabs and reloads are free: several tabs at once, a reload, or closing the browser and coming back an hour later all stay in the same session. The only condition is that it is still the same day.
• Two people can be merged into one: visitors sharing an internet connection and running the same browser version look identical to us and share a session. On home traffic this is rare; behind a company network it is not.
• One person can be split into two: somebody who moves from wi-fi to mobile data halfway through starts a new session, because the identity is worked out from the connection they arrive on.

How the identity is worked out

This is the one paragraph with the cryptography in it. When an event arrives, the server takes three things: the visitor’s IP address, their browser’s User-Agent string and your project ID. It puts them through a keyed one-way hash — an HMAC — using a secret key that is replaced at midnight in your project’s timezone. One-way means the result cannot be turned back into an IP address. The IP and the User-Agent are used for the calculation and then dropped, never written down and never logged. Because the key is replaced every day, the same visitor produces a completely unrelated value tomorrow, so two days cannot be stitched together even by us. It is the same approach Plausible Analytics uses, which the French data protection authority has approved. The full picture is in the Privacy documentation.