Learn how to leverage our API to integrate online video ads using the following standards:
View IAB's standards, guidelines, and best practices for:
The response from an ad server may contain custom VAST extensions. These custom VAST extensions are included in the response provided for:
An ad server provides custom VAST extensions in XML format. The rules through which this XML content is converted to JSON are explained below.
The key for this child object is determined by the <Extension> tag's type attribute.
For example, the key for the following <Extension> tag is "waterfall."
This child object will contain an object for each additional attribute in its <Extension> tag.
For example, the above "waterfall" object will contain a "fallback_index" object.
...
{
"waterfall":[
{
"fallback_index":"0"
}
]
},
...
Nested nodes will be converted into nested objects.
For example, the following "geo" object contains two nested objects (i.e., Country and Bandwidth).
<Extension type="geo">
<Country>US</Country>
<Bandwidth>0</Bandwidth>
The resulting JSON for the above XML is:
...
{
"geo":[
{
"Country":"US"
},
{
"Bandwidth":"0"
}
]
},
...
Exception: If a nested node only contains text, then the corresponding object's key will be the tag and the object's value will be the text contained within the tag.
Example
A sample XML response from an ad server is provided below.
<Extensions> <Extension fallback_index="0" type="waterfall" /> <Extension type="geo"> <Country>US</Country> <Bandwidth>0</Bandwidth> </Extension> <Extension type="activeview"> <CustomTracking> <Tracking event="viewable_impression">https://pubads.g.doubleclick.net/pagead/conversion/?ai=BYW1B...AHHw&sigh=qtzpMUZ5DzM&label=viewable_impression&acvw=[VIEWABILITY]&gv=[GOOGLE_VIEWABILITY]&ad_mt=[AD_MT]</Tracking> <Tracking event="abandon">https://pubads.g.doubleclick.net/pagead/conversion/?ai=BYW1B...AHHw&sigh=qtzpMUZ5DzM&label=video_abandon&acvw=[VIEWABILITY]&gv=[GOOGLE_VIEWABILITY]</Tracking> </CustomTracking> </Extension> <Extension type="metrics"> <FeEventId>8_zT4LjWGM7gpAOa7p8Q</FeEventId> <AdEventId>CIDG5POK7dICFReRaQodN-kNMw</AdEventId> </Extension> </Extensions>
The above custom VAST extensions will be included in the Preplay and Ping responses under the extensions array as indicated below.
...
"extensions":[
{
"waterfall":[
{
"fallback_index":"0"
}
]
},
{
"geo":[
{
"Country":"US"
},
{
"Bandwidth":"0"
}
]
},
{
"activeview":[
{
"CustomTracking":[
{
"Tracking":"https://pubads.g.doubleclick.net/pagead/conversion/?ai=BpL3zK...AYRAB&sigh;=edOT3dMFSbQ&label;=viewable_impression&acvw;=[VIEWABILITY]&gv;=[GOOGLE_VIEWABILITY]&ad;_mt=[AD_MT]",
"event":"viewable_impression"
},
{
"Tracking":"https://pubads.g.doubleclick.net/pagead/conversion/?ai=BpL3zK...AYRAB&sigh;=edOT3dMFSbQ&label;=video_abandon&acvw;=[VIEWABILITY]&gv;=[GOOGLE_VIEWABILITY]",
"event":"abandon"
}
]
}
]
},
{
"metrics":[
{
"FeEventId":"KSL1WK-fN4X6vgKH4pnoBQ"
},
{
"AdEventId":"CO-FsISnrNMCFVWxTwodkIgH_Q"
}
]
}
],
...
Information that facilitates the interaction between a video player and a VPAID ad unit is included in the response provided for:
The ad break portion of the response for both of these methods is identical and information on it may be found in the Preplay API article.
Perform the following steps:
Set up the player to perform the following tasks whenever it encounters a VPAID ad unit:
Send beaconing data by leveraging the event data provided in the events object.
Server-side beaconing will not be triggered for VPAID (Video Player-Ad Interface Definition) ad units.
Ad slate will be inserted into a live/linear stream for the duration of each VPAID ad. By default, this allows the live/linear stream to resume immediately after the completion of the VPAID ad. However, users that interact with a VPAID ad unit may cause the ad to exceed this duration. It is important to set up your video player to handle this type of situation.
Common methods for handling this situation are:
Reduce bandwidth usage by setting up the video player to switch to a lower ray during a VPAID ad.
On-demand content will contain a placeholder ad for each VPAID ad unit. This placeholder ad consists of two seconds of black frames. A video player should be configured to pause playback upon detecting these black frames and resume playback once the user's interaction with the VPAID ad unit has completed.
VPAID information is reported in the exact same manner for both the Ping and Preplay methods.
Learn more about the ads object.
Sample response:
...
"ads": {
"breaks": [{
"breakId": "0.0.0.1234567890",
"ads": [{
"mimeType": "application/javascript",
"apiFramework": "VPAID",
"companions": [],
"creative": "https://.../ad/.../vpaid.js",
"width": 640,
"duration": 15,
"height": 480,
"events": {
"firstquartiles": [
"http://account.v.fwmrm.net/ad/1/1?..."
],
"clicktrackings": [
"http://account.v.fwmrm.net/ad/1/1?..."
],
"GENERIC": "http://account.v.fwmrm.net/ad/1/1?...",
"midpoints": [
"http://account.v.fwmrm.net/ad/1/1?..."
],
"thirdquartiles": [
"http://account.v.fwmrm.net/ad/1/1?..."
],
"impressions": [
"http://account.v.fwmrm.net/ad/1/1?..."
],
"completes": [
"http://account.v.fwmrm.net/ad/1/1?..."
]
}
}
],
"duration": 15,
"height": 0,
"width": 0,
"timeOffset": 0,
"position": "preroll",
"type": "linear",
"events": {
"impressions": [
"http://account.v.fwmrm.net/ad/1/1?..."
]
}
}, {
...