Documentation Index
Fetch the complete documentation index at: https://mintlify.com/vemetric/vemetric/llms.txt
Use this file to discover all available pages before exploring further.
The Vemetric JavaScript SDK provides automatic pageview tracking and a simple API for tracking custom events in browser-based applications.
Installation
The JavaScript SDK is loaded via a script tag and doesn’t require npm installation. For React applications, see the React SDK documentation. Script Installation
Add the Vemetric script to your HTML <head> section:
<script
src="https://cdn.vemetric.com/v1.js"
data-token="your-project-token"
data-host="https://hub.vemetric.com"
defer
></script>
src and data-host URLs with your own domain.
Configuration Options
Configure the script using data attributes:
Your project token from the Vemetric dashboard (required)
The URL of your Vemetric hub instance (e.g., https://hub.vemetric.com)
Whether to allow cookies for user tracking. Set to "false" for cookieless tracking.
Comma-separated list of URL patterns to mask in analyticsExample: "/admin/*,/settings,/user/*/private"
Basic Usage
Automatic Pageview Tracking
Pageviews are tracked automatically once the script is loaded. No additional code is required.
Manual Event Tracking
Track custom events using the global vemetric object:
vemetric.trackEvent('ButtonClicked');
Event with Custom Data
Attach custom properties to your events:
vemetric.trackEvent('ProductViewed', {
eventData: {
productId: '12345',
category: 'Electronics',
price: 299.99
}
});
User Identification
Identify Users
Identify authenticated users to track them across sessions:
vemetric.identify({
identifier: 'user-123',
displayName: 'John Doe',
avatarUrl: 'https://example.com/avatar.jpg'
});
Unique identifier for the user (e.g., user ID, email)
Display name for the user
URL to the user’s avatar image
Set User Properties
Update user properties alongside identification:
vemetric.identify({
identifier: 'user-123',
displayName: 'John Doe',
data: {
set: {
plan: 'premium',
signupDate: '2024-01-15'
}
}
});
Reset User Identity
Clear the current user identity (useful for logout):
Advanced Usage
Track Events with User Data
Combine event tracking with user property updates:
vemetric.trackEvent('UpgradePlan', {
eventData: {
fromPlan: 'free',
toPlan: 'premium'
},
userData: {
set: {
plan: 'premium',
upgradedAt: new Date().toISOString()
}
}
});
User Data Operations
Set Properties
Set Once
Unset Properties
Set or update user properties:vemetric.trackEvent('FeatureUsed', {
userData: {
set: {
lastFeature: 'export',
featureCount: 5
}
}
});
Set properties only if they don’t exist:vemetric.trackEvent('FirstVisit', {
userData: {
setOnce: {
firstVisitDate: new Date().toISOString(),
referrer: document.referrer
}
}
});
Remove user properties:vemetric.trackEvent('CancelSubscription', {
userData: {
unset: ['plan', 'subscriptionId']
}
});
Outbound Link Tracking
Outbound links are tracked automatically when users click links to external domains.
API Reference
vemetric.trackEvent(name, options?)
Track a custom event.
Name of the event to track
Optional configuration object
Custom properties for the event
User property updates
Properties to set or update
Properties to set only if they don’t exist
Override the current page URL for this event
vemetric.identify(options)
Identify a user and optionally update their properties.
Unique identifier for the user
Display name for the user
User property updates (same structure as userData in trackEvent)
vemetric.resetUser()
Reset the current user identity. Call this when users log out.
Privacy & Compliance
Cookieless Tracking
Disable cookies for privacy-focused tracking:
<script
src="https://cdn.vemetric.com/v1.js"
data-token="your-project-token"
data-host="https://hub.vemetric.com"
data-allow-cookies="false"
defer
></script>
Cookieless tracking may reduce accuracy for returning visitor identification.
Path Masking
Mask sensitive URLs from being tracked:
<script
src="https://cdn.vemetric.com/v1.js"
data-token="your-project-token"
data-host="https://hub.vemetric.com"
data-mask-paths="/admin/*,/user/*/settings,/checkout/confirmation"
defer
></script>
Examples
E-commerce Tracking
// Track product views
vemetric.trackEvent('ProductViewed', {
eventData: {
productId: 'prod_123',
name: 'Wireless Headphones',
price: 99.99,
category: 'Electronics'
}
});
// Track add to cart
vemetric.trackEvent('AddedToCart', {
eventData: {
productId: 'prod_123',
quantity: 1
}
});
// Track purchase
vemetric.trackEvent('Purchase', {
eventData: {
orderId: 'order_456',
total: 99.99,
currency: 'USD'
},
userData: {
set: {
lastPurchase: new Date().toISOString(),
totalOrders: 5
}
}
});
SaaS Application Tracking
// User signup
vemetric.identify({
identifier: user.email,
displayName: user.name,
data: {
set: {
plan: 'trial',
signupDate: new Date().toISOString()
}
}
});
// Feature usage
vemetric.trackEvent('FeatureUsed', {
eventData: {
feature: 'export-data',
exportType: 'csv'
}
});
// User logout
vemetric.resetUser();
Next Steps
React SDK
Use Vemetric in React applications
Tracking Events
Learn event tracking best practices
Configuration
Advanced configuration options
Node.js SDK
Server-side tracking with Node.js
