Sessions

Understand how Narrowbeam generates sessions using a privacy-preserving, cookie-free approach based on 4-hour time buckets and SHA-256 hashing.

Privacy-First: Sessions are generated server-side without cookies or persistent identifiers.

How Sessions Work

Unlike traditional analytics that use cookies to track sessions, Narrowbeam generates sessions server-side using a combination of:

Origin (your website domain)
IP address (not stored, only used for hashing)
User agent string
Time bucket (4-hour windows)

These values are combined and hashed with SHA-256 to create a session identifier that:

✅ Groups related visits from the same user
✅ Automatically expires after 4 hours
✅ Cannot be used to identify individuals
✅ Requires no cookies or user consent
✅ Is privacy-preserving by design

4-Hour Time Buckets

Sessions are based on 4-hour time windows aligned to midnight UTC:

Time Bucket	UTC Time Range	Session Behavior
Bucket 1	00:00 - 03:59	All visits in this window share the same session
Bucket 2	04:00 - 07:59	New session starts at 04:00
Bucket 3	08:00 - 11:59	New session starts at 08:00
Bucket 4	12:00 - 15:59	New session starts at 12:00
Bucket 5	16:00 - 19:59	New session starts at 16:00
Bucket 6	20:00 - 23:59	New session starts at 20:00

Example

If a user visits your site at 10:30 AM UTC and returns at 11:45 AM UTC, these will be counted as the same session (both in Bucket 3: 08:00-11:59).

If they return at 12:15 PM UTC, this will be a new session (Bucket 4: 12:00-15:59).

Session ID Generation

Here's how a session ID is generated:

// Input values
origin = "https://yoursite.com"
ip = "192.0.2.1"
userAgent = "Mozilla/5.0..."
timeBucket = 1730970000000 // Current 4-hour bucket

// Combine and hash
input = `${origin}:${ip}:${userAgent}:${timeBucket}`
sessionId = SHA256(input)

// Result (simplified)
sessionId = "abc123xyz789..." // 64-character hash

Privacy Note: The IP address is only used for hashing and is never stored in the database. The hash cannot be reversed to obtain the IP address.

Sessions vs Visitors

Understanding the difference between sessions (visits) and visitors:

Metric	Definition	Example
Views	Unique sessions within a time period	User visits at 10 AM and 2 PM = 2 views
Visitors	Unique people (based on longer time period)	Same user visiting twice = 1 visitor
Pageviews	Total pages viewed	User views 5 pages in one visit = 5 pageviews

See Events, Views & Visitors for a detailed explanation of these metrics.

Why 4 Hours?

The 4-hour session window balances several factors:

Design Trade-offs

Privacy: Shorter sessions = less tracking capability = more privacy
Accuracy: 4 hours captures typical browsing sessions without over-counting
Simplicity: Fixed time buckets are predictable and deterministic
No cookies needed: Server-side generation means no browser storage required

Understanding the Implications

Because sessions expire every 4 hours, a user who browses throughout the day may generate multiple sessions. This means your visitor counts may be higher than cookie-based analytics. This is expected behavior and prioritizes user privacy.

Session Persistence Across Changes

Sessions remain consistent as long as:

✅ User stays on the same network (same IP)
✅ User stays in the same browser
✅ User stays within the same 4-hour window

Sessions will change if:

❌ User switches networks (IP changes)
❌ User switches browsers or devices
❌ 4-hour time bucket changes
❌ User agent changes (rare)

Comparing to Cookie-Based Sessions

Feature	Narrowbeam Sessions	Cookie-Based Sessions
Privacy	High	Low
Cookies Required	No	Yes
Consent Needed	No	Often yes (GDPR)
Duration	4 hours (fixed)	30 minutes (typical, extendable)
Cross-Device	Not tracked	Possible with login
Session Count	May be higher	Lower (extended sessions)
Ad Blockers	Unaffected	Often blocked

Technical Implementation

The session generation happens server-side in lib/session-id.ts:34-35:

// Calculate current 4-hour time bucket
const timeBucket = Math.floor(now / FOUR_HOURS_MS) * FOUR_HOURS_MS;

// Create hash input
const input = `${origin}:${ip}:${userAgent}:${timeBucket}`;

// Generate SHA-256 hash
const sessionId = await sha256(input);

Viewing Session Data

In your Narrowbeam dashboard, sessions appear as:

Views: The primary metric for unique sessions
Visitor Count: Aggregated unique visitors over longer periods
Session Duration: Time between first and last event in a session
Pages per Session: Average page views per visit

Best Practices

Don't compare directly to cookie-based tools: Session counts will differ due to the privacy-first approach
Focus on trends: Week-over-week and month-over-month comparisons are more meaningful than absolute numbers
Use views for engagement: "Views" is the most accurate metric for session-based analysis
Understand the 4-hour boundary: Users browsing throughout the day may have multiple sessions
Embrace privacy: Higher session counts are a feature, not a bug - they reflect better privacy protection