@nice2dev/game-engine 1.1.5 → 1.1.7

package/dist/types/systems/NiceAnalytics.d.ts

@@ -0,0 +1,493 @@
+/**
+ * NiceAnalytics - Game Analytics & Telemetry System
+ *
+ * Comprehensive analytics system for tracking player behavior, game performance,
+ * progression metrics, and generating insights for game improvement.
+ *
+ * Features:
+ * - Event tracking
+ * - Session management
+ * - Player journey tracking
+ * - Funnel analysis
+ * - Retention metrics
+ * - Performance monitoring
+ * - Custom dimensions
+ * - A/B testing support
+ * - Real-time dashboards
+ * - Privacy compliance
+ * - Offline queuing
+ * - Data export
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+/** Unique event ID */
+export type AnalyticsEventId = string;
+/** Unique session ID */
+export type SessionId = string;
+/** Unique user ID */
+export type AnalyticsUserId = string;
+/** Unique experiment ID */
+export type ExperimentId = string;
+/** Event category */
+export type EventCategory = 'gameplay' | 'progression' | 'economy' | 'social' | 'ui' | 'performance' | 'error' | 'monetization' | 'engagement' | 'custom';
+/** Event priority */
+export type EventPriority = 'low' | 'normal' | 'high' | 'critical';
+/** Data type for custom dimensions */
+export type DimensionValue = string | number | boolean;
+/** Funnel stage */
+export type FunnelStage = string;
+/** Analytics event */
+export interface AnalyticsEvent {
+    id: AnalyticsEventId;
+    name: string;
+    category: EventCategory;
+    priority: EventPriority;
+    timestamp: number;
+    sessionId: SessionId;
+    userId?: AnalyticsUserId;
+    parameters: Record<string, DimensionValue>;
+    dimensions: Record<string, DimensionValue>;
+    metrics: Record<string, number>;
+    sequenceNumber: number;
+    gameVersion: string;
+    platform: string;
+    metadata?: Record<string, unknown>;
+}
+/** Session data */
+export interface AnalyticsSession {
+    id: SessionId;
+    userId?: AnalyticsUserId;
+    startTime: number;
+    endTime?: number;
+    duration: number;
+    eventCount: number;
+    isActive: boolean;
+    platform: string;
+    gameVersion: string;
+    deviceInfo: DeviceInfo;
+    entryPoint?: string;
+    exitPoint?: string;
+    dimensions: Record<string, DimensionValue>;
+}
+/** Device information */
+export interface DeviceInfo {
+    type: 'desktop' | 'mobile' | 'tablet' | 'console' | 'unknown';
+    os: string;
+    osVersion: string;
+    browser?: string;
+    browserVersion?: string;
+    screenWidth: number;
+    screenHeight: number;
+    devicePixelRatio: number;
+    language: string;
+    timezone: string;
+    memory?: number;
+    cpuCores?: number;
+    gpu?: string;
+}
+/** User properties */
+export interface UserProperties {
+    userId: AnalyticsUserId;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    totalSessions: number;
+    totalPlayTime: number;
+    level: number;
+    isPaying: boolean;
+    totalSpent: number;
+    acquisitionSource?: string;
+    acquisitionCampaign?: string;
+    cohort?: string;
+    segment?: string;
+    tags: string[];
+    customProperties: Record<string, DimensionValue>;
+}
+/** Funnel definition */
+export interface FunnelDefinition {
+    id: string;
+    name: string;
+    stages: FunnelStage[];
+    timeout?: number;
+    isActive: boolean;
+}
+/** Funnel progress */
+export interface FunnelProgress {
+    funnelId: string;
+    userId: AnalyticsUserId;
+    currentStage: number;
+    completedStages: FunnelStage[];
+    startTime: number;
+    lastActivityTime: number;
+    isCompleted: boolean;
+    isAbandoned: boolean;
+    conversionTime?: number;
+}
+/** A/B Experiment */
+export interface Experiment {
+    id: ExperimentId;
+    name: string;
+    description?: string;
+    variants: ExperimentVariant[];
+    startDate: number;
+    endDate?: number;
+    targetAudience?: string;
+    isActive: boolean;
+    metrics: string[];
+}
+/** Experiment variant */
+export interface ExperimentVariant {
+    id: string;
+    name: string;
+    weight: number;
+    config: Record<string, unknown>;
+}
+/** User experiment assignment */
+export interface ExperimentAssignment {
+    experimentId: ExperimentId;
+    variantId: string;
+    assignedAt: number;
+    userId: AnalyticsUserId;
+}
+/** Performance metrics */
+export interface PerformanceMetrics {
+    fps: number;
+    frameTime: number;
+    memoryUsed: number;
+    memoryTotal: number;
+    loadTime: number;
+    drawCalls?: number;
+    triangles?: number;
+    networkLatency?: number;
+    timestamp: number;
+}
+/** Retention bucket */
+export interface RetentionBucket {
+    day: number;
+    cohort: string;
+    totalUsers: number;
+    returnedUsers: number;
+    retentionRate: number;
+}
+/** Revenue event */
+export interface RevenueEvent {
+    transactionId: string;
+    productId: string;
+    productName: string;
+    category: string;
+    price: number;
+    currency: string;
+    quantity: number;
+    isSubscription: boolean;
+    timestamp: number;
+}
+/** Error report */
+export interface ErrorReport {
+    id: string;
+    type: 'error' | 'warning' | 'crash';
+    message: string;
+    stack?: string;
+    context: Record<string, unknown>;
+    timestamp: number;
+    sessionId: SessionId;
+    count: number;
+    firstOccurrence: number;
+    lastOccurrence: number;
+}
+/** Analytics summary */
+export interface AnalyticsSummary {
+    totalEvents: number;
+    totalSessions: number;
+    totalUsers: number;
+    averageSessionDuration: number;
+    eventsPerSession: number;
+    topEvents: Array<{
+        name: string;
+        count: number;
+    }>;
+    topCategories: Array<{
+        category: EventCategory;
+        count: number;
+    }>;
+    errorRate: number;
+    performanceAvg: PerformanceMetrics;
+}
+/** Queue item */
+export interface QueuedEvent {
+    event: AnalyticsEvent;
+    retries: number;
+    queuedAt: number;
+}
+/** Privacy settings */
+export interface PrivacySettings {
+    analyticsEnabled: boolean;
+    errorReportingEnabled: boolean;
+    performanceTrackingEnabled: boolean;
+    personalDataEnabled: boolean;
+    consentTimestamp?: number;
+    consentVersion?: string;
+}
+/** Analytics event types */
+export type AnalyticsEventType = 'event_tracked' | 'session_started' | 'session_ended' | 'session_resumed' | 'user_identified' | 'user_updated' | 'funnel_progressed' | 'funnel_completed' | 'funnel_abandoned' | 'experiment_assigned' | 'revenue_tracked' | 'error_reported' | 'performance_recorded' | 'queue_flushed' | 'privacy_changed';
+/** Analytics system event */
+export interface AnalyticsSystemEvent {
+    type: AnalyticsEventType;
+    timestamp: number;
+    eventId?: AnalyticsEventId;
+    sessionId?: SessionId;
+    userId?: AnalyticsUserId;
+    data?: unknown;
+}
+/** Analytics event callback */
+export type AnalyticsEventCallback = (event: AnalyticsSystemEvent) => void;
+/** Analytics configuration */
+export interface AnalyticsConfig {
+    appId: string;
+    appVersion: string;
+    platform: string;
+    flushIntervalMs: number;
+    maxQueueSize: number;
+    maxRetries: number;
+    batchSize: number;
+    enableOfflineQueue: boolean;
+    enableAutoTracking: boolean;
+    enablePerformanceTracking: boolean;
+    enableErrorTracking: boolean;
+    performanceTrackingIntervalMs: number;
+    sessionTimeoutMs: number;
+    respectDoNotTrack: boolean;
+    anonymizeIp: boolean;
+    endpointUrl?: string;
+}
+/** Default configuration */
+export declare const DEFAULT_ANALYTICS_CONFIG: AnalyticsConfig;
+/**
+ * Game analytics and telemetry system
+ */
+export declare class NiceAnalytics extends EventEmitter {
+    private config;
+    private currentSession?;
+    private currentUser?;
+    private events;
+    private eventQueue;
+    private funnels;
+    private funnelProgress;
+    private experiments;
+    private assignments;
+    private errors;
+    private performanceHistory;
+    private privacySettings;
+    private deviceInfo;
+    private globalDimensions;
+    private sequenceCounter;
+    private flushInterval?;
+    private performanceInterval?;
+    private lastActivityTime;
+    private isOnline;
+    constructor(config?: Partial<AnalyticsConfig>);
+    /**
+     * Collect device information
+     */
+    private collectDeviceInfo;
+    /**
+     * Detect device type
+     */
+    private detectDeviceType;
+    /**
+     * Detect operating system
+     */
+    private detectOS;
+    /**
+     * Check Do Not Track setting
+     */
+    private checkDoNotTrack;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Emit analytics event
+     */
+    private emitEvent;
+    /**
+     * Start flush interval
+     */
+    private startFlushInterval;
+    /**
+     * Start performance tracking
+     */
+    private startPerformanceTracking;
+    /**
+     * Start new session
+     */
+    startSession(entryPoint?: string): SessionId;
+    /**
+     * End current session
+     */
+    endSession(exitPoint?: string): void;
+    /**
+     * Resume session after pause
+     */
+    resumeSession(): void;
+    /**
+     * Get current session
+     */
+    getCurrentSession(): AnalyticsSession | undefined;
+    /**
+     * Identify user
+     */
+    identify(userId: AnalyticsUserId, properties?: Partial<UserProperties>): void;
+    /**
+     * Update user properties
+     */
+    updateUser(properties: Partial<UserProperties>): void;
+    /**
+     * Set user property
+     */
+    setUserProperty(key: string, value: DimensionValue): void;
+    /**
+     * Get current user
+     */
+    getCurrentUser(): UserProperties | undefined;
+    /**
+     * Reset user (logout)
+     */
+    resetUser(): void;
+    /**
+     * Track event
+     */
+    track(name: string, category?: EventCategory, parameters?: Record<string, DimensionValue>, metrics?: Record<string, number>, priority?: EventPriority): AnalyticsEventId | undefined;
+    /**
+     * Track timed event start
+     */
+    startTimedEvent(name: string, _category?: EventCategory): string;
+    /**
+     * Track timed event end
+     */
+    endTimedEvent(timingId: string, name: string, category?: EventCategory, additionalParams?: Record<string, DimensionValue>): void;
+    /**
+     * Enqueue event for sending
+     */
+    private enqueue;
+    /**
+     * Flush event queue
+     */
+    flush(): Promise<void>;
+    /**
+     * Set global dimension
+     */
+    setDimension(key: string, value: DimensionValue): void;
+    /**
+     * Remove global dimension
+     */
+    removeDimension(key: string): void;
+    /**
+     * Get all dimensions
+     */
+    getDimensions(): Record<string, DimensionValue>;
+    /**
+     * Set multiple dimensions
+     */
+    setDimensions(dimensions: Record<string, DimensionValue>): void;
+    /**
+     * Define funnel
+     */
+    defineFunnel(funnel: FunnelDefinition): void;
+    /**
+     * Check funnel progress
+     */
+    private checkFunnels;
+    /**
+     * Get funnel progress
+     */
+    getFunnelProgress(funnelId: string): FunnelProgress | undefined;
+    /**
+     * Reset funnel progress
+     */
+    resetFunnelProgress(funnelId: string): void;
+    /**
+     * Register experiment
+     */
+    registerExperiment(experiment: Experiment): void;
+    /**
+     * Get variant for experiment
+     */
+    getVariant(experimentId: ExperimentId): ExperimentVariant | undefined;
+    /**
+     * Track experiment exposure
+     */
+    trackExposure(experimentId: ExperimentId): void;
+    /**
+     * Track experiment conversion
+     */
+    trackConversion(experimentId: ExperimentId, value?: number): void;
+    /**
+     * Track revenue
+     */
+    trackRevenue(event: Omit<RevenueEvent, 'timestamp'>): void;
+    /**
+     * Track subscription
+     */
+    trackSubscription(productId: string, action: 'start' | 'renew' | 'cancel', price?: number): void;
+    /**
+     * Track error
+     */
+    trackError(message: string, stack?: string, context?: Record<string, unknown>, type?: 'error' | 'warning' | 'crash'): void;
+    /**
+     * Get error reports
+     */
+    getErrors(): ErrorReport[];
+    /**
+     * Record performance metrics
+     */
+    recordPerformance(metrics?: Partial<PerformanceMetrics>): void;
+    /**
+     * Get performance history
+     */
+    getPerformanceHistory(): PerformanceMetrics[];
+    /**
+     * Get average performance
+     */
+    getAveragePerformance(): PerformanceMetrics;
+    /**
+     * Set privacy settings
+     */
+    setPrivacySettings(settings: Partial<PrivacySettings>): void;
+    /**
+     * Get privacy settings
+     */
+    getPrivacySettings(): PrivacySettings;
+    /**
+     * Opt out of all tracking
+     */
+    optOut(): void;
+    /**
+     * Opt in to tracking
+     */
+    optIn(): void;
+    /**
+     * Get analytics summary
+     */
+    getSummary(): AnalyticsSummary;
+    /**
+     * Export all data
+     */
+    exportData(): object;
+    /**
+     * Clear all data
+     */
+    clearData(): void;
+    /**
+     * Set online status
+     */
+    setOnlineStatus(online: boolean): void;
+    /**
+     * Destroy analytics system
+     */
+    destroy(): void;
+}
+/**
+ * Create analytics system instance
+ */
+export declare function createAnalyticsSystem(config?: Partial<AnalyticsConfig>): NiceAnalytics;
+export default NiceAnalytics;