Skip to main content

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.

​
Overview

This guide covers common issues you might encounter when integrating Vemetric and provides step-by-step solutions to resolve them.
Most tracking issues can be diagnosed by checking your browser’s developer console and network tab. Enable verbose logging during development.

​
Events Not Appearing

​
Events Not Showing in Dashboard

Diagnosis: Open browser DevTools and check the Network tab.What to look for:
  1. Requests to https://hub.vemetric.com/e (event endpoint)
  2. Request should return 200 OK status
  3. Request payload should contain event data
Common issues:
  • No requests: SDK not initialized or event tracking code not executed
  • 404 or 400 errors: Invalid endpoint URL or malformed request
  • CORS errors: Cross-origin request blocked
Solutions:
// Verify SDK is initialized
if (typeof vemetric === 'undefined') {
  console.error('Vemetric SDK not loaded');
}

// Check event is being called
vemetric.track('test_event', { debug: true });
console.log('Event tracked');
Problem: Using incorrect or missing project token.Diagnosis:
// Check current configuration
console.log(vemetric.getConfig());
Solution:
  1. Log in to your Vemetric dashboard
  2. Go to Project Settings
  3. Copy the correct project token
  4. Update your initialization code:
vemetric.init({
  token: 'your-correct-project-token' // Verify this matches dashboard
});
Problem: Your requests are being identified as bot traffic.How Vemetric detects bots:
  • User agent matching known bot patterns
  • Automated testing tools (Selenium, Puppeteer)
  • Missing or suspicious headers
Solution for testing:
  • Use a real browser (not headless)
  • Ensure user agent is set correctly
  • For automated tests, add the user agent to allowed list
Problem: Your IP address or country is in the exclusion list.Check exclusion settings:
  1. Go to Project Settings
  2. Look for “Excluded IPs” and “Excluded Countries”
  3. Verify your IP/country is not listed
What happens when excluded:
  • Request returns 200 OK (appears successful)
  • No data is stored or processed
  • Events silently dropped
Solution:
  • Remove your IP from exclusion list
  • Disable country exclusions during testing
  • Use a VPN to test from different locations
Problem: Browser is prefetching pages, and those events are being filtered.How Vemetric detects prefetch:
// Automatically filtered headers:
'X-Purpose': 'prefetch'
'Purpose': 'prefetch'
'X-Moz': 'prefetch'
Verification:
  • Check request headers in Network tab
  • Look for prefetch-related headers
  • These requests are intentionally ignored
Expected behavior: This is working as intended to prevent false page views.

​
SDK Integration Issues

​
SDK Not Loading

1

Verify script tag

Ensure the SDK is properly included:
<!-- Correct -->
<script src="https://cdn.vemetric.com/sdk.js"></script>

<!-- Common mistakes -->
<script src="http://cdn.vemetric.com/sdk.js"></script> <!-- Missing HTTPS -->
<script src="https://cdn.vemetric.com/sdk.min.js"></script> <!-- Wrong filename -->
2

Check loading order

Initialize Vemetric after the SDK loads:
<!-- Wrong: Initialization runs before SDK loads -->
<script>
  vemetric.init({ token: 'xxx' }); // Error: vemetric is undefined
</script>
<script src="https://cdn.vemetric.com/sdk.js"></script>

<!-- Correct: SDK loads first -->
<script src="https://cdn.vemetric.com/sdk.js"></script>
<script>
  vemetric.init({ token: 'xxx' }); // Works correctly
</script>
3

Handle async loading

If loading the SDK asynchronously:
<script async src="https://cdn.vemetric.com/sdk.js"></script>
<script>
  // Wait for SDK to load
  window.addEventListener('load', function() {
    if (typeof vemetric !== 'undefined') {
      vemetric.init({ token: 'your-token' });
    }
  });
</script>
4

Verify CDN accessibility

Test if the CDN is accessible:
# Check if SDK is downloadable
curl -I https://cdn.vemetric.com/sdk.js

# Should return 200 OK
Common CDN issues:
  • Corporate firewall blocking CDN
  • Ad blockers removing tracking scripts
  • Network connectivity issues

​
Initialization Errors

Error: Token is requiredCause: Initialization called without project token.Solution:
// Wrong
vemetric.init();

// Correct
vemetric.init({
  token: 'your-project-token'
});
Warning: Vemetric already initializedCause: init() called more than once.Solution:
// Check before initializing
if (!vemetric.isInitialized()) {
  vemetric.init({ token: 'xxx' });
}

​
User Identification Issues

​
Users Not Being Identified

1

Check identification request

Look for requests to /i endpoint in Network tab:
// Correct usage
vemetric.identify('user-123', {
  displayName: 'John Doe',
  email: 'john@example.com'
});
Request should:
  • POST to https://hub.vemetric.com/i
  • Return 200 OK or 202 Accepted
  • Include identifier in payload
2

Verify identifier format

Requirements:
  • Must be a non-empty string
  • Should be unique per user
  • Can be email, user ID, or custom identifier
// Valid identifiers
vemetric.identify('user-12345');
vemetric.identify('john@example.com');
vemetric.identify('auth0|abc123');

// Invalid identifiers
vemetric.identify(''); // Empty string
vemetric.identify(null); // Null
vemetric.identify(12345); // Number (should be string)
3

Check for concurrent identifications

Problem: Multiple identify calls for the same user happening simultaneously.What happens:
  • Only the first call acquires a lock
  • Subsequent calls return 202 Accepted (“already running”)
  • This is expected behavior to prevent race conditions
Verification:
// Both of these run at the same time
vemetric.identify('user-123');
vemetric.identify('user-123'); // Returns 202

// Expected: Second call waits for first to complete
4

Verify user appears in dashboard

After identification:
  1. Go to Vemetric dashboard
  2. Navigate to Users section
  3. Search for the identifier
  4. Check if user profile exists with correct data
Delay: User data may take a few seconds to appear due to queue processing.

​
User Merging Not Working

Scenario: User browses anonymously, then logs in. Events should merge to identified user.
How it works:
  1. Anonymous user visits site → User ID generated (e.g., 1234567890)
  2. Events tracked with anonymous ID
  3. User logs in → identify() called with email
  4. System finds existing user with that email
  5. Anonymous events merged to identified user
  6. Cookie updated with identified user’s ID
What to check:
// Step 1: Anonymous browsing
// User ID: auto-generated (e.g., 1234567890)
vemetric.track('page_view', { page: '/home' });

// Step 2: User logs in
vemetric.identify('john@example.com');

// Step 3: Verify merge happened
// Check dashboard: all events should be under john@example.com
Common issues:
  • Identification called too late (after session ends)
  • Different project tokens used before/after login
  • User already identified with different email
Verification:
// Check current cookie setting
console.log('Cookies allowed:', vemetric.areCookiesAllowed());

// Enable cookies if disabled
vemetric.allowCookies(true);
Common causes:
  • Initialized with allowCookies: false
  • User declined cookie consent
  • Cookies disabled in browser settings
Problem: Cookie not set on HTTP sites.Why: Vemetric uses Secure flag, which requires HTTPS.Solution:
  • Use HTTPS in production (required)
  • For local development, use https://localhost or disable secure cookies:
// Development only - NOT for production
vemetric.init({
  token: 'xxx',
  secureCookies: false // Only for local HTTP testing
});
Problem: Cookie blocked due to SameSite policy.Browser console error:
Cookie "_vuid" has been rejected because it is in a cross-site context
and the "SameSite" attribute is "None"
Causes:
  • Missing Secure attribute
  • Browser blocking third-party cookies
  • Tracking prevention enabled
Solutions:
  1. Ensure HTTPS is used
  2. Inform users about cookie requirements
  3. Use cookieless tracking as fallback:
vemetric.init({
  token: 'xxx',
  allowCookies: true, // Try cookies first
  fallbackToCookieless: true // Use cookieless if blocked
});
Scenario: Cookie not accessible across subdomains.
1

Inspect cookie in DevTools

  1. Open browser DevTools
  2. Go to Application/Storage → Cookies
  3. Look for _vuid cookie
  4. Check the Domain column
2

Verify domain format

Correct formats:
  • .example.com (with leading dot - works on all subdomains)
  • example.com (works on example.com and subdomains)
Incorrect formats:
  • www.example.com (only works on www subdomain)
  • https://example.com (includes protocol - invalid)
3

Configure base domain

Set the correct domain in project settings:
// In Vemetric dashboard
Project Settings → Domain: example.com

// Or override in SDK
vemetric.init({
  token: 'xxx',
  domain: 'example.com'
});

​
Session Tracking Issues

​
Sessions Breaking Unexpectedly

Behavior: Sessions expire after 30 minutes of inactivity.How it works:
  • Each page view or event extends the session by 30 minutes
  • If 30 minutes pass with no activity, session ends
  • Next event creates a new session
Verification:
// Track session ID
vemetric.track('page_view', {
  debug_session: vemetric.getSessionId()
});
Expected: Session ID changes after 30 minutes of inactivity.

​
Multiple Sessions for Same User

Causes:
  • Switching between devices/browsers
  • Cookieless tracking with changing IP or user agent
  • Clearing cookies between visits
  • Using incognito/private mode
Diagnosis: 
// Track device fingerprint
vemetric.track('page_view', {
  user_agent: navigator.userAgent,
  platform: navigator.platform,
  screen_size: `${screen.width}x${screen.height}`
});
Solution: Use identify() to merge sessions: 
// When user logs in
vemetric.identify('user@example.com');
// All previous sessions for this user will be linked

​
Performance Issues

​
Slow Page Loads

Prevent blocking page render:
<!-- Blocking (bad) -->
<script src="https://cdn.vemetric.com/sdk.js"></script>

<!-- Non-blocking (good) -->
<script async src="https://cdn.vemetric.com/sdk.js"></script>
Handle async initialization:
// Queue events until SDK loads
window.vemetricQueue = window.vemetricQueue || [];

function track(eventName, properties) {
  if (typeof vemetric !== 'undefined') {
    vemetric.track(eventName, properties);
  } else {
    vemetricQueue.push(['track', eventName, properties]);
  }
}

// Process queue when SDK loads
window.addEventListener('load', function() {
  vemetricQueue.forEach(([method, ...args]) => {
    vemetric[method](...args);
  });
});
Problem: Sending too many individual events.Solution: Batch non-critical events:
// Instead of tracking every scroll
let scrollDepth = 0;
window.addEventListener('scroll', () => {
  scrollDepth = Math.max(scrollDepth, 
    window.scrollY / document.body.scrollHeight);
});

// Track once on page leave
window.addEventListener('beforeunload', () => {
  vemetric.track('scroll_depth', {
    max_depth: Math.round(scrollDepth * 100)
  });
});
Problem: Large custom properties slow down requests.Solution:
// Bad: Sending huge objects
vemetric.track('form_filled', {
  entire_form_data: formData, // Could be 100KB+
  user_object: userData // Redundant data
});

// Good: Send only what's needed
vemetric.track('form_filled', {
  form_id: 'contact-form',
  fields_count: Object.keys(formData).length,
  completion_time: timeSpent
});

​
Network and CORS Issues

​
CORS Errors

Error: Access to fetch at 'https://hub.vemetric.com/e' from origin 'https://example.com' has been blocked by CORS policy Cause: Cross-Origin Resource Sharing configuration issue. Solutions:
1

Verify request includes credentials

// SDK handles this automatically, but for custom implementations:
fetch('https://hub.vemetric.com/e', {
  method: 'POST',
  credentials: 'include', // Required for cookies
  headers: {
    'Content-Type': 'application/json',
    'Origin': window.location.origin
  }
});
2

Check origin header

Ensure the Origin header matches your actual domain:
  • Should be https://example.com (not http://)
  • Should not include trailing slash
  • Should match exactly what’s in the browser address bar
3

Verify HTTPS

Mixed content (HTTPS page loading HTTP resources) can cause CORS issues:
  • Ensure your site uses HTTPS
  • Vemetric endpoints are always HTTPS
  • Check for HTTP resources in your page

​
Request Timeouts

Problem: Event requests timing out. Diagnosis: 
// Set a timeout for debugging
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);

fetch('https://hub.vemetric.com/e', {
  signal: controller.signal,
  // ... other options
}).catch(err => {
  if (err.name === 'AbortError') {
    console.error('Request timed out after 5 seconds');
  }
});
Solutions:
  • Check network connectivity
  • Verify firewall isn’t blocking requests
  • Test from different networks
  • Contact Vemetric support if persistent

​
Debugging Tools

​
Enable Debug Mode

vemetric.init({
  token: 'your-token',
  debug: true // Enables verbose logging
});

// Logs will show:
// - Every event tracked
// - API requests/responses
// - Cookie operations
// - Errors and warnings

​
Browser Console Checks

// Check SDK is loaded
typeof vemetric !== 'undefined' // Should be true

// Get current configuration
vemetric.getConfig()

// Get current user ID
vemetric.getUserId()

// Get current session ID
vemetric.getSessionId()

// Check if cookies are allowed
vemetric.areCookiesAllowed()

// Manually trigger a test event
vemetric.track('debug_test', { timestamp: Date.now() })

​
Network Tab Inspection

What to look for in browser DevTools Network tab:
  1. Event tracking (/e endpoint):
    • Method: POST
    • Status: 200 OK
    • Response: Empty (200 status is success)
  2. User identification (/i endpoint):
    • Method: POST
    • Status: 200 OK or 202 Accepted
    • Response: Empty
  3. Headers to verify:
    • Content-Type: application/json
    • allow-cookies: true/false
    • v-sdk, v-sdk-version
    • v-host (if using subdomains)
  4. Request payload:
    • Should be valid JSON
    • Contains event name and properties
    • No sensitive data leaked

​
Getting Help

Documentation

Review the full Vemetric documentation for detailed guides.

GitHub Issues

Report bugs or request features on GitHub.

Community Support

Join the Vemetric community for help from other users.

Contact Support

Reach out to Vemetric support for personalized assistance.
When reporting issues, include:
  • Browser and version
  • SDK version
  • Console errors/warnings
  • Network request details
  • Steps to reproduce

Build docs developers (and LLMs) love

Get started for freeTalk to us