Prebid Server Event Notification proposal

[bretg]

Overview

Prebid Server currently only has information about part of the header bidding process: the request and the bids. As the platform matures with analytics and other functionality, it may need to know the results of what was displayed in the adunits or other user events.

Use Cases

1. Analytics modules plugged into Prebid Server would like to have access to ad server win notifications so that reporting numbers coming from the interface are more complete.
2. For future support of video events, Prebid Server should be able to accept events of any kind, e.g. pause, firstQuartile ad viewed, etc.
3. For future optimization efforts, clients should be able to inform Prebid Server when there was a timeout. A smarter Prebid Server might be able to determine a more realistic timeout value by considering user location, bidders, and past timeout data.

Background

OpenRTB supports several specific event types, but not a general event mechanism:

• nurl - notice URL. This is currently used by Prebid Server to store the location of the VAST XML. It’s called by the SDK (not seeing this explicitly in the SDK code). This value is dropped from OpenRTB 3.0 in favor of ADCOM’s ‘curl’ (creative URL) value.
• burl - billing URL is meant to be called when the ad can be billed, whether on render or view.
• purl - pending URL is meant as a notice that this bid won a non-authoritative auction, but may not be chosen by subsequent auctions.
• lurl - loss URL is an optional signal to the bidder that the bid was not accepted.

Events associated with video creatives are listed in 3.14.1 of https://iabtechlab.com/wp-content/uploads/2018/06/VAST4.1-June7-FINAL.pdf

Mobile renders currently work this way:

• Prebid Server adapters must set one or both of the following fields:
  • adm - the AD Markup, or body of the creative
  • nurl - a URL pointing to a cached version of the ad markup
• Prebid Servers forward adm and nurl through OpenRTB response (in seatbid.bid)
• Prebid SDK forwards all targeting variables to the ad server
• If the ad server chooses the header bid as the winner, it serves the Prebid Universal Creative containing the supplied hb_* variables.
• The Prebid Universal Creative obtains the metadata from the winning bid either from local storage or by retrieving it from cache using hb_cache_id
• The Prebid Universal Creative then renders the creative by either:
  • If the bid contains AD Markup, it writes to the allocated space. If the bid also contains nurl, it's assumed to be a tracking pixel that's added to the bottom of the markup.
  • If the bid contains only nurl, it creates a script with nurl as the src.

Assumptions

1. A future release of Prebid Server will support OpenRTB 3.0.
2. Bidders will utilize all of the OpenRTB events for their own purposes: nurl, burl, purl, and lurl.
3. If we insert a layer of redirection before an existing bidder event, we should include protection against tampering with the redirect URL so as not to be an open redirector.
4. When an event comes in to the server, the auction may not have cached the bid portion of the auction, or may have been far enough in the past that we cannot assume any cached creative or bid entries are still in the cache. Therefore, we can’t utilize the cache uuid to obtain bid metadata.
5. Wrapping the VAST XML in a Prebid-Server specific wrapper containing event URLs will be a separate project. Therefore, the primary focus of this document is on ad server win notification, with consideration given to future expansion of video events.
6. Likewise, it’s not expected that end-to-end viewability support is in scope for this document, but consideration is given to how it works within Prebid Server.
7. It will be necessary to join events offline with the original auction response to obtain the full set of auction metadata that may be needed.

Requirements

General

1. The host and path used to communicate events should be configurable for each cluster of Prebid Servers.
2. The Prebid Server event system must not override or block events required by the bidder such as nurl, burl, etc.
3. The event system should be capable of supporting several modes of invocation. It should be able to respond to an event URL with any of these options:
   1. A standalone event system returning an HTTP 200.
   2. A blank tracking pixel in case an event needs to be placed in a creative.
   3. In the future, we may want a redirect so Prebid Server can inject tracking events in a redirect chain. The redirect requires a checksum created with a host-specific key. An encrypted datetime stamp should also be used to frustrate attempts to use Prebid Server as an open redirector. The specific checksum algorithm is not detailed here.
4. If an event URL contains an error (including failed checksum), the system should respond with code 400.
5. Event URLs must support specifying the following event types:
   1. win - the ad serving process chose a header bid as the overall auction winner. This may or may not mean at the ad has been rendered on the page and is viewable by the user.
   2. view - the ad has been viewed by the user.
   3. video events - All the events defined by the IAB. The specifics of supporting video events is left for a later project.
6. Event URLs must support appropriate attributes so that events can be A) unduplicated and B) joined with the original bid response to get information such as advertiser, price, context, etc.
   1. Auction seatbid[].bid[].bidid - the specific bidid supplied by the bidder.
   2. Auction seatbid[].seat - may help inform Prebid Server which adapter needs to process the event in case there are multiple places to route internally.
7. It should be possible to configure Prebid Server to create ‘win’ events on a per-account basis.
   1. Direct win and view events URL should be made available to the client in response.seatbid.bid.ext.prebid.events.win and response.seatbid.bid.ext.prebid.events.view.
   2. For AMP and app requests, a new ‘hb_winurl’ and 'hb_bidid_BIDDER' targeting parameters should be supplied in the response. The Prebid Universal Creative will be modified to resolve the BIDID macro and hit this URL when present.
8. Events must be available through the Prebid Server analytics interface, so that analytics adapters can forward the event through to the analytics endpoint.

Event URLs

Image (triggered by the existence of format parameter):

PREBIDHOST/event?t=win&b=111-111-111&f=i

See below for App and AMP scenarios.

For Native, event URLs are placed into the seatbid[].bid[].ext.prebid.events object:

{
  seatbid: [{
    bid: [{
      ext: {
        prebid: {
          events: {
            win: “PREBIDHOST/event?t=win&b=111-111-111”,
            view: “PREBIDHOST/event?t=view&b=111-111-111”
          }
        }
      }
    }]
  }]
}

Mobile Apps

No near term changes to the SDK are expected for mobile support. See above for details on how mobile apps render in conjunction with the Prebid Universal Creative.

When win notification is turned on for a given account, the hb_winurl targeting variable will be returned and the Prebid Universal Creative will hit the URL provided.

AMP

Accelerated Mobile Pages (AMP) can only receive parameters through ad server targeting, so it requires us to pass new targeting variables that will be utilized by the Prebid Universal Creative. (See prebid/prebid-universal-creative#70)

{
    "targeting": {
        "hb_winurl":"https://prebid-server.rubiconproject.com/event?t=win&b=BIDID&f=i",
        "hb_bidid":"4b61fbb6-d864-4a36-b3dc-ef860d104601",
        "hb_bidid_rubicon":"4b61fbb6-d864-4a36-b3dc-ef860d104601",
        "hb_pb": "1.20",
        ...
    }
}

1. The Prebid Universal Creative will be updated to look for the ‘hb_winurl’ and 'hb_bidid_BIDDER' targeting variables and to hit the resolved URL after rendering the creative. See Support win notifications prebid-universal-creative#70
2. If ‘hb_winurl’ is not present in the set of targeting keys, no additional action should take place after render.
3. If ‘hb_winurl’ was present and the HTTP response from the event is not 200, an error should be logged to the javascript console.

Prebid.js

Prebid.js implementations will not use hb_winurl - it's assumed that the analytics adapter will be able to handle the BID_WON event.

It’s assumed that viewability is a future feature in Prebid.js, so making use of response.seatbid.bid.ext.prebid.events.view is out of scope for now.

Native

TBD

[bretg]

Met with members of the committee to talk this through.

A suggestion came up around AMP, that instead of having the client/PrebidUniversalCreative explicitly hit an event URL, we have Prebid Cache server generate the event as part of the cache read. It could work something like this:

1. Prebid Server AMP response contains a new targeting variable to trigger a behavior in Prebid Universal Creative. e.g. "hb_int=amp". ('int' being short for integration)
2. Prebid Universal Creative sees this value, causing it to add another parameter to the end of the cache retrieval. e.g. "https://HB_CACHE_HOST/HB_CACHE_PATH?uuid=HB_CACHE_ID&event=win"
3. When Prebid Cache sees "&event=win", and the cache entry was successfully retrieved, that triggers PBC to generate that event directly to Prebid Server containing the retrieved bidId.

Pros

• Lighter on the client: shorter targeting value and one less outbound call

Cons

• Creates application logic in PBC, which as of right now doesn't have any app logic.
• Creates a need for host companies to allow network traffic to initiate on PBC and route to PBS. Currently, that network link is only the other way around -- PBS initiates communication.

[bretg]

After digging through how Prebid Universal Creatives does rendering for apps, updated the description above to refine how PBS should interact with apps: modifying the nurl is more nuanced than originally written.

[bretg]

Instead of modifying the nurl, we have another option: we could utilize the hb_winurl approach for mobile as well as AMP, significantly simplifying implementation and probably improving robustness. (I'd expect some percentage of nurl-redirects to fail.)

But as Jordi pointed out, the hb_winurl approach does create another outgoing request.

[bretg]

Met with the committee today. We resolved for the first phase:

• Go with hb_winurl approach for both app and AMP
• No need to implement the redirect interface for now.
• We will consider a second phase where hosting companies can create implicit events from cache retrieval

The description above has been updated to reflect the changes. Next step is that Rubicon will release a tech spec.

[bretg]

We've decided to simplify and have Prebid.js use the hb_winurl approach. This will require anyone interested in having win-events to use the (future) version of Prebid Universal Creative (PUC), but this is ok, and keeps display aligned with AMP and SDK. However, Native is still outstanding -- it doesn't use PUC so we're going to keep the bid.ext.prebid.events.win field in the response.

Here's the technical specification the PBS-Java team is working towards.

Prebid Server Event Notifications - Tech Spec.pdf

[bretg]

Closing this issue. Will open another for video when we get there.