Session management

A session ID groups the pageviews and events from one page load, and links revenue back to them.

How sessions workCopy Anchor Link

• The tracker creates a random UUID when it's constructed: on page load for the script tag, or when you call new Supapulse().
• The ID lives in memory only. There are no cookies, no localStorage and no sessionStorage.
• Client-side navigations (pushState, replaceState, back and forward) keep the same ID.
• A full page load, a new tab or a reload starts a new ID.

There's no inactivity timeout and no way to reset the ID by hand: it lasts exactly as long as the page.

Getting the session IDCopy Anchor Link

const sessionId = supapulse.getSessionId(); // "c8df4c3c-…"

Session IDs are random and carry no personal data, so it's safe to send them to your server and store them in payment metadata.

Sessions and revenueCopy Anchor Link

A revenue event can carry a session_id, and reports join it to pageviews with the same session_id. That's one of the ways a payment ends up under a source, campaign or landing page. The others are the visitor fingerprint and identify(); see Revenue attribution.

For the session path, read the ID on the page where checkout starts, right before you redirect:

async function startCheckout(priceId: string) {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ priceId, sessionId: supapulse.getSessionId() }),
  });
  const { url } = await response.json();
  location.href = url;
}

Because a full page load creates a new ID, a payment links to the pageviews of the page load where checkout started. In a single-page app that covers the whole visit. On a multi-page site it covers the page with the checkout button, which still carries the referrer and UTM parameters if the visitor landed there.

See Revenue attribution for what this does and doesn't cover.

Sessions and visitorsCopy Anchor Link

Sessions and visitors are counted separately. A visitor is the server-side hash of IP address, user agent, site and salt, so the same person reloading the page is one visitor with two sessions.