Adgent SDK

Lightweight, framework-agnostic VAST Player SDK for Smart TV platforms.

Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Configuration
• Usage
  • Basic Setup
  • Event Handling
  • Platform Detection
• API Reference
  • AdgentSDK Class
  • Configuration Options
  • Events
• Platform Support
• Performance
• Development
• License

Overview

Adgent SDK is a high-performance, lightweight VAST (Video Ad Serving Template) player SDK designed specifically for Smart TV platforms. It provides a robust foundation for displaying video advertisements with full VAST 4.x compliance while maintaining minimal footprint.

Why Adgent SDK?

• Zero Framework Dependencies: Works with any JavaScript/TypeScript project
• Smart TV Optimized: Purpose-built for WebOS, Tizen, Vidaa, and WhaleOS
• Production Ready: Battle-tested error handling and recovery mechanisms
• Type-Safe: Full TypeScript support with typed APIs

Features

| Feature | Description | |---------|-------------| | VAST 4.x Compliance | Full wrapper resolution, tracking events, and smart media file selection | | Multi-Platform | Native adapters for WebOS, Tizen, Vidaa, WhaleOS, and generic web environments | | Minimal Footprint | Target size under 20KB gzipped, single dependency (fast-xml-parser) | | Fault Tolerant | Nuclear Mute autoplay strategy with soft-fail recovery mechanisms | | Remote Control Ready | Built-in focus management and key code normalization | | Event Driven | Comprehensive event system for granular ad playback control |

Quick Start

Get up and running in 3 simple steps:

# 1. Install the SDK
npm install adgent-sdk

# 2. Import and initialize
import { AdgentSDK } from 'adgent-sdk';

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

await sdk.init();

# 3. Start ad playback
await sdk.play();

Installation

NPM

npm install adgent-sdk

Yarn

yarn add adgent-sdk

CDN

<script src="https://cdn.example.com/adgent-sdk.min.js"></script>

Configuration

Configuration Options

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | container | HTMLElement | Yes | - | Container element for the ad player | | vastUrl | string | Yes | - | VAST tag URL to fetch ad data | | targetBitrate | number | No | 2500 | Preferred bitrate in kbps (2500 ≈ 1080p) | | maxWrapperDepth | number | No | 5 | Maximum VAST wrapper chain depth | | timeout | number | No | 10000 | Request timeout in milliseconds | | debug | boolean | No | false | Enable debug logging for development | | skipOffset | number | No | - | Override skip offset in seconds | | skipButtonText | string | No | 'Skip Ad' | Custom skip button text | | mutedAutoplay | boolean | No | true | Enable muted autoplay for compliance |

Callback Events

| Callback | Type | Description | |----------|------|-------------| | onStart | () => void | Triggered when ad starts playing | | onProgress | (progress: AdProgress) => void | Periodic progress updates | | onComplete | () => void | Triggered when ad finishes normally | | onSkip | () => void | Triggered when user skips the ad | | onError | (error: AdError) => void | Triggered on any ad-related error | | onPause | () => void | Triggered when ad is paused | | onResume | () => void | Triggered when ad resumes from pause | | onClick | (url: string) => void | Triggered when user clicks the ad |

Usage

Basic Setup

import { AdgentSDK } from 'adgent-sdk';

// Initialize the SDK
const sdk = new AdgentSDK({
  container: document.getElementById('ad-container')!,
  vastUrl: 'https://example.com/vast.xml',
  targetBitrate: 2500,
  mutedAutoplay: true,
  skipButtonText: 'Skip in 5s',
  onStart: () => {
    console.log('Ad playback started');
  },
  onComplete: () => {
    console.log('Ad completed successfully');
    // Resume main content playback
  },
  onError: (err) => {
    console.error('Ad error:', err);
    // Graceful fallback - resume main content
  },
  onSkip: () => {
    console.log('User skipped the ad');
  }
});

// Initialize and prepare
await sdk.init();

// Play the ad
await sdk.play();

Event Handling

Using Callbacks

const sdk = new AdgentSDK({
  container: document.getElementById('ad-container')!,
  vastUrl: 'https://example.com/vast.xml',
  onStart: () => console.log('Ad started'),
  onProgress: (progress) => {
    console.log(`Progress: ${progress.percent}%`);
    console.log(`Current time: ${progress.currentTime}s`);
    console.log(`Duration: ${progress.duration}s`);
  },
  onComplete: () => console.log('Ad completed'),
  onSkip: () => console.log('Ad skipped'),
  onPause: () => console.log('Ad paused'),
  onResume: () => console.log('Ad resumed'),
  onClick: (url) => {
    console.log(`Clicked: ${url}`);
    window.open(url, '_blank');
  },
  onError: (error) => {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
  }
});

Using Event Listener API

// Subscribe to events
const unsubscribe = sdk.on((event) => {
  switch (event.type) {
    case 'start':
      console.log('Ad playback started');
      break;
    case 'quartile':
      console.log(`Quartile reached: ${event.data.quartile}`);
      console.log(`Progress: ${event.data.percent}%`);
      break;
    case 'complete':
      console.log('Ad completed successfully');
      break;
    case 'skip':
      console.log('User skipped the ad');
      break;
    case 'error':
      console.error('Ad error:', event.data);
      break;
    case 'click':
      console.log('Ad clicked, URL:', event.data.url);
      break;
  }
});

// Unsubscribe when done
unsubscribe();

Event Types

| Event Type | Data | Description | |------------|------|-------------| | start | { timestamp: number } | Ad started playing | | quartile | { quartile: number, percent: number } | Quartile milestone reached (25, 50, 75, 100) | | complete | { timestamp: number } | Ad finished successfully | | skip | { timestamp: number } | User skipped the ad | | error | { code: number, message: string } | An error occurred | | click | { url: string } | User clicked the ad | | pause | { timestamp: number } | Ad was paused | | resume | { timestamp: number } | Ad resumed from pause |

Platform Detection

import { getPlatformAdapter, Platform } from 'adgent-sdk';

// Get platform-specific adapter
const adapter = getPlatformAdapter();

console.log('Platform:', adapter.platform);
// Output: 'tizen' | 'webos' | 'vidaa' | 'whaleos' | 'generic'

// Check platform capabilities
if (adapter.capabilities.sendBeacon) {
  console.log('Beacon API available for tracking');
}

if (adapter.capabilities.hdr) {
  console.log('HDR playback supported');
}

// Access platform-specific utilities
adapter.utils.normalizeKeyCode('ArrowRight'); // Returns platform-specific key code
adapter.utils.focusElement(element);

API Reference

AdgentSDK Class

Constructor

new AdgentSDK(config: AdgentConfig): AdgentSDK

Creates a new AdgentSDK instance with the specified configuration.

Methods

| Method | Returns | Description | |--------|---------|-------------| | init() | Promise<void> | Initializes SDK, fetches VAST, prepares player | | play() | Promise<void> | Starts ad playback | | pause() | Promise<void> | Pauses ad playback | | resume() | Promise<void> | Resumes ad playback | | stop() | Promise<void> | Stops ad playback | | skip() | Promise<void> | Skips the current ad | | destroy() | Promise<void> | Cleans up resources, removes event listeners | | on(callback) | UnsubscribeFn | Subscribe to ad events | | getState() | AdState | Get current ad playback state |

Usage Example

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

// Initialize
await sdk.init();

// Play
await sdk.play();

// Pause after 5 seconds
setTimeout(() => {
  await sdk.pause();
  
  // Resume after 2 seconds
  setTimeout(() => {
    sdk.resume();
  }, 2000);
}, 5000);

// Cleanup when done
sdk.destroy();

Platform Support

Supported Platforms

| Platform | Version | Status | |----------|---------|--------| | WebOS | 3.0+ | ✅ Fully Supported | | Tizen | 4.0+ | ✅ Fully Supported | | Vidaa | 2.0+ | ✅ Fully Supported | | WhaleOS | 1.0+ | ✅ Fully Supported | | Generic Web | Modern browsers | ✅ Fully Supported |

Platform-Specific Features

WebOS

• Native video player integration
• LG remote control support
• WebOS specific tracking endpoints

Tizen

• Tizen TV Player API
• Samsung remote control mapping
• Tizen analytics integration

Vidaa

• HisenseVidaa OS support
• Vidaa remote control codes
• Lightweight implementation

WhaleOS

• Naver Whale browser support
• Whale-specific optimizations

Performance

Size Comparison

| Metric | Value | |--------|-------| | Gzipped Size | < 20 KB | | Minified Size | ~50 KB | | Dependencies | 1 (fast-xml-parser) |

Optimization Tips

1. Enable Tree Shaking: Use ES modules for optimal bundle size
2. Lazy Load: Only load SDK when ad playback is needed
3. VAST Caching: Cache VAST responses to reduce network requests
4. Bitrate Selection: Set appropriate targetBitrate for your platform

// Example: Optimized configuration
const sdk = new AdgentSDK({
  container: document.getElementById('ad-container')!,
  vastUrl: cachedVastUrl, // Use cached VAST when available
  targetBitrate: 1500, // Appropriate for most Smart TVs
  timeout: 5000, // Faster timeout for better UX
});

Development

Setup

# Clone the repository
git clone https://github.com/your-org/adgent-sdk.git

# Navigate to project directory
cd adgent-sdk

# Install dependencies
npm install

# Install dev dependencies
npm run install:dev

Available Scripts

| Command | Description | |---------|-------------| | npm run build | Build the library for production | | npm run build:watch | Build in watch mode for development | | npm run typecheck | Run TypeScript type checking | | npm run lint | Lint the codebase | | npm run test | Run unit tests | | npm run test:watch | Run tests in watch mode | | npm run dev | Start development server | | npm run docs | Generate documentation |

Project Structure

adgent-sdk/
├── src/
│   ├── core/           # Core SDK functionality
│   ├── adapters/       # Platform-specific adapters
│   ├── utils/          # Utility functions
│   ├── types/          # TypeScript type definitions
│   └── index.ts        # Main entry point
├── test/               # Test files
├── dist/               # Built output
├── docs/               # Documentation
└── package.json

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Proprietary - All rights reserved.

This software and its source code are the exclusive property of the copyright holder. No part of this software may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the copyright holder, except in the case of brief quotations embodied in critical reviews and certain other non-commercial uses permitted by copyright law.

For licensing inquiries, please contact: [email protected]

adgent-sdk