unified-video-framework 1.4.159 → 1.4.161

package/src/analytics/adapters/PlayerAnalyticsAdapter.ts

@@ -1,572 +0,0 @@
-/**
- * PlayerAnalyticsAdapter - Adapter for integrating with player analytics API
- * Maps internal analytics events to the player analytics system format
- */
-
-import { 
-  AnalyticsEvent as InternalAnalyticsEvent,
-  PlayerState,
-  DeviceInfo,
-  PlayerSessionInfo,
-  AnalyticsConfig
-} from '../types/AnalyticsTypes';
-
-// Types for the player analytics system
-export interface PlayerAnalyticsConfig {
-  baseUrl: string;
-  apiKey: string;
-  tenantId?: string;
-  playerId: string;
-  heartbeatInterval?: number; // seconds, default 10
-  batchSize?: number; // default 10
-  flushInterval?: number; // seconds, default 30
-}
-
-export interface AnalyticsSession {
-  sessionId: string;
-  playerId: string;
-  timestamp: number;
-  customData?: Record<string, any>;
-}
-
-export interface VideoInfo {
-  id: string;
-  title?: string;
-  type: 'video' | 'series' | 'episode' | 'audio' | 'season' | 'live';
-  duration?: number; // seconds
-  isLive?: boolean;
-  metadata?: Record<string, any>;
-}
-
-export interface DeviceData {
-  deviceType: 'mobile' | 'tablet' | 'smart_tv' | 'desktop' | 'tv';
-  model?: string;
-  os?: string;
-  osVersion?: string;
-  appVersion?: string;
-  screen?: { width: number; height: number };
-  connection?: {
-    effectiveType?: string;
-    downlink?: number;
-    rtt?: number;
-    saveData?: boolean;
-  };
-  browser?: string;
-}
-
-export interface PlayerData {
-  playbackRate?: number;
-  muted?: boolean;
-  volume?: number;
-  readyState?: number;
-  networkState?: number;
-}
-
-export interface EngagementData {
-  totalWatchTime?: number; // milliseconds
-  completionPercentage?: number; // 0-100
-  maxWatchedPosition?: number; // seconds
-  seekEvents?: number;
-  qualityChanges?: number;
-  fullscreenToggles?: number;
-  totalBufferingTime?: number; // milliseconds
-}
-
-export interface ErrorData {
-  code?: string;
-  message?: string;
-  type?: string;
-}
-
-export interface AnalyticsEventData {
-  eventType: string;
-  timestamp: number;
-  currentTime?: number; // seconds
-  video?: VideoInfo;
-  device?: DeviceData;
-  location?: {
-    country?: string;
-    region?: string;
-    city?: string;
-    lat?: number;
-    lon?: number;
-  };
-  player?: PlayerData;
-  engagement?: EngagementData;
-  error?: ErrorData;
-}
-
-export interface AnalyticsPayload {
-  session: AnalyticsSession;
-  events: AnalyticsEventData[];
-}
-
-export class PlayerAnalyticsAdapter {
-  private config: PlayerAnalyticsConfig;
-  private currentSession: AnalyticsSession | null = null;
-  private eventQueue: AnalyticsEventData[] = [];
-  private engagementTracker: {
-    totalWatchTime: number;
-    seekEvents: number;
-    qualityChanges: number;
-    fullscreenToggles: number;
-    totalBufferingTime: number;
-    maxWatchedPosition: number;
-    lastPlayTime?: number;
-    bufferingStartTime?: number;
-  } = {
-    totalWatchTime: 0,
-    seekEvents: 0,
-    qualityChanges: 0,
-    fullscreenToggles: 0,
-    totalBufferingTime: 0,
-    maxWatchedPosition: 0
-  };
-  private heartbeatInterval: NodeJS.Timeout | null = null;
-  private flushInterval: NodeJS.Timeout | null = null;
-
-  constructor(config: PlayerAnalyticsConfig) {
-    this.config = {
-      heartbeatInterval: 10,
-      batchSize: 10,
-      flushInterval: 30,
-      ...config
-    };
-  }
-
-  /**
-   * Start a new analytics session
-   */
-  public startSession(videoInfo: {
-    id: string;
-    title?: string;
-    type?: 'video' | 'series' | 'episode' | 'audio' | 'season' | 'live';
-    duration?: number;
-    isLive?: boolean;
-    metadata?: Record<string, any>;
-  }, customData?: Record<string, any>): string {
-    // End current session if active
-    if (this.currentSession) {
-      this.endSession();
-    }
-
-    const sessionId = this.generateSessionId();
-    this.currentSession = {
-      sessionId,
-      playerId: this.config.playerId,
-      timestamp: Date.now(),
-      customData
-    };
-
-    // Reset engagement tracker
-    this.engagementTracker = {
-      totalWatchTime: 0,
-      seekEvents: 0,
-      qualityChanges: 0,
-      fullscreenToggles: 0,
-      totalBufferingTime: 0,
-      maxWatchedPosition: 0
-    };
-
-    // Create session_start event
-    const sessionStartEvent: AnalyticsEventData = {
-      eventType: 'session_start',
-      timestamp: Date.now(),
-      video: {
-        id: videoInfo.id,
-        title: videoInfo.title,
-        type: videoInfo.type || 'video',
-        duration: videoInfo.duration,
-        isLive: videoInfo.isLive,
-        metadata: videoInfo.metadata
-      },
-      device: this.mapDeviceInfo()
-    };
-
-    this.queueEvent(sessionStartEvent);
-    this.startHeartbeat();
-    this.startFlushInterval();
-
-    return sessionId;
-  }
-
-  /**
-   * End the current session
-   */
-  public async endSession(): Promise<void> {
-    if (!this.currentSession) {
-      return;
-    }
-
-    // Stop intervals
-    if (this.heartbeatInterval) {
-      clearInterval(this.heartbeatInterval);
-      this.heartbeatInterval = null;
-    }
-    if (this.flushInterval) {
-      clearInterval(this.flushInterval);
-      this.flushInterval = null;
-    }
-
-    // Create session_end event with final engagement data
-    const sessionEndEvent: AnalyticsEventData = {
-      eventType: 'session_end',
-      timestamp: Date.now(),
-      engagement: { ...this.engagementTracker }
-    };
-
-    this.queueEvent(sessionEndEvent);
-
-    // Flush remaining events
-    await this.flush();
-
-    this.currentSession = null;
-  }
-
-  /**
-   * Track an internal analytics event and convert it to API format
-   */
-  public trackEvent(internalEvent: InternalAnalyticsEvent, playerState?: PlayerState, videoInfo?: any): void {
-    if (!this.currentSession) {
-      console.warn('No active analytics session');
-      return;
-    }
-
-    const apiEvent = this.convertInternalEvent(internalEvent, playerState, videoInfo);
-    if (apiEvent) {
-      this.updateEngagementMetrics(apiEvent, playerState);
-      this.queueEvent(apiEvent);
-    }
-  }
-
-  /**
-   * Track a custom event directly
-   */
-  public trackCustomEvent(eventType: string, data: Partial<AnalyticsEventData> = {}): void {
-    if (!this.currentSession) {
-      console.warn('No active analytics session');
-      return;
-    }
-
-    const event: AnalyticsEventData = {
-      eventType,
-      timestamp: Date.now(),
-      ...data
-    };
-
-    this.queueEvent(event);
-  }
-
-  /**
-   * Manually flush queued events
-   */
-  public async flush(): Promise<void> {
-    if (this.eventQueue.length === 0) {
-      return;
-    }
-
-    const eventsToSend = this.eventQueue.splice(0, this.config.batchSize!);
-    const payload: AnalyticsPayload = {
-      session: this.currentSession!,
-      events: eventsToSend
-    };
-
-    try {
-      await this.sendEvents(payload);
-    } catch (error) {
-      console.error('Failed to send analytics events:', error);
-      // Re-queue events for retry (simple strategy)
-      this.eventQueue.unshift(...eventsToSend);
-    }
-  }
-
-  /**
-   * Get current session info
-   */
-  public getCurrentSession(): AnalyticsSession | null {
-    return this.currentSession;
-  }
-
-  /**
-   * Get engagement metrics
-   */
-  public getEngagementMetrics(): EngagementData {
-    return { ...this.engagementTracker };
-  }
-
-  /**
-   * Destroy the adapter and cleanup
-   */
-  public destroy(): void {
-    if (this.currentSession) {
-      this.endSession();
-    }
-  }
-
-  // Private methods
-
-  private convertInternalEvent(
-    internalEvent: InternalAnalyticsEvent, 
-    playerState?: PlayerState,
-    videoInfo?: any
-  ): AnalyticsEventData | null {
-    const eventTypeMap: Record<string, string> = {
-      'play': 'play',
-      'pause': 'pause',
-      'ended': 'ended',
-      'seeking': 'seeking',
-      'seeked': 'seeked',
-      'waiting': 'waiting',
-      'stalled': 'stalled',
-      'buffering': 'waiting',
-      'rebuffering': 'stalled',
-      'qualitychange': 'quality_change',
-      'volumechange': 'volume_change',
-      'fullscreenchange': 'fullscreen_change',
-      'error': 'error',
-      'timeupdate': 'heartbeat',
-      'chapterstart': 'custom_chapter_start',
-      'chapterend': 'custom_chapter_end',
-      'chapterskip': 'custom_chapter_skip'
-    };
-
-    const mappedEventType = eventTypeMap[internalEvent.eventType];
-    if (!mappedEventType) {
-      // Use custom_ prefix for unmapped events
-      return {
-        eventType: `custom_${internalEvent.eventType}`,
-        timestamp: internalEvent.timestamp,
-        currentTime: internalEvent.currentTime
-      };
-    }
-
-    const apiEvent: AnalyticsEventData = {
-      eventType: mappedEventType,
-      timestamp: internalEvent.timestamp,
-      currentTime: internalEvent.currentTime
-    };
-
-    // Add video info if available
-    if (videoInfo) {
-      apiEvent.video = {
-        id: videoInfo.id || internalEvent.videoId,
-        title: videoInfo.title,
-        type: videoInfo.type || 'video',
-        duration: videoInfo.duration,
-        isLive: videoInfo.isLive
-      };
-    }
-
-    // Add player state if available
-    if (playerState) {
-      apiEvent.player = {
-        playbackRate: playerState.playbackRate,
-        muted: playerState.muted,
-        volume: playerState.volume,
-        readyState: playerState.readyState,
-        networkState: playerState.networkState
-      };
-    }
-
-    // Add device info
-    apiEvent.device = this.mapDeviceInfo();
-
-    // Add specific event data
-    if (internalEvent.eventType === 'error') {
-      const errorEvent = internalEvent as any;
-      apiEvent.error = {
-        code: errorEvent.errorCode,
-        message: errorEvent.errorMessage,
-        type: errorEvent.errorType
-      };
-    }
-
-    return apiEvent;
-  }
-
-  private mapDeviceInfo(): DeviceData {
-    const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent.toLowerCase() : '';
-    
-    let deviceType: DeviceData['deviceType'] = 'desktop';
-    if (userAgent.includes('mobile')) deviceType = 'mobile';
-    else if (userAgent.includes('tablet') || userAgent.includes('ipad')) deviceType = 'tablet';
-    else if (userAgent.includes('smart-tv') || userAgent.includes('tv')) deviceType = 'smart_tv';
-
-    let os = 'Unknown';
-    let osVersion = '';
-    
-    if (userAgent.includes('windows')) {
-      os = 'Windows';
-      const match = userAgent.match(/windows nt ([\d.]+)/);
-      osVersion = match ? match[1] : '';
-    } else if (userAgent.includes('mac')) {
-      os = 'macOS';
-      const match = userAgent.match(/mac os x ([\d_]+)/);
-      osVersion = match ? match[1].replace(/_/g, '.') : '';
-    } else if (userAgent.includes('linux')) {
-      os = 'Linux';
-    } else if (userAgent.includes('android')) {
-      os = 'Android';
-      const match = userAgent.match(/android ([\d.]+)/);
-      osVersion = match ? match[1] : '';
-    } else if (userAgent.includes('ios') || userAgent.includes('iphone') || userAgent.includes('ipad')) {
-      os = 'iOS';
-      const match = userAgent.match(/os ([\d_]+)/);
-      osVersion = match ? match[1].replace(/_/g, '.') : '';
-    }
-
-    const device: DeviceData = {
-      deviceType,
-      os,
-      osVersion: osVersion || undefined,
-      browser: this.getBrowserName(userAgent)
-    };
-
-    // Add screen info if available
-    if (typeof window !== 'undefined' && window.screen) {
-      device.screen = {
-        width: window.screen.width,
-        height: window.screen.height
-      };
-    }
-
-    // Add connection info if available
-    if (typeof navigator !== 'undefined' && 'connection' in navigator) {
-      const connection = (navigator as any).connection;
-      if (connection) {
-        device.connection = {
-          effectiveType: connection.effectiveType,
-          downlink: connection.downlink,
-          rtt: connection.rtt,
-          saveData: connection.saveData
-        };
-      }
-    }
-
-    return device;
-  }
-
-  private getBrowserName(userAgent: string): string {
-    if (userAgent.includes('edg/')) return 'Edge';
-    if (userAgent.includes('chrome/')) return 'Chrome';
-    if (userAgent.includes('firefox/')) return 'Firefox';
-    if (userAgent.includes('safari/') && !userAgent.includes('chrome')) return 'Safari';
-    if (userAgent.includes('opera/')) return 'Opera';
-    return 'Unknown';
-  }
-
-  private updateEngagementMetrics(event: AnalyticsEventData, playerState?: PlayerState): void {
-    const now = Date.now();
-
-    switch (event.eventType) {
-      case 'play':
-        this.engagementTracker.lastPlayTime = now;
-        break;
-
-      case 'pause':
-        if (this.engagementTracker.lastPlayTime) {
-          this.engagementTracker.totalWatchTime += now - this.engagementTracker.lastPlayTime;
-          this.engagementTracker.lastPlayTime = undefined;
-        }
-        break;
-
-      case 'seeking':
-        this.engagementTracker.seekEvents++;
-        break;
-
-      case 'quality_change':
-        this.engagementTracker.qualityChanges++;
-        break;
-
-      case 'fullscreen_change':
-        this.engagementTracker.fullscreenToggles++;
-        break;
-
-      case 'waiting':
-        this.engagementTracker.bufferingStartTime = now;
-        break;
-
-      case 'stalled':
-        if (this.engagementTracker.bufferingStartTime) {
-          this.engagementTracker.totalBufferingTime += now - this.engagementTracker.bufferingStartTime;
-          this.engagementTracker.bufferingStartTime = undefined;
-        }
-        break;
-
-      case 'heartbeat':
-        if (this.engagementTracker.lastPlayTime) {
-          this.engagementTracker.totalWatchTime += now - this.engagementTracker.lastPlayTime;
-          this.engagementTracker.lastPlayTime = now;
-        }
-        if (event.currentTime && event.currentTime > this.engagementTracker.maxWatchedPosition) {
-          this.engagementTracker.maxWatchedPosition = event.currentTime;
-        }
-        break;
-    }
-  }
-
-  private queueEvent(event: AnalyticsEventData): void {
-    this.eventQueue.push(event);
-
-    // Auto-flush if batch size reached
-    if (this.eventQueue.length >= this.config.batchSize!) {
-      this.flush().catch(error => {
-        console.error('Auto-flush failed:', error);
-      });
-    }
-  }
-
-  private async sendEvents(payload: AnalyticsPayload): Promise<void> {
-    const response = await fetch(`${this.config.baseUrl}/analytics/player/ingest`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-API-Key': this.config.apiKey,
-        ...(this.config.tenantId && { 'X-Tenant-ID': this.config.tenantId })
-      },
-      body: JSON.stringify(payload)
-    });
-
-    if (!response.ok) {
-      throw new Error(`Analytics API error: ${response.status} ${response.statusText}`);
-    }
-  }
-
-  private startHeartbeat(): void {
-    if (this.heartbeatInterval) {
-      clearInterval(this.heartbeatInterval);
-    }
-
-    this.heartbeatInterval = setInterval(() => {
-      if (this.currentSession) {
-        const heartbeatEvent: AnalyticsEventData = {
-          eventType: 'heartbeat',
-          timestamp: Date.now(),
-          device: this.mapDeviceInfo()
-        };
-        this.queueEvent(heartbeatEvent);
-      }
-    }, this.config.heartbeatInterval! * 1000);
-  }
-
-  private startFlushInterval(): void {
-    if (this.flushInterval) {
-      clearInterval(this.flushInterval);
-    }
-
-    this.flushInterval = setInterval(() => {
-      this.flush().catch(error => {
-        console.error('Scheduled flush failed:', error);
-      });
-    }, this.config.flushInterval! * 1000);
-  }
-
-  private generateSessionId(): string {
-    return `sess_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-  }
-}
-
-// Factory function
-export function createPlayerAnalyticsAdapter(config: PlayerAnalyticsConfig): PlayerAnalyticsAdapter {
-  return new PlayerAnalyticsAdapter(config);
-}