Player Types

AdPlayerConfig

Configuration options for initializing the AdPlayer SDK.

interface AdPlayerConfig {
  container: HTMLElement;
  vastUrl: string;
  targetBitrate?: number;
  maxWrapperDepth?: number;
  timeout?: number;
  debug?: boolean;
  skipButtonText?: string;
  skipOffset?: number;
  onComplete?: () => void;
  onError?: (error: AdError) => void;
  onStart?: () => void;
  onProgress?: (progress: AdProgress) => void;
  onSkip?: () => void;
  onClick?: (clickThroughUrl: string) => void;
  onPause?: () => void;
  onResume?: () => void;
  customStartOverlay?: HTMLElement;
  onClose?: () => void;
}

container

HTMLElement

required

Container element to render the ad player into. The player will create a video element and UI overlay within this container.

vastUrl

string

required

VAST tag URL to fetch. Supports VAST 4.x specification.

targetBitrate

number

Target bitrate in kbps for media file selection. Default: 2500 (approximately 1080p quality)

maxWrapperDepth

number

Maximum VAST wrapper depth to follow. Prevents infinite wrapper chains. Default: 5

timeout

number

Request timeout in milliseconds for VAST fetching and media loading. Default: 10000

debug

boolean

Enable debug logging to console. Default: false

skipButtonText

string

Custom text for the skip button. Default behavior shows countdown and “Skip Ad” text.

skipOffset

number

Skip offset override in seconds. Set to 0 to disable skipping entirely. If not set, uses the skip offset from VAST.

onComplete

() => void

Callback invoked when ad playback completes successfully.

onError

(error: AdError) => void

Callback invoked when an error occurs during ad loading or playback.

onStart

() => void

Callback invoked when ad starts playing for the first time.

onProgress

(progress: AdProgress) => void

Callback invoked periodically during playback with current progress information.

onSkip

() => void

Callback invoked when user skips the ad.

onClick

(clickThroughUrl: string) => void

Callback invoked when user clicks the ad. Receives the click-through URL from VAST.

onPause

() => void

Callback invoked when ad is paused.

onResume

() => void

Callback invoked when ad resumes from pause.

customStartOverlay

HTMLElement

Custom “Start Ad” overlay UI element for autoplay fallback scenarios. Displayed when browser blocks autoplay.

onClose

() => void

Callback invoked when user triggers Back or Exit key action on Smart TV platforms.

Example

const config: AdPlayerConfig = {
  container: document.getElementById('ad-container')!,
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 3000,
  skipOffset: 5,
  debug: true,
  onStart: () => console.log('Ad started'),
  onComplete: () => console.log('Ad completed'),
  onError: (error) => console.error('Ad error:', error)
};

AdPlayerState

Current state of the ad player.

interface AdPlayerState {
  status: PlaybackStatus;
  currentTime: number;
  duration: number;
  muted: boolean;
  volume: number;
  canSkip: boolean;
  skipCountdown: number;
  mediaFile: MediaFile | null;
  error: AdError | null;
}

status

PlaybackStatus

Current playback status. See PlaybackStatus enum.

currentTime

number

Current playback time in seconds.

duration

number

Total duration of the ad in seconds.

muted

boolean

Whether the ad is currently muted.

volume

number

Current volume level from 0 (muted) to 1 (full volume).

canSkip

boolean

Whether the skip button is currently available to the user.

skipCountdown

number

Seconds remaining until skip becomes available. 0 when skip is available.

mediaFile

MediaFile | null

Selected media file currently being played. See MediaFile type.

error

AdError | null

Last error that occurred, if any. See AdError interface.

PlaybackStatus

Enum representing the current playback state.

enum PlaybackStatus {
  Idle = 'idle',
  Loading = 'loading',
  Ready = 'ready',
  Playing = 'playing',
  Paused = 'paused',
  Completed = 'completed',
  Error = 'error',
  WaitingForInteraction = 'waiting_for_interaction'
}

Idle

'idle'

Player is initialized but no ad has been loaded.

'loading'

Player is fetching VAST or loading media.

Ready

'ready'

Media is loaded and ready to play.

Playing

'playing'

Ad is currently playing.

Paused

'paused'

Ad playback is paused.

Completed

'completed'

Ad playback has completed successfully.

Error

'error'

An error occurred during loading or playback.

WaitingForInteraction

'waiting_for_interaction'

Autoplay was blocked; waiting for user interaction to start playback.

AdProgress

Progress event data emitted during playback.

interface AdProgress {
  currentTime: number;
  duration: number;
  percentage: number;
  quartile: 0 | 1 | 2 | 3 | 4;
}

currentTime

number

Current playback time in seconds.

duration

number

Total duration in seconds.

percentage

number

Playback progress as a percentage (0-100).

quartile

0 | 1 | 2 | 3 | 4

Current quartile milestone:

0 - Start
1 - First quartile (25%)
2 - Midpoint (50%)
3 - Third quartile (75%)
4 - Complete (100%)

AdError

Error structure with VAST error code and details.

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

code

VASTErrorCode | number

Error code. Uses standard VASTErrorCode values when applicable, or custom numeric codes.

message

string

Human-readable error message.

details

string

Additional error details or stack trace information.

recoverable

boolean

Whether the error is recoverable and playback can be retried.

Example

const error: AdError = {
  code: VASTErrorCode.MEDIA_NOT_SUPPORTED,
  message: 'No supported media files found',
  details: 'Available codecs: video/webm, Required: video/mp4',
  recoverable: false
};

AdPlayerEvent

Union type representing all events emitted by the player.

type AdPlayerEvent = 
  | { type: 'loaded' }
  | { type: 'start' }
  | { type: 'progress'; data: AdProgress }
  | { type: 'quartile'; data: { quartile: TrackingEventType } }
  | { type: 'complete' }
  | { type: 'skip' }
  | { type: 'click'; data: { url: string } }
  | { type: 'pause' }
  | { type: 'resume' }
  | { type: 'mute' }
  | { type: 'unmute' }
  | { type: 'error'; data: AdError }
  | { type: 'destroy' };

loaded

{ type: 'loaded' }

VAST has been loaded and media is ready.

start

{ type: 'start' }

Ad playback has started.

progress

{ type: 'progress'; data: AdProgress }

Playback progress update. Emitted periodically with current progress data.

quartile

{ type: 'quartile'; data: { quartile: TrackingEventType } }

Quartile milestone reached (firstQuartile, midpoint, thirdQuartile).

complete

{ type: 'complete' }

Ad playback completed successfully.

skip

{ type: 'skip' }

User skipped the ad.

click

{ type: 'click'; data: { url: string } }

User clicked the ad. Contains the click-through URL.

pause

{ type: 'pause' }

Ad playback was paused.

resume

{ type: 'resume' }

Ad playback resumed from pause.

mute

{ type: 'mute' }

Ad was muted.

unmute

{ type: 'unmute' }

Ad was unmuted.

error

{ type: 'error'; data: AdError }

An error occurred. Contains error details.

destroy

{ type: 'destroy' }

Player instance was destroyed.

Example

player.addEventListener((event: AdPlayerEvent) => {
  switch (event.type) {
    case 'progress':
      console.log(`Progress: ${event.data.percentage}%`);
      break;
    case 'error':
      console.error('Error:', event.data.message);
      break;
    case 'click':
      console.log('Ad clicked:', event.data.url);
      break;
  }
});

AdPlayerEventListener

Type definition for event listener callbacks.

type AdPlayerEventListener = (event: AdPlayerEvent) => void;

Callback function that receives AdPlayerEvent objects. Used with the player’s event system.

Example

const listener: AdPlayerEventListener = (event) => {
  if (event.type === 'complete') {
    console.log('Ad playback finished');
  }
};

player.addEventListener(listener);

Core Classes

Type Definitions

Utilities

AdPlayerConfig

Example

AdPlayerState

PlaybackStatus

AdProgress

AdError

Example

AdPlayerEvent

Example

AdPlayerEventListener

Example

Build docs developers (and LLMs) love

Core Classes

Type Definitions

Utilities

​AdPlayerConfig

​Example

​AdPlayerState

​PlaybackStatus

​AdProgress

​AdError

​Example

​AdPlayerEvent

​Example

​AdPlayerEventListener

​Example

Build docs developers (and LLMs) love

AdPlayerConfig

Example

AdPlayerState

PlaybackStatus

AdProgress

AdError

Example

AdPlayerEvent

Example

AdPlayerEventListener

Example