Tracking Events - Vemetric

Vemetric provides powerful event tracking capabilities to help you understand user behavior and product usage. This guide covers best practices for tracking pageviews, custom events, and user identification.

Event Types

Vemetric supports several types of events:

Pageviews

Automatically tracked page visits

Custom Events

User actions and interactions

Outbound Links

Clicks on external links

System Events

Internal events prefixed with $$

Pageview Tracking

Pageviews are automatically tracked when you install the Vemetric script or SDK.

Automatic Tracking

JavaScript
React

<script>
  window.vemetricConfig = {
    host: 'https://hub.yourdomain.com',
    token: 'your-token'
  };
</script>
<script src="https://hub.yourdomain.com/script.js" defer></script>

Pageviews are tracked automatically on page load and navigation.

import { VemetricScript } from '@vemetric/react';

<VemetricScript
  host="https://hub.yourdomain.com"
  token="your-token"
/>

Pageviews are tracked automatically, including SPA navigation.

System Pageview Event

Pageviews are tracked with the system event name $$pageView. You can see these in your analytics dashboard under “Page View” events.

Custom Event Tracking

Custom events let you track specific user actions and interactions.

Basic Event Tracking

JavaScript
React
Node.js

vemetric.trackEvent('ButtonClicked');

import { vemetric } from '@vemetric/react';

function Button() {
  const handleClick = () => {
    vemetric.trackEvent('ButtonClicked');
  };
  
  return <button onClick={handleClick}>Click Me</button>;
}

import { Vemetric } from '@vemetric/node';

const vemetric = new Vemetric({
  host: process.env.VEMETRIC_HOST!,
  token: process.env.VEMETRIC_TOKEN!
});

await vemetric.trackEvent('ApiKeyCreated', {
  userIdentifier: user.id
});

Events with Custom Data

Attach custom properties to track additional context:

JavaScript/React
Node.js

vemetric.trackEvent('ProductViewed', {
  eventData: {
    productId: 'prod_123',
    productName: 'Wireless Headphones',
    category: 'Electronics',
    price: 99.99,
    currency: 'USD'
  }
});

await vemetric.trackEvent('OrderPlaced', {
  userIdentifier: user.id,
  userDisplayName: user.name,
  eventData: {
    orderId: order.id,
    total: order.total,
    itemCount: order.items.length,
    paymentMethod: 'credit_card'
  }
});

User Identification

Identify users to track them across sessions and devices.

Identifying Users

JavaScript
React
Node.js

vemetric.identify({
  identifier: 'user_123',
  displayName: 'John Doe',
  avatarUrl: 'https://example.com/avatar.jpg'
});

import { vemetric } from '@vemetric/react';
import { useEffect } from 'react';

function App() {
  const { user } = useAuth();
  
  useEffect(() => {
    if (user) {
      vemetric.identify({
        identifier: user.id,
        displayName: user.name,
        avatarUrl: user.avatar
      });
    }
  }, [user]);
  
  return <div>...</div>;
}

// Include user info with events
await vemetric.trackEvent('UserSignup', {
  userIdentifier: user.id,
  userDisplayName: user.name,
  userAvatarUrl: user.avatar,
  eventData: {
    provider: 'google'
  }
});

User Identity Parameters

identifier

string

required

Unique identifier for the user. This can be:

User ID from your database
Email address
Username
Any unique identifier

The identifier is used to merge anonymous and identified user sessions.

displayName

string

Human-readable name displayed in the Vemetric dashboard

avatarUrl

string

URL to the user’s profile picture or avatar

Reset User Identity

Clear the user identity when they log out:

JavaScript/React
Node.js

vemetric.resetUser();

// Node.js doesn't maintain session state,
// so no reset is needed

User Properties

Track custom user attributes and update them over time.

Set Properties

Set or update user properties:

vemetric.trackEvent('ProfileUpdated', {
  userData: {
    set: {
      plan: 'premium',
      company: 'Acme Corp',
      role: 'admin',
      lastActive: new Date().toISOString()
    }
  }
});

Set Once

Set properties only if they don’t already exist:

vemetric.identify({
  identifier: user.id,
  data: {
    setOnce: {
      firstSeen: new Date().toISOString(),
      signupSource: 'landing-page',
      initialReferrer: document.referrer
    }
  }
});

Unset Properties

Remove user properties:

vemetric.trackEvent('SubscriptionCancelled', {
  userData: {
    unset: ['plan', 'subscriptionId', 'billingDate']
  }
});

Combining Operations

You can combine set, setOnce, and unset in a single call:

vemetric.trackEvent('AccountUpgraded', {
  eventData: {
    fromPlan: 'free',
    toPlan: 'premium'
  },
  userData: {
    set: {
      plan: 'premium',
      upgradedAt: new Date().toISOString()
    },
    setOnce: {
      firstUpgrade: new Date().toISOString()
    },
    unset: ['trialEndDate']
  }
});

Outbound Link Tracking

Clicks on external links are automatically tracked as $$outboundLink events.

What’s Tracked

Vemetric automatically tracks:

Clicks on links to external domains
The destination URL
The page where the click occurred

What’s Not Tracked

Links to the same domain (including subdomains) are considered internal and not tracked as outbound links.

Custom Outbound Tracking

You can manually track outbound link clicks:

vemetric.trackEvent('ExternalLinkClicked', {
  eventData: {
    destination: 'https://example.com',
    linkText: 'Visit Example',
    section: 'footer'
  }
});

Event Naming Best Practices

Use PascalCase for event names

Use clear, descriptive names in PascalCase:✅ Good:

ButtonClicked
ProductViewed
SignupCompleted
PaymentProcessed

❌ Bad:

button_clicked (snake_case)
product-viewed (kebab-case)
click (too generic)
event1 (not descriptive)

Be specific but concise

Use specific names that clearly describe the action:✅ Good:

CheckoutStarted
VideoPlayed
FilterApplied

❌ Bad:

Click (too generic)
UserClickedTheBlueButtonInTheHeaderNavigationMenu (too verbose)

Use past tense for completed actions

Name events for what happened:✅ Good:

SignupCompleted
EmailSent
PaymentProcessed

❌ Bad:

SignupComplete (adjective)
SendingEmail (in progress)

Avoid system event prefixes

Don’t use the $$ prefix - it’s reserved for system events:✅ Good:

CustomPageView
FormSubmitted

❌ Bad:

$$customEvent
$$myEvent

Common Tracking Patterns

E-commerce

// Product view
vemetric.trackEvent('ProductViewed', {
  eventData: {
    productId: 'prod_123',
    name: 'Wireless Headphones',
    price: 99.99,
    category: 'Electronics'
  }
});

// Add to cart
vemetric.trackEvent('AddedToCart', {
  eventData: {
    productId: 'prod_123',
    quantity: 1,
    price: 99.99
  }
});

// Checkout started
vemetric.trackEvent('CheckoutStarted', {
  eventData: {
    cartTotal: 199.98,
    itemCount: 2
  }
});

// Purchase completed
vemetric.trackEvent('Purchase', {
  eventData: {
    orderId: 'order_456',
    total: 199.98,
    currency: 'USD',
    itemCount: 2
  },
  userData: {
    set: {
      lastPurchase: new Date().toISOString(),
      totalOrders: 5,
      lifetimeValue: 899.90
    }
  }
});

SaaS Application

// User signup
vemetric.identify({
  identifier: user.email,
  displayName: user.name,
  data: {
    set: {
      plan: 'trial',
      signupDate: new Date().toISOString()
    },
    setOnce: {
      firstSeen: new Date().toISOString(),
      source: 'landing-page'
    }
  }
});

// Feature usage
vemetric.trackEvent('FeatureUsed', {
  eventData: {
    feature: 'data-export',
    exportType: 'csv',
    recordCount: 1000
  }
});

// Upgrade plan
vemetric.trackEvent('PlanUpgraded', {
  eventData: {
    fromPlan: 'trial',
    toPlan: 'premium'
  },
  userData: {
    set: {
      plan: 'premium',
      upgradedAt: new Date().toISOString()
    },
    unset: ['trialEndDate']
  }
});

Content Platform

// Article view
vemetric.trackEvent('ArticleViewed', {
  eventData: {
    articleId: 'article_789',
    title: 'Getting Started with Analytics',
    category: 'Tutorial',
    wordCount: 1200
  }
});

// Video playback
vemetric.trackEvent('VideoPlayed', {
  eventData: {
    videoId: 'video_123',
    title: 'Product Demo',
    duration: 300,
    quality: '1080p'
  }
});

// Content engagement
vemetric.trackEvent('CommentPosted', {
  eventData: {
    contentType: 'article',
    contentId: 'article_789'
  },
  userData: {
    set: {
      totalComments: 15,
      lastCommentDate: new Date().toISOString()
    }
  }
});

Advanced Techniques

Contextual Event Data

Include context about where and how an event occurred:

vemetric.trackEvent('FormSubmitted', {
  eventData: {
    formType: 'contact',
    formLocation: 'footer',
    fieldCount: 5,
    completionTime: 45 // seconds
  }
});

Event Sequences

Track related events with shared identifiers:

const sessionId = generateSessionId();

// Start
vemetric.trackEvent('OnboardingStarted', {
  eventData: { sessionId }
});

// Progress
vemetric.trackEvent('OnboardingStepCompleted', {
  eventData: { sessionId, step: 1, stepName: 'profile' }
});

// Complete
vemetric.trackEvent('OnboardingCompleted', {
  eventData: { sessionId, duration: 120 }
});

Error Tracking

Track errors and failures:

vemetric.trackEvent('PaymentFailed', {
  eventData: {
    errorCode: 'card_declined',
    errorMessage: 'Insufficient funds',
    amount: 99.99,
    paymentMethod: 'credit_card'
  }
});

Privacy Considerations

Don’t Track PII

Avoid tracking personally identifiable information in event data: ❌ Bad:

vemetric.trackEvent('FormSubmitted', {
  eventData: {
    email: 'user@example.com',
    phone: '+1234567890',
    ssn: '123-45-6789'
  }
});

✅ Good:

vemetric.trackEvent('FormSubmitted', {
  eventData: {
    formType: 'contact',
    fieldCount: 5
  }
});

Mask Sensitive URLs

Use path masking to prevent tracking sensitive pages:

window.vemetricConfig = {
  host: 'https://hub.yourdomain.com',
  token: 'your-token',
  maskPaths: [
    '/admin/*',
    '/user/*/settings',
    '/checkout/confirmation'
  ]
};

Testing Events

Verify in Dashboard

Open your Vemetric dashboard
Navigate to the Events page
Filter by event name to see your tracked events
Verify event data and user properties are correct

Console Debugging

For development, you can log events before tracking:

function trackEvent(name, options) {
  if (process.env.NODE_ENV === 'development') {
    console.log('Tracking event:', name, options);
  }
  return vemetric.trackEvent(name, options);
}

Next Steps

JavaScript SDK

Detailed JavaScript SDK reference

React SDK

React-specific tracking guide

Node.js SDK

Server-side event tracking

Configuration

Advanced configuration options

Get Started

Integration

Features

Self-Hosting

Guides

Documentation Index

​Event Types

Pageviews

Custom Events

Outbound Links

System Events

​Pageview Tracking

​Automatic Tracking

​System Pageview Event

​Custom Event Tracking

​Basic Event Tracking

​Events with Custom Data

​User Identification

​Identifying Users

​User Identity Parameters

​Reset User Identity

​User Properties

​Set Properties

​Set Once

​Unset Properties

​Combining Operations

​Outbound Link Tracking

​What’s Tracked

​What’s Not Tracked

​Custom Outbound Tracking

​Event Naming Best Practices

​Common Tracking Patterns

​E-commerce

​SaaS Application

​Content Platform

​Advanced Techniques

​Contextual Event Data

​Event Sequences

​Error Tracking

​Privacy Considerations

​Don’t Track PII

​Mask Sensitive URLs

​Testing Events

​Verify in Dashboard

​Console Debugging

​Next Steps

JavaScript SDK

React SDK

Node.js SDK

Configuration

Event Types

Pageview Tracking

Automatic Tracking

System Pageview Event

Custom Event Tracking

Basic Event Tracking

Events with Custom Data

User Identification

Identifying Users

User Identity Parameters

Reset User Identity

User Properties

Set Properties

Set Once

Unset Properties

Combining Operations

Outbound Link Tracking

What’s Tracked

What’s Not Tracked

Custom Outbound Tracking

Event Naming Best Practices

Common Tracking Patterns

E-commerce

SaaS Application

Content Platform

Advanced Techniques

Contextual Event Data

Event Sequences

Error Tracking

Privacy Considerations

Don’t Track PII

Mask Sensitive URLs

Testing Events

Verify in Dashboard

Console Debugging

Next Steps