Advertising Events

Advertising

🚧

Video ad insertion requires a JW Player Enterprise license. Please contact our team to upgrade your account.

This API provides developers with more control over the functionality of the Advertising edition of JW Player. For VAST and IMA plugins, this API allows for things like impression verification, custom scheduling, and multiple companions.

.on('adBidRequest')

Fired when header bidding starts requesting for bids.

Returns an object with the following:

Each bidder object contains the following:

.on('adBidResponse')

Fired when header bidding returns response.

Return an object with the following:

Bidder Object

Each bidder object contains the following:

.on('adBlock')

This event is fired when an ad plugin (Either VAST or Google IMA) is configured inside of the JW Player setup, and an ad blocker is detected on a viewer's browser. It is then possible to request a user disable their ad blocker to proceed.

.on('adBreakEnd')

Fires when control is passed back to the player from the ad.

Returns an object with the following:

.on('adBreakIgnored')

(VAST only) Fires when the time elapsed between the previous fully-watched ad break and the current ad break is less than the value defined by advertising.rules.timeBetweenAds

Returns an object with the following content.

{
    "id": "adbreak2",
    "tag": "{ad_tag_url}",
    "offset": 6,
    "timeSinceLastAd": 3.256,
    "type": "adBreakIgnored"
}

.on('adBreakStart')

Fires after the ad request and immediately before the ad is loaded into the player. Only fires before the first ad inside of an ad break.

Returns an object with the following:

.on('adClick')

VAST and IMA. Fired whenever a user clicks an ad to be redirected to its landing page.

Returns an object with the following:

.on('adCompanions')

VAST and IMA. Fired whenever an ad contains companions.

Returns an object with the following:

Every companion will return the following object:

.on('adComplete')

Fired whenever an ad has completed playback.

Returns an object with the following:

.on('adError')

Fired whenever an error prevents the ad from playing.

📘

This may fire multiple times for a single ad tag if Google IMA is being used.

Returns an object with the following at a minimum*:

.on('adImpression')

VAST, IMA. Fired based on the IAB definition of an ad impression. This occurs the instant a video ad begins to play.

Returns an object with the following:

.on('adItem')

Fires when the VAST XML has been parsed, loaded, and is ready for display

Returns an object containing the following content:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{ad_tag_url}",
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "id": "1a2b3c4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "LinearInlineSkippable",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "LinearInlineSkippable ad",
    "creativeAdId": "",
    "adId": "123456789",
    "universalAdId": [{
        ...
    }],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "{linear_ad_video_file_url}"
    },
    "type": "adItem"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "6f5e4d3c2b1a",
    "adPlayId": "6f5e4d3c2b1a",
    "offset": "pre",
    "item": {
        ...
    },
    "type": "adItem"
}

.on('adLoaded')

Fires when the VAST XML has been parsed, loaded, and is ready for display

Returns an object containing the following content:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{ad_tag_url}",
    "adBreakId": "1a3c2b4d5e6f",
    "adPlayId": "1a3c2b4d5e6f",
    "id": "1a3c2b4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "",
    "creativeAdId": "",
    "adId": "232859236",
    "universalAdId": [],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "{linear_ad_video_file_url}"
    },
    "type": "adLoaded"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "offset": "pre",
    "id": "dlsjb0-test",
    "tag": "{ad_tag_url}",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "",
    "adschedule": {
        ...
    },
    "item": {
        ...
    },
    "timeLoading": 57,
    "type": "adLoaded"
}

.on('adManager')

Starting with JW Player 8.8.0, use .on('adsManager')

FreeWheel only. Fires when the ad manager is loaded into the player.

This event allows publishers to integrate additional FreeWheel ad manager functionality before ad playback.

Response

This event returns an object similar to the following:

{
  "adManager": {...},
  "type": "adManager"
}

.on('adMeta')

VAST only. Continuously triggers when new metadata has been received from the ad by the player. Values may vary based on the ad itself.

Returns an object with the following:

.on('adPause')

Fired whenever an ad is paused.

Returns an object with the following:

.on('adPlay')

Fired whenever an ad starts playing or when an ad is unpaused.

Returns an object with the following:

.on('adRequest')

Fired whenever an ad is requested by the player.

Returns an object with the following:

.on('adRequestedContentResume')

(IMA, VAST) Fires when one of the following events occurs: an ad completes, an error is triggered, or the ad is skipped

This event signals the transition back to content playback.

Object returned

{
    "type": "adRequestedContentResume"
}

.on('adSchedule')

VAST only. Fires when the ad schedule is loaded and parsed by the plugin.

Returns an object with the following:

.on('adLoadedXML')

VAST only. Fires when the VAST ad client loads an ad tag. The response contains an XML parameter that exposes the XML downloaded from the tag as well as the same object properties as other ad events, such as adBreakId, adPlayId, adPosition, client, and tag.

.on('adSkipped')

(VAST, IMA) Fired whenever an ad has been skipped.

Returns an object with the following:

.on('adStarted')

(VPAID - VAST, FW | all ads - IMA) This API will trigger when an ad creative signals to our player that it is starting.

Returns an object with the following:

.on('adTime')

Fired while ad playback is in progress.

Returns an object with the following:

.on('adViewableImpression')

VAST and IMA. Fires only when both of the following conditions are met:

• Ad has played for two consecutive seconds
• At least 50% of the player is in the viewport.

Use the adViewableImpression to track the viewability of your ad impressions. The ad viewable impressions metric is comparable to Google's TrueView viewable impression metric.

Returns an object with the following:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{google_ad_tag}",
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "id": "1a2b3c4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "External Linear Inline",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "External Linear Inline ad",
    "creativeAdId": "",
    "adId": "697x312-p",
    "universalAdId": [{
        ...
    }],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        ...
    },
    "type": "adViewableImpression"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "f61a2b3c4d5e",
    "adPlayId": "f61a2b3c4d5e",
    "offset": "pre",
    "id": "f61a2b3c4d5e",
    "tag": "{ad_tag_url}",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Ad System",
    "adschedule": {
        ...
    },
    "adtitle": "VPAID 2 Linear",
    "description": "VPAID 2 Linear Video Ad",
    "adId": "1234567",
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        ...
    },
    "conditionalAdOptOut": false,
    "vastversion": 3,
    "clickThroughUrl": "https://click-through-url.com",
    "mediaFileCompliance": true,
    "mediafile": {
        ...
    },
    "viewable": 1,
    "creativetype": "application/javascript",
    "type": "adViewableImpression"
}

.on('adWarning')

VAST only. Signals a non-fatal warning that is not critical to the playback of an ad.

{
  "message": "Tracking events are missing breakStart, breakEnd, or error for AdBreak",
  "code": 1002,
  "adErrorCode": 70001,
  "type": "adWarning",
  "tag": "{ad_tag_url}"
}

.on('adsManager')

Fires when the ad manager is loaded into the player.

This event allows publishers to integrate additional ad manager functionality before ad playback.

❗️

Using this event to integrate additional functionality could impact ad playback.

Response

This event returns an object similar to the following:

{
  "adsManager": {...},
  "type": "adsManager",
  "videoElement": {}
}

.on('beforeComplete')

Fired just before the player completes playing. Unlike the onComplete event, the player will not have moved on to either showing the replay screen or advancing to the next playlistItem, which makes this the right moment to insert post-roll ads using playAd().

.on('beforePlay')

Fired just before the player begins playing. Unlike the onPlay event, the player will not have begun playing or buffering when triggered, which makes this the right moment to insert preroll ads using playAd().