unified-video-framework 1.4.217 → 1.4.219

package/packages/web/src/ads/README.md

@@ -1,403 +0,0 @@
-# Google Ads Integration for Unified Video Framework
-
-Comprehensive ads support with Google IMA SDK integration and custom ad formats.
-
-## Features
-
-### Google Standard Ads
-- ✅ Skippable In-Stream (TrueView)
-- ✅ Non-Skippable In-Stream
-- ✅ Bumper Ads (6-second)
-- ✅ Responsive Display Ads
-- ✅ Masthead Ads
-
-### Custom Ad Formats
-- ✅ Pause Overlay Ads (YouTube-style split-screen)
-- ✅ Overlay Banner Ads
-- ✅ Interactive Ads (hotspots, CTA buttons)
-
-### Ad Placements
-- ✅ Preroll (before content)
-- ✅ Midroll (during content at specified times)
-- ✅ Postroll (after content)
-- ✅ Pause Ads (when user pauses)
-- ✅ Overlay Ads (non-intrusive banners)
-
-## Installation
-
-The ads module is included in the `@unified-video-framework/web` package.
-
-```bash
-npm install unified-video-framework
-```
-
-## Quick Start
-
-### Basic Setup with Google IMA
-
-```typescript
-import { AdsManager } from 'unified-video-framework/web';
-
-// Create ad container in your HTML
-<div id="player-container">
-  <div id="ad-container"></div>
-  <video id="main-video" controls></video>
-</div>
-
-// Initialize ads
-const adsManager = new AdsManager({
-  adsEnabled: true,
-  adContainer: '#ad-container',
-  videoElement: '#main-video',
-  preroll: true,
-  postroll: true,
-  debug: true,
-});
-
-// Listen to ad events
-adsManager.on('adStarted', (event) => {
-  console.log('Ad started:', event.ad.metadata.title);
-});
-
-adsManager.on('adCompleted', (event) => {
-  console.log('Ad completed:', event.ad.metadata.title);
-});
-```
-
-### With Backend API Integration
-
-```typescript
-const adsManager = new AdsManager({
-  adsEnabled: true,
-  adContainer: '#ad-container',
-  videoElement: '#main-video',
-  
-  // Backend API for ad configuration
-  apiEndpoint: 'https://your-backend.com/api/ads',
-  
-  // Ad breaks
-  preroll: true,
-  midroll: {
-    enabled: true,
-    interval: 300, // Every 5 minutes
-  },
-  postroll: true,
-  
-  // Privacy
-  gdprConsent: true,
-  coppa: false,
-  
-  // Callbacks
-  onAdStarted: (ad) => {
-    console.log('Ad started:', ad.metadata.title);
-  },
-  onAdError: (error) => {
-    console.error('Ad error:', error.message);
-  },
-});
-```
-
-### Using VAST/VMAP URLs
-
-```typescript
-const adsManager = new AdsManager({
-  adsEnabled: true,
-  adContainer: '#ad-container',
-  videoElement: '#main-video',
-  
-  // Direct VAST URL for preroll
-  preroll: {
-    id: 'preroll-1',
-    type: 'preroll',
-    position: 'start',
-    ads: [{
-      id: 'ad-1',
-      type: 'SKIPPABLE_IN_STREAM',
-      vastUrl: 'https://pubads.g.doubleclick.net/gampad/ads?...',
-      metadata: {
-        id: 'ad-1',
-        title: 'Advertisement',
-        duration: 30,
-        skippable: true,
-        skipOffset: 5,
-      },
-    }],
-  },
-});
-```
-
-### Custom Pause Ads
-
-```typescript
-const adsManager = new AdsManager({
-  adsEnabled: true,
-  adContainer: '#ad-container',
-  videoElement: '#main-video',
-  
-  // Pause overlay ads (YouTube-style)
-  pauseAds: {
-    type: 'PAUSE_OVERLAY',
-    layout: {
-      type: 'split_screen',
-      contentSide: 'left',
-      adSide: 'right',
-      splitRatio: '60:40',
-    },
-    closeButton: {
-      enabled: true,
-      position: 'top-right',
-      style: '×',
-      delay: 0,
-    },
-    resumeButton: {
-      enabled: true,
-      text: 'Resume Video',
-      position: 'center',
-    },
-    triggers: {
-      minPauseDuration: 3, // Show after 3 seconds of pause
-      maxDisplayTime: 30, // Hide after 30 seconds
-      frequency: 'once_per_session',
-    },
-  },
-});
-```
-
-### Overlay Ads
-
-```typescript
-const adsManager = new AdsManager({
-  adsEnabled: true,
-  adContainer: '#ad-container',
-  videoElement: '#main-video',
-  
-  overlayAds: {
-    type: 'OVERLAY_AD',
-    positions: ['bottom', 'top-right'],
-    sizes: ['20%', '25%', '30%'],
-    closeButton: {
-      enabled: true,
-      position: 'top-right',
-      style: '×',
-      delay: 5,
-    },
-    animation: {
-      entrance: 'slideUp',
-      exit: 'fadeOut',
-    },
-  },
-});
-```
-
-## Event Handling
-
-### Available Events
-
-```typescript
-// Ad Break Events
-adsManager.on('adBreakReady', (event) => {
-  console.log('Ad break ready:', event.adBreak);
-});
-
-adsManager.on('adBreakStarted', (event) => {
-  console.log('Ad break started:', event.adBreak);
-});
-
-adsManager.on('adBreakCompleted', (event) => {
-  console.log('Ad break completed:', event.adBreak);
-});
-
-// Individual Ad Events
-adsManager.on('loaded', (event) => {
-  console.log('Ad loaded:', event.ad);
-});
-
-adsManager.on('started', (event) => {
-  console.log('Ad started:', event.ad);
-});
-
-adsManager.on('firstQuartile', (event) => {
-  console.log('Ad 25% complete');
-});
-
-adsManager.on('midpoint', (event) => {
-  console.log('Ad 50% complete');
-});
-
-adsManager.on('thirdQuartile', (event) => {
-  console.log('Ad 75% complete');
-});
-
-adsManager.on('completed', (event) => {
-  console.log('Ad completed:', event.ad);
-});
-
-adsManager.on('skipped', (event) => {
-  console.log('Ad skipped:', event.ad);
-});
-
-adsManager.on('clicked', (event) => {
-  console.log('Ad clicked:', event.ad);
-});
-
-// Error Events
-adsManager.on('adError', (event) => {
-  console.error('Ad error:', event.customData);
-});
-
-// All Ads Complete
-adsManager.on('allAdsCompleted', () => {
-  console.log('All ads completed');
-});
-```
-
-## Backend API Integration
-
-### GET /api/ads/config
-
-Request ad configuration from your backend:
-
-```typescript
-// Query Parameters
-{
-  contentId: 'video_123',
-  userId: 'user_456',
-  sessionId: 'session_abc',
-  placement: 'preroll|midroll|postroll|pause|overlay',
-  position: 300, // for midroll, time in seconds
-  width: 1920,
-  height: 1080,
-  deviceType: 'desktop|mobile|tablet|tv',
-  browser: 'Chrome/91.0',
-  language: 'en-US',
-  referrer: 'https://example.com',
-  gdprConsent: true,
-  coppa: false,
-}
-```
-
-Response format:
-
-```json
-{
-  "status": "success",
-  "data": {
-    "adBreaks": [
-      {
-        "id": "preroll-1",
-        "type": "preroll",
-        "position": "start",
-        "ads": [
-          {
-            "id": "ad-123",
-            "type": "SKIPPABLE_IN_STREAM",
-            "vastUrl": "https://...",
-            "metadata": {
-              "id": "ad-123",
-              "title": "Advertisement",
-              "duration": 30,
-              "skippable": true,
-              "skipOffset": 5
-            }
-          }
-        ]
-      }
-    ],
-    "companionAds": [],
-    "settings": {
-      "maxAdsPerBreak": 3,
-      "maxTotalAds": 10
-    }
-  }
-}
-```
-
-### POST /api/ads/track/event
-
-Track ad events to your backend:
-
-```json
-{
-  "eventType": "started|firstQuartile|midpoint|thirdQuartile|completed|skipped|clicked",
-  "adId": "ad-123",
-  "sessionId": "session_abc",
-  "contentId": "video_123",
-  "userId": "user_456",
-  "timestamp": "2024-12-19T10:30:00Z",
-  "playerTime": 45.5,
-  "customData": {}
-}
-```
-
-## Advanced Usage
-
-### Manual Ad Control
-
-```typescript
-// Request specific ad breaks manually
-adsManager.requestPrerollAds();
-adsManager.requestMidrollAds(300); // at 5 minutes
-adsManager.requestPostrollAds();
-
-// Control ad playback
-adsManager.pause();
-adsManager.resume();
-adsManager.skip();
-
-// Resize ads (e.g., on window resize)
-adsManager.resize(1920, 1080);
-
-// Clean up
-adsManager.destroy();
-```
-
-### TypeScript Types
-
-```typescript
-import type {
-  AdsManagerConfig,
-  Ad,
-  AdBreak,
-  AdEvent,
-  AdError,
-  AdType,
-  AdPlacement,
-  AdEventType,
-} from 'unified-video-framework/web';
-```
-
-## Browser Support
-
-- Chrome 90+
-- Firefox 88+
-- Safari 14+
-- Edge 90+
-- Mobile browsers (iOS Safari, Chrome Mobile)
-
-## Google IMA SDK
-
-The ads manager automatically loads the Google IMA SDK v3. No manual script inclusion needed.
-
-- SDK URL: `https://imasdk.googleapis.com/js/sdkloader/ima3.js`
-- Documentation: https://developers.google.com/interactive-media-ads
-
-## Best Practices
-
-1. **Always provide fallbacks**: Handle ad errors gracefully
-2. **Respect user privacy**: Implement GDPR/COPPA compliance
-3. **Track events**: Monitor ad performance with backend tracking
-4. **Optimize for mobile**: Test on mobile devices for UX
-5. **Test thoroughly**: Use IMA Video Suite for testing: https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/vastinspector
-
-## Examples
-
-See the `/examples` directory for complete implementation examples:
-- Basic Google IMA ads
-- Backend API integration
-- Pause overlay ads
-- Interactive ads
-- React integration
-
-## License
-
-MIT License - Flicknexs Team

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

@@ -1,17 +0,0 @@
-/**
- * Ads Module - Google Ads Integration for Unified Video Framework
- * Author: Flicknexs Team
- */
-
-export * from './types';
-export { AdsManager } from './AdsManager';
-
-// Re-export commonly used types for convenience
-export type {
-  AdsManagerConfig,
-  Ad,
-  AdBreak,
-  AdEvent,
-  AdError,
-  AdMetadata,
-} from './types';