Track Events

Oppla provides comprehensive event tracking capabilities including standard events, feature flag interactions, experiment conversions, and automation triggers. All events are automatically enriched with user context, IP geolocation, and session data.

Using Data Attributes

Track events by adding data attributes to your HTML elements:
<!-- Basic event tracking -->
<button id="signup-button" data-oppla-event="Signup button">
  Sign up
</button>

<!-- Event tracking with additional data -->
<button 
  id="signup-button" 
  data-oppla-event="Signup button"
  data-oppla-event-buttonId="signup-button"
  data-oppla-event-page="homepage">
  Sign up
</button>

Using JavaScript

Track events programmatically using the Oppla object:
// Browser implementation
window.oppla.track('Button Clicked', {
  buttonId: 'signup-button',
  page: 'homepage'
});

// Node.js implementation
oppla.track('Button Clicked', {
  buttonId: 'signup-button',
  page: 'homepage'
});

Event Properties

Add detailed properties to your events:
// Browser implementation
window.oppla.track('Purchase Completed', {
  // Order details
  orderId: '12345',
  amount: 99.99,
  currency: 'USD',
  items: ['product1', 'product2'],
  
  // User context
  userId: 'user_123',
  userType: 'premium',
  
  // Custom properties
  source: 'homepage',
  campaign: 'summer_sale'
});

// Node.js implementation
oppla.track('Purchase Completed', {
  // Same properties as above
});

Standard Event Types

Page Views

Track page views with automatic enrichment:
// Automatic tracking (enabled by default)
// Tracks: URL, referrer, title, session info, IP location

// Manual tracking with custom properties
window.oppla.track('Page Viewed', {
  path: '/products',
  title: 'Products Page',
  referrer: document.referrer,
  category: 'product_catalog',
  searchQuery: 'premium plans'
});

User Actions

Track user interactions:
<!-- Button clicks -->
<button 
  id="checkout-button" 
  data-oppla-event="Button Clicked"
  data-oppla-event-buttonId="checkout-button"
  data-oppla-event-buttonText="Checkout Now">
  Checkout Now
</button>

<!-- Form submissions -->
<form 
  id="contact-form" 
  data-oppla-event="Form Submitted"
  data-oppla-event-formId="contact-form"
  data-oppla-event-formType="contact">
  <!-- form content -->
</form>

<!-- Link clicks -->
<a 
  id="pricing-link" 
  data-oppla-event="Link Clicked"
  data-oppla-event-linkId="pricing-link"
  data-oppla-event-linkText="View Pricing"
  data-oppla-event-destination="/pricing"
  href="/pricing">
  View Pricing
</a>

E-commerce Events

Track e-commerce activities:
// Browser implementation
window.oppla.track('Product Viewed', {
  productId: 'prod_123',
  name: 'Premium Plan',
  price: 99.99
});

window.oppla.track('Added to Cart', {
  productId: 'prod_123',
  quantity: 1,
  price: 99.99
});

window.oppla.track('Checkout Started', {
  orderId: 'order_123',
  total: 99.99,
  items: ['prod_123']
});

// Node.js implementation
oppla.track('Product Viewed', {
  productId: 'prod_123',
  name: 'Premium Plan',
  price: 99.99
});

Feature Flag Events

Track feature flag exposures and interactions:
// Automatic tracking when checking flag status
const isEnabled = window.oppla.getFeatureFlagStatus('new-feature');
// Automatically tracks: { event: 'new-feature', flg_name: 'new-feature', flg_value: true }

// Track feature interaction
if (isEnabled) {
  window.oppla.track('feature-interaction', {
    feature: 'new-feature',
    action: 'clicked',
    variant: 'enabled',
    interactionCount: 1
  });
}

// Track feature adoption
window.oppla.track('feature-adopted', {
  feature: 'ai-assistant',
  timeToAdopt: 120, // seconds
  onboardingStep: 'completed'
});

Experiment Events

Track experiment exposures and conversions:
// Get experiment variant (automatically tracks exposure)
const variant = window.oppla.getExperimentStatus('pricing-test');

// Track conversion event
window.oppla.track('experiment-conversion', {
  experiment: 'pricing-test',
  variant: variant,
  action: 'purchase',
  revenue: 99.99
});

// Track experiment interactions
window.oppla.track('experiment-interaction', {
  experiment: 'homepage-test',
  variant: variant,
  element: 'hero-cta',
  timeOnPage: 45 // seconds
});

// Track guardrail metrics
window.oppla.track('experiment-guardrail', {
  experiment: 'performance-test',
  variant: variant,
  metric: 'page-load-time',
  value: 1.2 // seconds
});

Automation Trigger Events

Trigger automated workflows based on user behavior:
// Trigger cart abandonment automation
window.oppla.trigger('cart-abandoned', 'auto_recovery', {
  cartValue: 299.99,
  items: ['product_1', 'product_2'],
  userSegment: 'high_value',
  abandonedAt: new Date().toISOString()
});

// Trigger churn prevention
window.oppla.trigger('churn-risk', 'auto_retention', {
  userId: 'user_123',
  lastLoginDaysAgo: 14,
  usageDecline: 60, // percentage
  subscriptionEndDate: '2024-03-01'
});

// Trigger onboarding assistance
window.oppla.trigger('onboarding-stuck', 'auto_help', {
  step: 'profile_setup',
  timeOnStep: 300, // seconds
  attemptsCount: 3
});

Cross-Product Tracking

Track users across multiple products:
// Track cross-product navigation
window.oppla.track('product-switched', {
  fromProduct: 'web_app',
  toProduct: 'mobile_app',
  method: 'deep_link',
  userId: 'user_123'
});

// Track feature usage across products
window.oppla.track('cross-product-feature', {
  feature: 'advanced_search',
  products: ['web', 'mobile', 'api'],
  primaryProduct: 'web'
});

User Identification Events

Track user identity and properties:
// Identify user (enriches all subsequent events)
window.oppla.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
  company: 'Acme Corp',
  signupDate: '2024-01-01',
  location: 'auto' // Uses IP geolocation
});

// Track user property changes
window.oppla.track('user-upgraded', {
  previousPlan: 'free',
  newPlan: 'premium',
  upgradeReason: 'needed_more_features'
});

Performance Tracking

Monitor application performance:
// Track page load performance
window.addEventListener('load', () => {
  const perfData = performance.getEntriesByType('navigation')[0];
  window.oppla.track('page-performance', {
    url: window.location.href,
    loadTime: perfData.loadEventEnd - perfData.fetchStart,
    domInteractive: perfData.domInteractive,
    firstPaint: perfData.responseEnd - perfData.fetchStart
  });
});

// Track API performance
const startTime = performance.now();
fetch('/api/data')
  .then(response => {
    const duration = performance.now() - startTime;
    window.oppla.track('api-performance', {
      endpoint: '/api/data',
      duration: duration,
      status: response.status,
      success: response.ok
    });
  });

Event Batching

Oppla automatically batches events for performance:
// Events are automatically batched and sent every 5 seconds
// or when 10 events accumulate, whichever comes first

// Force immediate send (useful for critical events)
window.oppla.track('critical-event', {
  type: 'payment_completed',
  amount: 999.99
}, { immediate: true });

Important Notes

  1. Automatic Enrichment:
    • All events include timestamp, session ID, and user context
    • IP geolocation is automatically added via ipapi.co
    • Device and browser information is captured
  2. Data Types:
    • JavaScript method supports all data types
    • HTML attributes are converted to strings
    • Nested objects and arrays are supported
  3. Privacy:
    • Never include passwords or sensitive data
    • PII should be hashed when necessary
    • Respect user privacy preferences

Best Practices

Naming Conventions

// Use consistent naming patterns
window.oppla.track('product.viewed', { id: '123' });      // Good
window.oppla.track('product.added_to_cart', { id: '123' }); // Good
window.oppla.track('checkout.started', { total: 99.99 });  // Good

Event Properties

// Include comprehensive context
window.oppla.track('button.clicked', {
  // What
  buttonId: 'cta-hero',
  buttonText: 'Start Free Trial',
  
  // Where
  page: '/homepage',
  section: 'hero',
  
  // When
  sessionDuration: 45,
  isFirstVisit: false,
  
  // Who
  userSegment: 'trial',
  accountType: 'business'
});

Error Tracking

// Track errors with context
window.addEventListener('error', (e) => {
  window.oppla.track('error.occurred', {
    message: e.message,
    source: e.filename,
    line: e.lineno,
    column: e.colno,
    stack: e.error?.stack,
    url: window.location.href
  });
});

Next Steps