PBS - Provision for Injecting Video Event Trackers

[ShriprasadM]

To enable company hosting prebid-server to inject their Video Event Trackers in the winning bids.

NOTE: Please provide feedback on this proposal. We are ready to contribute

Benefits of having it in Prebid Server

1. Reuse Parser - Reuse the existing VAST parsing capabilities of PBS (Already present for Impression Tracking -PBS video impression tracking #1015
2. Abstraction Layer for Event Tracker Injection - Helps companies in the way, no need to write the custom parsing for injecting video event trackers

Proposal

1. Introduce a new application-level config parameter - video_tracking_url - This will contain the base tracker URL along with all the required parameters with value as macro. e.g.

video_tracking_url = mycomany.tracker?e=[VIDEO_EVENT_ID]&cb=[CACHEBUSTING]

2. PBS will receive all the bids from all the adaptors
3. PBS will run the auction to obtain winning bids
4. PBS will inject the Video event trackers in each VAST bid as follows (After auction *** - check the last paragraph of the proposal)

   1. Checks if the bid's bidder config allows modifying VAST XML for event tracking

   2. PBS will obtain the template video event tracking URL from video_tracking_url from the exchange

   3. New call back function will be called to replace all the macros present in video_tracking_url

   4. New call back function will have the following structure

      

   5. No Injection - If the above function return nil or empty map then PBS will not inject tracker for the event type

   6. callBackFuntion will be called per eventType. Right now we can support for following video event trackers

      1. firstQuartile
      2. midpoint
      3. thirdQuartile
      4. complete

Sample Code Snippet

*** Current tracker module inject trackers, optionally, before the auction. It can be optimized by moving it after the auction. Because in the case of ad pod, it can be expensive to parse and inject trackers for each adaptor bid. Instead, we can inject trackers only for winning bids.

[bretg]

I'd like to step back and consider the requirements here, @ShriprasadM . Are you with a Prebid.org member company? Would like to discuss in this week's committee meeting and/or set up set up a separate call. This is not a small feature.

I get that you want to be able to add the quartile events. But does the tracking URL really have to be configurable?

Ideally we could wait on this additional tracking for when we have the modularity design in place. Then it could be a VAST tracking module and you can build whatever you want.

But since that's probably quite a ways out still, here's a counter-proposal that better fits the "Prebid Way" as documented at https://docs.google.com/document/d/1ry0X4C2EV-R0pMrm1IQk9BstxaT395UCl3KKqTGa5c8/edit

1. Account-Level Configuration defines which accounts need which events. We started outlining a more powerful set of configs in Revise Account Configuration storage #1672.

Here's an example config that could extend easily to all video events:

event-config: [
   {eventtype: "firstQuartile", channel: ["*"], mediatype: [“video”], config: {“enabled”: true, "vast": true}}, 
   {eventtype: "midpoint", channel: ["*"], mediatype: [“video”], config: {“enabled”: true, "vast": true}}, 
   {eventtype: "thirdQuartile", channel: ["*"], mediatype: [“video”], config: {“enabled”: true, "vast": true}}, 
   {eventtype: "complete", channel: ["*"], mediatype: [“video”], config: {“enabled”: true, "vast": true}}, 
]

2. The VAST modification routine scans the account event-config. If it sees an event where config.vast is true, it does the following:

• If the VAST is a Wrapper, skip it. Events cannot be tracked. (Someday we could build a system that ingests the chain of Wrappers and becomes the master copy of the VAST, but that needs time and discussion.)
• Parse the VAST for TrackingEvents and add in a Tracking element.

<TrackingEvents>
  <Tracking event=”EVENTTYPE”>
    <![CDATA[https://PBS_HOST/event?t=EVENTTYPE&b=BIDID&f=b&a=ACCOUNT&ts=TIMESTAMP&bidder=BIDDER&int=INTEGRATION]>
  </Tracking>
</TrackingEvents>

3. The player fires the URL to the PBS /event endpoint at the appropriate time.

4. The PBS analytics adapter receives the event and can log it to the appropriate analytics endpoint

There are a couple of aspects of the original proposal either I don't find appealing or maybe I just don't understand them:

• callbacks. Nothing in Prebid Server works like this. Also, how would PBS-core know which eventTypes to call it for?
• event URLs outside of the already-established event structure
• application-level config. App-level default could be ok, but video tracking should be turned on per account.

Adding @mike-chowla and @dbridges12 as video experts to weigh in on the details of VAST, especially the idea of adding tracking to Wrappers.

[mike-chowla]

Hi @bretg,

Thanks for the feedback on this. @ShriprasadM is an engineer at PubMatic.

I didn't quite follow what the issue is with adding tracking to a VAST wrapper. My understanding is that tracking elements can appear in a wrapper. The VAST that comes back from Prebid bidders is usually the SSP's wrapper with some tracking elements added.

My initial thought is that the trackers would just be fired from the VAST direct instead of being proxied by the PBS but thinking about it some more, I can see the advantage sending them to PBS which can then call events on PBS Analytics adapters.

I've ask Shriprasad if he can attend the PBS PMC meeting to discuss further

[bretg]

@dbridges12 also confirmed that are supported in Wrappers. The VAST 3.0 standard is confusing on this point -- glad it's not an issue. He also confirmed that multiple blocks for one type of event are ok.

[ShriprasadM]

Thanks, @mike-chowla for an update on this.

Hi @bretg

Here are answers to the questions

1. Why tracking URL needs to be configurable?

   1. Company level implementation can override the configuration if their trackers are listening on endpoint apart from /event
   2. Default value would be - external_url/event (Where external_url is existing prebid configuration)
      For Example, http://prebid.site.com/event. Here external_url is http://prebid.site.com

2. callback function

   1. Instead of callback we can call it a custom macro provider function
   2. It will help the company to provide custom macros along with its values that need to be part of the event trackers
   3. It will help in merging PBS upgrades in a smoother way in the company's fork.
   4. company can also use it to provide overriding the default behavior of handling standard macros (As a part of this framework, we will supporting standard VAST macros. Please checkout Support for standard macros section below)

3. how would PBS-core know which eventTypes to call it for?

   1. We will be introducing new things in /event endpoint as follows

      Parameter	Value	Significance
      t	vtrack **(new value)	it will help PBS-core in identifying that its video event tracker call
      e **(new query param)	[EVENT_ID] ** new PBS macro	It will help PBS-analytics in identifying the video tracker event is for specific quartile. It can have values described in below table.

      Event Name	Event ID for [EVENT_ID] macro
      firstQuartile	fq
      midpoint	mp
      thirdQuartile	tq
      complete	cmplt

   2. For example, http://prebid.site.com/event?t=vtrack&e=mp (here [EVENT_ID] is replaced with mp , being its midpoint event tracker)

4. application-level config. App-level default could be ok, but video tracking should be turned on per account.

   1. We can introduce application-level configuration - inject_video_event_trackers (Default: false)
   2. If the value is false, PBS will not inject any video event tracker
   3. If the value is true, PBS will inject video event trackers for firstQuartile, midpoint, thirdQuartile and complete

5. What if there's already a Tracking element for the given event? Do they need to be merged? -

   1. Framework will add one more tracking element in such a case for injecting PBS specific tracker for that event type

Support for standard macros (Feature)

1. The framework will support replacing the following standard VAST macros internally.

   Standard Macro	Description	Reference
   [ADTYPE]	Type of creative. e.g. video	https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html#macro-spec-adtype
   [APPBUNDLE]	For app ads, a platform-specific application identifier, bundle or package name and should not be an app store ID such as iTunes store ID	https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html#macro-spec-appbundle
   [DOMAIN]	Domain of the top level page where the end user will view the ad.	https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html#macro-spec-domain
   [PAGEURL]	The full URL of the top level page where the end user will view the ad	https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html#macro-spec-pageurl

2. Company can override this default macro replacement using the custom macro provider function. PBS will give priority to use company-defined macro values over its own behavior.

**Video Event Tracker Injections Scenarios **

Response Type	Framework behavior
InLine VAST XML	Modify the received VAST XML by adding the video event trackers
Wrapper VAST XML	Modify the received VAST XML by adding the video event trackers
Vast Tag URL	Generate Wrapper VAST XML containing the Vast TAG URL along with the video event trackers injected

Questions

1. What does the account stand for? It is company using PBS or partner ?
2. Not getting this (Mentioned in the feedback) - event URLs outside of the already-established event structure

Modularity Design - We can check if we can accommodate the current design proposal here.

[bretg]

I want to support the effort to improve video, but it's going to take some more discussion to iron out how to do this - there are several design aspects here I'm concerned about.

You might save us all some time if you wrote out the requirements first, but we made an effort to read between the lines of your more intricate suggestions. Let us know if we got them right.

Please note that this all coming up in the context of us working out a new modular architecture that could accommodate some of these requests.

What does the account stand for? It is company using PBS or partner ?

PBS terminology is that "host company" is the entity that downloads and hosts the server.
"Account" is the site.publisher.id or app.publisher.id -- the clients of the host company.

if their trackers are listening on endpoint apart from /event

What this suggests is that a Prebid Server host company should be able to delegate ALL event tracking to a system outside of Prebid Server. You didn't state why, but it must be that you already have an analytics server and you want the player's events to go directly there rather than via PBS.

However, I'm not architecturally comfortable with complete delegation -- i.e. totally overriding the PBS/event URL. The long term vision is that Prebid Server becomes an ecosystem of many modules, some of which may want to receive the video events. This implies two possible approaches:

1. Support the default PBS event URL format in addition to an external custom event URL. i.e. be able to insert multiple and tags.
2. Keep things the way they are and just build an analytics adapter plugged into PBS that forwards the events to an external system.

There are obviously tradeoffs here. #1 is more work for the player. #2 is more work coding up the "analytics redirect" module.

t=vtrack

Since there's already a /vtrack endpoint that means something else, I'd suggest just calling this t=vast.

firstQuartile = fq

Why not just pass the full VAST event name in the new 'e' parameter? That seems much cleaner than making up another mapping table. i.e. why not:

/event?t=vast&e=firstQuartile
/event?t=vast&e=midpoint
/event?t=vast&e=thirdQuartile
/event?t=vast&e=complete
/event?t=vast&e=pause
...

If inject_video_event_trackers is true, PBS will inject video event trackers
for firstQuartile, midpoint, thirdQuartile and complete

Two thoughts here:

• I would like to be considered a tracking event like these. i.e. they need to all work the same way
• I don't want PBS hardcoded to be able to handle only these 4 events. We know that someone's going to want other VAST events. We need to plan for that.

Support for standard macros

We don't understand why PBS needs to deal with macros. This is something the player is supposed to do. Discussing internally and reading between the lines, we're guessing that you want to be able to support players that don't support VAST 4.x macros.

My view is that's rather weird to shove this functionality into Prebid Server core. Seems quite out of place unless we dramatically expand what Prebid Server is thought to be. My preference would be that this kind of boutique feature should be a module that different Prebid Server host companies could decide to utilize or not.

If perhaps it's not a module in the initial implementation, I would request that it be implemented such that it could later be pulled out as a separate module.

Instead of callback we can call it a custom macro provider function

Again, reading between the lines here, I'm guessing that you guys have a bunch of modifications forked off of Prebid Server and this discussion is your effort to standardize some of them. I applaud that effort.

But we have no precedence at all for anything like a host-company-specific block of code. For this aspect of your quest, I would like to suggest that the modularity effort is a perfect match. One intent of the module architecture is that a host company can build proprietary modules in their fork that have well-known and unchanging interfaces into PBS-core.

So I'm hoping that you guys might be able to hold off on at least this last requirement and perhaps help us define/build the more generic modularity feature rather than defining a one-off "macro provider" interface.

[bretg]

@ShriprasadM and @mike-chowla -- I've drafted a counter-proposal at https://docs.google.com/document/d/1iiKnqZjqpnAvtsP3jVyW66hTySLUmgWtl9_7Z9Wx3oM/edit#

I believe this proposal is a fairly clean integration of the current PBS event design that covers almost all of your needs, including non-PBS tracking URLs. It doesn't, however, support a custom macro interface because I think you can just fork it for that until the modularity architecture is ready.

Will send email to see when would be a good time to review and talk through this proposal.

[ShriprasadM]

Thanks, @bretg!

[bretg]

This document has been reviewed and is basically ready for implementation. There may be some tweaks to the proposed configuration, so whoever implements in PBS-Go may want to discuss config with @SyntaxNode and @bretg .

PBS-Java will be implementing this as a module after the modularity infrastructure is done. It's fine for an implementor to build this into PBS-Go core, but should do so keeping in mind that it might become a module someday.

[SyntaxNode]

Hi @ShriprasadM. Do you still plan to implement this feature for PBS-Go?

[ShriprasadM]

Hi @SyntaxNode , Yes. I will update on it after discussing with @mike-chowla

[ShriprasadM]

@bretg and @SyntaxNode : here is the Phase I plan. Updating here so that others can be notified. https://docs.google.com/document/d/1zzi06jWpYsvhuiQ_3KCpes0DpmpO2teatmo4V5kIhi0/edit?usp=sharing

[ShriprasadM]

https://docs.google.com/document/d/1tMO8J3diZQyKx6_usA0GRIcppVlugYSqVcOEOjX4I9Y/edit?usp=sharing - Macro replacement framework reviewed with Prebid Team.
Questions Document - https://docs.google.com/document/d/1tH6I9Vho-_KaUIGNCMum9JwbxHDc0FyG2wD8T-h3wkY/edit?usp=sharing