Enhance mobile tracking

[bretg]

While doing a review of mobile tracking for the docs site, several gaps were discovered in the tracking implementation:

1. The "Prebid-Rendered" scenarios don't track either burl or nurl.
2. The mediation scenarios don't track either burl or nurl.
3. In PUC scenarios, there's a discrepancy between the handling of burl and the PBS win event. The burl uses MRAID to trigger on viewability, which can be quite different from the numbers reported by the PBS win event.

In addition, the Prebid.js team is discussing an expansion of tracking abilities in prebid/Prebid.js#12216 . Here's a multi-part proposal to address tracking:

Prebid SDK

1. Enhance the Prebid-Rendered and Mediation scenarios to support firing the nurl and burl. The notice URL (nurl) should be treated as a "win url" -- fired on the ad server choosing the Prebid ad. The billing URL (burl) should be fired when viewable by OMSDK's definition of "isViewable". (Someone needs to decide what percent viewable counts here.)
2. Enhance all tracking scenarios (Bidding-Only, Prebid-Rendered, Native, and Mediation) to support looking beyond burl and nurl. Loop through through the eventtrackers array:
   1. If type: 500, treat it per the current PBS win event logic
   2. If type: 1, treat it as a burl - add a pixel when in-view 10%
   3. If type: 2, treat it as a burl - add a pixel when in-view 50%
   4. If type: 3, treat it as a burl - add a pixel when in-view 100%

Prebid Server

PBS currently does the following:

1. For banners, when analytics is enabled for an account, it returns seatbid.bid.ext.prebid.events.{win,imp} in the ORTB
2. For banners and native when analytics is enabled and PBS is told to cache the bid (ext.prebid.cache.bids), it stores a field in the cache called wurl along with nurl. This wurl (win url) field is Prebid-specific and is utilized by the PUC when it retrieves bids from the cache.
3. For video, when analytics is enabled, it adds an tag to the VAST before returning or caching it.

A new account-level configuration will be added that will change the core tracking behavior. Suggested name is auction.events.eventtracker_support.

1. If auction.events.eventtracker_support:false (the default) the current tracking behavior continues.
2. If auction.events.eventtracker_support:true:
   1. seatbid.bid.ext.prebid.events is no longer emitted
   2. instead, the seatbid.bid.ext.eventtrackers array is created or appended. Example below.
   3. wurl is no longer stored with other bid data
   4. instead, all of the bid's eventtrackers (including any PBS-generated entries) are added to the cached bid as eventtrackers in the ORTB array-of-objects format.
   5. video tracking does not change

When in the new tracking mode, PBS emits these ORTB objects instead of the existing seatbid.bid.ext.prebid.events:

seatbid[].bid[].ext.eventtrackers: [{
    type: 500, // win event
    method: 1, // 1x1
    url: "https://PBSDOMAIN/event?t=win&b=BID&a=22312&aid=AUCTION&ts=1726779089912&bidder=BIDDER&f=i"
},{
    type: 1, // imp event
    method: 1, // 1x1
    url: "https://PBSDOMAIN/event?t=imp&b=BID&a=22312&aid=AUCTION&ts=1726779089912&bidder=BIDDER&f=i"
}]

The eventtrackers are cached in PBC along with other bid metadata:

{
        "adm": "... creative body ...",
        "width": 300,
        "height": 250,
        "eventtrackers": [{
           type: 500, // win event
           method: 1, // 1x1
           url: "https://PBSDOMAIN/event?t=win&b=BID&a=22312&aid=AUCTION&ts=1726779089912&bidder=BIDDER&f=i"
},{
           type: 1, // imp event
           method: 1, // 1x1
           url: "https://PBSDOMAIN/event?t=imp&b=BID&a=22312&aid=AUCTION&ts=1726779089912&bidder=BIDDER&f=i"
}]
}

PUC

Instead of just looking for wurl in the PBS response, the PUC should also look through the eventtrackers array:

1. If type: 500, treat it per the current wurl logic
2. If type: 1 and MRAID is present to determine viewability, treat this URL the same as the burl is currently treated in that scenario.

Prebid.js

Instead of just looking for seatbid.bid.ext.prebid.events.win in the PBS response, Prebid.js also looks through the eventtrackers array:

1. If type: 500, treat it per the current pbsWurl logic
2. If type: 1, the ideal would be to append a pixel to the iframe after injecting the creative body. Unclear whether this is as straightforward as it sounds.

[YuriyVelichkoPI]

Hi @bretg! Everything looks reasonable in this ticket and should be implemented.

In addition, we would like to discuss the additional experimental event tracking approach introduced in #1060.

In short, we want to track imp (burl) event on the Prebid SDK side when GAM's BannerView appears on the screen. However, the approach in the above PR conflicts with the current tracking of the burl event. Because the burl is tracked by PUC.

To address the conflict, we wanted to introduce the issue and @OlenaPostindustria has prepared the text, but it looks like we should discuss it first in the scope of this initiative.

What need to change for current behaviour

We need to block the burl tracking by PUC if SDK's tracking is activated. For this purpose, we propose to exclude the burl field from the cached creative if the request contains a custom field imp.ext.prebid.sdkimptracking = true.

In this case, the PUC will have nothing to track, and burl will be tracked once by the Prebid SDK. No changes to PUC or creative code on GAM are required.

Note: the impression tracking by SDK is an opt-in feature, not a default one. Publishers will have to change the code to activate it. So the current behavior won't change with introducing SDK-side imp tracking.

Extension for eventtrackers

In the scope of introducing eventtrackers, we can add the flag tracker to the eventtracker object. The value of tracker can be puc or sdk. The puc should be treated as a default value in no value is provided.

Server

If the request contains imp.ext.prebid.sdkimptracking = true the tracker for imp event should be sdk.

PUC

Manage the event trackers in which tracker is empty or equal to puc.

SDK

Manage the event trackers in which tracker is equal to sdk.

Does it sound reasonable?