Custom Events

Track custom user interactions and events with the JavaScript API.

Use the global pipetrace object to track custom events beyond automatic page views and interactions.

Basic Usage

Track any custom event with pipetrace.track():

javascript
// Track a simple event
pipetrace.track('button_click');

// Track with properties
pipetrace.track('button_click', {
  button_id: 'cta-signup',
  button_text: 'Start Free Trial',
  location: 'hero'
});

API Reference

pipetrace.track(name, properties?)

Track a custom event with optional properties.

ParameterTypeDescription
namestringEvent name (required)
propertiesobjectCustom properties (optional)
pipetrace.goal(name, value?)

Track a goal or conversion with optional numeric value.

javascript
// Track a signup goal
pipetrace.goal('signup');

// Track a goal with value
pipetrace.goal('newsletter_subscribe', 10);
pipetrace.revenue(amount, currency?, orderId?)

Track revenue from purchases.

javascript
// Track a purchase
pipetrace.revenue(99.99, 'USD', 'order-12345');

// Track with default currency (USD)
pipetrace.revenue(49.99);

// Track with different currency
pipetrace.revenue(89.99, 'EUR', 'order-67890');
pipetrace.identify(userId, traits?)

Associate the current visitor with a user ID (optional, for logged-in users).

javascript
// Identify a logged-in user
pipetrace.identify('user-123');

// Identify with traits
pipetrace.identify('user-123', {
  plan: 'pro',
  company: 'Acme Inc',
  role: 'admin'
});

Privacy Note: Only use identify() if you need to tie analytics to specific user accounts. It's completely optional.

Common Examples

Button Clicks

javascript
document.querySelector('#signup-btn').addEventListener('click', () => {
  pipetrace.track('cta_click', {
    button: 'signup',
    location: 'navbar'
  });
});

Form Submissions

javascript
document.querySelector('#contact-form').addEventListener('submit', (e) => {
  pipetrace.track('form_submission', {
    form: 'contact',
    fields: ['name', 'email', 'message']
  });
});

Video Engagement

javascript
const video = document.querySelector('video');

video.addEventListener('play', () => {
  pipetrace.track('video_play', { video_id: 'intro-video' });
});

video.addEventListener('ended', () => {
  pipetrace.track('video_complete', { video_id: 'intro-video' });
});

E-commerce Tracking

javascript
// Add to cart
function addToCart(product) {
  pipetrace.track('add_to_cart', {
    product_id: product.id,
    product_name: product.name,
    price: product.price,
    quantity: 1
  });
}

// Complete purchase
function completePurchase(order) {
  pipetrace.revenue(order.total, order.currency, order.id);
  pipetrace.goal('purchase');
}

Feature Usage

javascript
// Track when user uses a specific feature
function useFeature(featureName) {
  pipetrace.track('feature_used', {
    feature: featureName,
    timestamp: new Date().toISOString()
  });
}

React Integration

tsx
// Create a custom hook
function useTracking() {
  const track = (name: string, props?: Record<string, any>) => {
    if (typeof window !== 'undefined' && window.pipetrace) {
      window.pipetrace.track(name, props);
    }
  };

  const goal = (name: string, value?: number) => {
    if (typeof window !== 'undefined' && window.pipetrace) {
      window.pipetrace.goal(name, value);
    }
  };

  return { track, goal };
}

// Use in component
function SignupButton() {
  const { track, goal } = useTracking();

  const handleClick = () => {
    track('signup_button_click', { location: 'hero' });
  };

  const handleSuccess = () => {
    goal('signup');
  };

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

TypeScript Types

Add type definitions for the global pipetrace object:

typescript
// types/pipetrace.d.ts
declare global {
  interface Window {
    pipetrace: {
      track: (name: string, properties?: Record<string, unknown>) => void;
      goal: (name: string, value?: number) => void;
      revenue: (amount: number, currency?: string, orderId?: string) => void;
      identify: (userId: string, traits?: Record<string, unknown>) => void;
      getWebVitals: () => {
        lcp: number | null;
        fid: number | null;
        inp: number | null;
        cls: number;
        fcp: number | null;
        ttfb: number | null;
      };
      getQueueStatus: () => { pending: number; processing: boolean };
    };
  }
}

export {};