Session Management

Understand how the Tappd Web SDK manages user sessions.

How Sessions Work

The SDK uses a hybrid session approach combining browser-based and time-based tracking:

1. Browser-based: New session per browser tab/window (stored in memory)
2. Time-based: Session expires after inactivity (default: 30 minutes)

Session Lifecycle

Session Start

A new session starts automatically when:

• SDK initializes on page load
• User returns after session timeout
• User switches browser tabs and returns after timeout

// Session starts automatically
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID'
});
// Session ID is generated: sess_abc123...

Session Activity

Session activity is updated automatically when:

• Events are tracked (track())
• Page views are tracked (trackPageView())
• Any SDK method is called

// This automatically updates session activity
await tappd.track('button_click');
// Session lastActivityAt is updated

Session Expiration

A session expires when:

• User is inactive for the configured timeout period (default: 30 minutes)
• User closes the browser tab/window
• Browser navigates away from the page

After expiration, a new session starts on the next activity.

Session Configuration

Configuring Timeout

Set the session timeout when initializing the SDK:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 60 // 60 minutes instead of default 30
});

Recommended Timeouts

• E-commerce: 30 minutes (default)
• SaaS Applications: 60 minutes
• Content Sites: 15 minutes
• Games: 10 minutes

Getting Session Information

Get Current Session ID

const sessionId = tappd.getSessionId();
console.log('Current session:', sessionId);

Session in Events

Every tracked event automatically includes session information:

await tappd.track('purchase', { amount: 99.99 });
// Event includes:
// - sessionId: 'sess_abc123'
// - sessionStartTime: 1234567890
// - sessionDuration: 120 (seconds)

Session Tracking Details

What Gets Tracked

Each session includes:

• Session ID: Unique identifier
• Start Time: When session began (timestamp)
• Last Activity: Last event timestamp
• Duration: Time since session start (calculated on each event)

Session Data Structure

{
  sessionId: 'sess_abc123def456',
  startedAt: 1234567890000, // Timestamp
  lastActivityAt: 1234567895000 // Timestamp
}

SPA (Single Page Application) Support

The SDK handles SPAs automatically:

Automatic Tracking

// Initialize SDK with autoTrack
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: true // Default
});

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

Manual SPA Tracking

If autoTrack: false, manually track route changes:

// In your router
router.beforeEach((to, from) => {
  tappd.trackPageView(to.fullPath, {
    from: from.fullPath,
    routeName: to.name
  });
});

Page Visibility API

The SDK respects browser visibility state:

• Page Hidden: Session activity paused
• Page Visible: Session checked for expiration, refreshed if needed

// User switches tabs
// Page becomes hidden → Session paused

// User returns to tab
// Page becomes visible → Session checked, refreshed if expired

Best Practices

1. Don't manually manage sessions - SDK handles it automatically
2. Use appropriate timeout - Match your application's user behavior
3. Trust automatic tracking - Manual tracking only when needed
4. Monitor session data - Use session IDs for analytics in your dashboard

Session vs User

Important distinction:

• Session: Browser session (starts/ends with activity)
• User: Identified user (persists across sessions)

// User opens site (anonymous)
// Session 1 starts

// User logs in
await tappd.identify('user_123');
// Still Session 1, but now identified

// User closes browser, returns next day
// Session 2 starts, still user_123

Next Steps

• Anonymous Tracking - How anonymous users are tracked
• API Reference - Session-related methods
• Examples - Session tracking examples