Pirsch Event Tracking: Cookie-Free Custom Events | OpsBlu Docs

Pirsch Event Tracking: Cookie-Free Custom Events

How to track custom events in Pirsch without cookies or personal data. Covers pirsch() JavaScript API, server-side HTTP API, goal tracking, and...

Event Tracking Overview

Pirsch provides a simple, privacy-focused event tracking system that allows you to monitor specific user actions and conversions without collecting personal data. Events are tracked using the lightweight Pirsch JavaScript function and can include custom metadata for richer analytics while maintaining GDPR compliance.

Basic Event Tracking

Track events using the global pirsch function:

// Simple event
pirsch('Button Clicked');

// Event with metadata
pirsch('Download', {
  meta: {
    file_type: 'PDF',
    file_name: 'whitepaper.pdf',
    file_size: '2.3MB'
  }
});

// Event with duration
pirsch('Video Watched', {
  duration: 180, // seconds
  meta: {
    video_id: 'intro-tutorial',
    completion_rate: 75
  }
});

Event Metadata

Add custom properties to events for detailed analysis:

// E-commerce events
pirsch('Product Viewed', {
  meta: {
    product_id: 'PROD-123',
    product_name: 'Premium Widget',
    category: 'Electronics',
    price: 99.99,
    currency: 'USD'
  }
});

pirsch('Add to Cart', {
  meta: {
    product_id: 'PROD-123',
    quantity: 2,
    cart_value: 199.98
  }
});

pirsch('Purchase Completed', {
  meta: {
    order_id: 'ORD-456',
    order_value: 199.98,
    payment_method: 'credit_card',
    items_count: 2
  }
});

Common Event Patterns

Conversion Events

// Signups and registrations
pirsch('Signup Completed', {
  meta: {
    plan: 'Free',
    source: 'homepage_cta'
  }
});

pirsch('Trial Started', {
  meta: {
    plan: 'Pro',
    trial_days: 14
  }
});

pirsch('Subscription Created', {
  meta: {
    plan: 'Business',
    billing_cycle: 'annual',
    mrr: 99
  }
});

Content Engagement

// Article reading
pirsch('Article Read', {
  duration: 245, // time spent reading in seconds
  meta: {
    article_id: 'blog-post-123',
    article_title: 'Guide to Analytics',
    category: 'Tutorials',
    scroll_depth: 85
  }
});

// Resource downloads
pirsch('Resource Downloaded', {
  meta: {
    resource_type: 'ebook',
    resource_name: 'Analytics Best Practices',
    format: 'PDF'
  }
});

// Newsletter signup
pirsch('Newsletter Subscribed', {
  meta: {
    source: 'blog_footer',
    list: 'weekly_digest'
  }
});

User Engagement

// Feature usage
pirsch('Feature Used', {
  meta: {
    feature_name: 'Advanced Filters',
    frequency: 'first_time'
  }
});

// Search performed
pirsch('Search', {
  meta: {
    query_length: 15,
    results_count: 42,
    filter_applied: true
  }
});

// Share action
pirsch('Content Shared', {
  meta: {
    platform: 'twitter',
    content_type: 'blog_post',
    content_id: 'post-789'
  }
});

Goal Configuration

Configure tracked events as goals in Pirsch dashboard:

Setting Up Goals

  1. Navigate to Settings > Goals in Pirsch dashboard
  2. Click "Create Goal"
  3. Select event name from tracked events
  4. Configure goal parameters:
    • Goal name (display name)
    • Event name (technical name)
    • Value (optional monetary value)
    • Conversion type

Goal Types

Conversion Goals:

// Track these events
pirsch('Purchase Completed', { meta: { value: 199.99 } });
pirsch('Lead Generated', { meta: { source: 'contact_form' } });
pirsch('Demo Requested', { meta: { plan_interest: 'Enterprise' } });

// Configure in dashboard as conversion goals
// Monitor conversion rates and revenue

Engagement Goals:

// Track engagement milestones
pirsch('Onboarding Completed', {
  duration: 300,
  meta: { steps_completed: 5 }
});

pirsch('Profile Completed', {
  meta: { completion_rate: 100 }
});

// Set as engagement goals in dashboard

Server-Side Event Tracking

Track events from your backend using Pirsch API:

// Node.js example
const axios = require('axios');

async function trackServerEvent(eventName, metadata) {
  await axios.post('https://api.pirsch.io/api/v1/event', {
    event_name: eventName,
    event_meta: metadata,
    event_duration: 0
  }, {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    }
  });
}

// Track server-side events
trackServerEvent('API Call', {
  endpoint: '/api/users',
  method: 'POST',
  status: 201
});

trackServerEvent('Cron Job Completed', {
  job_name: 'daily_report',
  duration: 45,
  records_processed: 1000
});

Event Naming Best Practices

Use Clear, Descriptive Names:

// Good
pirsch('Newsletter Subscription');
pirsch('Premium Upgrade Started');
pirsch('PDF Download');

// Avoid
pirsch('click');
pirsch('event1');
pirsch('thing');

Use Consistent Patterns:

// Consistent object-action pattern
pirsch('Form Submitted');
pirsch('Video Watched');
pirsch('Report Generated');

// Or action-object pattern
pirsch('Submit Form');
pirsch('Watch Video');
pirsch('Generate Report');

Group Related Events:

// Checkout flow events
pirsch('Checkout Started');
pirsch('Checkout Payment Info Added');
pirsch('Checkout Completed');

// Account management
pirsch('Account Created');
pirsch('Account Updated');
pirsch('Account Deleted');

Funnel Tracking

Track multi-step processes with events:

// Step 1: Funnel entry
pirsch('Signup Started', {
  meta: { source: 'homepage', campaign: 'summer_sale' }
});

// Step 2: Progress
pirsch('Email Verified', {
  meta: { verification_method: 'link' }
});

// Step 3: Additional info
pirsch('Profile Created', {
  meta: { has_avatar: true, bio_completed: false }
});

// Step 4: Conversion
pirsch('Onboarding Completed', {
  meta: { time_to_complete: 180, steps_skipped: 0 }
});

// Analyze funnel drop-off in Pirsch dashboard

Event Validation and Testing

Verify events are being tracked correctly:

// Test in browser console
console.log(typeof pirsch); // Should output 'function'

// Trigger test event
pirsch('Test Event', {
  meta: {
    test: true,
    timestamp: new Date().toISOString()
  }
});

// Check network tab for POST to Pirsch API
// Event should appear in Pirsch dashboard within seconds

Privacy Considerations

Pirsch events maintain privacy compliance:

What to Track:

// Good - Anonymous aggregate data
pirsch('Purchase', {
  meta: {
    product_category: 'Electronics',
    price_range: '100-200',
    payment_method: 'card'
  }
});

What to Avoid:

// Bad - Personal identifiable information
pirsch('Purchase', {
  meta: {
    customer_email: 'user@example.com', // Don't include PII
    customer_name: 'John Doe', // Don't include PII
    credit_card: '****1234' // Don't include sensitive data
  }
});

Event Volume and Performance

Pirsch handles high event volumes efficiently:

// Events are lightweight and don't impact performance
// No need to throttle or batch events

// Track frequent user actions
document.addEventListener('scroll', debounce(() => {
  const depth = calculateScrollDepth();
  if (depth > 75) {
    pirsch('Article Scroll 75%', {
      meta: { article_id: getCurrentArticleId() }
    });
  }
}, 1000));

Analytics and Reporting

Use tracked events in Pirsch dashboard:

  • Event Timeline: View all events chronologically
  • Event Breakdown: See event counts and trends over time
  • Goal Conversion: Monitor goal completion rates
  • Event Metadata: Filter and segment by metadata fields
  • Custom Reports: Create reports combining events and pageviews
  • Export Data: Export event data for external analysis

Integration with UTM Parameters

Combine events with UTM tracking:

// Events automatically inherit UTM parameters from pageview
// Track conversion and attribute to campaign

pirsch('Lead Generated', {
  meta: {
    form_type: 'contact_sales',
    company_size: '50-100'
  }
});

// View in dashboard: Which UTM campaigns generate most leads?
Back to top