No VPAID Support
Adgent SDK explicitly does not support VPAID (Video Player-Ad Interface Definition) executables.Why VPAID is Excluded
VPAID is deliberately excluded for Smart TV platforms due to:Performance Impact
Performance Impact
VPAID requires executing arbitrary JavaScript within the player context, which severely degrades performance on resource-constrained TV hardware.Smart TVs typically have:
- 512MB - 2GB RAM (vs 8GB+ on desktops)
- Slow ARM CPUs (vs x86 desktops)
- Limited GPU acceleration
- Frame drops during playback
- UI freezing and stuttering
- Memory exhaustion crashes
Stability Issues
Stability Issues
Third-party VPAID scripts are a common source of:
- Memory leaks: Especially problematic for long-running TV apps
- Application crashes: TV browsers have less resilient JavaScript engines
- Unpredictable behavior: VPAID code runs with full player access
Security Concerns
Security Concerns
Executing unverified external code poses significant security risks:
- Data exfiltration from TV devices
- Unauthorized network requests
- Injection of malicious code
- Privacy violations (TV viewing data)
Modern Alternatives Exist
Modern Alternatives Exist
The industry has moved towards better solutions:
- VAST 4.x: Enhanced tracking without executable code
- OMID (Open Measurement Interface Definition): Standardized measurement without VPAID
- SIMID: Secure alternative for interactive ads
What Happens to VPAID Ads
The SDK automatically filters out VPAID media files during media selection:- The SDK will fire a
VASTErrorCode.WRAPPER_NO_ADS_VAST_RESPONSE(303) - The
onErrorcallback will be triggered - Playback will not start
Device Compatibility Constraints
Smart TVs, especially older models (2016-2019), have strict hardware limitations.Video Codec Requirements
Recommended: H.264
H.264 (AVC) Main Profile Level 4.1 or lower
- Maximum compatibility (99% of Smart TVs)
- Hardware-accelerated on all platforms
- Reliable across all brands and years
Limited: HEVC (H.265)
Supported on newer models only
- 2018+ TVs: Usually supported
- 2016-2017 TVs: Often fails
- Hisense/Vidaa: Limited support
- May fall back to software decode (slow)
Experimental: VP9
Widely supported but less reliable
- Chromium-based platforms: Good
- WebOS/Tizen: Varies by model year
- Less reliable for ad insertion than H.264
Avoid: AV1
Very limited Smart TV support
- Only on 2021+ high-end models
- Not hardware-accelerated on most TVs
- Will cause playback failures
Resolution Constraints
| Resolution | Recommendation | Reason |
|---|---|---|
| 1920x1080 (1080p) | ✅ Recommended | Best balance of quality and compatibility |
| 1280x720 (720p) | ✅ Safe fallback | Universal support, lower bandwidth |
| 3840x2160 (4K) | ⚠️ Penalized | High memory usage, UI stuttering, crashes |
| Higher than 4K | ❌ Avoid | Will be rejected by SDK |
src/core/VASTParser.ts:302-305:
Bitrate Guidelines
Set
targetBitrate: 1500 if targeting 2016-2019 TV models or regions with slower internet.- TV WiFi chips are often slow (2.4GHz only on older models)
- Living room WiFi signal is typically weaker
- TVs lack aggressive adaptive bitrate switching
- Buffering during ads causes poor user experience
Audio Codec Requirements
| Codec | Support | Notes |
|---|---|---|
| AAC-LC | ✅ Universal | Use this for maximum compatibility |
| HE-AAC | ✅ Common | Supported on most modern TVs |
| Dolby Digital (AC-3) | ⚠️ Limited | Premium TVs only |
| Dolby Atmos | ⚠️ Very Limited | 2020+ high-end models |
Container Format
Memory Constraints
Smart TVs have significantly less RAM than desktop browsers:| Device Type | Typical RAM | Impact |
|---|---|---|
| Budget TV (2016-2019) | 512MB - 1GB | High memory pressure |
| Mid-range TV (2020-2022) | 1.5GB - 2GB | Moderate constraints |
| Premium TV (2023+) | 3GB - 4GB | Similar to low-end desktops |
- Avoid 4K ads: Can consume 200MB+ of video buffer memory
- Limit concurrent requests: Stick to SDK defaults (max 5 wrapper depth)
- Clean up promptly: Call
sdk.destroy()after ad completion
Network Limitations
Slow VAST Response Times
Slow VAST Response Times
Smart TV network requests are slower than desktop:
- DNS resolution: 200-500ms (vs 20-50ms desktop)
- TLS handshake: 500-1000ms (vs 100-200ms desktop)
- HTTP request: 300-800ms (vs 50-150ms desktop)
timeout: 8000 or higher for VAST requests.Limited Concurrent Connections
Limited Concurrent Connections
TV browsers limit concurrent HTTP connections:
- Typically 4-6 connections per domain (vs 10+ on desktop)
- Tracking pixels may queue up
sendBeacon() to avoid blocking the main connection pool.No HTTP/3 Support
No HTTP/3 Support
Most Smart TV browsers don’t support HTTP/3 (QUIC):
- Stuck on HTTP/1.1 or HTTP/2
- Higher latency on poor WiFi connections
Browser Limitations
JavaScript Engine Performance
Smart TV browsers use older/slower JavaScript engines:| Platform | Engine | Performance |
|---|---|---|
| Tizen 4.0+ | JavaScriptCore | ~5x slower than desktop |
| WebOS 3.0+ | V8 (older) | ~3x slower than desktop |
| Vidaa | Custom | ~8x slower than desktop |
- Avoid heavy JavaScript processing during ad playback
- Minimize VAST wrapper chains (default limit: 5)
- Use SDK’s built-in parsers (optimized for TV)
Missing Web APIs
Some modern Web APIs are unavailable:The SDK handles these fallbacks automatically—you don’t need to check feature support yourself.
Best Practices for Compatibility
See Also
- Platform Support - Platform-specific capabilities
- Optimization Guide - Performance tuning
- Performance Metrics - Bundle size and benchmarks
