Troubleshooting

Common issues and solutions for Vemetric integration

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

Check if events are being sent

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');

Verify project token

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
});

Check for bot filtering

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

IP or country exclusion

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

Prefetch requests

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

Missing required configuration

Error: Token is required

Cause: Initialization called without project token.

Solution:

// Wrong
vemetric.init();

// Correct
vemetric.init({
  token: 'your-project-token'
});

Multiple initializations

Warning: Vemetric already initialized

Cause: 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: '[e-mail]'
   });
   

   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('[e-mail]');
   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.

Understanding user merging

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('[e-mail]');

// Step 3: Verify merge happened
// Check dashboard: all events should be under [e-mail]

Common issues:

• Identification called too late (after session ends)
• Different project tokens used before/after login
• User already identified with different email

Cookie Issues

Cookie Not Being Set

Check if cookies are allowed

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

HTTPS requirement

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
});

SameSite restrictions

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
});

Third-party cookie blocking

Problem: Browsers like Safari and Firefox block third-party cookies by default.

Detection:

// Check if cookie was set
setTimeout(() => {
  if (!document.cookie.includes('_vuid')) {
    console.warn('Cookie blocked - using cookieless tracking');
  }
}, 1000);

Expected behavior: Vemetric falls back to cookieless tracking automatically.

Cookie Domain Issues

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

Session timeout

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.

Cookie deletion

Cause: Cookie containing user ID is deleted.

Common culprits:

• User clears cookies manually
• Browser privacy settings auto-delete cookies
• Other scripts deleting cookies
• Session/private browsing mode

Detection:

// Monitor for cookie changes
setInterval(() => {
  if (!document.cookie.includes('_vuid')) {
    console.warn('Vemetric cookie was deleted');
  }
}, 5000);

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('[e-mail]');
// All previous sessions for this user will be linked

Performance Issues

Slow Page Loads

Load SDK asynchronously

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);
  });
});

Batch events

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)
  });
});

Reduce event payload size

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