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.

This guide will walk you through setting up Vemetric and tracking your first events. By the end, you’ll have analytics running on your website or application.

​
Prerequisites

Before you begin, make sure you have:
  • A Vemetric account (or a self-hosted instance)
  • A website or application where you want to track analytics
  • Basic knowledge of JavaScript or your preferred framework

​
Choose Your Integration Path

Pick the integration method that best fits your stack:

JavaScript

Vanilla JavaScript for any website

React

React applications and Next.js

Node.js

Server-side tracking

Self-Hosted

Deploy your own instance

​
JavaScript Setup

Perfect for static websites, WordPress, or any site where you can add a script tag.
1

Get your project token

  1. Log in to your Vemetric dashboard
  2. Navigate to Settings → Projects
  3. Copy your project token (starts with vem_)
Keep your project token secure. It will be visible in your frontend code, so only use it for tracking - never for API authentication.
2

Add the tracking script

Add this script tag to the <head> section of your HTML:
<script 
  src="https://cdn.vemetric.com/v1.js" 
  data-token="your-project-token"
  data-host="https://hub.vemetric.com"
  defer
></script>
Replace your-project-token with the token from step 1.
You can customize the tracking script with these data attributes:
  • data-token - Your project token (required)
  • data-host - The ingestion endpoint (defaults to https://hub.vemetric.com)
  • data-allow-cookies - Enable cookie-based tracking (default: "true")
  • data-mask-paths - Mask sensitive URL paths (comma-separated list)
3

Verify tracking

  1. Open your website in a browser
  2. Open the browser console (F12)
  3. You should see a message: Vemetric initialized
  4. Go to your Vemetric dashboard
  5. Navigate to Dashboard → you should see your pageview appear within seconds
Check the Live Events section to see events as they come in real-time.
4

Track custom events

Add custom event tracking anywhere in your JavaScript:
// Track a button click
document.querySelector('#signup-btn').addEventListener('click', () => {
  vemetric.track('button_clicked', {
    button_name: 'signup',
    location: 'header'
  });
});

// Track form submission
document.querySelector('#contact-form').addEventListener('submit', (e) => {
  vemetric.track('form_submitted', {
    form_name: 'contact',
    email: e.target.email.value
  });
});

​
React Setup

For React applications, including Next.js, Remix, and Create React App.
1

Install the React SDK

npm install @vemetric/react
2

Add the VemetricProvider

Wrap your app with the VemetricProvider:
import { VemetricProvider } from '@vemetric/react';

function App() {
  return (
    <VemetricProvider 
      token="your-project-token"
      host="https://hub.vemetric.com"
    >
      <Router>
        {/* Your routes */}
      </Router>
    </VemetricProvider>
  );
}
3

Track events with the hook

Use the useVemetric hook in any component:
import { useVemetric } from '@vemetric/react';

function SignupButton() {
  const { track } = useVemetric();

  const handleSignup = () => {
    track('signup_clicked', {
      button_location: 'hero',
      plan: 'pro'
    });
    // Handle signup...
  };

  return <button onClick={handleSignup}>Sign Up</button>;
}
4

Identify users

When a user logs in, identify them to track their journey:
import { useVemetric } from '@vemetric/react';

function LoginPage() {
  const { identify } = useVemetric();

  const handleLogin = async (email) => {
    // Your login logic...
    
    // Identify the user in Vemetric
    identify({
      identifier: email,
      displayName: 'John Doe',
      properties: {
        plan: 'pro',
        signup_date: '2024-01-15'
      }
    });
  };

  return <LoginForm onSubmit={handleLogin} />;
}

​
Node.js Setup

For server-side tracking in Node.js applications.
1

Install the Node.js SDK

npm install @vemetric/node
2

Initialize the client

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

const vemetric = new Vemetric({
  token: 'your-project-token',
  host: 'https://hub.vemetric.com'
});
3

Track server-side events

// Track an event
await vemetric.track({
  identifier: 'user@example.com',
  event: 'order_completed',
  customData: {
    order_id: '12345',
    total: 99.99,
    items: 3
  }
});

// Identify a user
await vemetric.identify({
  identifier: 'user@example.com',
  displayName: 'John Doe',
  userData: {
    plan: 'enterprise',
    company: 'Acme Corp'
  }
});

​
Next Steps

Now that you’re tracking events, explore these features:

User Journeys

Visualize individual user paths through your product

Funnels

Analyze conversion rates and drop-off points

Custom Events

Track specific user actions and behaviors

Dashboard

Explore your analytics dashboard

​
Troubleshooting

Check these common issues:
  1. Verify your token - Make sure you’re using the correct project token
  2. Check the browser console - Look for any Vemetric-related errors
  3. Bot detection - Vemetric filters out bot traffic by default
  4. IP exclusion - Check if your IP is excluded in project settings
  5. Wait a moment - While events appear in real-time, there might be a brief delay
See the troubleshooting guide for more details.
If you’re getting CORS errors:
  1. Make sure you’re using the correct data-host or host value
  2. For self-hosted instances, ensure your CORS configuration allows your domain
  3. Check that you’re using HTTPS (required for cookie-based tracking)
Common causes:
  1. Content Security Policy (CSP) - Add Vemetric domains to your CSP
  2. Ad blockers - Some ad blockers may block analytics scripts
  3. Environment variables - Verify your token is correctly set in production
Need more help? Check our troubleshooting guide or review the integration documentation.