Key Concepts

Overview

Vemetric’s data model is built around several core concepts that work together to provide comprehensive analytics. Understanding these concepts will help you effectively track and analyze user behavior.

Projects

A project represents a website or application you want to track. Each project has:

Unique domain: The primary domain of your site (e.g., example.com)
Project token: A unique identifier used by the tracking SDK
Settings: Configuration for tracking behavior, excluded IPs, and excluded countries

// Project structure in the database
interface Project {
  id: string;
  name: string;
  domain: string;              // Primary domain
  token: string;               // Used for tracking SDK
  organizationId: string;
  publicDashboard: boolean;    // Allow public access to dashboard
  eventIcons: object;          // Custom icons for events
  excludedIps?: string;        // Comma-separated IPs to ignore
  excludedCountries?: string;  // Comma-separated country codes
  createdAt: Date;
  firstEventAt?: Date;         // When first event was tracked
}

Projects support cross-subdomain tracking automatically. Users are tracked seamlessly across app.example.com, blog.example.com, etc.

Project Configuration

When setting up a project, you can configure:

Excluded IPs

Filter out traffic from specific IP addresses, useful for:

Excluding your team’s internal traffic
Ignoring bot traffic from known IPs
Filtering out test environments

Example: 192.168.1.1,10.0.0.5

Excluded Countries

Exclude traffic from specific countries using ISO country codes:Example: US,GB,CAThe Hub service checks the geo-location of each request and silently ignores events from excluded countries.

Event Icons

Customize how events appear in your dashboard with custom icons stored as JSON:

{
  "purchase_completed": "shopping-cart",
  "signup_started": "user-plus",
  "video_played": "play"
}

Events

An event represents a single user action or occurrence. Events are the foundation of your analytics data.

Event Structure

interface Event {
  // Identifiers
  id: string;              // Unique event ID
  projectId: bigint;
  userId: bigint;
  sessionId: string;
  deviceId: bigint;
  contextId: string;       // Groups related events (e.g., same page load)
  
  // Event data
  name: string;            // Event name (e.g., 'button_clicked')
  isPageView: boolean;     // Special page view events
  createdAt: string;       // ISO timestamp
  
  // Location data
  origin: string;          // e.g., 'https://example.com'
  pathname: string;        // e.g., '/products/123'
  urlHash: string;         // e.g., '#pricing'
  queryParams: object;     // Parsed query parameters
  
  // User context
  userIdentifier?: string;  // Email, user ID, etc.
  userDisplayName?: string;
  
  // Device & browser
  browser: string;
  browserVersion: string;
  os: string;
  osVersion: string;
  deviceType: string;      // 'mobile', 'desktop', 'tablet'
  
  // Geographic data
  countryCode: string;     // ISO country code
  city: string;
  latitude: number | null;
  longitude: number | null;
  
  // Traffic source
  referrer: string;        // Referrer domain
  referrerUrl: string;     // Full referrer URL
  referrerType: string;    // 'search', 'social', 'direct', etc.
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  utmContent?: string;
  utmTerm?: string;
  
  // Custom data
  customData: object;      // Any custom properties you track
  requestHeaders: object;  // HTTP headers for debugging
}

Built-in Events

Vemetric automatically tracks two special events:

// Tracked automatically - no code needed
// Event name: '$$pageView'
{
  name: '$$pageView',
  url: 'https://example.com/products',
  // ... other properties
}

Custom Events

Track any user action with custom events:

// Simple event
vemetric.track('button_clicked');

// Event with properties
vemetric.track('purchase_completed', {
  product_id: '12345',
  amount: 99.99,
  currency: 'USD',
  category: 'electronics'
});

// Event with URL context (for backend tracking)
vemetric.track('api_call_made', 
  {
    endpoint: '/api/users',
    method: 'POST'
  },
  {
    url: 'https://example.com/dashboard'
  }
);

Event names starting with $$ are reserved for Vemetric’s built-in events. Use custom names for your events.

Users

A user represents a unique visitor to your site. Users can be anonymous or identified.

User Lifecycle

Anonymous User

When someone first visits your site, Vemetric automatically creates an anonymous user with a randomly generated ID:

const userId = generateUserId(); // Returns a bigint

This ID is stored in a cookie (if cookies are allowed) to track the user across sessions.

User Identification

When the user signs up or logs in, you identify them:

vemetric.identify('user@example.com', {
  displayName: 'Jane Doe',
  plan: 'premium',
  company: 'Acme Inc'
});

This creates a mapping between the identifier and the user ID in PostgreSQL.

User Merging

If an identified user later visits from a different device (different anonymous ID), Vemetric automatically merges the user data:

All events from the old anonymous user are reassigned
User properties are combined
Session history is preserved

This creates a unified view of the user across all devices.

User Properties

Users have both system properties and custom properties:

interface User {
  // System properties
  id: bigint;
  projectId: bigint;
  identifier: string;       // Email, username, or custom ID
  displayName?: string;
  avatarUrl?: string;
  createdAt: string;
  firstSeenAt: string;      // First time user visited
  updatedAt: string;
  
  // Attribution data (from first session)
  origin?: string;
  pathname?: string;
  referrer?: string;
  referrerType?: string;
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  
  // Geographic data (from last session)
  countryCode: string;
  city: string;
  
  // Custom properties
  customData: {
    plan?: string;
    role?: string;
    company?: string;
    // ... any properties you set
  };
}

Updating User Properties

You can update user properties in several ways:

// Set properties (overwrites existing values)
vemetric.updateUser({
  set: {
    plan: 'enterprise',
    last_login: new Date().toISOString()
  }
});

// Set once (only if not already set)
vemetric.updateUser({
  setOnce: {
    first_purchase_date: new Date().toISOString()
  }
});

// Unset properties
vemetric.updateUser({
  unset: ['temporary_flag']
});

// Combine operations
vemetric.updateUser({
  set: { last_active: new Date() },
  setOnce: { created_at: new Date() },
  unset: ['old_property']
});

User property updates are queued and processed asynchronously. There may be a slight delay before they appear in analytics queries.

Sessions

A session represents a continuous period of user activity on your site. Sessions help you understand engagement patterns and user flows.

Session Management

Duration: Sessions continue as long as there’s activity within 30 minutes
Creation: A new session starts when:
- The user visits after 30+ minutes of inactivity
- The user is a first-time visitor
Tracking: Session ID is managed by the Hub service using Redis

// Session duration constant from source
const SESSION_DURATION_MINUTES = 30;

// Session structure
interface Session {
  id: string;               // Unique session ID
  projectId: bigint;
  userId: bigint;
  
  // Timing
  startedAt: string;
  endedAt: string;
  duration: number;         // In seconds
  
  // Entry point
  origin: string;
  pathname: string;         // Landing page
  urlHash?: string;
  queryParams: object;
  
  // Traffic source
  referrer?: string;
  referrerUrl?: string;
  referrerType?: string;    // 'direct', 'search', 'social', 'referral'
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  utmContent?: string;
  utmTerm?: string;
  
  // User context
  userIdentifier?: string;
  userDisplayName?: string;
  
  // Geographic data
  countryCode: string;
  city: string;
  latitude: number | null;
  longitude: number | null;
  
  // Device info
  userAgent?: string;
}

Session Metrics

Vemetric calculates several session-based metrics:

Session count: Total number of sessions
Average session duration: Mean time users spend on your site
Bounce rate: Percentage of single-page sessions
Pages per session: Average page views per session

// Bounce rate calculation from source
const BOUNCE_RATE_QUERY = 'round(countIf(pageViews = 1) / count() * 100, 2)';

User Journeys

User journeys visualize the complete path a user takes through your product, showing:

All page views in chronological order
Custom events triggered
Time spent on each page
Device and location changes
Session boundaries

Journey Data

A user journey is composed of events from the ClickHouse events table, ordered by timestamp:

SELECT 
  name,
  createdAt,
  pathname,
  customData,
  sessionId,
  deviceType,
  browser,
  countryCode
FROM event
WHERE projectId = ? AND userId = ?
ORDER BY createdAt ASC

This shows the complete timeline of user activity, essential for understanding user behavior patterns.

Funnels

A funnel is a defined sequence of steps that users should complete, such as a signup or checkout flow.

Funnel Definition

Funnels are stored in PostgreSQL and consist of ordered steps:

interface Funnel {
  id: string;
  projectId: string;
  name: string;
  icon?: string;
  steps: FunnelStep[];
  createdAt: Date;
  updatedAt: Date;
}

interface FunnelStep {
  id: string;
  name: string;
  filter: PageFilter | EventFilter;
}

// Example: Signup funnel
{
  name: 'Signup Flow',
  steps: [
    {
      id: 'step-1',
      name: 'Visit Homepage',
      filter: {
        type: 'page',
        pathFilter: { operator: 'is', value: '/' }
      }
    },
    {
      id: 'step-2', 
      name: 'Start Signup',
      filter: {
        type: 'event',
        nameFilter: { operator: 'is', value: 'signup_started' }
      }
    },
    {
      id: 'step-3',
      name: 'Complete Signup',
      filter: {
        type: 'event',
        nameFilter: { operator: 'is', value: 'signup_completed' }
      }
    }
  ]
}

Funnel Analysis

Vemetric uses ClickHouse’s windowFunnel function to calculate conversion rates:

-- Simplified funnel query
SELECT 
  windowFunnel(86400)( -- 24 hour window
    createdAt,
    -- Step conditions
    pathname = '/',
    name = 'signup_started',
    name = 'signup_completed'
  ) AS step_reached
FROM event
WHERE projectId = ?
GROUP BY userId

This returns how far each user progressed through the funnel, enabling:

Conversion rate calculation for each step
Drop-off analysis
Time-to-convert metrics

Properties

Properties are custom attributes attached to events or users.

Event Properties

Event properties are stored in the customData field:

vemetric.track('product_viewed', {
  product_id: 'SKU-123',
  product_name: 'Wireless Headphones',
  price: 79.99,
  category: 'electronics',
  in_stock: true
});

These properties can be used for:

Filtering events
Segmenting analytics
Building custom reports

User Properties

User properties are stored in the user’s customData field and persist across sessions:

vemetric.identify('user@example.com', {
  plan: 'enterprise',
  role: 'admin',
  company: 'Acme Corp',
  employee_count: 500
});

Property Types

Vemetric supports various property types:

Strings: Text values
Numbers: Numeric values for calculations
Booleans: True/false flags
Dates: ISO timestamp strings
Objects: Nested data structures (stored as JSON)
Arrays: Lists of values

Avoid using property names that conflict with system fields like projectId, userId, createdAt, etc.

Filtering

Vemetric provides powerful filtering capabilities to segment your data:

Filter Types

Page Filters
Event Filters
Location Filters
User Filters

Filter by URL components:

{
  type: 'page',
  originFilter: { operator: 'is', value: 'https://example.com' },
  pathFilter: { operator: 'startsWith', value: '/blog' },
  hashFilter: { operator: 'contains', value: 'pricing' }
}

Operators: any, is, isNot, contains, notContains, startsWith, endsWith

Filter by event names and properties:

{
  type: 'event',
  nameFilter: { operator: 'is', value: 'purchase_completed' },
  propertiesFilter: [
    {
      property: 'amount',
      valueFilter: { operator: 'gt', value: '100' }
    }
  ]
}

Filter by geographic location:

{
  type: 'location',
  countryFilter: { operator: 'oneOf', value: ['US', 'CA', 'GB'] },
  cityFilter: { operator: 'oneOf', value: ['New York', 'London'] }
}

Operators: any, oneOf, noneOf

Filter by user type:

{
  type: 'user',
  anonymous: false  // Only identified users
}

Combining Filters

Filters can be combined with AND/OR logic:

{
  operator: 'and',
  filters: [
    {
      type: 'location',
      countryFilter: { operator: 'is', value: 'US' }
    },
    {
      type: 'event',
      nameFilter: { operator: 'is', value: 'purchase_completed' }
    }
  ]
}

Next Steps

Now that you understand Vemetric’s core concepts, you’re ready to:

Quickstart Guide

Set up Vemetric in your application

JavaScript SDK

Learn how to use the JavaScript SDK

Track Events

Master event tracking and user identification

Dashboard Features

Explore the analytics dashboard

Get Started

Integration

Features

Self-Hosting

Guides

Overview

Projects

Project Configuration

Events

Event Structure

Built-in Events

Custom Events

Users

User Lifecycle

User Properties

Updating User Properties

Sessions

Session Management

Session Metrics

User Journeys

Journey Data

Funnels

Funnel Definition

Funnel Analysis

Properties

Event Properties

User Properties

Property Types

Filtering

Filter Types

Combining Filters

Next Steps

Quickstart Guide

JavaScript SDK

Track Events

Dashboard Features

Get Started

Integration

Features

Self-Hosting

Guides

Documentation Index

​Overview

​Projects

​Project Configuration

​Events

​Event Structure

​Built-in Events

​Custom Events

​Users

​User Lifecycle

​User Properties

​Updating User Properties

​Sessions

​Session Management

​Session Metrics

​User Journeys

​Journey Data

​Funnels

​Funnel Definition

​Funnel Analysis

​Properties

​Event Properties

​User Properties

​Property Types

​Filtering

​Filter Types

​Combining Filters

​Next Steps

Quickstart Guide

JavaScript SDK

Track Events

Dashboard Features

Overview

Projects

Project Configuration

Events

Event Structure

Built-in Events

Custom Events

Users

User Lifecycle

User Properties

Updating User Properties

Sessions

Session Management

Session Metrics

User Journeys

Journey Data

Funnels

Funnel Definition

Funnel Analysis

Properties

Event Properties

User Properties

Property Types

Filtering

Filter Types

Combining Filters

Next Steps