Questions on VAST in Prebid Mobile

[bretg]

(this was originally in email, but it got lost... making it a proper issue)

There have been two separate threads pop up relating to SDK video:

I've gotten questions from the Magnite team about the rendering of SDK video, and specifically what looks to be a non-standard way that PubNative's outstream video response works.
The Prebid Slack message from Huanzhi Zhang (Newsbreak) about rendering VAST through the "Rendering API". Apparently this is a known issue.

In both cases, minimally this appears to be a lack of documentation. Minimally, a FAQ entry. But ideally, there ought to be a reference in the Prebid Server bid adapter guide explaining video response conventions and I would suggest a new page describing video rendering in the mobile environment.

More importantly, we ought to make sure there are solid conventions on how bidders need to respond to instream/outstream video, including rendering scripts. It's pretty clear from PubNative's situation that there's a disconnect.

Details

I'm pretty familiar with video rendering in Prebid.js, but have not wrapped my head around the various options for mobile apps.

For all video formats, the bidder expected to return one of two things:

• bidResponse.vastXml containing VAST (for Prebid Server, this is seatbid.bid.adm)
• bidResponse.vastUrl continuing a URL where the VAST lives (for Prebid Server, this is seatbid.bid.nurl)

For Prebid.js, rendering works this way:

• instream: the page is set up in a special way. It creates the adserver URL with targeting KVPs appended and passes it to the player. The player is fully responsible for rendering.
• outstream: the bid contains VAST, but the bidder can specify a separate "bidResponse.renderer" which is a javascript function that knows how to retrieve that VAST and play it. A rendering function is absolutely required and can be provided in on

Here are the specific questions I got from the Magnite support team

does a publisher need a VAST order in their GAM account to run instream in-app video via Prebid SDK?
does a publisher need a VAST order in their GAM account to run outstream in-app video via Prebid SDK?

I think the answer to both is "no". There are adserver-less ways of rendering.

does a publisher require a renderer to run instream/outstream in-app video?

I think the answer is 'yes', but I don't know all the options.

can a bidder return a renderer on their end?

I believe the answer is seatbid[].bid[].ext.prebid.meta.rendererUrl

are there any guidelines as to what format a bidder should be returning their video bid response as? e.g. serialized VAST or HTML?

For this I'm sure the answer is no, and this is where the PubNative situation... all other bidders respond to outstream video with VAST XML in the adm. The Pubnative bid adapter is returning Javascript instead of VAST.

Here are some details. The request contains

     "video": {
        "mimes": [
          "video/mp4"
        ],
        "maxduration": 120,
        "protocols": [
          2
        ],
        "w": 300,
        "h": 250,
        "placement": 4,   // outstream in-feed
        "playbackmethod": [
          1,
          2
        ],
        "delivery": [
          3
        ],
        "api": [
          1,
          2
        ]
      },

Appnexus and Index respond with VAST in the adm, but PubNative is returning something like:

<script class=\"pn-ad-tag\" type=\"text/javascript\">\r\n  (function(beacons, trackerURL, options){\r\n    var delay = 1, passed = 0, fired = ...

This cannot be rendered the same way that other bidders work, and is prompting questions from our team.

[bretg]

@YuriyVelichkoPI responded to the original email above with:

RENDERING ENGINES

There are three video rendering engines on mobile:

• Google Mobile Ads SDK (Outstream Video).
• Prebid SDK (Outstream Video)
• Google IMA SDK (Intsream Video)

All of them expect that the winning bid will contain the VAST.

• GMA SDK renders the VAST tag provided in the GAM creative (https://docs.prebid.org/adops/setting-up-prebid-video-in-dfp.html).
• Prebid SDK renders the locally cached bid response.
• Google IMA SDK renders the tag provided in the GAM creative (https://docs.prebid.org/adops/setting-up-prebid-video-in-dfp.html).

Q&A

1. What are bidders supposed to return - vast? How do they return an outstream renderer?

Bidders are supposed to return VAST.

SDKs contain out-stream renderer. There is no need to provide any custom renderer (with one exception described further).

2. How is an app developer supposed to handle the rendering of each scenario: instream/outstream, mraid, original rendering/etc.

Publishers should follow the Prebid documentation for the respective integration kind (instream/outstream, Prebid SDK + Google SDK, Prebid SDK only). They are different and too big to cite them here. But Mobile docs contain integration instructions for all supported cases.

does a publisher need a VAST order in their GAM account to run instream in-app video via Prebid SDK?
does a publisher need a VAST order in their GAM account to run outstream in-app video via Prebid SDK?

It depends on the integration kind. If the renderer is GMA SDK or IMA SDK - then yes, because they should send and process the ad request.

does a publisher require a renderer to run instream/outstream in-app video?

Prebid/GMA/IMA SDKs have all needed renderers.

can a bidder return a renderer on their end?

The custom renderers (another native SDK that supports VAST rendering) are supported on Android (https://docs.prebid.org/prebid-mobile/pbm-api/android/pbm-plugin-renderer.html). Bidder can signal the Prebid SDK that the custom rendered should be used.

But still - it is not the same as the renderer in the js.

are there any guidelines as to what format a bidder should be returning their video bid response as? e.g. serialized VAST or HTML?

The mobile integration fully relied on the current video support by PBS. If there is a bidder guide for video - that is the case.

PubMatic case. Using the rendering delegation feature, PubMatic can render their bids in their own SDK on the client. So, the bid response can be PubMatic-specific. But default engines won't parse and render it. Pubmatic, as a bidder, should return the VAST.

WHAT's NEXT

Support of video ads on mobile differs from the js world now. On mobile, the video ads are rendered by native iOS and Android video players. SDK implements VAST parsing, event tracking, and others.

It is a legacy approach that can be adjusted by implementing in-WebView rendering of the video ads utilizing the same approach as for js - seatbid[].bid[].ext.prebid.meta.rendererUrl.

Mobile and video committees can combine efforts and develop a solid, unified, and reliable solution for video ads.

[bretg]

@YuriyVelichkoPI - we need a flowchart to help app developers understand the options for how to render video.

Something like this:

1. Intream video? If yes, then the player is making the ad call and will deal with the rendering. Assuming the top-level stored request is set up properly, all bids from Prebid Server will return a URL to a cached VAST block.
2. Else it's outstream video. Bidders should submit VAST and Prebid Server will supply a URL to that VAST. They should also be able to submit a URL to a renderer in seatbid.bid.ext.prebid.meta.rendererUrl
3. Using PUC? If yes, do ...
4. Using No AdServer? If yes, do...
5. Using Rendering API? If yes, do...

[bretg]

@YuriyVelichkoPI - Got some details from our solutions engineering team about the scenario:

they are just following prebid's instructions, so they don't do anything special things (like implementing the ExoPlayer) for Outstream/Interstitial video rendering. Also, their GAM order/lineitems/creatives are generated using standard PUC as their GAM creative code.

Reading through the instructions, it does seem like Pubnative's approach of supplying a built-in renderer is the only way outstream could render via PUC/webview?

[YuriyVelichkoPI]

Hi @bretg ! Thanks for the clarification. It is important that the integration scenario is based on PUC.

All the time for any API (Original or Rendering), integration of video ads with Prebid SDK doesn't assume using PUC.

The creative should be set up as a Video creative: https://docs.prebid.org/adops/setting-up-prebid-video-in-dfp.html. So, the current integration examples expect only the following creative code. Not a PUC.

https://prebid.adnxs.com/pbc/v1/cache?uuid=%%PATTERN

Later, the rendering engine (GMA SDK or Prebid SDK) processes the VAST supplied by the above link and displays the ad in the internal player (publishers shouldn't provide any players).

So I'd say that the pub integrates the Outstream ad incorrectly.

However, I dug deeper and found out that the docs contain another section GAM Step by Step - Banner/Outstream/AMP Creatives. It states that for the outstream video publishers should use PUC. And I also found one more explainer for Outsream video that states

Outstream video is displayed in banner ad slots using video renderers that are provided either by the demand partner with the bid response or by a renderer that the publisher has associated with the ad unit. This is a high-level diagram showing how header bidding works with outstream video:

So I assume that there is a scenario for integration of outstream video when the video renderer is provided "_by the demand partner with the bid response or by ... publisher _". It means that according to that doc, It is possible to implement the outstream video with custom (not VAST) ad markup and custom player that is able to parse and render the code. So far I can't find the particular documentation of how to provide the custom renderer to outstream video bid response. The search through the docs shows that the seatbid[].bid[].ext.prebid.meta.rendererUrl is used for native ads, but I could miss something here.

And assuming all the above, I would answer your last question

Reading through the instructions, it does seem like Pubnative's approach of supplying a built-in renderer is the only way outstream could render via PUC/webview?

Yes, for the Pubnative's approach the only way to support out-stream video integration is via WebView and PUC. But, for now, Prebid SDK doesn't assume such an integration scenario. We should implement it in the Demo Apps to confirm/deny/adjust the integration approach.

====

All these things make me more confident in the necessity of unifying the supporting video on mobile with the Prebid video ecosystem.

====

Also I've prepared the draft flowchart for choosing the integration approach. (It is in the .pdf format so far to provide clickable links to the docs):

Prebid SDK API Flowchart.pdf

[bretg]

Thanks Yuriy. Yes, oustream video is very different than instream video.

I'm still trying to wrap my head around the possibility that in-app outstream has never actually worked. Trying to get some data.

Whatever the case, seems to me that mobile outstream is a bit of a mess right now, at least in the documentation. I would propose several phases of resolving the situation since there are several possibilities taking place right now for the "Original API":

1. Bidder returns a block of HTML/javascript that is a renderer that knows how to load the VAST. (Note: Prebid cannot able to track video imps with this approach)
2. Bidder returns VAST that's cached server-side in Prebid Cache. No renderer is provided. (Note: currently this doesn't result in renders without special publisher work.)
3. Bidder returns VAST that's not cached server-side in Prebid Cache. No renderer is provided. (Note: currently this doesn't result in renders without special publisher work.)
4. Bidders returns VAST or VAST URL and also provides a rendererUrl. (Note: currently this doesn't result in renders without special publisher work.)

Phase 1 - Develop robust "PUC invocation" code as a documentation workaround

The goal is to support all 4 scenarios noted above because bidders will be inconsistent for a while.

To do this, we have to define how the code at the other end of a "rendererURL" is going to receive the VAST. I propose simply passing an encoded URL as a query string. In order to that, we have to make sure the VAST is cached server-side.

It's not clear to me what the right long term solution is, but in the short term, it seems possible to replace the PUC invocation and build out the logic to deal with the various scenarios.

Pseudo-code:

1. Inspect the creative body
2. If the creative contains "<VAST" and either "" or "" (all case insensitive) assume it's a VAST creative.
   1. Check the response for seatbid.bid.ext.prebid.cache.vastXml. If it doesn't exist, we can't render it because renderers need a URL. (PBJS does "client-side caching", we shouldn't have to do this In-App because it's very easy for the PBS host company to force server-side caching.)
3. If there's no creative body, check the response for seatbid.bid.ext.prebid.cache.vastXml. If it exists, assume it's a VAST creative.
4. If it's NOT VAST, render as HTML the normal PUC way: create an iframe and dump the contents of the body into the iframe.
5. If it is VAST, we need a renderer. The publisher should have a way of specifying a renderer URL in the PUC invocation code and whether that URL should be used as the primary or as a backup only.
6. If the PUC invocation didn't specify a renderer or if the "backup only" flag was specified, check the bid response for seatbid[].bid[].ext.prebid.meta.rendererUrl .
7. If a renderer URL was found, append an argument to it containing the VAST location:
   1. Search the rendererURL for an existing query string. If there's already a query string, add "&vastUrl=URLENCODED_VASTURL".
   2. If there's not a query string then append "?vastUrl=URLENCODED_VASTURL".

Phase 2 - Define The Right Way To Do It

The Prebid.js committee is moving away from the PUC. If the mobile committee needs to keep the original webview render functionality, it's going to need to own a revised 'MPUC' that incorporates something like the logic above.

[YuriyVelichkoPI]

Hi Bret!

Thanks for the input. In general, looking at the Prebid approach, I support the idea of unifying video ads. However, it makes sense to take into consideration that on mobile, things are implemented in a bit another way, so we shouldn’t push publishers and bidders to switch the mobile approach (rendering in the SDK using an in-app video player) to Prebid’s approach (rendering in the WebView).

I'm still trying to wrap my head around the possibility that in-app outstream has never actually worked. Trying to get some data.

Outstream video is supported according to the mobile approach. The SDK (Google, or Prebid) renders the video ad using the VAST tag or VAST markup in the “adm” field. SDK doesn’t need any other renderer for this purpose. Publishers just need to create video creative:
https://docs.prebid.org/adops/setting-up-prebid-video-in-dfp.html

And then render it for interstitial or banner video ads (both outstream).

Whatever the case, it seems to me that mobile outstream is a bit of a mess right now, at least in the documentation.

Agree, we should better organize the docs.

I could miss something, but when we created this variant of documentation I didn’t find how to add more nested layers in the index. I really don’t like that we have the guides for all ad formats in a single doc for a particular API. It’s hard to create and support it. I would like to create the following hierarchy,

Prebid Mobile

• For Android
  ++ Integration
  ++ Original API
  +++ HTML Banner
  +++ Video Banner (Outstream)
  +++ HTML Interstitial
  +++ Video Interstitial (Outstream)
  +++ Instream Video
  +++ ….
  ++ Rendering API
  +++ ...
• For iOS
  ….

But I couldn’t find how to achieve this in the index panel. So we put all formats in the particular API page.

I would propose several phases of resolving the situation since there are several possibilities taking place right now for the "Original API":

Agree with variants to support.

Phase 1 - Develop robust "PUC invocation" code as a documentation workaround
The goal is to support all 4 scenarios noted above because bidders will be inconsistent for a while.

+1

It's not clear to me what the right long term solution is, but in the short term, it seems possible to replace the PUC invocation and build out the logic to deal with the various scenarios.

I'm not sure about the details right now, too, but the goal is clear and feasible.
Phase 2 - Define The Right Way To Do It

The Prebid.js committee is moving away from the PUC. If the mobile committee needs to keep the original webview render functionality, it's going to need to own a revised 'MPUC' that incorporates something like the logic above.

I believe that mobile should be as consolidated with .js as possible. I’m not sure if we can get rid of PUC for the “Original API,” but it is definitely not needed for the Rendering API. But in any case, we must strive for it.

[bretg]

We discussed this in a recent committee meeting and I think we made progress identifying an underlying disconnect:

Outstream video is rendered differently in Prebid Mobile vs Prebid.js:

• Mobile handles both instream and outstream video by requiring line item targeting to hb_format=video . Neither publishers nor bidders can supply an outstream renderer.
• PBJS does not advise targeting by hb_format. There, it's assumed that banner line items also handle outstream creatives.

This leaves publishers who run both Prebid.js and Prebid Mobile with conflicting requirements for line item setup.

What's needed is a comprehensive take on the line item configuration needed to cover all mediatypes in both PBJS and SDK.

[bretg]

Ok, with help from @YuriyVelichkoPI I've come up with a workaround and some improvements we can talk about in PBJS and Mobile committee meetings.

In short, I propose that we change the Prebid AdOps recommendation for outstream:

• explain the awkward situation
• for mobile, utilize a slightly different size like 300x251v instead of 300x250v.

Maybe this is an ok workaround even for the long term, but nonetheless, we could discuss a couple of smoother solutions:

1. change outstream to hb_format=banner
2. implement a new hb_render KVP

Full writeup is https://docs.google.com/document/d/1kTqgRPvWI111_oDBkCbmvdBG3nqfJLM5WcryT64j-sE/edit

[fowler446]

1. change outstream to hb_format=banner

I don't love this. I think it will create confusion I personally have setups where this would cause issues.

2. implement a new hb_render KV

How video impressions render is really what we're trying to figure out here. I think this options makes the most sense.

[jsligh]

Mentioned in another issue #979