@web-engine-dev/telemetry

Game analytics and event tracking for web-engine-dev.

Features

• Event Tracking: Custom game events
• Session Tracking: Player sessions
• Performance Metrics: Frame time, memory
• Error Tracking: Crash and error reports
• Funnels: Conversion tracking
• A/B Testing: Experiment integration

Installation

npm install @web-engine-dev/telemetry
# or
pnpm add @web-engine-dev/telemetry

Quick Start

import { Telemetry } from '@web-engine-dev/telemetry';

// Initialize
const telemetry = new Telemetry({
  apiKey: 'your-api-key',
  gameId: 'my-game',
  enabled: true,
});

// Track events
telemetry.track('level_start', { level: 1 });
telemetry.track('item_collected', { item: 'coin', value: 10 });
telemetry.track('level_complete', { level: 1, time: 120 });

// Track errors
telemetry.trackError(error, { context: 'loading' });

// End session
telemetry.endSession();

API Overview

Event Tracking

// Simple event
telemetry.track('button_click');

// Event with properties
telemetry.track('purchase', {
  item: 'sword',
  price: 100,
  currency: 'gold',
});

// Timed event
const timer = telemetry.startTimer('level_duration');
// ... level gameplay ...
timer.stop({ level: 1, score: 5000 });

Session Management

// Session starts automatically

// Get session info
const session = telemetry.getSession();
console.log(session.id);
console.log(session.startTime);
console.log(session.duration);

// Set user properties
telemetry.setUser({
  id: userId,
  level: playerLevel,
  isPremium: true,
});

// End session
telemetry.endSession();

Performance Metrics

// Automatic metrics
telemetry.enablePerformanceTracking();

// Manual metrics
telemetry.trackPerformance({
  fps: averageFps,
  frameTime: avgFrameTime,
  memoryUsed: memoryMB,
  drawCalls: drawCallCount,
});

Error Tracking

// Track errors
try {
  riskyOperation();
} catch (error) {
  telemetry.trackError(error, {
    context: 'level_loading',
    level: currentLevel,
  });
}

// Automatic error tracking
telemetry.enableErrorTracking();

Funnels

// Track funnel steps
telemetry.trackFunnel('onboarding', 'step1_welcome');
telemetry.trackFunnel('onboarding', 'step2_tutorial');
telemetry.trackFunnel('onboarding', 'step3_play');
telemetry.trackFunnel('onboarding', 'complete');

Privacy

// Opt out
telemetry.setEnabled(false);

// Check status
if (telemetry.isEnabled()) {
  // ...
}

// Clear stored data
telemetry.clearData();