Skip to main content
The Tappd Web SDK manages sessions automatically using a hybrid model that combines browser-based isolation with time-based expiration. You get complete session context attached to every event — no manual session handling required.

​
How Sessions Work

The SDK uses two complementary mechanisms to define a session:
  1. Browser-based: Each browser tab or window gets its own session, stored in memory.
  2. Time-based: A session expires after a configurable period of inactivity (default: 30 minutes).
When both conditions are considered together, you get an accurate picture of a single user’s focused engagement with your app.

​
Session Lifecycle

1

Session Starts

A new session begins automatically when the SDK initializes on page load, when a user returns after a timeout, or when a user switches back to a tab after the session has expired.
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID'
});
// A session ID is generated immediately: sess_abc123...
2

Activity Updates

The session’s lastActivityAt timestamp is refreshed every time you call any tracking method — track(), trackPageView(), or any other SDK method.
// Each call automatically keeps the session alive
await tappd.track('button_click');
// Session lastActivityAt is updated
3

Session Expires

The session ends when the user is inactive for longer than the configured timeout, closes the tab, or navigates away. The next interaction starts a fresh session.

​
Configuration

​
Setting the Timeout

Pass the sessionTimeout option (in minutes) when you initialize the SDK: 
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 60 // 60 minutes instead of the default 30
});

E-commerce

30 minutes (default) — Matches typical shopping session length.

SaaS Applications

60 minutes — Users work in the app for longer periods without triggering events.

Content Sites

15 minutes — Readers consume content quickly and bounce frequently.

Games

10 minutes — Short, intense activity bursts define a play session.

​
Getting Session Information

​
Read the Current Session ID

getSessionId() returns the current session ID as a string, or null if no session is active yet. 
const sessionId = tappd.getSessionId();
console.log('Current session:', sessionId);
// Output: 'sess_abc123def456'  — or null if the session hasn't started yet

​
Session Data in Every Event

Every event you track automatically includes session context — you don’t need to attach it manually: 
await tappd.track('purchase', { amount: 99.99 });
// The event payload automatically includes:
// - sessionId: 'sess_abc123def456'
// - sessionStartTime: 1234567890
// - sessionDuration: 120  (seconds since session started)

​
Session Data Structure

Each session carries the following properties, which are automatically included on every event: 
{
  sessionId: 'sess_abc123def456',
  startedAt: 1234567890000,    // Timestamp (ms)
  lastActivityAt: 1234567895000 // Timestamp (ms)
}

​
SPA (Single Page Application) Support

The SDK handles client-side routing automatically so your session and page view tracking stays accurate in React, Vue, Angular, and any other SPA framework.
When autoTrack is enabled (the default), the SDK listens to history.pushState(), history.replaceState(), and popstate events and tracks page views for every route change.
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: true // This is the default
});

// The SDK automatically tracks:
// - Initial page load
// - history.pushState() calls
// - history.replaceState() calls
// - popstate events (back/forward navigation)

​
Page Visibility API

The SDK respects the browser’s Page Visibility API so session time is accurate even when users multitask:
  • Tab hidden: Session activity is paused — idle time doesn’t count against the timeout.
  • Tab visible again: The SDK checks whether the session has expired and starts a new one if needed.
This behavior is automatic. You don’t need to configure anything for it to work.

​
Session vs. User

Sessions and users are distinct concepts in Tappd:
ConceptScopePersistence
SessionA single browser sessionStarts/ends with activity in a tab
UserAn identified personPersists across many sessions
// Day 1: User opens the site anonymously
// → Session 1 starts

// User logs in
await tappd.identify({ external_id: 'user_123', email: 'john@example.com' });
// → Still Session 1, but now identified

// User closes the browser and returns the next day
// → Session 2 starts, still identified as user_123
Call identify() as early as possible so that events within the current session are attributed to the correct user.