Advertising Events

🚧

Video ad insertion requires a JWP 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 JWP. 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:

ValueDescription
bidders arrayAn array of all bidders in the current bid request.
bidTimeout numberThe amount of milliseconds it will wait for the bids to return after user clicks to play.
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
floorPriceCents numberFloor price that the return bids need to beat to play.

Not returned when using dfp mediation layer
floorPriceCurrency stringThe currency of the floor price cents value.

Needs to be usd for Facebook. Only used for Facebook bids when mediation layer is set to jwp.
mediationLayerAdServer stringThe mediation layer, which is the decision-maker in what ad to run

Possible Values:
   • dfp
   • jwp
   • jwpdfp
   • jwpspotx
offset stringThe offset of the ad
type stringThe type of the event

This will always return adBidRequest
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

Each bidder object contains the following:

ValueDescription
id numberThe publisher ID used for header bidding for each of the bidder
name stringThe name of the bidder

Possible Values:
See: advertising.bids.bidders[].name


.on('adBidResponse')

Fired when header bidding returns response.

Return an object with the following:

ValueDescription
bidders arrayAn array of all bidders in the current bid request.
bidTimeout numberThe amount of milliseconds it will wait for the bids to return after user clicks to play.
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
floorPriceCents numberFloor price that the return bids need to beat to play.

Not returned when using dfp mediation layer
floorPriceCurrency stringThe currency of the floor price cents value.

Needs to be usd for Facebook. Only used for Facebook bids when mediation layer is set to jwp.
mediationLayerAdServer stringThe mediation layer, which is the decision-maker in what ad to run

Possible Values:
   • dfp
   • jwp
   • jwpdfp
   • jwpspotx
offset stringThe offset of the ad
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
type stringThe type of the event

This will always return adBidResponse
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

Bidder Object

Each bidder object contains the following:

ValueDescription
id numberThe publisher ID used for header bidding for each of the bidder
name stringThe name of the bidder

Possible Values:
   See: advertising.bids.bidders[].name
priceInCents numberThe price of the bid.

Only used when JWP is the mediation layer
result stringThe result of the bidder's bid

Possible Values:
   • bid
   • noBid
   • timeout
tagKey numberThe tagKey of the bid returned.

Only used for SpotX bidder
timeForBidResponse numberTime taken for the bid to return in milliseconds
winner booleanSet to true when the bidder is the winning bid

Possible Values:
   • false
   • true


.on('adBlock')

This event is fired when an ad plugin (Either VAST or Google IMA) is configured inside of the JWP 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.

ValueDescriptionType
-No value returned-


.on('adBreakEnd')

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

Returns an object with the following:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • post
   • pre
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
type stringThe type of the event is firing

This will always return adBreakEnd
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: The player is below 50% or is in an inactive tab
   • 1: The player is at least 50% in view and is in the active tab


.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"
}
ValueDescription
id stringDescriptive name of the ad break
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ad breaks.)
   • post
   • pre
tag stringURL of the ad tag
timeSinceLastAd numberDuration between the current ad break and the saved time of the last ad break

This value will always be less than the advertising.rules.timeBetweenAds value.
type stringThe type of the event is firing

This will always return 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:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • post
   • pre
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
type stringThe type of the event is firing

This will always return adBreakStart
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: The player is below 50% or is in an inactive tab
   • 1: The player is at least 50% in view and is in the active tab


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

ValueDescription
clickThroughUrl stringThe redirect URL
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that is just completed
tag stringThe URL of the ad tag that just completed


.on('adCompanions')

VAST and IMA. Fired whenever an ad contains companions.

Returns an object with the following:

ValueDescription
companions arrayAn array with available companion information
tag stringThe URL of the ad tag that is currently playing

Every companion will return the following object:

ValueDescription
click stringURL to link to when clicking the companion. Only available if the type is static
creativeview arrayAn array of included creativeview event tracking pixels
height numberThe height of the companion in pixels
resource stringThe URL to the static/iframe resource, or the raw HTML content
type stringThe type of the creative: static, iframe, or HTML
width numberThe width of the companion in pixels


.on('adComplete')

Fired whenever an ad has completed playback.

Returns an object with the following:

ValueDescription
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that is just completed
tag stringThe URL of the ad tag that just completed
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1


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

ValueDescription
message stringThe ad error message.

See table below.
tag stringThe URL of the ad tag that produced the error
*Additional adError information may be returned when available.

Possible Error MessagesCauses
ad tag emptyNo ad was available after searching wrapped ad tags
error playing creative404 on a creative file
error loading ad tagAll additional ad errors
invalid ad tagInvalid XML, Improperly formatted VAST syntax
no compatible creativesFLV video creative or VPAID SWF is attempting to play in HTML5 player


.on('adImpression')

Fires based on the IAB definition of an ad impression

This occurs the instant a video ad begins to play.

{
    "client": "dai",
    "viewable": 1,
    "id": "z5bbhua8yw00",
    "adPlayId": "7e8jal5j9y80",
    "adtitle": "External NCA1C1L1 Preroll",
    "adsystem": "GDFP",
    "creativetype": "application/x-mpegURL",
    "linear": "linear",
    "adposition": "pre",
    "type": "adImpression"
}
{
    "client": "freewheel",
    "tag": "placeholder_preroll",
    "freewheel": {
        "ad": {
            "adId": "20747694"
        }
    },
    "adposition": "pre",
    "id": "20747694",
    "linear": "linear",
    "creativetype": "video/mp4",
    "viewable": 1,
    "timeLoading": 752,
    "type": "adImpression"
}
{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "//playertest-cdn.longtailvideo.com/vast-30s-ad.xml?vid_t=sintel",
    "adBreakId": "m26lcvab5a1o",
    "adPlayId": "m26lcvab5a1o",
    "id": "m26lcvab5a1o",
    "ima": {...},
    "adtitle": "",
    "adsystem": "Alex_Vast",
    "creativetype": "video/mp4",
    "duration": 30,
    "linear": "linear",
    "description": "",
    "creativeAdId": "",
    "adId": "232859236",
    "universalAdId": [],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "//content.jwplatform.com/videos/AEhg3fFb-bPwArWA4.mp4"
    },
    "timeLoading": 48,
    "type": "adImpression"
}
{
    "client": "vast",
    "placement": 1,
    "adBreakId": "u73yp6nm93y1",
    "adPlayId": "u73yp6nm93y1",
    "offset": "pre",
    "id": "1bfd53080g7t",
    "tag": "//playertest-cdn.longtailvideo.com/pre-60s.xml",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Alex_Vast",
    "skipoffset": 5,
    "adschedule": {
        "item": 1,
        "breakid": "adbreak1",
        "tags": [
            "//playertest-cdn.longtailvideo.com/pre-60s.xml"
        ],
        "offset": "pre"
    },
    "adtitle": "JW Test Preroll",
    "description": "",
    "adId": "232859236",
    "adVerifications": null,
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        "location": null
    },
    "conditionalAdOptOut": false,
    "vastversion": 2,
    "clickThroughUrl": "//jwplayer.com/",
    "duration": 60,
    "linear": "linear",
    "mediaFileCompliance": false,
    "nonComplianceReasons": [
        "video/mp4 has only 2 qualities"
    ],
    "mediafile": {
        "file": "//content.jwplatform.com/videos/zz4Abp0Z-bPwArWA4.mp4"
    },
    "viewable": 1,
    "creativetype": "video/mp4",
    "categories": [],
    "timeLoading": 154,
    "type": "adImpression"
}
Property Description
adBreakId string Unique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId string From the ad XML, identity of the ad server that provides the creative

Definition from IAB Tech Lab
adPlayId string Unique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition string Position of an ad

Possible Values:
  • mid
  • post
  • pre
adschedule object Settings for the ad break
adsystem string From the ad XML, name of the ad server that returned the ad

Definition from IAB Tech Lab
adtitle string From the ad XML, common name for the ad

Definition from IAB Tech Lab
adVerifications object From the ad XML, lists resources and metadata required to execute third-party measurement code in order to verify creative playback

Definition from IAB Tech Lab
advertiser string From the ad XML, name of the advertiser as defined by the ad serving party

Definition from IAB Tech Lab
advertiserId string From the ad XML, optional identifier for the advertiser, provided by the ad server

Definition from IAB Tech Lab
bidders array (IMA) Bidders which made bids on the ad slot

This is only added if header bidding occurred.

Review the bidder object to see the object properties.
categories array From the ad XML, list of category codes or labels that identifies the ad content categories

Definition from IAB Tech Lab
clickThroughUrl string From the ad XML, URI to the advertiser's site that the media player opens when a viewer clicks the ad

Definition from IAB Tech Lab
client string Ad client that is currently being used

Possible Values:
  • dai
  • freewheel
  • googima
  • vast
conditionalAdOptOut boolean (VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeAdId string From the ad XML, the ad server's unique identifier for the creative

Definition from IAB Tech Lab
creativeId string From the ad XML, identifier of the ad server that provides the creative

Definition from IAB Tech Lab
creativetype string MIME type of the current media file specified in the VAST XML
dealId string From the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition from Google
description string From the ad XML, provides a long ad description

Definition from IAB Tech Lab
duration number From the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition from IAB Tech Lab
freewheel object Contains the unique ad identifier within its ad.adId property
id string Unique ad identifier
ima object Contains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear string Value of the linear attribute of the ad XML

Possible Values:
  • linear: Video ad that interrupts video content playback
  • nonlinear Static display ad that overlays a portion of the player and does not interrupt playback
mediafile | mediaFile object From the ad XML, contains the video file for a linear ad

Definition from IAB Tech Lab
mediaFileCompliance boolean Indicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:
  • .m3u8
  • VPAID
  • At least three quality level per MIME type
nonComplianceReasons array Reasons why mediaFileCompliance has failed
offset number | string Position of an ad

Possible Values:
  • (Midroll) {number in seconds}
  • post
  • pre
placement number Value sent in a bid request that identifies the location of a player in accordance with updated IAB Digital Video Guidelines

Possible Values:
  • 1: Instream
  • 2: Accompanying Content
  • 3: Interstitials
  • 4: No Content / Standalone
This value is sent using the plcmt attribute in Object:Video. For more information, read List: Plcmt Subtypes - Video
request object XML HTTP request to the ad tag URL
response object XML response received from the request
sequence number Returns the sequence number with which the ad is associated
tag string URL of the ad tag
timeLoading number Loading time of the ad in milliseconds
type string Category of player event

This is always adImpression for this event.
universalAdId object From the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition from IAB Tech Lab
vastversion number VAST version reference in the VAST XML
viewable boolean Viewability of the player

Possible Values:
  • 0: Player is not in view.
  • 1: Player is in view.
wcount number Waterfall count
witem number Waterfall index
wrapper array (VAST) Ad systems specified in any utilized ad wrappers

An index value denotes the level of the wrapper.


.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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adsystem stringFrom the ad XML, name of the ad server that returned the ad

Definition derived from IAB Tech Lab
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the VAST XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
item objectPlaylist item that is currently being played as the content
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
sequence numberReturns the sequence number with which the ad is associated
tag stringURL of the ad tag
type stringCategory of the player event

This is always adItem for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1


.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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adschedule objectAd break information
adsystem stringFrom the ad XML, name of the ad server that returned the ad
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the ad XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
item objectPlaylist item that is currently being played as the content
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
sequence numberReturns the sequence number with which the ad is associated
tag stringURL of the ad tag
timeLoading integerTime the ad took to load in milliseconds
type stringCategory of the player event

This is always adLoaded for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1
wcount numberWaterfall count
witem numberWaterfall index


.on('adManager')

Starting with JW 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"
}
ValueDescription
adManager objectObject containing the ad manager configuration
type stringCategory of the player event

This is always adManager for this event.


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

ValueDescription
metadata objectObject containing the metadata from the ad

The values contained within the object will vary based on the ad.


.on('adPause')

Fired whenever an ad is paused.

Returns an object with the following:

ValueDescription
creativetype stringVAST-only The MIME type of the current media file specified in the VAST XML
newstate stringThe new state of the player

This should be "paused"
oldstate stringThe state of the player prior to ad pause
pauseReason 8.7.0+ stringReason ad playback has been paused

Possible Values:
   • clickthrough: Viewer clicked an ad
   • external: Native VPAID controls or jwplayer().pauseAd()
   • interaction: Viewer clicked the pause control on the player
tag stringThe URL of the ad tag that is currently playing.
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable


.on('adPlay')

Fires whenever an ad starts playing or when an ad is unpaused

{
    "client": "dai",
    "viewable": 1,
    "id": "cfau4gxh3q00",
    "adPlayId": "of0i8kj1tkp0",
    "adtitle": "External NCA1C1L1 Preroll",
    "adsystem": "GDFP",
    "creativetype": "application/x-mpegURL",
    "linear": "linear",
    "adposition": "pre",
    "newstate": "playing",
    "oldstate": "playing",
    "type": "adPlay"
}
{
    "oldstate": "buffering",
    "client": "freewheel",
    "tag": "placeholder_preroll",
    "freewheel": {
        "ad": {
            "adId": "17302931"
        }
    },
    "adposition": "pre",
    "id": "17302931",
    "linear": "linear",
    "creativetype": "video/mp4",
    "viewable": 1,
    "sequence": 1,
    "skipoffset": 3,
    "newstate": "playing",
    "playReason": "interaction",
    "type": "adPlay"
}
{
    "oldstate": "buffering",
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "//playertest-cdn.longtailvideo.com/vast-30s-ad.xml",
    "adBreakId": "lbvj8f1bk67a",
    "adPlayId": "lbvj8f1bk67a",
    "id": "lbvj8f1bk67a",
    "ima": {...},
    "adtitle": "",
    "adsystem": "Alex_Vast",
    "creativetype": "video/mp4",
    "duration": 30,
    "linear": "linear",
    "description": "",
    "creativeAdId": "",
    "adId": "232859236",
    "universalAdId": [],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "//content.jwplatform.com/videos/AEhg3fFb-bPwArWA4.mp4"
    },
    "newstate": "playing",
    "playReason": "interaction",
    "type": "adPlay"
}
{
    "oldstate": "buffering",
    "client": "vast",
    "placement": 1,
    "adBreakId": "rtcr7l1md0og",
    "adPlayId": "rtcr7l1md0og",
    "offset": "pre",
    "id": "1njnx9fbk02y",
    "tag": "//playertest-cdn.longtailvideo.com/pre-60s.xml",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Alex_Vast",
    "skipoffset": 5,
    "adschedule": {
        "item": 1,
        "breakid": "adbreak1",
        "tags": [
            "//playertest-cdn.longtailvideo.com/pre-60s.xml"
        ],
        "offset": "pre"
    },
    "adtitle": "JW Test Preroll",
    "description": "",
    "adId": "232859236",
    "adVerifications": null,
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        "location": null
    },
    "conditionalAdOptOut": false,
    "vastversion": 2,
    "clickThroughUrl": "//jwplayer.com/",
    "mediaFileCompliance": false,
    "nonComplianceReasons": [
        "video/mp4 has only 2 qualities"
    ],
    "mediafile": {
        "file": "//content.jwplatform.com/videos/zz4Abp0Z-bPwArWA4.mp4"
    },
    "viewable": 1,
    "creativetype": "video/mp4",
    "categories": [],
    "newstate": "playing",
    "playReason": "interaction",
    "type": "adPlay"
}
Property Description
adBreakId string Unique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId string From the ad XML, identity of the ad server that provides the creative

Definition from IAB Tech Lab
adPlayId string Unique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition string Position of an ad

Possible Values:
  • mid
  • post
  • pre
adschedule object Settings for the ad break
adsystem string From the ad XML, name of the ad server that returned the ad

Definition from IAB Tech Lab
adtitle string From the ad XML, common name for the ad

Definition from IAB Tech Lab
adVerifications object From the ad XML, lists resources and metadata required to execute third-party measurement code in order to verify creative playback

Definition from IAB Tech Lab
advertiser string From the ad XML, name of the advertiser as defined by the ad serving party

Definition from IAB Tech Lab
advertiserId string From the ad XML, optional identifier for the advertiser, provided by the ad server

Definition from IAB Tech Lab
categories array From the ad XML, list of category codes or labels that identifies the ad content categories

Definition from IAB Tech Lab
clickThroughUrl string From the ad XML, URI to the advertiser's site that the media player opens when a viewer clicks the ad

Definition from IAB Tech Lab
client string Ad client that is currently being used

Possible Values:
  • dai
  • freewheel
  • googima
  • vast
conditionalAdOptOut boolean (VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeAdId string From the ad XML, the ad server's unique identifier for the creative

Definition from IAB Tech Lab
creativeId string From the ad XML, identifier of the ad server that provides the creative

Definition from IAB Tech Lab
creativetype string MIME type of the current media file specified in the VAST XML
dealId string From the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition from Google
description string From the ad XML, provides a long ad description

Definition from IAB Tech Lab
duration number From the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition from IAB Tech Lab
freewheel object Contains the unique ad identifier within its ad.adId property
id string Unique ad identifier
ima object Contains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear string Value of the linear attribute of the ad XML

Possible Values:
  • linear: Video ad that interrupts video content playback
  • nonlinear Static display ad that overlays a portion of the player and does not interrupt playback
mediafile | mediaFile object From the ad XML, contains the video file for a linear ad

Definition from IAB Tech Lab
newstate string New state of the player

This value will be playing.
offset number | string Position of an ad

Possible Values:
  • (Midroll) {number in seconds}
  • post
  • pre
oldstate string State of the player prior to ad play
placement number Value sent in a bid request that identifies the location of a player in accordance with updated IAB Digital Video Guidelines

Possible Values:
  • 1: Instream
  • 2: Accompanying Content
  • 3: Interstitials
  • 4: No Content / Standalone
This value is sent using the plcmt attribute in Object:Video. For more information, read List: Plcmt Subtypes - Video
playReason string Reason for the play

Possible Values:
  • autostart
  • external: API usage
  • interaction: Click, touch, keyboard
  • playlist: Auto-advancing
  • related-audio: Auto-advancing a Recommendations playlist
  • related-interaction: Interaction to go to a Recommendations playlist item
request object XML HTTP request to the ad tag URL
response object XML response received from the request
sequence number Returns the sequence number with which the ad is associated
skipoffset number If not present in the VAST file, skip offset value added to static VAST ads
tag string URL of the ad tag
type string Category of player event

This is always adPlay for this event.
universalAdId object From the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition from IAB Tech Lab
vastversion number VAST version reference in the VAST XML
viewable boolean Viewability of the player

Possible Values:
  • 0: Player is not in view.
  • 1: Player is in view.
wcount number Waterfall count
witem number Waterfall index


.on('adRequest')

Fired whenever an ad is requested by the player.

Returns an object with the following:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • pre
   • post
client stringThe client that is currently being used

Possible Values:
   • freewheel
   • googima
   • vast
offset number | stringAn ad's position.

Will return a number (in seconds) of a midroll's position

Possible Values:
   • {number}
   • post
   • pre
tag stringThe URL of the ad tag that is being requested
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable


.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"
}
ValueDescription
type stringType of event

This will always return adRequestedContentResume.


.on('adSchedule')

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

Returns an object with the following:

ValueDescription
adbreaks arrayAn array of objects, each containing information about an ad break.
client stringThe ad client in use for the ad schedule

Possible Values:
   • freewheel
   • googima
   • vast
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
tag stringThe URL of the ad schedule.


.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')

Fires whenever an ad has been skipped

{
    "client": "freewheel",
    "tag": "placeholder_preroll",
    "freewheel": {
        "ad": {
            "adId": "17302931"
        }
    },
    "adposition": "pre",
    "id": "17302931",
    "linear": "linear",
    "creativetype": "video/mp4",
    "viewable": 1,
    "sequence": 1,
    "podcount": 2,
    "skipoffset": 3,
    "type": "adSkipped"
}
{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "//pubads.g.doubleclick.net/gampad/ads...etc",
    "adBreakId": "wdglp2rmb9qe",
    "adPlayId": "wdglp2rmb9qe",
    "id": "wdglp2rmb9qe",
    "ima": {...},
    "adtitle": "External NCA1C1L1 LinearInlineSkippable",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "External NCA1C1L1 LinearInlineSkippable ad",
    "creativeAdId": "",
    "adId": "697200496",
    "universalAdId": [
        {
            "universalAdIdRegistry": "GDFP",
            "universalAdIdValue": "57860459056"
        }
    ],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": ""
    },
    "type": "adSkipped"
}
{
    "client": "vast",
    "placement": 1,
    "adBreakId": "mlhd5f15zf6p",
    "adPlayId": "mlhd5f15zf6p",
    "offset": "pre",
    "id": "tfdpe61g5v1f",
    "tag": "//playertest-cdn.longtailvideo.com/pre-60s.xml",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Alex_Vast",
    "skipoffset": 5,
    "adschedule": {
        "item": 1,
        "breakid": "adbreak1",
        "tags": [
            "//playertest-cdn.longtailvideo.com/pre-60s.xml"
        ],
        "offset": "pre"
    },
    "adtitle": "JW Test Preroll",
    "description": "",
    "adId": "232859236",
    "adVerifications": null,
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        "location": null
    },
    "conditionalAdOptOut": false,
    "vastversion": 2,
    "clickThroughUrl": "//jwplayer.com/",
    "duration": 60,
    "mediaFileCompliance": false,
    "nonComplianceReasons": [
        "video/mp4 has only 2 qualities"
    ],
    "mediafile": {
        "file": "//content.jwplatform.com/videos/zz4Abp0Z-bPwArWA4.mp4"
    },
    "viewable": 1,
    "creativetype": "video/mp4",
    "categories": [],
    "position": 5.777861,
    "watchedPastSkipPoint": 0.7778609999999997,
    "type": "adSkipped"
}
Property Description
adBreakId string Unique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId string From the ad XML, identity of the ad server that provides the creative

Definition from IAB Tech Lab
adPlayId string Unique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition string Position of an ad

Possible Values:
  • mid
  • post
  • pre
adschedule object Settings for the ad break
adsystem string From the ad XML, name of the ad server that returned the ad

Definition from IAB Tech Lab
adtitle string From the ad XML, common name for the ad

Definition from IAB Tech Lab
adVerifications object From the ad XML, lists resources and metadata required to execute third-party measurement code in order to verify creative playback

Definition from IAB Tech Lab
advertiser string From the ad XML, name of the advertiser as defined by the ad serving party

Definition from IAB Tech Lab
advertiserId string From the ad XML, optional identifier for the advertiser, provided by the ad server

Definition from IAB Tech Lab
categories array From the ad XML, list of category codes or labels that identifies the ad content categories

Definition from IAB Tech Lab
clickThroughUrl string From the ad XML, URI to the advertiser's site that the media player opens when a viewer clicks the ad

Definition from IAB Tech Lab
client string Ad client that is currently being used

Possible Values:
  • freewheel
  • googima
  • vast
conditionalAdOptOut boolean (VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeAdId string From the ad XML, the ad server's unique identifier for the creative

Definition from IAB Tech Lab
creativeId string From the ad XML, identifier of the ad server that provides the creative

Definition from IAB Tech Lab
creativetype string MIME type of the creative
dealId string From the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition from Google
description string From the ad XML, provides a long ad description

Definition from IAB Tech Lab
duration number From the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition from IAB Tech Lab
freewheel object Contains the unique ad identifier within its ad.adId property
id string Unique ad identifier
ima object Contains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear string Value of the linear attribute of the ad XML

Possible Values:
  • linear: Video ad that interrupts video content playback
  • nonlinear Static display ad that overlays a portion of the player and does not interrupt playback
mediafile | mediaFile object From the ad XML, contains the video file for a linear ad

Definition from IAB Tech Lab
mediaFileCompliance boolean Indicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:
  • .m3u8
  • VPAID
  • At least three quality level per MIME type
nonComplianceReasons array Reasons why mediaFileCompliance has failed
offset number | string Position of an ad

Possible Values:
  • (Midroll) {number in seconds}
  • post
  • pre
placement number Value sent in a bid request that identifies the location of a player in accordance with updated IAB Digital Video Guidelines

Possible Values:
  • 1: Instream
  • 2: Accompanying Content
  • 3: Interstitials
  • 4: No Content / Standalone
This value is sent using the plcmt attribute in Object:Video. For more information, read List: Plcmt Subtypes - Video
podcount number Total number of ads in the pod
position number Current playback position in the ad creative in seconds
request object XML HTTP request to the ad tag URL
response object XML response received from the request
sequence number Returns the sequence number with which the ad is associated
skipoffset number If not present in the VAST file, skip offset value added to static VAST ads
tag string URL of the ad tag
type string Category of player event

This is always adSkipped for this event.
universalAdId object From the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition from IAB Tech Lab
vastversion number VAST version reference in the VAST XML
viewable boolean Viewability of the player

Possible Values:
  • 0: Player is not in view.
  • 1: Player is in view.
watchedPastSkipPoint number Time that elapsed while the ad was skippable before the user skipped it
wcount number Waterfall count
witem number Waterfall index

Returns an object with the following:

ValueDescription
client stringThe client that is currently being used

Possible Values:
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that was skipped
tag stringThe URL of the ad tag that was skipped


.on('adStarted')

(VAST [VPAID], FreeWheel [VPAID], IMA [All ads]) Fires when an ad creative signals to the JWP player that it is starting

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "//playertest-cdn.longtailvideo.com/vpaid2-jwp-30s.xml?vid_t=Bunny",
    "adBreakId": "179y6cu228me",
    "adPlayId": "179y6cu228me",
    "id": "179y6cu228me",
    "ima": {...},
    "adtitle": "VPAID 2 Linear",
    "adsystem": "Ad System",
    "creativetype": "application/javascript",
    "duration": 30,
    "linear": "linear",
    "description": "VPAID 2 Linear Video Ad",
    "creativeAdId": "",
    "adId": "1234567",
    "universalAdId": [],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "//playertest.longtailvideo.com/vpaid-2-player-test.js"
    },
    "type": "adStarted"
}
{
    "client": "vast",
    "placement": 1,
    "adBreakId": "hd7kj31r2jpu",
    "adPlayId": "hd7kj31r2jpu",
    "offset": "pre",
    "id": "1020ed21wj9r",
    "tag": "//playertest-cdn.longtailvideo.com/vast/adpod-first-vpaid.xml",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Ad System",
    "wrapperAdSystem": [
        "Alex_Vast",
        "Alex_Vast"
    ],
    "wrappedTags": [
        "https://playertest.longtailvideo.com/vpaid2-jwp-30s.xml",
        "//playertest.longtailvideo.com/pre.xml",
        "//playertest.longtailvideo.com/mid.xml"
    ],
    "wrapperAdIds": [
        "lr3"
    ],
    "adschedule": {
        "item": 1,
        "tags": [
            "//playertest-cdn.longtailvideo.com/vast/adpod-first-vpaid.xml"
        ],
        "offset": "pre"
    },
    "adtitle": "VPAID 2 Linear",
    "description": "VPAID 2 Linear Video Ad",
    "adId": "1234567",
    "adVerifications": null,
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        "location": null
    },
    "conditionalAdOptOut": false,
    "vastversion": 3,
    "clickThroughUrl": "http://google.com",
    "mediaFileCompliance": true,
    "mediafile": {
        "file": "//playertest.longtailvideo.com/vpaid-2-player-test.js"
    },
    "viewable": 1,
    "podcount": 3,
    "creativetype": "application/javascript",
    "categories": [],
    "type": "adStarted"
}
Property Description
adBreakId string Unique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId string From the ad XML, identity of the ad server that provides the creative

Definition from IAB Tech Lab
adPlayId string Unique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition string Position of an ad

Possible Values:
  • mid
  • post
  • pre
adschedule object Settings for the ad break
adsystem string From the ad XML, name of the ad server that returned the ad

Definition from IAB Tech Lab
adtitle string From the ad XML, common name for the ad

Definition from IAB Tech Lab
adVerifications object From the ad XML, lists resources and metadata required to execute third-party measurement code in order to verify creative playback

Definition from IAB Tech Lab
advertiser string From the ad XML, name of the advertiser as defined by the ad serving party

Definition from IAB Tech Lab
advertiserId string From the ad XML, optional identifier for the advertiser, provided by the ad server

Definition from IAB Tech Lab
categories array From the ad XML, list of category codes or labels that identifies the ad content categories

Definition from IAB Tech Lab
clickThroughUrl string From the ad XML, URI to the advertiser's site that the media player opens when a viewer clicks the ad

Definition from IAB Tech Lab
client string Ad client that is currently being used

Possible Values:
  • freewheel
  • googima
  • vast
conditionalAdOptOut boolean (VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeAdId string From the ad XML, the ad server's unique identifier for the creative

Definition from IAB Tech Lab
creativeId string From the ad XML, identifier of the ad server that provides the creative

Definition from IAB Tech Lab
creativetype string MIME type of the VPAID creative
dealId string From the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition from Google
description string From the ad XML, provides a long ad description

Definition from IAB Tech Lab
duration number From the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition from IAB Tech Lab
freewheel object Contains the unique ad identifier within its ad.adId property
id string Unique ad identifier
ima object Contains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear string Value of the linear attribute of the ad XML

Possible Values:
  • linear: Video ad that interrupts video content playback
  • nonlinear Static display ad that overlays a portion of the player and does not interrupt playback
mediafile | mediaFile object From the ad XML, contains the video file for a linear ad

Definition from IAB Tech Lab
mediaFileCompliance boolean Indicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:
  • .m3u8
  • VPAID
  • At least three quality level per MIME type
offset number | string Position of an ad

Possible Values:
  • (Midroll) {number in seconds}
  • post
  • pre
placement number Value sent in a bid request that identifies the location of a player in accordance with updated IAB Digital Video Guidelines

Possible Values:
  • 1: Instream
  • 2: Accompanying Content
  • 3: Interstitials
  • 4: No Content / Standalone
This value is sent using the plcmt attribute in Object:Video. For more information, read List: Plcmt Subtypes - Video
podcount number Total number of ads in the pod
request object XML HTTP request to the ad tag URL
response object XML response received from the request
sequence number Returns the sequence number with which the ad is associated
tag string URL of the ad tag
type string Category of player event

This is always adStarted for this event.
universalAdId object From the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition from IAB Tech Lab
vastversion number VAST version reference in the VAST XML
viewable boolean Viewability of the player

Possible Values:
  • 0: Player is not in view.
  • 1: Player is in view.
wcount number Waterfall count
witem number Waterfall index


.on('adTime')

Fires while ad playback is in progress

{
    "client": "dai",
    "viewable": 1,
    "id": "cz1a5nqne800",
    "adPlayId": "6xszr0hh2v90",
    "adtitle": "External NCA1C1L3 Midroll",
    "adsystem": "GDFP",
    "creativetype": "application/x-mpegURL",
    "linear": "linear",
    "adposition": "mid",
    "position": 0.48821499999999673,
    "duration": 10.01,
    "type": "adTime"
}
{
    "client": "freewheel",
    "tag": "placeholder_midroll",
    "freewheel": {
        "ad": {
            "adId": "17302933"
        }
    },
    "adposition": "mid",
    "id": "17302933",
    "linear": "linear",
    "creativetype": "video/mp4",
    "viewable": 1,
    "sequence": 1,
    "podcount": 2,
    "skipoffset": 3,
    "position": 3.393394,
    "duration": 30,
    "type": "adTime"
}
{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "//pubads.g.doubleclick.net/gampad/ads?sz=640x480...etc",
    "adBreakId": "1n822171mob5",
    "adPlayId": "1n822171mob5",
    "id": "1n822171mob5",
    "ima": {...},
    "adtitle": "External NCA1C1L1 LinearInlineSkippable",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "External NCA1C1L1 LinearInlineSkippable ad",
    "creativeAdId": "",
    "adId": "697200496",
    "universalAdId": [
        {
            "universalAdIdRegistry": "GDFP",
            "universalAdIdValue": "57860459056"
        }
    ],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": ""
    },
    "position": 0,
    "type": "adTime"
}
{
    "client": "vast",
    "placement": 1,
    "adBreakId": "mlhd5f15zf6p",
    "adPlayId": "mlhd5f15zf6p",
    "offset": "pre",
    "id": "tfdpe61g5v1f",
    "tag": "//playertest-cdn.longtailvideo.com/pre-60s.xml",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Alex_Vast",
    "skipoffset": 5,
    "adschedule": {
        "item": 1,
        "breakid": "adbreak1",
        "tags": [
            "//playertest-cdn.longtailvideo.com/pre-60s.xml"
        ],
        "offset": "pre"
    },
    "adtitle": "JW Test Preroll",
    "description": "",
    "adId": "232859236",
    "adVerifications": null,
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        "location": null
    },
    "conditionalAdOptOut": false,
    "vastversion": 2,
    "clickThroughUrl": "//jwplayer.com/",
    "duration": 60,
    "mediaFileCompliance": false,
    "nonComplianceReasons": [
        "video/mp4 has only 2 qualities"
    ],
    "mediafile": {
        "file": "//content.jwplatform.com/videos/zz4Abp0Z-bPwArWA4.mp4"
    },
    "viewable": 1,
    "creativetype": "video/mp4",
    "position": 5.777861,
    "type": "adTime"
}
Property Description
adBreakId string Unique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId string From the ad XML, identity of the ad server that provides the creative

Definition from IAB Tech Lab
adPlayId string Unique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition string Position of an ad

Possible Values:
  • mid
  • post
  • pre
adschedule object Settings for the ad break
adsystem string From the ad XML, name of the ad server that returned the ad

Definition from IAB Tech Lab
adtitle string From the ad XML, common name for the ad

Definition from IAB Tech Lab
adVerifications object From the ad XML, lists resources and metadata required to execute third-party measurement code in order to verify creative playback

Definition from IAB Tech Lab
advertiser string From the ad XML, name of the advertiser as defined by the ad serving party

Definition from IAB Tech Lab
advertiserId string From the ad XML, optional identifier for the advertiser, provided by the ad server

Definition from IAB Tech Lab
clickThroughUrl string From the ad XML, URI to the advertiser's site that the media player opens when a viewer clicks the ad

Definition from IAB Tech Lab
client string Ad client that is currently being used

Possible Values:
  • dai
  • freewheel
  • googima
  • vast
conditionalAdOptOut boolean (VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeAdId string From the ad XML, the ad server's unique identifier for the creative

Definition from IAB Tech Lab
creativeId string From the ad XML, identifier of the ad server that provides the creative

Definition from IAB Tech Lab
creativetype string MIME type of the current media file specified in the VAST XML
dealId string From the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition from Google
description string From the ad XML, provides a long ad description

Definition from IAB Tech Lab
duration number From the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition from IAB Tech Lab
freewheel object Contains the unique ad identifier within its ad.adId property
id string Unique ad identifier
ima object Contains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear string Value of the linear attribute of the ad XML

Possible Values:
  • linear: Video ad that interrupts video content playback
  • nonlinear Static display ad that overlays a portion of the player and does not interrupt playback
mediafile | mediaFile object From the ad XML, contains the video file for a linear ad

Definition from IAB Tech Lab
mediaFileCompliance boolean Indicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:
  • .m3u8
  • VPAID
  • At least three quality level per MIME type
nonComplianceReasons array Reasons why mediaFileCompliance has failed
offset number | string Position of an ad

Possible Values:
  • (Midroll) {number in seconds}
  • post
  • pre
placement number Value sent in a bid request that identifies the location of a player in accordance with updated IAB Digital Video Guidelines

Possible Values:
  • 1: Instream
  • 2: Accompanying Content
  • 3: Interstitials
  • 4: No Content / Standalone
This value is sent using the plcmt attribute in Object:Video. For more information, read List: Plcmt Subtypes - Video
position number Current playback position in the ad creative in seconds
request object XML HTTP request to the ad tag URL
response object XML response received from the request
sequence number Returns the sequence number with which the ad is associated
skipoffset number If not present in the VAST file, skip offset value added to static VAST ads
tag string URL of the ad tag
type string Category of player event

This is always adTime for this event.
universalAdId object From the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition from IAB Tech Lab
vastversion number VAST version reference in the VAST XML
viewable boolean Viewability of the player

Possible Values:
  • 0: Player is not in view.
  • 1: Player is in view.
wcount number Waterfall count
witem number Waterfall index


.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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adschedule objectAd break information
adsystem stringFrom the ad XML, name of the ad server that returned the ad

Definition derived from IAB Tech Lab
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
advertiserId stringFrom the ad XML, optional identifier for the advertiser, provided by the ad server

Definition derived from IAB Tech Lab
clickThroughUrl stringFrom the ad XML, URI to the advertiser’s site that the media player opens when a viewer clicks the ad

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
conditionalAdOptOut boolean(VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeId stringFrom the ad XML, identifier of the ad server that provides the creative

Definition derived from IAB Tech Lab
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the VAST XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JWP passes to the IMA SDK when requesting an ad
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediafile | mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
mediaFileCompliance booleanIndicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:

   • .m3u8
   • VPAID
   • At least three quality level per MIME type
offset stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
request objectXML HTTP request to the ad tag URL
response objectXML response received from the request
sequence numberReturns the sequence number with which the ad is associated
tag stringURL of the ad tag
type stringCategory of the player event

This is always adViewabilityImpression for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
vastversion numberFrom the ad XML, official version with which the VAST response is compliant

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1
wcount numberWaterfall count
witem numberWaterfall index


.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}"
}
ValueDescription
adErrorCode numberJWP ad warning code
code numberVAST warning code
message stringAd error message
tag stringURL of the ad tag that produced the error
type stringCategory of player event

This is always adWarning for this event.


.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": {}
}
ValueDescription
adsManager objectObject containing the ad manager configuration

See Google's and FreeWheel's documentation for the properties returned by the respective SDK.
type stringCategory of the player event

This is always adsManager for this event.
videoElement object(IMA only) Video tag used for playback


.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().

ValueDescriptionType
-No value returned-


.on('beforePlay')

Fires before any of the following occur:

  • Initial playback of a single media or individual playlist item begins.
  • After a pause, media playback resumes initiated by a viewer or other mechanism.

💡

Since this event fires before .on('play'), use this event to trigger calling loadAdTag(tag) or loadAdTag(xml) to play a preroll ad when the state is idle.

{
    "playReason": "interaction",
    "state": "idle",
    "viewable": 1,
    "type": "beforePlay"
}
Value Description
playReason string Reason for the play

Possible Values:
  • autostart
  • external: API usage
  • interaction: Click, touch, keyboard
  • playlist: Auto-advancing
  • related-audio: Auto-advancing a Recommendations playlist
  • related-interaction: Interaction to go to a Recommendations playlist item
state string Playback state when the event fires

Possible Values:
  • idle Occurs before initial playback or when switching between playlist items
  • paused Occurs when playback has been resumed on a single media item
type string Category of the event

This value is always beforePlay.
viewable boolean Viewability of the player container

Possible Values:
  • 0: Player container is not in view
  • 1: Player container is in view