Publisher APIs

Expand all   Collapse all

Ad Pod Support for OpenWrap Video

Currently, the programmatic video ad ecosystem doesn't enforce consistent context across video ad content, leading to inefficiencies and behavior like:

  • The same ad playing repeatedly to the user during each ad break within the main video content.
  • Suboptimal ad duration fill; that is, multiple requests to load ads one at a time can be problematic, resulting in a bad user experience.

The VAST 3+ standard offers a technical solution called, Ad Pod, that lets publishers/players request a group (or playlist) of ads.

What are Ad Pods?

Ad Pods are a sequenced collection of ads, as described in the IAB VAST4.1 Specification:

Sequence showing multiple Ad Pods (Pre, Mid, and Post Roll pacements) during video content:

Current publisher challenges 

  • None of the Wrapper/Unified platforms allow publishers to optimize multiple ads coming from different SSP and demand sources.
  • There is partial Ad Pod support but there are very few platforms that support optimization within and across pods for a user viewing session.

OpenWrap Ad Pod support: high-level approach and flow

STEP NO

DESCRIPTION

1Video SDK /Player/SSAI initiates request for ads with Ad Pod details
2Server side wrapper interprets this request to AdPod optimisation / Selection Engine 
3Selection engine looks at available ads (if already present in cache / collection store) if it doesn't have all ads as per rules, sends altered request to Requester
4Bid details with ad exclusion and other rules are sent to Prebid server Bidder adapters module
5The bid responses are added to ad collection and Selection Engine reevaluates if it has all ads based on rules
6Post Timeout or fullfilment of ads per rule all relevant ads is pushed to  collector/cache
7All selected / relevant ads are sent to ad pod generator - which generates VAST XML
8This VAST may be hosted in cache - bases on use case / settings
9Ad Pod details and price is communicated back to Client
10Client select best ads from direct / programmatic to serve 
11Player gets the ad during break and tries to render all ads in a pod.

oRTB API specs for Ad Pod requests

PubMatic's implementation adds the AdPod extension object as a child the BidRequest object and/or the Video object. When you use and AdPod object as a child of BidRequest, then the AdPod's settings are global in scope. When AdPod is a child of Video, the AdPod's settings are local scope for the Video object and its parent Impression. When both BidRequest and Video each have an AdPod object, then the Impression. Video.Ext.AdPod settings override the BidRequest global settings. And while BidRequest and Video can each use most of AdPod's parameters, there are a few that apply only to BidRequest as shown in the table below.

ParameterTypeMandatory
(with a defined AdPod object)		DescriptionDefault value
(with a defined AdPod object)
offsetIntegerN

Defines the position where the AdPod might play in a long video; for example, 30 min from start. This helps define duration based rules to determine when the same ads can/cannot play.

0
minadsIntegerNMinimum number of ads to include in the AdPod.2
maxadsIntegerNMaximum number of ads to inlcude in the AdPod.3
admindurationIntegerNMinimum duration in seconds for each ad in the AdPod.video.minduration/2
admaxdurationIntegerNMaximum duration in seconds for each ad in the AdPod.video.maxduration/2
excladvIntegerNPercentage of ads allowed to have the same advertiser in the AdPod.100
excliabcatIntegerNPercentage of ads allowed to have the same IAB category in the AdPod.100
BidRequest-only parameters
adpod
(POST method only)		ObjectYNew object for defining an AdPod object.
crosspodexcladvIntegerNPercentage of ads allowed to have the same advertiser across all AdPods in the BidRequest.100
crosspodexcliabcatIntegerNPercentage of ads allowed to have the same IAB categories across all AdPods in the BidRequest .100
excliabcatwindowIntegerN

The number of minutes during which the exclusive IAB rule applies. If two AdPods render within a window, then the rule applies, otherwise the rule resets.

100
excladvwindowIntegerN

The number of minutes during which the exclusive advertiser rule applies. If two AdPods render within a window, then the rule applies, otherwise the rule resets.

100

Sample oRTB 2.x request

The sample oRTB request below performs the following:

  1. Configure two AdPod objects:
    1. First AdPod:
      1. Minimum duration of overall ad is 10 secs with a max duration of 30 seconds
      2. AdPod must contain a minimum of two ads and a maximum of 3 ads 
      3. Each ad must fall between a minimum of 5 seconds and maximum 10 seconds in duration
      4. All ads in the pod must come from different advertisers
      5. IAB categories can match
      6. AdPod plays at the start of the main video content
    2. Second AdPod:
      1. Minimum duration of overall ad should be 90 sec and max duration of 120 seconds 
      2. Minimum 3 ad should be part of the ad pod and maximum 5 ads 
      3. Each ad should be minimum 30 sec in duration and max 40 sec.
      4. 50%  the ads in the pod can be from same advertiser. 
      5. The IAB categories can be same.
      6. This AdPod will play after 25 min of video playback.
  2. Global rules:
    1. These AdPods should not share more than 50% ads from the same advertiser.


Configure two Ad Pods with global rules 
{
  "id":"1234567893",
  "at":2,
  "tmax":120,
  "imp":[    {      "id":"1",
      "bidfloor":0.03,
      "video":{        "w":640,
        "h":480,
        "pos":1,
        "sequence":1,
        "startdelay":0,
        "minduration":10,
        "maxduration":30,
        "maxextended":30,
        "minbitrate":300,
        "maxbitrate":1500,
        "api":[
          1,
          2
        ],
        "protocols":[
          2,
          3
        ],
        "mimes":[
          "video/x-flv",
          "video/mp4",
          "application/x-shockwave-flash",
          "application/javascript"
        ],
        "linearity":1,
        "boxingallowed":1,
        "playbackmethod":[
          1,
          3
        ],
        "delivery":[
          2
        ],
        "battr":[
          13,
          14
        ],
        "companionad":[
          {
            "id":"1234567893-1",
            "w":300,
            "h":250,
            "pos":1,
            "battr":[
              13,
              14
            ],
            "expdir":[
              2,
              4
            ]
          }
        ],
        "companiontype":[
          1,
          2
        ],
        "ext":{
          "offset":0,
          "adpod":{
            "minads":2, // Default 1 if unspecified
            "maxads":3,
            "adminduration":5, // adpod.adminduration*adpod.minads should be greater than or equal to video.minduration
            "admaxduration":10, // adpod.admaxduration*adpod.maxads should be less than or equal to video.maxduration + video.maxextended
            "excladv":0, // 0% means same advertiser ads not allowed; 100% means same advertiser ads allowed
            "excliabcat":100 // 100% means same IAB categories allowed; 0% means ads must be different IAB categories
          }
        }
      }
    },
    {
      "id":"2",
      "bidfloor":0.05,
      "video":{
        "w":640,
        "h":480,
        "pos":1,
        "sequence":2,
        "startdelay":0,
        "minduration":90,
        "maxduration":120,
        "maxextended":30,
        "minbitrate":300,
        "maxbitrate":1500,
        "api":[
          1,
          2
        ],
        "protocols":[
          2,
          3
        ],
        "mimes":[
          "video/x-flv",
          "video/mp4",
          "application/x-shockwave-flash",
          "application/javascript"
        ],
        "linearity":1,
        "boxingallowed":1,
        "playbackmethod":[
          1,
          3
        ],
        "delivery":[
          2
        ],
        "battr":[
          13,
          14
        ],
        "companionad":[
          {
            "id":"1234567893-1",
            "w":300,
            "h":250,
            "pos":1,
            "battr":[
              13,
              14
            ],
            "expdir":[
              2,
              4
            ]
          }
        ],
        "companiontype":[
          1,
          2
        ],
        "ext":{
          "offset":25,
          "adpod":{
            "minads":3, //Default 1 if not specified
            "maxads":5,
            "adminduration":30, // adpod.adminduration*adpod.minads should be greater than or equal to video.minduration
            "admaxduration":40, // adpod.admaxduration*adpod.maxads should be less than or equal to video.maxduration + video.maxextended
            "excladv":50, // 0% means same advertiser ads not allowed; 100% means same advertiser ads allowed
            "excliabcat":100 // 0% means all ads must be different IAB categories; 100% means ads can be same IAB categories.
          }
        }
      }
    }
  ],
  "site":{
    "id":"1345135123",
    "name":"Site ABCD",
    "domain":"siteabcd.com",
    "cat":[
      "IAB2-1",
      "IAB2-2"
    ],
    "page":"http://siteabcd.com/page.htm",
    "ref":"http://referringsite.com/referringpage.htm",
    "privacypolicy":1,
    "publisher":{
      "id":"pub12345",
      "name":"Publisher A"
    },
    "content":{
      "id":"1234567",
      "id":"1234567893-2",
      "w":728,
      "h":90,
      "pos":1,
      "battr":[
        13,
        14
      ],
      "series":"All About Cars",
      "season":"2",
      "episode":23,
      "title":"Car Show",
      "cat":[
        "IAB2-2"
      ],
      "keywords":"keyword-a,keyword-b,keyword-c"
    }
  },
  "device":{
    "ip":"64.124.253.1",
    "ua":"Mozilla/5.0 (Linux; Tizen 2.3) AppleWebKit/538.1 (KHTML, like Gecko)Version/2.3 TV Safari/538.1",
    "os":"Tizen"
  },
  "user":{
    "id":"456789876567897654678987656789",
    "buyeruid":"545678765467876567898765678987654",
    "data":[
      {
        "id":"6",
        "name":"Data Provider 1",
        "segment":[
          {
            "id":"12341318394918",
            "name":"auto intenders"
          },
          {
            "id":"1234131839491234",
            "name":"auto enthusiasts"
          }
        ]
      }
    ]
  },
  "ext":{
    "adpod":{
      "minads":2, //Default 1 if not specified
      "maxads":3,
      "adminduration":5, // adpod.adminduration*adpod.minads should be greater than or equal to video.minduration
      "admaxduration":10, // adpod.admaxduration*adpod.maxads should be less than or equal to video.maxduration + video.maxextended
      "excladv":0, // 0% means no ads allowed from same advertiser; 100% means same advertisers allowed
      "excliabcat":100, // 0% means all ads must be different IAB categories; 100% means ads can be the same IAB category.
       // Across Ad Pod rules - this is applicable only when using two or more ad pods. Note:: These params do not apply at impression level.
      "crosspodexcladv":50, // Percent Value - Across multiple impressions no ads allowed from same advertiser. Note: These cross pod rule % values can not be more restrictive than per pod
      "crosspodexcliabcat":100, // Percent Value - Across multiple impressions no ads allowed from same IAB category
      "excliabcatwindow":30, // Duration in minutes between pods where exclusive IAB rule must apply
      "excladvwindow":30 // Duration in minutes between pods where exclusive advertiser rule must apply
    }
  }
}



⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents

PRIVACY

OPT-OUT

TERMS OF SERVICE

PUBMATIC LEGAL POLICIES


Copyright © 2021 PubMatic, Inc. All Rights Reserved

This website uses cookies for analytics and personalization.  Click here  to learn more or change your cookie settings. By continuing to browse, you agree to our use of cookies.