unified-video-framework 1.4.215 → 1.4.216

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

@@ -0,0 +1,403 @@
+# 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

@@ -0,0 +1,17 @@
+/**
+ * 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';