stormcloud-video-player 0.5.5 → 0.5.7

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, custom VAST ad serving, and optional Google IMA SDK integration for seamless 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 Prebid Server integration for server-side header bidding and VAST ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
@@ -147,7 +147,7 @@ Include the single script tag and access everything from `window.StormcloudVP`:
 </script>
 ```
 
-All ad player types (`ima`, `hls`, `prebid`) and 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.
+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.
 
 ## 🏗️ Professional Architecture
 
@@ -170,7 +170,7 @@ StormcloudPlayer (Main Component)
 - **Purpose**: Handles HLS (.m3u8) streams with advanced features
 - **Features**:
   - SCTE-35 ad marker detection and processing
-  - Google IMA SDK integration for VAST/VPAID ads
+  - Prebid Server integration for VAST ad playback
   - Live stream support with low-latency mode
   - Drift correction for live timing
   - Manifest-based and ID3 ad markers
@@ -274,10 +274,9 @@ interface StormcloudPlayerProps {
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
   // Ad player configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (HLS player + AdStorm VAST endpoint) or 'default' (IMA SDK + /ads/web endpoint) (default: 'default')
-  vastTagUrl?: string; // Custom VAST URL (used in default mode if provided; when not provided, uses /ads/web endpoint)
-  adPlayerType?: 'ima' | 'hls' | 'prebid'; // Manual override for ad player type (auto-determined by vastMode if not specified)
-  prebid?: PrebidConfig; // Prebid Server configuration (required when adPlayerType is 'prebid')
+  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;
@@ -362,10 +361,9 @@ interface StormcloudVideoPlayerConfig {
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
   // Ad configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (uses HLS player + AdStorm VAST endpoint) or 'default' (uses Google IMA SDK + /ads/web endpoint) (default: 'default')
-  vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided; when not provided, defaults to /ads/web endpoint)
-  adPlayerType?: 'ima' | 'hls' | 'prebid'; // Manual override for ad player type (auto-determined by vastMode if not specified)
-  prebid?: PrebidConfig; // Prebid Server configuration (required when adPlayerType is 'prebid')
+  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
@@ -448,7 +446,7 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 Automatically uses HLS ad player (`adPlayerType: 'hls'`)
+- 🎯 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
@@ -462,7 +460,7 @@ const player = new StormcloudVideoPlayer({
 4. HLS ad player loads and plays the ad segments
 
 **Benefits:**
-- ✅ Zero external dependencies (no Google IMA SDK)
+- ✅ Zero external ad SDK dependencies (Prebid Server only)
 - ✅ Full control over ad serving
 - ✅ Native HLS playback (same format as content)
 - ✅ Better performance and reliability
@@ -471,7 +469,7 @@ const player = new StormcloudVideoPlayer({
 
 #### 2. **Default Mode**
 
-Uses Google IMA SDK for traditional ad serving:
+Ad playback uses Prebid Server for VAST ads:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
@@ -479,7 +477,7 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
 
-  // Default mode - uses Google IMA SDK automatically
+  // Uses Prebid Controller for ad playback
   vastMode: 'default', // or omit this property entirely
   vastTagUrl: 'https://your-vast-server.com/vast.xml', // optional
 
@@ -488,20 +486,20 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 Automatically uses Google IMA SDK (`adPlayerType: 'ima'`)
+- 🎯 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 JSON response with IMA payload: `{ response: { ima: { "publisherdesk.ima": { payload: "VAST_URL" } } } }`
+     - Returns VAST URLs from your ad backend
      - Extracts VAST tag URL from the `payload` field
-- 📊 Standard VAST/VPAID ad serving through Google IMA SDK
+- 📊 VAST ad serving through Prebid Server
 
 **API Flow:**
 1. Player calls `/ads/web` endpoint with Bearer token (if no `vastTagUrl` provided)
-2. Backend returns JSON with IMA configuration
+2. Backend or Prebid Server provides VAST URLs
 3. Player extracts VAST tag URL from `response.ima["publisherdesk.ima"].payload`
-4. Google IMA SDK loads and plays the VAST ad
+4. Prebid Controller loads and plays the VAST ad
 
 **Benefits:**
 - ✅ Industry-standard ad serving
@@ -522,7 +520,7 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
 
-  adPlayerType: 'prebid',
+  prebid: { /* PrebidConfig */ },
   prebid: {
     enabled: true,
     serverUrl: "https://prebid-server.example.com",
@@ -586,7 +584,6 @@ await player.load();
     muted: true,
     licenseKey: "your-license-key",
 
-    adPlayerType: "prebid",
     prebid: {
       enabled: true,
       serverUrl: "https://prebid-server.example.com",
@@ -819,17 +816,13 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
 
   vastMode: 'default',
-  adPlayerType: 'hls', // Manual override to use HLS player with default mode
-  vastTagUrl: 'https://your-backend.com/vast', // Will use this URL directly
+  vastTagUrl: 'https://your-backend.com/vast', // Optional custom VAST URL
 
   debugAdTiming: true,
 });
 ```
 
-**Note:** When `adPlayerType` is manually set, the `vastMode` property still determines which backend endpoint is called:
-- `vastMode: 'adstorm'` → Always calls `/vast/{licenseKey}` endpoint
-- `vastMode: 'default'` → Calls `/ads/web` endpoint (unless `vastTagUrl` is provided)
-- `adPlayerType: 'prebid'` → Bypasses `vastMode` entirely; VAST URLs are sourced from Prebid Server auctions (requires `prebid` config)
+**Note:** The player uses Prebid Controller for ad playback. Provide `prebid` config for Prebid Server auctions.
 
 ### SCTE-35 Support
 
@@ -1003,7 +996,7 @@ Authenticated requests are sent to:
   
 - **Default Mode** (`vastMode: 'default'`):
   - Ad configuration: `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web` (requires `Authorization: Bearer {licenseKey}` header)
-  - Returns JSON with IMA payload containing VAST tag URL
+  - Returns VAST tag URL or Prebid Server provides creatives
 
 - **Player Tracking** (both modes):
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
@@ -1173,8 +1166,6 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   ├── ima.ts                         # Google IMA integration
-│   ├── hlsAdPlayer.ts                 # HLS ad player (AdStorm mode)
 │   ├── prebid.ts                      # Prebid Server auction manager
 │   ├── prebidController.ts            # Prebid ad controller (VAST playback + tracking)
 │   └── vastParser.ts                  # VAST XML parser
@@ -1297,7 +1288,7 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.5
 
-- **Prebid Server Integration**: New `adPlayerType: 'prebid'` mode for server-side header bidding via Prebid Server (OpenRTB 2.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
@@ -1329,17 +1320,14 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.3
 
-- 🎬 **Custom HLS Ad Player**: Native HLS ad playback with custom VAST service
-- 🎯 **Flexible Ad Integration**: Choose between custom HLS or Google IMA SDK
+- 🎬 **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
-- ⚡ **Better Performance**: Native HLS playback for ads (same format as content)
+- ⚡ **Better Performance**: Native VAST playback for ads
 - 🔧 **Custom VAST URLs**: Point to your own ad serving backend
-- 🔄 **Backward Compatible**: Existing Google IMA integration still works
-- 📦 **Zero Dependencies**: No external ad SDKs required (when using HLS ad player)
+- 📦 **Zero Dependencies**: No external ad SDKs (Prebid Server only)
 - 🎨 **Seamless Playback**: Same player for content and ads
-- 🔀 **VAST Mode System**: `vastMode` property automatically configures endpoints and ad players
-  - `vastMode: 'adstorm'` → Uses `/vast/{licenseKey}` endpoint with HLS ad player
-  - `vastMode: 'default'` → Uses `/ads/web` endpoint with Google IMA SDK
+- 🔀 **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