Platform DocsPlayers DocsRelease Notes
API Reference
System StatusSubmit a CaseDashboard LoginCompany Site

Advertising


🚧

Since any changes made to the advertising object override any advertising settings made in the dashboard, be sure to include all existing advertising dashboard configurations within the advertising object.

This object configures the video advertising capabilities of JW Player and overrides advertising settings configured in the dashboard. If no schedule is specified, the ad will play as a preroll by default.

Property Description
client* string (Required) Ad client that will be used to display advertisements

Possible Values:
  • dai: Use the Google IMA SDK for dynamic ad insertion
  • freewheel: Use the Freewheel client
  • googima: Use the Google IMA SDK,required for certain ad tags
  • vast: Use the JWP VAST client
outstream* 8.6.0+ boolean (Required for outstream only) Property enabling outstream functionality

Possible Values:
  • true: Enables outstream functionality
  • false: Disables outstream functionality
adTagParameters 8.18.3+ object (DAI) Adds custom parameter key value pairs
adscheduleid string (Recommended) Unique identifier for an ad (break) schedule

This ID is located on the Advanced tab of the Ad Schedule Detail page. If you do not have ad schedules created via the dashboard, a randomly-generated, eight character, alpha-numeric value can be set.
admessage < 8.6.0 string Text that displays during ad playback

WARNING: Starting with JW 8.6.0, use the intl object to set this property.

Default: The ad will end in xx seconds
allowedOmidVendors 8.20.0+ array (VAST) Defines allowed OMID vendors

Possible Values:
  • If not set or set as an empty array, all vendors can run.
  • If set, only the resources from the listed vendors can run.

All failures to run verification will be noted accordingly to the ad server.
autoplayadsmuted boolean For inline players that start muted when viewed on mobile devices, allows ads to play muted
bids object (IMA, VAST) Enables Player Bidding with the given settings and bidders

See: advertising.bids
clearAdsOnComplete object Determines whether an ad schedule block will be cleared during media replay or seek

Possible Values:
  • false: (Default) Maintains an ad schedule block when a replay or seek occurs
  • true: Clears an ad schedule block so that when a replay or seek occurs, ads won't be shown
companiondiv object (IMA, VAST) Gives information to the player related to which div(s) to populate with companion ads

See: advertising.companiondiv
conditionaladoptout boolean (VPAID-only - VAST) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response

Default: false
creativeTimeout number (VAST) In milliseconds, the maximum amount of time between the VAST XML being returned and the adStart event before timing out

Default: 15000
cuetext < 8.6.0 string Text that appears when a user mouses over a scheduled advertisement

WARNING: Starting with JW 8.6.0, use the intl object to set this property.

Default: Advertisement
duration number (FreeWheel) FreeWheel-provided length of the content
enablePPS 8.34.3+ boolean Enables Google Publisher Provided Signals*, automatically passing IAB contextual segments through the ad tag to improve programmatic monetization

When using this feature, note the following:
  • JWP will attempt to contextualize videos, but not all videos will have the IAB contextual segments passed through Google PPS.
  • If the &ppsj query parameter is defined in the ad tag, JWP will not override the value.
* Google Publisher Provided Signals needs to be enabled by JWP. Contact your JWP account representative to opt in.
endstate 8.6.0+ string (Outstream only) Player behavior after all ads within the ad break have played

Possible Values:
  • suspended: (Default) A gray background without controls remains.
  • close: The player gradually closes.
forceNonLinearFullSlot boolean (IMA) For forcing nonlinear ads to be fullsot ads rather than overlays
freewheel object (FreeWheel) FreeWheel ad client settings

See: advertising.freewheel
fwassetid string (FreeWheel) FreeWheel identifier for content configured in FreeWheel MRM

See: advertising.freewheel
loadVideoTimeout number (FreeWheel, IMA) In milliseconds, the maximum amount of time between the VAST XML being returned and the adstart event before timing out

Default: 15000
locale string (IMA) Valid two-letter language code for localization of skip-button language
maxRedirects number (IMA) Maximum number of redirects the player should follow before timing out

Default: 4
omidSupport 8.20.2+ string (IMA, VAST) Configures OMID support

Possible Values:
  • auto: (VAST default) Loads the OMID script when a parsed ad XML contains a verification node
  • disabled: (IMA default) Prevents the OMID script from ever loading
  • enabled: Always loads the OMID script as soon as the VAST plugin is loaded; for IMA, enables OMID support
placement 8.10.0+ string (IMA, VAST) Value sent in a bid request that identifies the location of a player

This value provides advertisers with more information before bidding for a video ad opportunity.

Possible Values:
  • instream: (Default)
  • article: (Outstream only default)
  • banner
  • feed
  • floating
  • interstitial
  • slider
podmessage < 8.6.0 string (VAST) Text that displays during playback of an ad pod

Use __AD_POD_CURRENT__ to denote the currently playing item in the pod and __AD_POD_LENGTH__ for the total number of ads in the pod.

WARNING: Starting with JW 8.6.0, use the intl object to set this property.

Default: Ad xx of yy.
ppid 8.13.3+ string (IMA) Pass a publisher provided ID to the IMA SDK
preloadAds boolean (IMA, VAST) Pre-requests ad response for an ad break

WARNING: By setting this property to true, you run the risk of reducing the fill rate for programmatic ads.

Default: false
repeat 8.6.0+ boolean (Outstream) Controls whether ads play once or continuously

Possible Values:
  • false: (Default) After all ads play once, the player enters into an endstate.
  • true: All ads within the ad break repeat until the viewer or an API call interacts with the player. Unless an ad request fails, the player never enters into an endstate.

Default: false
requestFilter function (VAST) Function that replaces the XMLHttpRequest used to request the ad tag

The function takes one parameter: the request.

Possible Values:
  • request.url: URL being requested
  • request.xhr: XMLHttpRequest instance

    Modify request.xhr or replace it by returning an object that implements open and send. Invoke xhr.onreadystatechange or xhr.onerror callbacks to complete the request. Invoke xhr.abort to receive abort requests from the player.

    For more information on XMLHttpRequest, visit MDN.

    You must return xhr from the function.
requestTimeout number For VAST, the maximum amount of time, in milliseconds, between the start of the ad break and a returned VAST file before timing out.

For IMA and Freewheel, the maximum amount of time, in milliseconds, between the start of the ad break and the ad impression being fired.

Defaults:
  • 5000 (VAST)
  • 10000 (IMA)
  • 15000 (FW)
rules object (IMA, VAST) Enables ad rules with the given settings and bidders

See: advertising.rules
schedule array | string Loads an ad schedule from an external JSON block (array) or VAMP XML (string)

See: advertising.schedule
skipmessage < 8.6.0 string (FreeWheel, VAST) Used to provide a customized countdown message

WARNING: Starting with JW 8.6.0, use the intl object to set this property.

Default: Skip ad in xx
skipoffset number (FreeWheel, VAST) If not present in the VAST file, adds a skip offset to static VAST ads
skiptext < 8.6.0 string (FreeWheel, VAST) Sets the text of the Skip button after the countdown is over

WARNING: Starting with JW 8.6.0, use the intl object to set this property.

Default: Skip
tag array | string When a string, URL of the ad tag for VAST and IMA plugins, or a string place holder for FreeWheel

(IMA, VAST) When an array, URLs of the VAST ad tags to be used as fallbacks in the event that one or multiple ad tags fail to render
  • Oustream: (Required)
  • Player Bidding: (Required) This is used as a fallback tag when using Player Bidding.
When a VAST tag is used, ad tag targeting macros can be added to define features such as GDPR consent.

Do not use this property and advertising.vastxml within the same ad break.

advertising.schedule is ignored if this option is set.

WARNING: If your ad tag uses a VMAP XML template, use the advertising.schedule property.
trackingFilter function (VAST) Function that can be used to filter out a tracking pixel URL so that it is not sent

The function takes one parameter, the tracker URL to be filtered out.

You must return false from the function to cancel the default behavior.
truncateMacros boolean (IMA) Truncates macro values to 1000 characters

Setting this option to false will not truncate the macro value to 1000 characters but GAM still has a limit of 4096 characters.

Default: true
vastLoadTimeout number (IMA) In milliseconds, the maximum amount of time between the ad request and a returned VAST file before timing out

Default: 10000
vastxml string (VAST) VAST XML ad tag that is requested during the configured ad break

Do not use this property and advertising.tag within the same ad break.

advertising.schedule is ignored if this option is set
vpaidcontrols boolean (IMA, VAST) For forcing controls to show for VPAID ads

If the VPAID creative has built-in controls, showing the controls may be redundant.
vpaidmode string (IMA VPAID-only)

Possible Values:
  • insecure: (Default) The VPAID ad will load in a friendly iFrame. This allows the ad access to the site via javascript Not supported in Freewheel
  • disabled: VPAID ads will not play and an error will be returned if VPAID is requested
  • enabled: VPAID is enabled using a cross domain iFrame. The VPAID ad cannot access the site. VPAID ads that depend on friendly iFrame access may not play
withCredentials 8.13.0+ boolean Indicates if Access-Control requests for ad tags are made using credentials such as cookies, authorization headers, or TLS client certificates

Possible Values:
  • true: (Default) The player requests an ad tag with credentials. If the request fails, the player makes a second request without credentials.
  • false: The player makes a single ad request without credentials.

advertising.bids

Use this property to enable and configure Player Bidding with supported bidders.

jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4", 
    "advertising": {
        ...
        "bids": {
            "bidOnBreaks": 3,
            "settings": {...},
            "bidders": [...],
            "ortbParams": {...}
        },
    ...
    }
});
Property Description
bidders* array (Required) Defines each bidding partner

See: advertising.bid.bidders
settings* object (Required) Defines the mediation layer, floor price, and timeout

See: advertising.bid.bidders
bidOnBreaks number Number of ad breaks for which bid requests are sent

NOTE: For content with more than three ad breaks, change the default setting to 3 and adjust this value depending on performance.

By default, a bid request is made for each ad break.
ortbParams object OpenRTB and Advertising Common Object Model (AdCOM) data included in the OpenRTB bid request

See: advertising.bid.ortbParams

advertising.bids.bidders[]

In the expandable sections below, you can find code samples and properties for each bidder. Click the bidder's name to view its information.

Configure the properties according to the provided settings.

JWDemand 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "jwdemand",
                "siteId": "KbJ3oU3m",
                "placementId": "24399793",
                "publisherId": "cpVDGgDj"
            }]
        }
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (jwdemand)
placementId* integer(Required) Xandr placement ID
publisherId* string(Required) JW account ID
propertyId* string(Required) JW property (site) ID
Azerion 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "improvedigital",
                "placementId": 1111
            }]
        }
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (improvedigital)
placementId* integer(Required) Azerion placement ID
Connatix 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "connatix",
                "placementId": "{placementId}"
            }]
        }
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (connatix)
placementId* integer(Required) Connatix placement ID
Criteo 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                    "name": "criteo",
                    "networkId": 1111,
                    "zoneId": 12345
            }]
        }
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (criteo)
networkId* integer(Required) Criteo network ID
zoneId* integer(Required) Criteo zone ID
Emodo 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "Axonix",
                "supplyId": "1234567"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (Amonix)
supplyId* string(Required) Supply UUID provided by Emodo
EMX 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{section_id}",
                "name": "EMX",
                "pubid": "{publisher_id}"
            }]
        }
        ...
    }
});
PropertyDescription
id* string(Required) EMX Digital tag ID
name* string(Required) Ad partner from which the bid is received (EMX)
Equativ 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "formatId": 1234,
                "name": "SmartAdServer",
                "networkId": 12345,
                "pageId": 1234,
                "siteId": "temp1234"
            }]
        },
        ...
    }
});
PropertyDescription
formatId* integer(Required) Equativ placement format ID

If not provided by Equativ, use any number.
name* string(Required) Ad partner from which the bid is received (SmartAdServer)
networkId* integer(Required) Equativ network identifier
pageId* integer(Required) Equativ placement page ID

If not provided by Equativ, use any number.
siteId* string(Required) Equativ placement site ID

If not provided by Equativ, use any integer.
iMDS 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{placement_id}",
                "name": "SynacorMedia",
                "pubid": "{seat_id}"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) iMDS placement ID or tag ID
name* string(Required) Ad partner from which the bid is received (SynacorMedia)
pubid* string(Required) iMDS seat ID

This will be the same for all ad units.
Index Exchange 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{section_id}",
                "name": "IndexExchange"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) Index Exchange site ID

An IX-specific identifier that is associated with this ad unit.
name* string(Required) Ad partner from which the bid is received (IndexExchange)
Kargo 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "kargo",
                "placementId": "a12345"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (kargo)
placementId* string(Required) Kargo placement ID
Magnite 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "Rubicon",
                "pubid": "{account_id}",
                "siteId": "{site_id}",
                "zoneId": "{zone_id}"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (Rubicon)
pubid* string(Required) Magnite publisher account ID
siteId* string(Required) Magnite site ID
zoneId* string(Required) Magnite zone ID
Media.net 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{crid}",
                "name": "MediaNet",
                "pubid": "{cid}"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) Media.net cid customer ID
name* string(Required) Ad partner from which the bid is received (MediaNet)
pubid* string(Required) Media.net crid placement ID
OpenX 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{unit}",
                "name": "OpenX",
                "delDomain": "{del_domain}"
            }]
        },
        ...
    }
});
PropertyDescription
delDomain* string(Required) OpenX delivery domain
id* string(Required) OpenX unit ad unit ID
name* string(Required) Ad partner from which the bid is received (OpenX)
PubMatic 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{section_id}",
                "name": "PubMatic",
                "pubid": "{publisher_id}"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (PubMatic)
pubid* string(Required) Pubmatic publisher ID
id stringPubmatic ad Slot
Sonobi 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{placement_id}",
                "name": "Sonobi"
            }]
        }
        ...
    },
});
PropertyDescription
id* string(Required) Sonobi placement ID
name* string(Required) Ad partner from which the bid is received (Sonobi)
Sovrn 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "Sovrn",
                "tagid": "1234567"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (Sovrn)
tagid* string(Required) Ad tag ID provided by Sovrn
SpotX 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{channel_id}",
                "name": "SpotX"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) SpotX channel ID

A unique five-digit ID that is generated by the SpotX publisher platform when a channel is created.
name* string(Required) Ad partner from which the bid is received (SpotX)
The MediaGrid 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{section_id}",
                "name": "MediaGrid",
                "pubid": "{publisher_id}"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) MediaGrid uid representing the MediaGrid bidder system ad slot ID associated with the respective <div> ID from the site page
name* string(Required) Ad partner from which the bid is received (MediaGrid)
pubid* stringIdentifier issued by the ad partner that represents the publisher
The Trade Desk 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "TheTradeDesk",
                "supplySourceId": "{supplySourceId}",
                "publisherId": "{publisherId}",
                "placementId": "{placementId}"
            }]
        }
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (TheTradeDesk)
publishedId* string(Required) Publisher ID

If there is a sellers.json, this should be the same as the seller_id in the sellers.json for the site being trafficked. If there is no sellers.json, this should be hardcoded to 1.
supplySourceId* string(Required) TTD-provided supply source name.
placementId stringAd unit name
Unruly 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "Unruly",
                "pubid": "{siteId}"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (Unruly)
pubid* string(Required) Unruly site ID
VideoByte 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                 "name": "VideoByte",
                 "nid": "temp_222",
                 "placementId": "temp_222",
                 "pubId": "temp_222"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (VideoByte)
pubId* string(Required) VideoByte publisher ID
nid stringVideoByte network ID
placementId stringVideoByte placement ID
Xandr 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "{placementId}",
                "name": "AppNexus",
                "member": "{member}",
                "invCode": "{invCode}",
                "publisherId": "{publisherId}"
            }]
        },
        ...
    }
});
PropertyDescription
id* string(Required) Xandr placement ID.

You may identify a placement using the invCode and member instead of a placement ID.
name* string(Required) Ad partner from which the bid is received (AppNexus)
invCode stringXandr inventory code

Must be used with member.
member stringXandr member ID

Must be used with invCode.
publisherId stringXandr publisher ID

It is used by the Xandr end point to identify the publisher when placement ID is not provided and invCode goes wrong.
YahooSSP 
jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "YahooSSP",
                "pubid": "{pub_id}",
                "siteId": "{site_id}",
                "id": "{placement_id}"
            }]
        },
        ...
    }
});
PropertyDescription
name* string(Required) Ad partner from which the bid is received (YahooSSP)
pubid* string(Required) YahooSSP Publisher External ID
id stringYahooSSP placementId
siteId stringYahooSSP Site ID

advertising.bids.bidders[].optionalParams

🚧

This object should be used only when IndexExchange, Pubmatic, SpotX, or Xandr (AppNexus) is an ad partner.

jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "name": "SpotX",
                "id": "85395",
                "optionalParams": {
                    "price_floor": 5.30,
                    "custom": {
                        "name": "{custom_param_name_goes_here}",
                        "value": "{custom_param_value_goes_here}"
                    }
                }
            }]
        },
        ...
    }
});

jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        "bids": {
            ...
            "bidders": [{
                "id": "12345",
                "name": "AppNexus",
                "optionalParams": {
                    "keywords": {
                        "segment1": "12346",
                        "segment2": "12347"
                    }
                }
            }]
        },
        ...
    }
});
Property Description
content object
OpenRTB content object.

See: "3.2.16 Object: Content" in the OpenRTB 2.5 specification.
custom object Publisher-defined custom key-value pairs for the bid-request
keywords object (Xandr Only) Set of key-value pairs applied to all ad slots on the page
no_vpaid_ads boolean Removes VPAID creatives from available creative media types
passFloorPrice boolean Passes the configured floorPriceCents value in the bid request
token < 8.13.0 object
Publisher-defined custom pass-through macros

advertising.bids.ortbParams

jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        ...
        "bids": {
            ...
            "ortbParams": {
                "plcmt": 1
            }
        },
        ...
    }
});
Property Description
plcmt number Placement of the video in accordance with updated IAB Digital Video Guidelines

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

advertising.bids.settings

jwplayer("myElement").setup({
    "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
    "advertising": {
        ...
        "bids": {
            ...
            "settings": {
                "mediationLayerAdServer": "jwp",
                "floorPriceCents": 10,
                "floorPriceCurrency": "usd",
                "bidTimeout": 4000
            }
        }
        ...
    }
});
PropertyDescription
mediationLayerAdServer* string(Required) Mediation layer that decides which ad runs

  • jwp: (VAST/IMA) An auction is conducted by the player. If a winner is selected, the winner's ad is called. If no winner is selected, the fallback tag is called. You must specify a floor price.

  • jwpspotx: (VAST) No auction is conducted by the player. The player asks SpotX for a bid and calls the returned ad response regardless of price. This option is equivalent to using JW Player mediation with a $.01 floor price. You must set up SpotX line items.

  • dfp: (IMA) No auction is conducted by the player. All bids are sent to Google Ad Manager (GAM) and rendered as line items that compete against other line items. GAM serves the winning line item. We recommend setting buckets to minimize the number of line items that you must set up in GAM.

  • jwpdfp: (IMA) An initial auction is conducted by the player. If a winner is selected, the winner's ad will is called. If no winner is selected, the fallback tag is called to serve. If no winner is selected for any reason, all valid bids are sent to Google Ad Manager (GAM) where the bid values are rendered as line items to compete against other line items. The winning line item is served by GAM. You must set floorPriceCents. We recommend setting buckets to minimize the number of line items that you must set up in GAM.

Default value: jwp
bidTimeout number8.17.0+ Timeout for bid response from when the bid request occurs, in milliseconds

Default value: 3000
Min value: 2000
8.13.0+ Timeout for bid response from when the bid request occurs, in milliseconds

Default value: 2000
< 8.13.0 Timeout for bid response from after the user clicks to play, in milliseconds

If you use SpotX as an ad partner, be sure to make a time allowance for the SpotX SDK to load.

Default value: 2000
buckets array(Recommended) Ranges of bid prices

When using buckets, bid prices sent to GAM are rounded down to the closest specified increment. Price buckets are helpful to reduce the number of line items in GAM. Without price buckets, one line item per one-cent increment is required.

This property only applies when dfp or jwpdfp (only for the GAM portion of the mediation) is selected as the mediationLayerAdServer.

See: advertising.bids.settings.buckets[] object
consentManagement objectResource for managing the EU General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA)

See: advertising.bids.settings.consentManagement object
disableConsentManagementOnNoCmp booleanAdjusts Prebid GDPR settings based upon the presence of a (Transparency and Consent Framework) TCF API function

The tcfapi() function is a standardized interface used by Consent Management Platforms (CMPs) in GDPR-regulated regions to communicate user consent status. The function checks if users have granted consent for data processing and advertising purposes, ensuring GDPR compliance.

Possible values:
  • false: (Default) JWP passes publisher consent management settings
  • true:
    • If tcfapi() function exists, consentManagement is left as defined by the publisher.
    • If tcfapi() function is absent, consentManagement is removed.

NOTE: As a publisher, you must ensure the CMP-loaded tcfapi() function is available when the JWP web player initiates.
floorPriceCents numberPrice in cents (CPM) that a bid has to beat in order to win

This property must be set when mediationLayerAdServer is set to jwp or jwpdfp.

NOTE: Determining the best floor price depends upon various factors. If you need assistance determining the best floor price, please consult with your JW Player representative or SSP partner.
floorPriceCurrency stringCurrency of the floorPriceCents

This property must be set to usd when mediationLayerAdServer is set to jwp.

advertising.bids.settings.buckets[]

Property Description
increment number Nearest increment to which a bid is rounded down, in bidding currency

Default: 0.01
max number Maximum value of a price bucket, in bidding currency
min number Maximum value of a price bucket, in bidding currency

Default: 0

advertising.bids.settings.consentManagement

Property Description
gdpr object Resource for supporting the GDPR

See: advertising.bids.settings.consentManagement.gdpr
usp object Resource for supporting the CCPA

See: advertising.bids.settings.consentManagement.usp

advertising.bids.settings.consentManagement.gdpr

For more details about the following parameters, see GDPR Consent Management Module.

Property Description
allowAuctionWithoutConsent boolean (TCF v1.1 only) Determines what will happen if obtaining consent information from the CMP fails
cmpApi string CMP interface that is in use
defaultGdprScope boolean Defines what the gdprApplies flag should be when the CMP doesn’t respond in time or the static data doesn’t supply
rules array of objects Lets the publisher override the default behavior

See: advertising.bids.settings.consentManagment.gdpr.rules
timeout integer Length of time (in milliseconds) to allow the CMP to obtain the GDPR consent string

advertising.bids.settings.consentManagement.gdpr.rules

Property Description
enforcePurpose boolean Determines whether to enforce the purpose consent
enforceVendor boolean Determines whether to enforce vendor signals for this purpose
purpose string Specific default behavior that can be overridden by the publisher

Possible Values:
  • storage (Purpose 1)
  • basicAds (Purpose 2)
  • measurement (Purpose 7)
vendorExceptions array Defines a list of bidder codes or module names that are exempt from the enforcement of this Purpose

advertising.bids.settings.consentManagement.usp

For more details about the following parameters, see US Privacy Consent Management Module.

Property Description
cmpApi string USP-API interface that is in use
timeout integer Length of time (in milliseconds) to allow the USP-API to obtain the CCPA string

advertising.companiondiv

This is an object with 3 properties: id, width and height. Set these to have JW Player load a companion ad from your VAST/IMA tag into a div on your page. See Companion Ads in the Additional Options table for more info.

Property Description
height number Targeted desired height of a companion ad that exists in a VAST ad
id string ID of the <div> element to replace with a companion ad
width number Targeted desired width of a companion ad that exists in a VAST ad

For an overview of JW Player's advertising capabilities, see its dedicated Video Ads section.


advertising.freewheel

jwplayer("myElement").setup({
  "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  "fwassetid": "test_asset",
  "duration": 600,
  "advertising": {
    ...
    "freewheel": {
      "networkid": 12345,
      "adManagerURL": "https://mssl.fwmrm.net/libs/adm/6.24.0/AdManager.js",
      "serverid": "http://demo.v.fwmrm.net/ad/g/1",
      "profileid": "12345:html5_test",
      "sectionid": "test_site_section",
      "streamtype": "live"
    }
  }
});
Property Description
fwassetid* string (Required) FreeWheel identifier of a particular media item

Example: DemoVideoGroup.01

IMPORTANT: When scheduling ad content for specific playlist items, each playlist item must have its own fwassetid.

Please see this recipe for an example configuration.
adManagerURL string URL of the FreeWheel Ad Manager

Example: https://mssl.fwmrm.net/libs/adm/6.24.0/AdManager.js

NOTE: Your FreeWheel Solution Engineer or Account Representative can provide you with a versioned AdManager URL.
custom object Passes custom-defined key-value pairs to the Freewheel SDK
networkid number FreeWheel identifier of a network

Example: 96749
profileid string FreeWheel identifier of a particular application environment

Example: global-js
sectionid string FreeWheel identifier of a location where the video content plays

Example: DemoSiteGroup.01
serverid string URL of FreeWheel ad server

Example: http://demo.v.fwmrm.net/ad/g/1
streamtype string Indicates if the media item is a live streaming asset

When using this property, set the value to live.

📘

If you do not know where to find the FreeWheel account values in the table, contact your FreeWheel representative.


advertising.rules

Use this property to control how frequently ads play back. See our Ad Rules Reference support article for more information.

jwplayer("myElement").setup({
  "playlist": [...],
  "advertising": {
    ...
    "rules": {
      "startOn": 2,
      "frequency": 1,
      "timeBetweenAds": 300,
      "startOnSeek": "pre",
      "deferAds": {}
    }
  }
});
PropertyAd clientDescriptionDefault
deferAds 8.12.0+ object
                                                                     		VASTAn empty-object setting that prevents ad playback when the player is on an inactive tab

When the player's tab is active again, the last deferred ad break will play. If you want to halt the playback of unviewable ads, configure the autoPause property.

This feature cannot be enabled from your JW Player dashboard.		-
frequency numberIMA,
VAST		Regularity of ads within a playlist. For example, if frequency: 3, ads play before every third playlist item.

Use 0 to only play ads on the first playlist item.

In the dashboard, this is one of the Ad Frequency Rules.		1
startOn numberIMA,
VAST		First playlist item allowing ad playback.

In the dashboard, this is one of the Ad Frequency Rules.		1
startOnSeek 8.5.0+ stringVASTSetting that defines if a returning visitor is served a pre-roll ad when resuming previously-watched video content.

pre: Player shows returning visitor a pre-roll ad before resuming video playback.

none: Player shows returning visitor no ads and resumes video playback.

In the dashboard, this is one of the Long-form Engagement Rules.

NOTE: Each of the following must be tracked: the unique viewer, the unique piece of content the viewer was watching, and the time when the viewer left the page during playback of the video content. During the player setup, this information must be passed into the player. Use starttime to pass the time location to resume playback.		-
timeBetweenAds numberVASTMinimum time in seconds that must elapse after displaying an ad in a schedule before playing the next scheduled ad.

In the dashboard, this is one of the Long-form Engagement Rules.		0

advertising.schedule

Use this property to load an entire advertising schedule to JW Player, containing multiple ad breaks. The property value can be a URL to a VMAP schedule or an inline JSON block with ads. This schedule will then be applied to each playlist item. For scheduling ads for individual playlist items, see scheduling ads for playlist items.


Ad Schedules with VMAP Files

If you are planning on using a VMAP file, add the link to a VMAP .xml file as the value for schedule:

jwplayer("myElement").setup({
  "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  "advertising": {
    "client": "vast",
    "adscheduleid": "t4Xk5tsF",
    "schedule": "myvmap.xml"
  }
});

The VMAP schedule will then be applied to each playlist item. See our article about VMAP schedules for more information.


Embedded Ad Schedules with JSON

In order to use a JSON-formatted schedule, you must define at least one ad break configured inside of the schedule property. Each ad break should include an offset and a tag or vastxml.

jwplayer("myElement").setup({
  "playlist": "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  "advertising": {
    "client": "vast",
    "adscheduleid": "p4Xk5lsZ",
    "schedule": [
      {
        "tag": "myPreroll.xml",
        "offset": "pre",
        "custParams": {
          "testkey1": "testval1",
          "testkey2": "testval2"
        },
      },
      {
        "vastxml": "<VAST version='2.0'> ... </VAST>",
        "offset": "50%"
      }
    ]
  }
});
Property Description
custParams object Allows for passing custom parameters to an ad break, which then pass through to the URL requested from the ad server
offset string | number When to play the configured ad tag

Possible Values:
  • pre: (Default - string) Ad plays as a preroll
  • post: (string) Ad plays as a postroll
  • (xx%): (string - VAST only) Ad plays after xx% of the content
  • (number): (number) Ad plays after the specified number of seconds
  • (timecode): (string) Ad plays at a specific time, in HH:MM:SS:sss format
pod array (VAST only) Configures a single ad break to play two or more VAST ads consecutively

Do not use use this property with advertising.schedule[].tag or advertising.schedule[].vastxml within the same ad break. Instead of using this property, we strongly recommend using a VAST 3.0 template to configure ad pods.
tag string | array When a string, URL of the ad tag for VAST and IMA plugins, or a string place holder for FreeWheel

(VAST plugin only) When an array, URLs of the VAST ad tags to be used as fallbacks in the event that one or multiple ad tags fail to render

When a VAST tag is used, ad tag targeting macros can be added to define features such as GDPR consent.

Do not use this property and advertising.schedule[].vastxml within the same ad break.
type string Property indicating the format of the ad to be served within the ad break:

  • linear: (Default) Video ad that interrupts video content playback
  • nonlinear: Static display ad that overlays a portion of the player and does not interrupt playback. No advertisting cuepoint is shown for this ad break.

If a mix of linear and non-linear ads will serve within an ad break, do not set this property. The player will interrupt video playback for linear ads and will not interrupt video playback for non-linear ads.
vastxml string (VAST only) VAST XML ad tag that is requested during the configured ad break

Do not use this property and advertising.schedule[].tag within the same ad break.
© 2007-2024 Longtail Ad Solutions, Inc.