stormcloud-video-player 0.6.12 → 0.6.13

package/README.md

@@ -1,6 +1,6 @@
 # Stormcloud Video Player
 
-A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Prebid Server integration for server-side header bidding and VAST ad playback. Now featuring a modern, extensible architecture inspired by react-player.
+A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Google Ad Manager (GAM) VAST ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
@@ -13,7 +13,6 @@ A professional video player with advanced ad integration for web applications. B
 - **Cross-Platform**: Works on desktop, mobile, tablets, and smart TVs
 - **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
-- **Prebid Server Support**: Server-side header bidding via OpenRTB 2.5 with zero client-side SDK
 - **Professional Architecture**: Modular player system with lazy loading
 
 ## 🚀 Quick Start
@@ -42,7 +41,6 @@ function MyVideoApp() {
       showCustomControls={true} // Enable enhanced UI controls
       allowNativeHls={true} // Allow native HLS for better performance
       licenseKey="your_license_key_here"
-      vastMode="adstorm" // Use AdStorm mode with HLS ad player
       style={{ width: "100%", aspectRatio: "16/9" }}
       wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
       onReady={(player) => {
@@ -79,7 +77,6 @@ function MyVideoApp() {
       allowNativeHls={true}
       showCustomControls={true}
       licenseKey="your_license_key_here"
-      vastMode="adstorm" // Use AdStorm mode (or omit for default mode)
       onReady={(player) => {
         console.log("Player is ready!", player);
       }}
@@ -147,7 +144,7 @@ Include the single script tag and access everything from `window.StormcloudVP`:
 </script>
 ```
 
-Prebid utilities (`createPrebidManager`, `createPrebidController`) are available on the `window.StormcloudVP` global. See the [Prebid Mode](#3-prebid-mode-server-side-header-bidding) section for a full CDN example with Prebid Server.
+VAST ad utilities (`createVastManager`, `createVastAdLayer`) are available from the package exports and on the `window.StormcloudVP` global when using the CDN bundle.
 
 ## 🏗️ Professional Architecture
 
@@ -170,7 +167,7 @@ StormcloudPlayer (Main Component)
 - **Purpose**: Handles HLS (.m3u8) streams with advanced features
 - **Features**:
   - SCTE-35 ad marker detection and processing
-  - Prebid Server integration for VAST ad playback
+  - GAM VAST integration for ad playback
   - Live stream support with low-latency mode
   - Drift correction for live timing
   - Manifest-based and ID3 ad markers
@@ -273,11 +270,6 @@ interface StormcloudPlayerProps {
   adFailsafeTimeoutMs?: number;
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
-  // Ad player configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode (default: 'default')
-  vastTagUrl?: string; // Custom VAST URL (if provided)
-  prebid?: PrebidConfig; // Prebid Server configuration for ad auctions
-
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
   onStart?: () => void;
@@ -360,11 +352,6 @@ interface StormcloudVideoPlayerConfig {
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
-  // Ad configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode (default: 'default')
-  vastTagUrl?: string; // Custom VAST tag URL (if provided)
-  prebid?: PrebidConfig; // Prebid Server configuration for ad auctions
-
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
   onControlClick?: () => void; // Callback for control area clicks
@@ -424,269 +411,36 @@ All controls use a consistent high-contrast design:
 
 ## 🎬 Ad Integration (HLS Streams Only)
 
-### VAST Mode Configuration
-
-The player supports two VAST modes that automatically configure the appropriate ad player:
+### GAM VAST Configuration
 
-#### 1. **AdStorm Mode** (Recommended)
-
-Uses AdStorm backend with HLS ad player for optimal performance:
+The player fetches VAST creatives from Google Ad Manager (GAM) and plays them natively during SCTE-35 ad breaks.
 
 ```javascript
 const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
-
-  // AdStorm mode - uses HLS ad player automatically
-  vastMode: 'adstorm',
-
   debugAdTiming: true,
 });
 ```
 
 **What happens:**
-- 🎯 Ad playback via Prebid Controller
-- 🔗 VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}`
-  - License key is passed in the URL path (no authorization header needed)
-  - Returns VAST XML directly with HLS media files
-- 📊 Direct tracking and analytics through AdStorm backend
-- ⚠️ Gracefully handles "no ads available" scenarios (logs warnings, not errors)
+- Fetches VAST XML from a GAM ad tag URL (built-in fallback or license-based backend lookup)
+- Parses VAST and plays MP4/HLS creatives through the internal ad layer
+- Fires VAST tracking events (impression, quartiles, complete, etc.)
+- Aligns ad playback to SCTE-35 CUE-OUT / CUE-IN markers
 
 **API Flow:**
-1. Player calls `/vast/{licenseKey}` endpoint
-2. Backend returns VAST XML with HLS media files
-3. Player parses VAST XML and extracts MediaFile URLs
-4. HLS ad player loads and plays the ad segments
+1. Player initializes `createVastManager` with optional `licenseKey`
+2. If a license key is set, the player may fetch a GAM tag URL from `/ads/web`
+3. Each ad request hits GAM with a unique correlator and receives VAST XML
+4. The ad layer loads and plays the winning creative
 
 **Benefits:**
-- ✅ Zero external ad SDK dependencies (Prebid Server only)
-- ✅ Full control over ad serving
-- ✅ Native HLS playback (same format as content)
-- ✅ Better performance and reliability
-- ✅ Custom targeting and selection
-- ✅ Proper error handling (distinguishes parsing errors from "no ads available")
-
-#### 2. **Default Mode**
-
-Ad playback uses Prebid Server for VAST ads:
-
-```javascript
-const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://your-stream.com/playlist.m3u8",
-  licenseKey: "your-license-key",
-
-  // Uses Prebid Controller for ad playback
-  vastMode: 'default', // or omit this property entirely
-  vastTagUrl: 'https://your-vast-server.com/vast.xml', // optional
-
-  debugAdTiming: true,
-});
-```
-
-**What happens:**
-- 🎯 Ad playback via Prebid Controller
-- 🔗 VAST endpoint resolution:
-  1. If `vastTagUrl` is provided, uses that URL directly
-  2. Otherwise, calls `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
-     - Requires `Authorization: Bearer {licenseKey}` header
-     - Returns VAST URLs from your ad backend
-     - Extracts VAST tag URL from the `payload` field
-- 📊 VAST ad serving through Prebid Server
-
-**API Flow:**
-1. Player calls `/ads/web` endpoint with Bearer token (if no `vastTagUrl` provided)
-2. Backend or Prebid Server provides VAST URLs
-3. Player extracts VAST tag URL from `response.ima["publisherdesk.ima"].payload`
-4. Prebid Controller loads and plays the VAST ad
-
-**Benefits:**
-- ✅ Industry-standard ad serving
-- ✅ Wide format support (VAST, VPAID)
-- ✅ Established ecosystem
-- ✅ Backward compatible with existing VAST tags
-- ✅ Supports both custom VAST URLs and AdStorm backend
-
-#### 3. **Prebid Mode** (Server-Side Header Bidding)
-
-Uses Prebid Server for server-side header bidding auctions. The player sends OpenRTB requests directly to a Prebid Server instance, receives bid responses with VAST creatives, and plays the winning ad — all without any external SDK.
-
-**Vanilla JavaScript:**
-
-```javascript
-const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://your-stream.com/playlist.m3u8",
-  licenseKey: "your-license-key",
-
-  prebid: { /* PrebidConfig */ },
-  prebid: {
-    enabled: true,
-    serverUrl: "https://prebid-server.example.com",
-    timeout: 3000,
-    debug: true,
-    cpmFloor: 0.50,
-    ortbRequest: {
-      id: "my-video-player",
-      imp: [
-        {
-          id: "video-imp-1",
-          video: {
-            w: 640,
-            h: 480,
-            mimes: ["video/mp4", "application/x-mpegURL"],
-            protocols: [2, 5],
-            minduration: 5,
-            maxduration: 60,
-            linearity: 1,
-            playbackmethod: [1, 2],
-          },
-          ext: {
-            prebid: {
-              bidder: {
-                appnexus: { placement_id: 12345 },
-                rubicon: { account_id: 1001, site_id: 2002, zone_id: 3003 },
-              },
-            },
-          },
-        },
-      ],
-      tmax: 3000,
-      site: {
-        domain: "example.com",
-        page: "https://example.com/video-page",
-      },
-    },
-  },
-
-  debugAdTiming: true,
-});
-
-await player.load();
-```
-
-**CDN Usage:**
-
-```html
-<video id="video" style="width:100%;aspect-ratio:16/9"></video>
-
-<script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
-<script>
-  var StormcloudVideoPlayer = window.StormcloudVP.StormcloudVideoPlayer;
-
-  var video = document.getElementById("video");
-
-  var player = new StormcloudVideoPlayer({
-    videoElement: video,
-    src: "https://your-stream.com/playlist.m3u8",
-    autoplay: true,
-    muted: true,
-    licenseKey: "your-license-key",
-
-    prebid: {
-      enabled: true,
-      serverUrl: "https://prebid-server.example.com",
-      timeout: 3000,
-      debug: true,
-      cpmFloor: 0.50,
-      ortbRequest: {
-        id: "my-video-player",
-        imp: [
-          {
-            id: "video-imp-1",
-            video: {
-              w: 640,
-              h: 480,
-              mimes: ["video/mp4", "application/x-mpegURL"],
-              protocols: [2, 5],
-              minduration: 5,
-              maxduration: 60,
-              linearity: 1,
-              playbackmethod: [1, 2],
-            },
-            ext: {
-              prebid: {
-                bidder: {
-                  appnexus: { placement_id: 12345 },
-                },
-              },
-            },
-          },
-        ],
-        tmax: 3000,
-      },
-    },
-
-    debugAdTiming: true,
-  });
-
-  player.load();
-</script>
-```
-
-**What happens:**
-- Sends OpenRTB 2.5 auction requests directly to your Prebid Server
-- Receives bid responses with VAST URLs (cached via Prebid Server) or inline VAST XML
-- Automatically selects the highest-CPM winning bid
-- Enforces CPM floor pricing (bids below the floor are rejected)
-- Plays the winning ad creative natively (MP4 or HLS)
-- Fires all VAST tracking events (impression, quartiles, complete, error, pause/resume, mute/unmute)
-
-**Auction Flow:**
-1. Player builds an OpenRTB request with device/site info auto-populated from the browser
-2. Request is sent to `{serverUrl}/openrtb2/auction` via POST
-3. Prebid Server runs the server-side auction across all configured bidders
-4. Player parses the response, selects the highest-CPM bid
-5. VAST creative (cached URL or inline XML) is loaded and played
-
-**Benefits:**
-- Zero external SDK dependencies (no Google IMA, no Prebid.js client-side library)
-- Full server-side auction — lower client-side resource usage
-- Support for any Prebid Server bidder (AppNexus, Rubicon, Index Exchange, etc.)
-- CPM floor enforcement on the client side
-- Native VAST ad playback with full tracking support
-- Works on all platforms including Smart TVs and legacy browsers
-- Complete OpenRTB 2.5 compliance
-
-### PrebidConfig Reference
-
-```typescript
-interface PrebidConfig {
-  enabled?: boolean;       // Enable/disable prebid (default: true)
-  serverUrl?: string;      // Prebid Server URL (e.g. "https://prebid-server.example.com")
-  ortbRequest: {           // OpenRTB 2.5 request template
-    id: string;            // Request ID (will be made unique per auction)
-    imp: [{                // Impression objects (at least one required)
-      id: string;
-      video?: {
-        w?: number;        // Video width
-        h?: number;        // Video height
-        mimes?: string[];  // Supported MIME types
-        protocols?: number[];
-        minduration?: number;
-        maxduration?: number;
-        linearity?: number;
-        playbackmethod?: number[];
-      };
-      ext?: {
-        prebid?: {
-          bidder: {        // Bidder configurations
-            [bidderName: string]: Record<string, any>;
-          };
-        };
-      };
-    }];
-    tmax?: number;         // Auction timeout in ms (default: 3000)
-    site?: Record<string, any>;   // Auto-populated from window.location if omitted
-    device?: Record<string, any>; // Auto-populated from navigator if omitted
-    ext?: Record<string, any>;
-  };
-  timeout?: number;        // Client-side fetch timeout in ms (default: 3000)
-  debug?: boolean;         // Enable debug logging (default: false)
-  cpmFloor?: number;       // Minimum CPM to accept a bid (default: 0, accepts all)
-}
-```
+- Direct GAM VAST integration (no Prebid.js or OpenRTB SSP)
+- Native MP4/HLS ad playback on CTV and web
+- Optional license-based VAST tag resolution from backend
+- Full VAST tracking support
 
 ### Ad Pod Generation (Multiple Consecutive Ads)
 
@@ -747,8 +501,6 @@ const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-live-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
-  
-  vastMode: 'default',
   debugAdTiming: true, // Enable to see adaptive calculations
 });
 ```
@@ -806,23 +558,20 @@ Final: 3 ads played (perfectly fills 120 seconds)
 - ✅ **Smart**: Improves calculation as more data is gathered (uses average of fetched durations)
 - ✅ **Self-Correcting**: Automatically adjusts if actual ad lengths differ from expectations
 
-### Manual Ad Player Override
+### Manual VAST Tag Override
 
-You can still manually override the ad player type if needed:
+You can customize the VAST tag URL when creating a `VastManager` via `createVastManager({ adstormApiUrl })` if your deployment resolves tags through a backend.
 
 ```javascript
 const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-stream.com/playlist.m3u8",
-
-  vastMode: 'default',
-  vastTagUrl: 'https://your-backend.com/vast', // Optional custom VAST URL
-
+  licenseKey: "your-license-key",
   debugAdTiming: true,
 });
 ```
 
-**Note:** The player uses Prebid Controller for ad playback. Provide `prebid` config for Prebid Server auctions.
+**Note:** The player uses `createVastManager` and `createVastAdLayer` for GAM VAST ad playback.
 
 ### SCTE-35 Support
 
@@ -967,7 +716,6 @@ Example with error handling:
 ```javascript
 const player = new StormcloudVideoPlayer({
   // ... config
-  vastMode: 'adstorm',
   debugAdTiming: true, // Enable detailed logging
 });
 
@@ -991,14 +739,11 @@ const player = new StormcloudVideoPlayer({
 
 Authenticated requests are sent to:
 
-- **AdStorm Mode** (`vastMode: 'adstorm'`):
-  - VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}` (license key in URL path)
-  
-- **Default Mode** (`vastMode: 'default'`):
-  - Ad configuration: `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web` (requires `Authorization: Bearer {licenseKey}` header)
-  - Returns VAST tag URL or Prebid Server provides creatives
+- **VAST tag lookup** (when `licenseKey` is set):
+  - `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web` (requires `Authorization: Bearer {licenseKey}` header)
+  - Returns GAM VAST tag URL from `response.ima["publisherdesk.ima"].payload`
 
-- **Player Tracking** (both modes):
+- **Player Tracking**:
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
   - Heartbeat monitoring: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat` (requires `Authorization: Bearer {licenseKey}` header)
 
@@ -1166,8 +911,8 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   ├── prebid.ts                      # Prebid Server auction manager
-│   ├── prebidController.ts            # Prebid ad controller (VAST playback + tracking)
+│   ├── vastManager.ts                 # GAM VAST tag fetcher
+│   ├── vastAdLayer.ts                 # VAST ad playback layer
 │   └── vastParser.ts                  # VAST XML parser
 ├── utils/
 │   ├── tracking.ts                    # Analytics and tracking
@@ -1288,14 +1033,11 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.5
 
-- **Prebid Server Integration**: Server-side header bidding via Prebid Server (OpenRTB 2.5)
-- **Zero-SDK Ad Auctions**: Run server-side auctions across multiple bidders (AppNexus, Rubicon, Index Exchange, etc.) without any client-side ad SDK
-- **PrebidConfig**: Full OpenRTB 2.5 request configuration with auto-populated device/site fields
-- **CPM Floor Enforcement**: Client-side floor pricing to reject bids below a minimum CPM threshold
-- **Native VAST Playback**: Winning bid creatives (cached VAST URL or inline VAST XML) played natively with full tracking (impression, quartiles, complete, pause/resume, mute/unmute, error)
+- **GAM VAST Integration**: Direct Google Ad Manager VAST tag fetching and native ad playback
+- **Native VAST Playback**: MP4/HLS creatives played with full tracking (impression, quartiles, complete, pause/resume, mute/unmute, error)
 - **Smart Media Selection**: Automatic selection of the best ad media file based on the main stream's current resolution and bitrate
 - **HLS Ad Creatives**: Support for HLS-format ad creatives alongside MP4, with automatic format detection
-- **CDN-Ready**: Full prebid support available via CDN (`window.StormcloudVP.StormcloudVideoPlayer`) with no build step required
+- **CDN-Ready**: Full player available via CDN (`window.StormcloudVP.StormcloudVideoPlayer`) with no build step required
 
 ### What's New in v0.4
 
@@ -1320,14 +1062,11 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.3
 
-- 🎬 **Prebid Ad Controller**: VAST ad playback via Prebid Server
-- 🎯 **Ad Integration**: Prebid Server for server-side header bidding
-- 📊 **Direct Analytics**: Full control over ad tracking and metrics
+- 🎬 **VAST Ad Layer**: GAM VAST ad playback with full tracking
+- 🎯 **Ad Integration**: Direct GAM VAST tag fetching during SCTE-35 breaks
+- 📊 **Direct Analytics**: MQTT-based player tracking and metrics
 - ⚡ **Better Performance**: Native VAST playback for ads
-- 🔧 **Custom VAST URLs**: Point to your own ad serving backend
-- 📦 **Zero Dependencies**: No external ad SDKs (Prebid Server only)
 - 🎨 **Seamless Playback**: Same player for content and ads
-- 🔀 **VAST Mode**: `vastMode` property for endpoint configuration
 - ⚠️ **Improved Error Handling**: Distinguishes between parsing errors and "no ads available" scenarios
   - Logs warnings for "no ads available" (graceful handling)
   - Logs errors for actual parsing/fetch failures