Skip to main content

​
Package Manager Installation

Adgent SDK is available on npm and can be installed using your preferred package manager: 
npm install adgent-sdk

​
Package Details

Once installed, you’ll have access to the following:
  • Package Name: adgent-sdk
  • Version: 0.1.10
  • Bundle Size: < 20KB gzipped (~50KB minified)
  • Dependencies: Only fast-xml-parser for VAST XML parsing
  • Module Formats: ES modules (.es.js) and UMD (.umd.js)
Adgent SDK is distributed as both ES modules and UMD, ensuring compatibility with modern bundlers (Webpack, Vite, Rollup) and legacy build systems.

​
TypeScript Setup

Adgent SDK includes full TypeScript definitions out of the box. No additional @types packages are required.

​
Import the SDK

import { AdgentSDK } from 'adgent-sdk';

// Or import specific types
import { 
  AdgentSDK, 
  AdPlayerConfig, 
  AdPlayerState,
  AdProgress,
  AdError,
  PlaybackStatus 
} from 'adgent-sdk';

​
Type Definitions

The SDK exports comprehensive TypeScript types for all configuration options, state, events, and platform adapters: 
interface AdPlayerConfig {
  container: HTMLElement;
  vastUrl: string;
  targetBitrate?: number;      // Default: 2500 kbps
  maxWrapperDepth?: number;    // Default: 5
  timeout?: number;            // Default: 10000ms
  debug?: boolean;             // Default: false
  skipButtonText?: string;     // Default: 'Skip Ad'
  skipOffset?: number;         // Override VAST skipOffset
  onComplete?: () => void;
  onError?: (error: AdError) => void;
  onStart?: () => void;
  onProgress?: (progress: AdProgress) => void;
  onSkip?: () => void;
  onClick?: (url: string) => void;
  onPause?: () => void;
  onResume?: () => void;
  onClose?: () => void;
}
All callback functions are optional. You can use either callbacks or the event listener API (sdk.on()) to handle ad events.

​
JavaScript Setup

For vanilla JavaScript projects, import the SDK using CommonJS or ES modules: 
import { AdgentSDK } from 'adgent-sdk';

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

​
Verification

Verify your installation by checking the SDK version: 
import { AdgentSDK } from 'adgent-sdk';

console.log('Adgent SDK loaded successfully');

const sdk = new AdgentSDK({
  container: document.getElementById('ad-container'),
  vastUrl: 'https://example.com/vast.xml',
  debug: true // Enable debug logging
});
With debug: true, you’ll see detailed console logs including:
  • Platform detection (WebOS, Tizen, Vidaa, WhaleOS, or generic)
  • VAST parsing progress
  • Media file selection
  • Tracking pixel fires
  • Playback events

​
Bundle Size Optimization

For optimal bundle size in production:
1

Enable tree-shaking

Use ES modules imports to allow your bundler to tree-shake unused code:
import { AdgentSDK } from 'adgent-sdk'; // Good ✅
const AdgentSDK = require('adgent-sdk').AdgentSDK; // Less optimal ⚠️
2

Lazy load the SDK

Load Adgent SDK only when ad playback is needed:
async function playAd() {
  const { AdgentSDK } = await import('adgent-sdk');
  // Initialize and play ad
}
3

Configure bundler

Ensure your bundler is configured for optimal minification:
Vite Example
// vite.config.js
export default {
  build: {
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true // Remove debug logs in production
      }
    }
  }
}

​
Next Steps

Quickstart Guide

Build your first ad player in 5 minutes

API Reference

Explore all configuration options and methods

Build docs developers (and LLMs) love

Get started for freeTalk to us