Configuration

The Adgent SDK is highly configurable to support various Smart TV platforms and advertising requirements. This guide covers all available configuration options with practical examples.

Basic Configuration

The minimal configuration requires only two parameters:

import { AdPlayer } from 'adgent-sdk';

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml'
});

await player.init();

AdPlayerConfig Interface

All configuration options are defined in src/types/player.ts:9.

Required Parameters

container

HTMLElement

required

Container element to render the ad player into. The video element and UI overlays will be appended as children.

const container = document.getElementById('ad-container');
if (!container) throw new Error('Container not found');

const player = new AdPlayer({ 
  container,
  vastUrl: 'https://example.com/vast.xml'
});

vastUrl

string

required

VAST tag URL to fetch ad data from. Supports VAST 4.x format including wrappers.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://adserver.example.com/vast?placementId=12345'
});

Media Selection

targetBitrate

number

default:"2500"

Target bitrate in kbps for media file selection. The SDK selects the closest match from available VAST MediaFiles.Default: 2500 (approximately 1080p quality)Use cases:

High-end TVs (4K): 5000-8000 kbps
Standard 1080p TVs: 2500-3500 kbps
Budget/720p TVs: 1500-2000 kbps
Low bandwidth: 800-1200 kbps

// Optimize for budget Smart TVs
const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 1500 // Lower bitrate for older hardware
});

The SDK uses a “closest match” algorithm defined in src/core/AdPlayer.ts:124. It automatically filters out excessively high bitrates that may cause buffering on TV platforms.

Network Configuration

maxWrapperDepth

number

default:"5"

Maximum VAST wrapper chain depth to prevent infinite redirects.Default: 5Use cases:

Standard ads: 3-5 (default is safe)
Complex programmatic chains: 7-10
Direct VAST only: 0 (no wrappers allowed)

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  maxWrapperDepth: 3 // Limit wrapper depth for faster load
});

Setting this too high may result in slow ad loads. Most ad networks use 2-3 wrapper levels.

timeout

number

default:"10000"

Network request timeout in milliseconds for VAST fetching.Default: 10000 (10 seconds)Use cases:

Fast networks: 5000-7000 ms
Standard: 10000 ms (default)
Slow TV WiFi: 15000-20000 ms

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  timeout: 15000 // Longer timeout for TV WiFi
});

Skip Configuration

skipOffset

number

default:"undefined"

Skip offset override in seconds. When set, this overrides the skip offset from the VAST XML.

undefined: Use skip offset from VAST (default behavior)
0: Disable skip button entirely
> 0: Force skip after specified seconds

// Force 5-second skip regardless of VAST settings
const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  skipOffset: 5
});

// Disable skip completely
const nonSkippable = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  skipOffset: 0
});

The skip button appears at src/core/AdPlayer.ts:506 and countdown logic is at src/core/AdPlayer.ts:542.

skipButtonText

string

default:"'Skip Ad'"

Custom text for the skip button when skip is available.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  skipButtonText: 'Skip Advertisement'
});

During countdown, the button displays: "Skip in {N}s" format.

UI Customization

customStartOverlay

HTMLElement

default:"undefined"

Custom “Start Ad” overlay UI element for autoplay fallback scenarios.When autoplay fails (common on TVs), the SDK shows an interactive overlay. By default, it creates a play button, but you can provide your own custom element.

// Create custom overlay
const customOverlay = document.createElement('div');
customOverlay.innerHTML = `
  <div style="display: flex; align-items: center; justify-content: center; height: 100%;">
    <button id="start-btn" style="padding: 20px 40px; font-size: 24px;">
      ▶ Play Advertisement
    </button>
  </div>
`;

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  customStartOverlay: customOverlay
});

The overlay is shown when autoplay fails (src/core/AdPlayer.ts:287) and removed when user clicks start.

Event Callbacks

All event callbacks are optional and provide hooks into the ad lifecycle.

onStart

() => void

Triggered when ad playback begins. Called after VAST impressions are fired.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onStart: () => {
    console.log('Ad started - pause main content');
    mainVideo.pause();
  }
});

See src/core/AdPlayer.ts:420 for implementation.

onComplete

() => void

Triggered when ad finishes playing completely (not skipped).

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onComplete: () => {
    console.log('Ad completed - resume main content');
    player.destroy();
    mainVideo.play();
  }
});

onError

(error: AdError) => void

Triggered when any error occurs during VAST fetch or playback.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onError: (error) => {
    console.error('Ad error:', error.code, error.message);
    
    if (error.recoverable) {
      // Attempt recovery
      console.log('Error is recoverable, retrying...');
    } else {
      // Skip ad and resume content
      player.destroy();
      mainVideo.play();
    }
  }
});

Error structure defined at src/types/player.ts:116:

interface AdError {
  code: VASTErrorCode | number;
  message: string;
  details?: string;
  recoverable: boolean;
}

onProgress

(progress: AdProgress) => void

Triggered continuously during playback with progress information.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onProgress: (progress) => {
    console.log(`${progress.percentage.toFixed(1)}% complete`);
    console.log(`Quartile: ${progress.quartile}/4`);
    
    // Update custom progress bar
    progressBar.style.width = `${progress.percentage}%`;
  }
});

Progress data structure (src/types/player.ts:108):

interface AdProgress {
  currentTime: number;     // Current playback time in seconds
  duration: number;        // Total duration in seconds
  percentage: number;      // 0-100
  quartile: 0 | 1 | 2 | 3 | 4; // 0=start, 1=25%, 2=50%, 3=75%, 4=complete
}

onSkip

() => void

Triggered when user skips the ad.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onSkip: () => {
    console.log('User skipped ad');
    analytics.track('ad_skipped');
    player.destroy();
  }
});

onClick

(clickThroughUrl: string) => void

Triggered when user clicks the ad video. Receives the click-through URL from VAST.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onClick: (url) => {
    console.log('Ad clicked:', url);
    // Ad is automatically paused
    // Click tracking pixels are automatically fired
    // URL is opened via platform.openExternalLink()
  }
});

Implementation: src/core/AdPlayer.ts:343

onPause

() => void

Triggered when ad is paused (either by user or click action).

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onPause: () => {
    console.log('Ad paused');
  }
});

onResume

() => void

Triggered when ad resumes from pause.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onResume: () => {
    console.log('Ad resumed');
  }
});

onClose

() => void

Triggered when user presses Back/Exit key on remote control.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  onClose: () => {
    console.log('User pressed back button');
    player.destroy();
    // Return to previous screen
    navigation.goBack();
  }
});

If not provided, the Back key defaults to skip behavior (src/core/AdPlayer.ts:699).

Debug Configuration

debug

boolean

default:"false"

Enable verbose debug logging to console.

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  debug: true // Enable for development
});

When enabled, logs:

VAST parsing steps
Media file selection
Video element events (loadstart, canplay, playing, etc.)
Key presses and actions
Tracking pixel fires

Disable in production to reduce console noise and improve performance.

Complete Example

Here’s a production-ready configuration with all common options:

import { AdPlayer } from 'adgent-sdk';

const player = new AdPlayer({
  // Required
  container: document.getElementById('ad-container'),
  vastUrl: 'https://adserver.example.com/vast?id=12345',
  
  // Media selection
  targetBitrate: 2500, // 1080p quality
  
  // Network
  maxWrapperDepth: 5,
  timeout: 10000,
  
  // Skip settings
  skipOffset: undefined, // Use VAST value
  skipButtonText: 'Skip Ad',
  
  // Lifecycle callbacks
  onStart: () => {
    console.log('Ad started');
    mainVideo.pause();
  },
  
  onComplete: () => {
    console.log('Ad completed');
    player.destroy();
    mainVideo.play();
  },
  
  onSkip: () => {
    console.log('Ad skipped');
    analytics.track('ad_skipped');
    player.destroy();
    mainVideo.play();
  },
  
  onError: (error) => {
    console.error('Ad error:', error);
    player.destroy();
    mainVideo.play();
  },
  
  onProgress: (progress) => {
    // Update UI
    updateProgressBar(progress.percentage);
  },
  
  onClick: (url) => {
    console.log('Ad clicked:', url);
    analytics.track('ad_clicked', { url });
  },
  
  onClose: () => {
    console.log('User closed ad');
    player.destroy();
    navigation.goBack();
  },
  
  // Debug (development only)
  debug: process.env.NODE_ENV === 'development'
});

// Initialize and start
await player.init();

Platform-Specific Recommendations

Tizen (Samsung)

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 3500, // Samsung TVs handle higher bitrates well
  timeout: 12000,
  debug: false
});

WebOS (LG)

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 2500, // Conservative for older LG models
  timeout: 15000, // WebOS networking can be slower
  debug: false
});

Generic Web / Desktop

const player = new AdPlayer({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 5000, // Desktop can handle higher quality
  timeout: 8000,
  debug: false
});

Default Values Summary

All defaults are defined at src/core/AdPlayer.ts:22:

const DEFAULT_CONFIG = {
  targetBitrate: 2500,
  maxWrapperDepth: 5,
  timeout: 10000,
  debug: false,
  skipButtonText: 'Skip Ad'
};

Next Steps

Event Handling

Learn about the event system and listeners

Platform Detection

Detect and adapt to different Smart TV platforms

Error Handling

Handle errors gracefully with recovery strategies

Optimization

Optimize performance for Smart TV constraints

Get Started

Core Concepts

Guides

Smart TV Platforms

Configuration

Configuration

Basic Configuration

AdPlayerConfig Interface

Required Parameters

Media Selection

Network Configuration

Skip Configuration

UI Customization

Event Callbacks

Debug Configuration

Complete Example

Platform-Specific Recommendations

Tizen (Samsung)

WebOS (LG)

Generic Web / Desktop

Default Values Summary

Next Steps

Event Handling

Platform Detection

Error Handling

Optimization

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Smart TV Platforms

Documentation Index

​Configuration

​Basic Configuration

​AdPlayerConfig Interface

​Required Parameters

​Media Selection

​Network Configuration

​Skip Configuration

​UI Customization

​Event Callbacks

​Debug Configuration

​Complete Example

​Platform-Specific Recommendations

​Tizen (Samsung)

​WebOS (LG)

​Generic Web / Desktop

​Default Values Summary

​Next Steps

Event Handling

Platform Detection

Error Handling

Optimization

Build docs developers (and LLMs) love

Configuration

Basic Configuration

AdPlayerConfig Interface

Required Parameters

Media Selection

Network Configuration

Skip Configuration

UI Customization

Event Callbacks

Debug Configuration

Complete Example

Platform-Specific Recommendations

Tizen (Samsung)

WebOS (LG)

Generic Web / Desktop

Default Values Summary

Next Steps