stormcloud-video-player 0.5.0 → 0.5.2

package/README.md

@@ -13,6 +13,7 @@ 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
@@ -126,6 +127,8 @@ await player.load();
 
 ### CDN Usage
 
+Include the single script tag and access everything from `window.StormcloudVP`:
+
 ```html
 <script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
 
@@ -144,6 +147,8 @@ await player.load();
 </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.
+
 ## 🏗️ Professional Architecture
 
 The Stormcloud Video Player now follows a professional, modular architecture similar to react-player:
@@ -271,7 +276,8 @@ interface StormcloudPlayerProps {
   // 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'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  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')
 
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
@@ -358,7 +364,8 @@ interface StormcloudVideoPlayerConfig {
   // 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'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  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')
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -503,6 +510,187 @@ const player = new StormcloudVideoPlayer({
 - ✅ 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",
+
+  adPlayerType: 'prebid',
+  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",
+
+    adPlayerType: "prebid",
+    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)
+}
+```
+
 ### Ad Pod Generation (Multiple Consecutive Ads)
 
 The player automatically generates **ad pods** (multiple ads played consecutively) from a single VAST URL. This works differently for VOD and live streams:
@@ -641,6 +829,7 @@ const player = new StormcloudVideoPlayer({
 **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)
 
 ### SCTE-35 Support
 
@@ -984,7 +1173,11 @@ src/
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   └── ima.ts                         # Google IMA integration
+│   ├── 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
 ├── utils/
 │   ├── tracking.ts                    # Analytics and tracking
 │   └── index.ts                       # Utility functions
@@ -1102,6 +1295,17 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 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)
+- **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)
+- **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
+
 ### What's New in v0.4
 
 - 🚀 **Early Ad Prefetching**: Detects SCTE-35 markers in manifest fragments before playback reaches them, prefetching ads in advance for zero-delay ad starts