IMA#

Introduction#

The KWIKplayer IMA Plugin integrates the Google Interactive Media Ads (IMA) SDK with KWIKplayer, enabling seamless ad playback in formats such as VAST, VMAP, or ad rules.

Configuration Options#

The plugin provides several configuration options to customize its behavior. Below is a list of the supported options:

Option	Type	Default	Description
`adLabel`	`string`	`"Advertisement"`	Replaces the "Advertisement" text in the ad label.
`adLabelNofN`	`string`	`"of"`	Replaces the "of" text in the ad label (e.g., `1 of 2`).
`adTagUrl`	`string`	`null`	URL for fetching a VAST, VMAP, or ad rules response. Overrides `adsResponse` and `adsSchedule`.
`adsRenderingSettings`	`object`	`{}`	Ads rendering settings as defined in the IMA SDK.
`adsResponse`	`string`	`null`	VAST/VMAP/ad rules response used instead of `adTagUrl`.
`adsSchedule`	`object`	`null`	Ad scheduling configuration. Allows VMAP construction automatically.
`adsRequest`	`object`	`{}`	Ad request properties defined in the IMA SDK.
`autoPlayAdBreaks`	`boolean`	`true`	Automatically plays VMAP/ad rules ad breaks.
`contribAdsSettings`	`object`	`{}`	Additional settings for the contrib-ads plugin.
`debug`	`boolean`	`false`	Enables or disables debug mode.
`disableAdControls`	`boolean`	`false`	Hides ad controls (play/pause, volume, fullscreen) during ad playback.
`disableCustomPlaybackForIOS10Plus`	`boolean`	`false`	Disables custom playback on iOS 10+ browsers.
`disableFlashAds`	`boolean`	`false`	Disables Flash ads.
`forceNonLinearFullSlot`	`boolean`	`true`	Forces non-linear ads to render as linear fullslot.
`locale`	`string`	`null`	Sets the locale for ad localization.
`numRedirects`	`number`	`null`	Maximum number of VAST redirects before aborting the ad load.
`preventLateAdStart`	`boolean`	`false`	Prevents ads from starting late after content playback begins.
`showControlsForJSAds`	`boolean`	`true`	Displays the control bar for VPAID JavaScript ads.
`showCountdown`	`boolean`	`true`	Shows the ad countdown timer.
`vastLoadTimeout`	`number`	`5000`	Overrides the VAST load timeout in milliseconds for a single wrapper.
`vpaidMode`	`"ENABLED" \| "DISABLED" \| "INSECURE"`	`"ENABLED"`	VPAID mode configuration. Overrides `vpaidAllowed`.

Usage#

To enable the IMA plugin, include its configuration under the imaPlugin key when initializing KWIKplayer:

const player = window.kwikMotion('my-video', {
  imaPlugin: {
    adTagUrl: 'https://example.com/vast.xml',
    autoPlayAdBreaks: true,
    showCountdown: true,
    debug: false,
  }
})

Ad Scheduling#

The adsSchedule option allows you to define a schedule for preroll, midroll, and postroll ads:

window.initPlayer('my-video', {
  imaPlugin: {
    adsSchedule: {
      preroll: ['https://example.com/preroll.xml'],
      30: ['https://example.com/midroll.xml'], // Midroll at 30 seconds
      postroll: ['https://example.com/postroll.xml'],
    },
  }
})

Events#

The plugin emits various events to help you monitor ad behavior: Key Events

ads-ad-started
adstart
adend
adskip
adtimeout
adsready
nopreroll
nopostroll
contentplay
adserror

Example#

player.on('ads-ad-started', () => {
  console.log('Ad started!');
});

Debugging#

Enable debugging to log detailed information about the plugin's behavior:

window.initPlayer('my-video', {
  imaPlugin: {
    debug: true,
  }
})