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

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

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
Data Types:
- JavaScript method supports all data types
- HTML attributes are converted to strings
- Nested objects and arrays are supported
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

Feature Flags

Control features and track adoption

Experiments

Run A/B tests and track conversions

Automation Triggers

Automate workflows based on events

Sessions

Understand session tracking

Getting Started

Advanced Features

How To

Track Events

Track Events

Using Data Attributes

Using JavaScript

Event Properties

Standard Event Types

Page Views

User Actions

E-commerce Events

Feature Flag Events

Experiment Events

Automation Trigger Events

Cross-Product Tracking

User Identification Events

Performance Tracking

Event Batching

Important Notes

Best Practices

Naming Conventions

Event Properties

Error Tracking

Next Steps

Feature Flags

Experiments

Automation Triggers

Sessions

Getting Started

Advanced Features

How To

Documentation Index

​Track Events

​Using Data Attributes

​Using JavaScript

​Event Properties

​Standard Event Types

​Page Views

​User Actions

​E-commerce Events

​Feature Flag Events

​Experiment Events

​Automation Trigger Events

​Cross-Product Tracking

​User Identification Events

​Performance Tracking

​Event Batching

​Important Notes

​Best Practices

​Naming Conventions

​Event Properties

​Error Tracking

​Next Steps

Feature Flags

Experiments

Automation Triggers

Sessions

Track Events

Using Data Attributes

Using JavaScript

Event Properties

Standard Event Types

Page Views

User Actions

E-commerce Events

Feature Flag Events

Experiment Events

Automation Trigger Events

Cross-Product Tracking

User Identification Events

Performance Tracking

Event Batching

Important Notes

Best Practices

Naming Conventions

Event Properties

Error Tracking

Next Steps