unified-video-framework 1.4.215 → 1.4.217

package/packages/web/src/ads/types.ts

@@ -0,0 +1,442 @@
+/**
+ * Comprehensive Ad Type Definitions for Unified Video Framework
+ * Based on google-ads-frontend-spec.json
+ * Author: Flicknexs Team
+ */
+
+// ============================================================================
+// ENUMS
+// ============================================================================
+
+export enum AdType {
+  // Google Standard Video Ads
+  SKIPPABLE_IN_STREAM = 'SKIPPABLE_IN_STREAM',
+  NON_SKIPPABLE_IN_STREAM = 'NON_SKIPPABLE_IN_STREAM',
+  BUMPER_ADS = 'BUMPER_ADS',
+  
+  // Google Display Ads
+  RESPONSIVE_DISPLAY = 'RESPONSIVE_DISPLAY',
+  MASTHEAD = 'MASTHEAD',
+  
+  // Custom Ads
+  PAUSE_OVERLAY = 'PAUSE_OVERLAY',
+  OVERLAY_AD = 'OVERLAY_AD',
+  INTERACTIVE_AD = 'INTERACTIVE_AD',
+}
+
+export enum AdPlacement {
+  PREROLL = 'preroll',
+  MIDROLL = 'midroll',
+  POSTROLL = 'postroll',
+  PAUSE = 'pause',
+  OVERLAY = 'overlay',
+}
+
+export enum AdEventType {
+  // Standard Events
+  IMPRESSION = 'impression',
+  LOADED = 'loaded',
+  STARTED = 'started',
+  FIRST_QUARTILE = 'firstQuartile',
+  MIDPOINT = 'midpoint',
+  THIRD_QUARTILE = 'thirdQuartile',
+  COMPLETED = 'completed',
+  SKIPPED = 'skipped',
+  CLICKED = 'clicked',
+  CLOSED = 'closed',
+  PAUSED = 'paused',
+  RESUMED = 'resumed',
+  MUTED = 'muted',
+  UNMUTED = 'unmuted',
+  FULLSCREEN = 'fullscreen',
+  EXIT_FULLSCREEN = 'exitFullscreen',
+  EXPANDED = 'expanded',
+  COLLAPSED = 'collapsed',
+  
+  // Custom Events
+  USER_ENGAGEMENT = 'userEngagement',
+  BRAND_INTERACTION = 'brandInteraction',
+  SOCIAL_SHARE = 'socialShare',
+  PRODUCT_VIEW = 'productView',
+  ADD_TO_CART = 'addToCart',
+  PURCHASE = 'purchase',
+  SIGN_UP = 'signUp',
+  DOWNLOAD_APP = 'downloadApp',
+  VISIT_STORE = 'visitStore',
+  
+  // Error Events
+  AD_ERROR = 'adError',
+  AD_BREAK_READY = 'adBreakReady',
+  AD_BREAK_STARTED = 'adBreakStarted',
+  AD_BREAK_COMPLETED = 'adBreakCompleted',
+  ALL_ADS_COMPLETED = 'allAdsCompleted',
+}
+
+// ============================================================================
+// UI COMPONENT INTERFACES
+// ============================================================================
+
+export interface SkipButtonConfig {
+  enabled: boolean;
+  skipOffset: number; // seconds
+  text: string;
+  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  style: 'button' | 'text' | 'custom';
+  customStyle?: React.CSSProperties;
+}
+
+export interface CountdownConfig {
+  enabled: boolean;
+  format: string; // e.g., "Ad: {time}" or "{time}"
+  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
+export interface ProgressBarConfig {
+  enabled: boolean;
+  color: string;
+  height?: number;
+  position?: 'top' | 'bottom';
+}
+
+export interface AdLabelConfig {
+  enabled: boolean;
+  text: string;
+  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  fontSize?: string;
+}
+
+export interface CloseButtonConfig {
+  enabled: boolean;
+  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  style: string; // e.g., "×"
+  delay?: number; // seconds before showing
+}
+
+// ============================================================================
+// AD TYPE CONFIGURATIONS
+// ============================================================================
+
+export interface SkippableInStreamAdConfig {
+  type: AdType.SKIPPABLE_IN_STREAM;
+  skipButton: SkipButtonConfig;
+  countdown: CountdownConfig;
+  progressBar: ProgressBarConfig;
+  controls: {
+    pauseOnClick: boolean;
+    volumeControl: boolean;
+    seekControl: boolean;
+  };
+}
+
+export interface NonSkippableInStreamAdConfig {
+  type: AdType.NON_SKIPPABLE_IN_STREAM;
+  countdown: CountdownConfig;
+  progressBar: ProgressBarConfig;
+  adLabel: AdLabelConfig;
+  controls: {
+    pauseOnClick: boolean;
+    volumeControl: boolean;
+    seekControl: boolean;
+  };
+}
+
+export interface BumperAdConfig {
+  type: AdType.BUMPER_ADS;
+  countdown: CountdownConfig;
+  adLabel: AdLabelConfig;
+  controls: {
+    pauseOnClick: boolean;
+    volumeControl: boolean;
+    seekControl: boolean;
+  };
+}
+
+export interface ResponsiveDisplayAdConfig {
+  type: AdType.RESPONSIVE_DISPLAY;
+  closeButton: CloseButtonConfig;
+  adLabel: AdLabelConfig;
+  responsive: {
+    breakpoints: {
+      mobile: string;
+      tablet: string;
+      desktop: string;
+    };
+    sizes: {
+      mobile: string[];
+      tablet: string[];
+      desktop: string[];
+    };
+  };
+}
+
+export interface MastheadAdConfig {
+  type: AdType.MASTHEAD;
+  playButton: {
+    enabled: boolean;
+    autoplay: boolean;
+    muted: boolean;
+  };
+  muteButton: {
+    enabled: boolean;
+    position: string;
+  };
+  companionBanners: {
+    enabled: boolean;
+    positions: string[];
+  };
+}
+
+// ============================================================================
+// CUSTOM AD CONFIGURATIONS
+// ============================================================================
+
+export interface PauseOverlayAdConfig {
+  type: AdType.PAUSE_OVERLAY;
+  layout: {
+    type: 'split_screen' | 'overlay' | 'popup';
+    contentSide?: 'left' | 'right';
+    adSide?: 'left' | 'right';
+    splitRatio?: string; // e.g., "60:40"
+  };
+  closeButton: CloseButtonConfig;
+  resumeButton: {
+    enabled: boolean;
+    text: string;
+    position: string;
+  };
+  triggers: {
+    minPauseDuration: number; // seconds
+    maxDisplayTime: number; // seconds
+    frequency: 'always' | 'once_per_session' | 'once_per_video';
+  };
+}
+
+export interface OverlayAdConfig {
+  type: AdType.OVERLAY_AD;
+  positions: string[];
+  sizes: string[];
+  closeButton: CloseButtonConfig;
+  animation: {
+    entrance: 'slideUp' | 'slideDown' | 'fadeIn' | 'none';
+    exit: 'fadeOut' | 'slideDown' | 'slideUp' | 'none';
+  };
+}
+
+export interface InteractiveAdConfig {
+  type: AdType.INTERACTIVE_AD;
+  hotspots: {
+    enabled: boolean;
+    style: 'pulsing_dot' | 'icon' | 'custom';
+    hoverEffect: 'tooltip' | 'expand' | 'highlight';
+  };
+  callToAction: {
+    enabled: boolean;
+    text: string;
+    animation: 'bounce' | 'pulse' | 'shake' | 'none';
+  };
+  progressTracker: {
+    enabled: boolean;
+    showInteractions: boolean;
+  };
+}
+
+// ============================================================================
+// AD BREAK & AD INTERFACES
+// ============================================================================
+
+export interface AdMetadata {
+  id: string;
+  title: string;
+  description?: string;
+  advertiser?: string;
+  duration: number; // seconds
+  skippable: boolean;
+  skipOffset?: number;
+}
+
+export interface TrackingUrls {
+  impression?: string[];
+  start?: string;
+  firstQuartile?: string;
+  midpoint?: string;
+  thirdQuartile?: string;
+  complete?: string;
+  skip?: string;
+  click?: string;
+  close?: string;
+  [key: string]: string | string[] | undefined;
+}
+
+export interface Ad {
+  id: string;
+  type: AdType;
+  vastUrl?: string;
+  vmapUrl?: string;
+  videoUrl?: string;
+  clickUrl?: string;
+  impressionUrls?: string[];
+  trackingUrls?: TrackingUrls;
+  metadata: AdMetadata;
+  targeting?: {
+    demographics?: any;
+    interests?: string[];
+    location?: any;
+    device?: string;
+    browser?: string;
+  };
+  config?: 
+    | SkippableInStreamAdConfig
+    | NonSkippableInStreamAdConfig
+    | BumperAdConfig
+    | ResponsiveDisplayAdConfig
+    | MastheadAdConfig
+    | PauseOverlayAdConfig
+    | OverlayAdConfig
+    | InteractiveAdConfig;
+}
+
+export interface AdBreak {
+  id: string;
+  type: AdPlacement;
+  position: 'start' | 'end' | number | string; // start, end, time in seconds, or percentage
+  ads: Ad[];
+}
+
+export interface CompanionAd {
+  id: string;
+  width: number;
+  height: number;
+  resourceUrl: string;
+  clickUrl?: string;
+  containerId?: string;
+}
+
+// ============================================================================
+// ADS MANAGER CONFIGURATION
+// ============================================================================
+
+export interface AdsManagerConfig {
+  // Google IMA SDK
+  adsEnabled: boolean;
+  adsManagerUrl?: string; // Default: https://imasdk.googleapis.com/js/sdkloader/ima3.js
+  debug?: boolean;
+  
+  // Container Elements
+  adContainer: HTMLElement | string;
+  videoElement: HTMLElement | string;
+  
+  // API Integration
+  apiEndpoint?: string; // Backend API for fetching ads
+  
+  // Ad Breaks
+  preroll?: boolean | AdBreak;
+  midroll?: boolean | AdBreak[] | { enabled: boolean; interval: number };
+  postroll?: boolean | AdBreak;
+  pauseAds?: PauseOverlayAdConfig;
+  overlayAds?: OverlayAdConfig;
+  
+  // Settings
+  maxAdsPerBreak?: number;
+  maxTotalAds?: number;
+  adTimeout?: number; // milliseconds
+  retryOnError?: boolean;
+  maxRetryAttempts?: number;
+  
+  // Privacy
+  gdprConsent?: boolean;
+  coppa?: boolean;
+  
+  // Callbacks
+  onAdBreakReady?: (adBreak: AdBreak) => void;
+  onAdBreakStarted?: (adBreak: AdBreak) => void;
+  onAdBreakCompleted?: (adBreak: AdBreak) => void;
+  onAdStarted?: (ad: Ad) => void;
+  onAdCompleted?: (ad: Ad) => void;
+  onAdSkipped?: (ad: Ad) => void;
+  onAdError?: (error: AdError) => void;
+  onAllAdsCompleted?: () => void;
+}
+
+// ============================================================================
+// AD EVENT INTERFACES
+// ============================================================================
+
+export interface AdEvent {
+  type: AdEventType;
+  ad?: Ad;
+  adBreak?: AdBreak;
+  timestamp: string;
+  playerTime?: number;
+  customData?: any;
+}
+
+export interface AdError {
+  code: number;
+  message: string;
+  ad?: Ad;
+  adBreak?: AdBreak;
+  details?: any;
+}
+
+// ============================================================================
+// API REQUEST/RESPONSE INTERFACES
+// ============================================================================
+
+export interface AdConfigRequest {
+  contentId: string;
+  userId?: string;
+  sessionId?: string;
+  placement: AdPlacement;
+  position?: number | string;
+  width: number;
+  height: number;
+  deviceType?: 'desktop' | 'mobile' | 'tablet' | 'tv';
+  browser?: string;
+  location?: any;
+  language?: string;
+  referrer?: string;
+  gdprConsent?: boolean;
+  coppa?: boolean;
+}
+
+export interface AdConfigResponse {
+  status: 'success' | 'error' | 'no_ads';
+  message?: string;
+  code?: number;
+  data?: {
+    adBreaks: AdBreak[];
+    vastUrl?: string;
+    vmapUrl?: string;
+    companionAds?: CompanionAd[];
+    settings?: {
+      maxAdsPerBreak?: number;
+      maxTotalAds?: number;
+      frequencyCapping?: any;
+    };
+  };
+}
+
+export interface TrackEventRequest {
+  eventType: AdEventType;
+  adId: string;
+  sessionId: string;
+  contentId?: string;
+  userId?: string;
+  timestamp: string;
+  playerTime: number;
+  customData?: any;
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export type AdConfig =
+  | SkippableInStreamAdConfig
+  | NonSkippableInStreamAdConfig
+  | BumperAdConfig
+  | ResponsiveDisplayAdConfig
+  | MastheadAdConfig
+  | PauseOverlayAdConfig
+  | OverlayAdConfig
+  | InteractiveAdConfig;

package/packages/web/src/index.ts

@@ -14,5 +14,8 @@ export { SecureVideoPlayer } from './SecureVideoPlayer';
 // Export EPG (Electronic Program Guide) components
 export * from './react/EPG';
 
+// Export Ads module (Google Ads Integration)
+export * from './ads/index';
+
 // Version
 export const VERSION = '1.0.0';