stormcloud-video-player 0.2.13 → 0.2.15

package/README.md

@@ -41,6 +41,7 @@ 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) => {
@@ -77,6 +78,7 @@ 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);
       }}
@@ -266,8 +268,9 @@ interface StormcloudPlayerProps {
   adFailsafeTimeoutMs?: number;
 
   // Ad player configuration
-  adPlayerType?: 'ima' | 'hls'; // Choose ad player (default: 'ima')
-  vastTagUrl?: string; // Custom VAST URL for HLS ad player
+  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)
 
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
@@ -351,8 +354,8 @@ interface StormcloudVideoPlayerConfig {
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
 
   // Ad configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (uses HLS player + AdStorm backend) or 'default' (uses Google IMA SDK) (default: 'default')
-  vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided)
+  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)
 
   onVolumeToggle?: () => void; // Callback for volume toggle
@@ -437,8 +440,17 @@ const player = new StormcloudVideoPlayer({
 
 **What happens:**
 - 🎯 Automatically uses HLS ad player (`adPlayerType: 'hls'`)
-- 🔗 VAST endpoint: `https://adstorm.co/api-adstorm-dev/adstorm/vast/${licenseKey}`
+- 🔗 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)
+
+**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
 
 **Benefits:**
 - ✅ Zero external dependencies (no Google IMA SDK)
@@ -446,6 +458,7 @@ const player = new StormcloudVideoPlayer({
 - ✅ 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**
 
@@ -455,6 +468,7 @@ Uses Google IMA SDK for traditional ad serving:
 const player = new StormcloudVideoPlayer({
   videoElement: video,
   src: "https://your-stream.com/playlist.m3u8",
+  licenseKey: "your-license-key",
 
   // Default mode - uses Google IMA SDK automatically
   vastMode: 'default', // or omit this property entirely
@@ -466,14 +480,26 @@ const player = new StormcloudVideoPlayer({
 
 **What happens:**
 - 🎯 Automatically uses Google IMA SDK (`adPlayerType: 'ima'`)
-- 🔗 VAST endpoint: Uses `vastTagUrl` if provided, otherwise `https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
-- 📊 Standard VAST/VPAID ad serving
+- 🔗 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" } } } }`
+     - Extracts VAST tag URL from the `payload` field
+- 📊 Standard VAST/VPAID ad serving through Google IMA SDK
+
+**API Flow:**
+1. Player calls `/ads/web` endpoint with Bearer token (if no `vastTagUrl` provided)
+2. Backend returns JSON with IMA configuration
+3. Player extracts VAST tag URL from `response.ima["publisherdesk.ima"].payload`
+4. Google IMA SDK 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
 
 ### Manual Ad Player Override
 
@@ -486,12 +512,16 @@ const player = new StormcloudVideoPlayer({
 
   vastMode: 'default',
   adPlayerType: 'hls', // Manual override to use HLS player with default mode
-  vastTagUrl: 'https://your-backend.com/vast',
+  vastTagUrl: 'https://your-backend.com/vast', // Will use this URL directly
 
   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)
+
 ### SCTE-35 Support
 
 The HlsPlayer automatically detects and responds to SCTE-35 signals embedded in HLS streams:
@@ -529,6 +559,44 @@ When viewers join during an ad break:
 />
 ```
 
+### Error Handling
+
+The player distinguishes between different types of ad-related issues:
+
+**"No Ads Available" (Warning):**
+- When the VAST response indicates no ads are available (e.g., empty `<MediaFiles>` or `AdTitle: "No Ad Available"`)
+- Logs warnings, not errors
+- Content playback continues normally
+- No error events are emitted
+
+**VAST XML Parsing Errors (Error):**
+- When the VAST XML is malformed or cannot be parsed
+- Logs errors
+- Emits `ad_error` event
+- Content playback continues
+
+**Network/Fetch Errors (Error):**
+- When the VAST endpoint is unreachable or returns an error status
+- Logs errors
+- Emits `ad_error` event
+- Content playback continues
+
+Example with error handling:
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  // ... config
+  vastMode: 'adstorm',
+  debugAdTiming: true, // Enable detailed logging
+});
+
+// Monitor ad events
+player.on('ad_error', (error) => {
+  console.error('Ad error occurred:', error);
+  // Handle error (e.g., show fallback, retry, etc.)
+});
+```
+
 ## 🔐 Authentication
 
 The player supports license key authentication for enhanced features:
@@ -542,9 +610,16 @@ const player = new StormcloudVideoPlayer({
 
 Authenticated requests are sent to:
 
-- Ad configuration: `https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
-- Player tracking: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track`
-- Heartbeat monitoring: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat`
+- **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 JSON with IMA payload containing VAST tag URL
+
+- **Player Tracking** (both modes):
+  - 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)
 
 ## 🔧 Advanced Configuration
 
@@ -805,6 +880,12 @@ Built with ❤️ by the Stormcloud team
 - 🔄 **Backward Compatible**: Existing Google IMA integration still works
 - 📦 **Zero Dependencies**: No external ad SDKs required (when using HLS ad player)
 - 🎨 **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
+- ⚠️ **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
 
 ### What's New in v0.2