API — WebAdSDK · CleverSphere

Quick start

The shortest path from an empty page to playing video with ads:

import { WebAdSdk } from 'web-ad-sdk';
import 'web-ad-sdk/streamix-sdk.css';

const sdk = new WebAdSdk();

await sdk.init({
  dom,                              // the 7 required elements (see DOM structure)
  logger: { info: console.log },
  partnerId: '12',
  acfSource: { kind: 'acfId', acfId: '1' },
  playerEngine: 'plyr',
});

sdk.on('adStarted', (e) => console.log('ad started:', e.kind));

await sdk.play('https://.../master.m3u8', { adsEnabled: true });

See it running on the Live Demo.

Public exports

All public symbols come from the package entry point web-ad-sdk:

WebAdSdk — the main (and only) class.
getSdkConfig, setSdkConfig, resetSdkConfig — runtime configuration.
Types: WebAdSdkInitOptions, WebAdSdkPlayOptions, AcfSource, Html5SdkDom, LoggerLike, PlayerEngine, SdkPlaybackState, SdkAdState, SdkConfig, SdkEventMap, SdkEventName.

The `WebAdSdk` class

Created with no arguments: const sdk = new WebAdSdk().

Method	Description
`init(options)`	Create the runtime and load the ACF. Returns a Promise. Deduplicates concurrent calls.
`play(url, options?)`	Start content (and ads). Waits for `init()` if it is still running.
`pause()` / `resume()`	Pause / resume content. Ignored while an overlay ad plays.
`seek(sec)`	Seek content. Ignored during ads.
`setVolume(v)` / `getVolume()`	Get/set content volume (0–1). `0` mutes.
`getState()` / `getAdState()`	Current playback / ad state.
`getCurrentTime()` / `getDuration()` / `isLive()`	Playhead, duration (∞ for live), live flag.
`setOnPauseEnabled(b)`	Toggle on‑pause ads for the session.
`stopAd()`	Stop the current ad and restore full‑screen content.
`showOnPauseAdNow()`	Programmatically trigger an on‑pause ad.
`forceReinit(reason?)`	Rebuild the VMAP ad plan (rolling horizon).
`on(event, fn)` / `off(event, fn)`	Subscribe / unsubscribe to events.
`destroy()`	Tear everything down. The instance can’t be reused afterwards.

`WebAdSdkInitOptions`

Field	Type	Notes
`dom`	`Html5SdkDom`	The 7 required elements (see below).
`logger`	`LoggerLike`	Only `info` is required; `debug/warn/error/raw` optional.
`partnerId`	`string`	Required, non‑empty.
`applicationName?`	`string`	Default `'WebAdSdk'`.
`acfSource`	`AcfSource`	How to obtain the ad config.
`onPauseEnabled?`	`boolean`	Default `true`.
`playerEngine?`	`PlayerEngine`	Default `'auto'`.
`loadingSpinnerEnabled?`	`boolean`	Default `true`.
`fullscreenButtonEnabled?`	`boolean`	Default `true`.

`WebAdSdkPlayOptions`

All fields optional. Ads are enabled unless adsEnabled: false.

Field	Type	Notes
`id`	`string`	Content id (analytics).
`categoryId`	`string`	Category (analytics).
`title`	`string`	Title (analytics).
`macros`	`Map<string,string>`	`[KEY]` → `encodeURIComponent(value)` in VAST URLs.
`adsEnabled`	`boolean`	`false` skips all ads.

`AcfSource`

A discriminated union — three ways to supply the Ad Config (ACF):

type AcfSource =
  | { kind: 'distribution'; distributionId: string }  // QC DeviceAPI
  | { kind: 'acfId';        acfId: string }           // CS API by id
  | { kind: 'raw';          acfJson: string };        // inline JSON

`PlayerEngine`

auto — HLS.js for .m3u8, DASH.js for .mpd.
plyr — Plyr UI wrapping HLS.js/DASH.js, with pseudo‑fullscreen.
native — plain <video>, no extra libraries.

Player libraries are loaded by your page via <script> (CDN) — the SDK doesn’t bundle them. Google IMA (ima3.js) is always required for ads.

Events

Subscribe with sdk.on(name, fn):

Event	Payload
`adStarted` / `adCompleted`	`{ kind: 'preroll'\|'midroll'\|'postroll'\|'onpause' }`
`adError`	`{ code: string; message: string }`
`contentLoaded` / `contentStarted` / `contentFinished`	`{}`
`timeUpdate`	`{ currentTime: number; watchTime: number }` (~250 ms, content only)
`fullscreenChange`	`{ isFullscreen: boolean }`
`error`	`{ code: string; message: string }`

Required DOM structure

The SDK renders into seven elements you provide:

<div id="playerRoot">                          // position: relative
  <img id="adsBackground" alt="" />
  <div id="contentContainer">
    <video id="contentVideo" controls playsinline></video>
  </div>
  <div id="adContainer">
    <video id="adVideo" playsinline></video>
    <img id="adImage" alt="on-pause ad" />
  </div>
</div>

playerRoot must be positioned; the child containers are absolutely positioned to fill it.

API at a glance

Quick start

Public exports

The WebAdSdk class

WebAdSdkInitOptions

WebAdSdkPlayOptions

AcfSource