Skip to main content
Databuddy uses a privacy-first approach to identify users and sessions without relying on cookies or personal information. Every visitor gets an anonymous ID, and sessions are automatically managed.

​
Anonymous IDs

Every visitor to your website receives a unique anonymous ID that persists across page views and sessions.

​
Generation

Anonymous IDs are generated using UUIDv4 and prefixed with anon_: 
// From packages/tracker/src/core/tracker.ts:167-169
generateAnonymousId(): string {
  return `anon_${generateUUIDv4()}`;
}
Example: anon_550e8400-e29b-41d4-a716-446655440000

​
Storage

Anonymous IDs are stored in localStorage with the key did (Databuddy ID): 
// From packages/tracker/src/core/tracker.ts:145-165
getOrCreateAnonymousId(): string {
  if (this.isServer()) {
    return this.generateAnonymousId();
  }

  // Check URL parameter first
  const urlParams = new URLSearchParams(window.location.search);
  const anonId = urlParams.get("anonId");
  if (anonId) {
    localStorage.setItem("did", anonId);
    return anonId;
  }

  // Check existing ID in localStorage
  const storedId = localStorage.getItem("did");
  if (storedId) {
    return storedId;
  }

  // Generate new ID
  const newId = this.generateAnonymousId();
  localStorage.setItem("did", newId);
  return newId;
}
Anonymous IDs persist until the user clears their browser’s localStorage or opts out of tracking.

​
Cross-Domain Tracking

Pass anonymous IDs between domains using URL parameters: 
// On domain A: app.example.com
const anonId = localStorage.getItem('did');
window.location.href = `https://shop.example.com?anonId=${anonId}`;

// On domain B: shop.example.com
// Databuddy automatically picks up the anonId from the URL
This allows you to track users across multiple domains while maintaining privacy.

​
Session IDs

Sessions represent a single visit to your website. A new session starts when:
  1. A user visits your site for the first time
  2. 30 minutes of inactivity have passed
  3. The user closes and reopens their browser

​
Generation

Session IDs use the same UUID format but are prefixed with sess_: 
// From packages/tracker/src/core/tracker.ts:204-206
generateSessionId(): string {
  return `sess_${generateUUIDv4()}`;
}
Example: sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Storage

Session IDs are stored in sessionStorage (not localStorage), which means:
  • They’re cleared when the tab is closed
  • They’re unique per browser tab
  • They don’t persist after the browser closes
// From packages/tracker/src/core/tracker.ts:171-202
getOrCreateSessionId(): string {
  if (this.isServer()) {
    return this.generateSessionId();
  }

  // Check URL parameter
  const urlParams = new URLSearchParams(window.location.search);
  const sessionIdFromUrl = urlParams.get("sessionId");
  if (sessionIdFromUrl) {
    sessionStorage.setItem("did_session", sessionIdFromUrl);
    sessionStorage.setItem("did_session_timestamp", Date.now().toString());
    return sessionIdFromUrl;
  }

  // Check existing session
  const storedId = sessionStorage.getItem("did_session");
  const sessionTimestamp = sessionStorage.getItem("did_session_timestamp");

  if (storedId && sessionTimestamp) {
    const sessionAge = Date.now() - Number.parseInt(sessionTimestamp, 10);
    if (sessionAge < 30 * 60 * 1000) {  // 30 minutes
      sessionStorage.setItem("did_session_timestamp", Date.now().toString());
      return storedId;
    }
    // Session expired, clear storage
    sessionStorage.removeItem("did_session");
    sessionStorage.removeItem("did_session_timestamp");
    sessionStorage.removeItem("did_session_start");
  }

  // Create new session
  const newId = this.generateSessionId();
  sessionStorage.setItem("did_session", newId);
  sessionStorage.setItem("did_session_timestamp", Date.now().toString());
  return newId;
}

​
Session Timeout

Sessions automatically expire after 30 minutes of inactivity. The timestamp is updated on each tracked event to keep active sessions alive.
The 30-minute timeout is a common standard used by Google Analytics and other analytics platforms.

​
Session Start Time

Databuddy tracks when each session started: 
// From packages/tracker/src/core/tracker.ts:208-221
getSessionStartTime(): number {
  if (this.isServer()) {
    return Date.now();
  }

  const storedTime = sessionStorage.getItem("did_session_start");
  if (storedTime) {
    return Number.parseInt(storedTime, 10);
  }

  const now = Date.now();
  sessionStorage.setItem("did_session_start", now.toString());
  return now;
}
This allows you to:
  • Calculate session duration
  • Track time to conversion
  • Analyze engagement patterns

​
User vs Session Metrics

Understand the difference between user and session metrics:
Counted by anonymous ID. Represents the number of distinct visitors across all time periods.
SELECT uniq(anonymous_id) as unique_users
FROM analytics.events
WHERE time >= now() - INTERVAL 7 DAY;
Counted by session ID. Represents the number of distinct visits.
SELECT uniq(session_id) as sessions
FROM analytics.events
WHERE time >= now() - INTERVAL 7 DAY;
Total number of pages viewed. One user can generate multiple page views per session.
SELECT count(*) as pageviews
FROM analytics.events
WHERE event_name = 'screen_view'
  AND time >= now() - INTERVAL 7 DAY;
Users with more than one session. Calculated by comparing session counts per anonymous ID.
SELECT countIf(session_count > 1) as returning_users
FROM (
  SELECT anonymous_id, uniq(session_id) as session_count
  FROM analytics.events
  GROUP BY anonymous_id
);

​
Activity Tracking

Databuddy tracks various activity metrics within each session:

​
Page Count

The number of pages viewed in the current session: 
pageCount = 0;

// Incremented on each page view
this.pageCount++;

​
Interaction Count

The number of user interactions (clicks, form inputs, etc.): 
interactionCount = 0;

// Incremented on tracked interactions
this.interactionCount++;

​
Engaged Time

Time spent actively engaging with the page (visible and active): 
// From packages/tracker/src/core/tracker.ts:596-624
startEngagement(): void {
  if (this.engagementStartTime === null) {
    this.engagementStartTime = Date.now();
    this.isPageVisible = true;
  }
}

pauseEngagement(): void {
  if (this.engagementStartTime !== null) {
    this.engagedTime += Date.now() - this.engagementStartTime;
    this.engagementStartTime = null;
    this.isPageVisible = false;
  }
}

getEngagedTime(): number {
  let total = this.engagedTime;
  if (this.engagementStartTime !== null) {
    total += Date.now() - this.engagementStartTime;
  }
  return total;
}
Engaged time is paused when:
  • The page loses focus
  • The user switches tabs
  • The page is hidden

​
User Identification (Optional)

While Databuddy is anonymous by default, you can optionally identify users after authentication:
Only use user identification if you have proper consent and privacy policies in place. Never send PII without user consent.
// After user logs in
window.db.track('user_identified', {
  userId: 'user_12345',  // Your internal user ID
  plan: 'pro'
});
Best practices for user identification:
  1. Use hashed IDs: Hash email addresses or use internal database IDs
  2. Store separately: Keep PII in PostgreSQL, not ClickHouse
  3. Get consent: Clearly inform users about identification
  4. Allow unlinking: Provide a way to disassociate the anonymous ID

​
Session Attributes

Every event in a session includes: 
{
  anonymousId: "anon_550e8400-e29b-41d4-a716-446655440000",
  sessionId: "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  sessionStartTime: 1709251200000,
  timestamp: 1709251320000,
  pageCount: 3,
  interactionCount: 7,
  scrollDepth: 85,
  timeOnPage: 120000,  // 120 seconds
}

​
Multi-Tab Behavior

Each browser tab gets its own session:
1

User opens site in Tab A

New session created: sess_abc123
2

User opens site in Tab B

New session created: sess_def456
3

Both tabs active

Two separate sessions tracked simultaneously with the same anonymous ID
This provides accurate tracking of multi-tab browsing behavior.

​
Session Replay (Coming Soon)

Databuddy will soon support privacy-friendly session replay:
  • Text content masked by default
  • Input fields never recorded
  • Opt-in per session
  • Full GDPR compliance

​
Database Schema

Sessions and users are tracked in the ClickHouse events table: 
-- From packages/db/src/clickhouse/schema.ts
CREATE TABLE analytics.events (
  id UUID,
  client_id String,
  anonymous_id String,      -- User identifier
  session_id String,        -- Session identifier
  session_start_time Nullable(DateTime64(3, 'UTC')),
  time DateTime64(3, 'UTC'),
  
  page_count UInt8 DEFAULT 1,
  interaction_count Nullable(Int16),
  time_on_page Nullable(Float32),
  scroll_depth Nullable(Float32),
  
  -- Other event data...
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(time)
ORDER BY (client_id, time, id);

​
Querying Sessions

Examples of common session queries: 
SELECT
  session_id,
  max(time) - min(time) as session_duration_ms,
  session_duration_ms / 1000 as session_duration_sec
FROM analytics.events
WHERE client_id = 'your-client-id'
  AND time >= now() - INTERVAL 7 DAY
GROUP BY session_id;

​
Best Practices

Don't Reset IDs

Never manually reset anonymous or session IDs. Let Databuddy manage them automatically.

Use URL Parameters

For cross-domain tracking, pass IDs via URL parameters:
https://example.com?anonId=anon_xxx&sessionId=sess_yyy

Respect Privacy

Don’t correlate anonymous IDs with PII without explicit user consent.

Monitor Session Length

Track average session duration to understand engagement:
SELECT avg(duration) FROM sessions

​
Learn More

Privacy First

Learn about Databuddy’s privacy architecture

Event Tracking

Understand how events are captured and sent

Data Model

Explore the complete database schema