unified-video-framework 1.4.158 → 1.4.159

package/src/analytics/adapters/PlayerAnalyticsAdapter.ts

@@ -0,0 +1,572 @@
+/**
+ * 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);
+}