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.

$3

- 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:

``bash


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

$3

`bash
npm install adgent-sdk
`

$3

`bash
yarn add adgent-sdk
`

$3

`html

`

---

Configuration

$3

| 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 |

$3

| 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

$3

`typescript
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();
`

$3

#### Using Callbacks

`typescript
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

`typescript
// 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 |

$3

`typescript
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

$3

#### Constructor

`typescript
new AdgentSDK(config: AdgentConfig): AdgentSDK
`

Creates a new AdgentSDK instance with the specified configuration.

#### Methods

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

#### Usage Example

`typescript
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

$3

| 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 |

$3

#### 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

$3

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

$3

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

`typescript
// 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

$3

`bash


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
`

$3

| 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 |

$3

`
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
`

$3

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: license@example.com

adgent-sdk