General client-side analytics response object

[bretg]

The split between server-side and client-side analytics continues to plague us, so adding another in a long line of features aimed at having equivalent analytics functionality. (seatnonbid was the most recent feature in this series.)

As a reminder, the use cases for server-side and client-side analytics are different:

• server-side analytics are the only game in town when it comes to App, AMP, DOOH, etc.
• However, when Prebid.js is in use and bidders are split between client-side and server-side, there are two analytics systems. The goal is that auctions are only logged once because processing them at scale is expensive.

So the aim is to have all relevant data passed to the client from Prebid Server so that client-side analytics can be the one to log the results. This behavior should be turned on the in the request so as not to send extra bytes back when unnecessary.

Here's a proposal:

1. We've already documented ext.prebid.analytics.ADAPTER as a way for the client to pass arguments through to server-side analytics adapters, so we add a new attribute in a new object ext.prebid.analytics.options.enableclientdetails as a boolean.
2. In case there are instances where analytics data is sensitive, there should be a control at a host and account level. Add a analytics.allow_client_details boolean configuration that defaults to false.
3. When creating the client response for the normal ORTB scenario (i.e. not AMP), if the request contains ext.prebid.analytics.options.enableclientdetails: true and config analytics.allow_client_details:false, emit a warning "analytics.options.enableclientdetails not enabled for account" in the response. No metrics or logs.
4. If the request contains ext.prebid.analytics.options.enableclientdetails: true and config analytics.allow_client_details:true, then PBS-core processes the analytics tags objects into the response at ext.prebid.analytics.tags.
5. It's the responsibility of the client-side analytics adapters to process this JSON for the module-specific data within.
6. This does not affect server-side analytics, which proceeds normally.

Example

The "pb-ortb-blocking" module at the "processed auction" stage adds the following Analytics Tags (from the ORTB2 blocking module)

[{
   activities: [{
    name: "enforce-blocking",
    status: "success",
    results: [{
        status: "success-block",
        values: {
                  "attributes": ["badv"],
                  "adomain": ["bad.com"]
        },
        appliedto: {
          "bidder": "bidderA",
           impids: ["1"]
        }
    },{
        status: "success-allow",
        appliedto: {
          "bidder": "bidderA",
          "impids": ["2","3","4"]
        }
    }]
 }]

The "vendorA-brand-safety" module at the "all processed bid responses" stage adds these ATags:

[{
   activities: [{
    name: "brand-safety",
    status: "success",
    results: [{
        status: "success-allow",
        appliedto: {
          "bidder": "bidderA",
          "impids": ["1,","2","3","4"]
        }
    }]
 }]

The resulting response with the request ext.prebid.analytics.options.enableclientdetails: true and config analytics.options.enableclientdetails:true would be

ext.prebid.analytics.tags: [{
  "stage": "processed-auction-request",
  "module": "pb-ortb-blocking",
  "analyticstags": [{
     activities: [{
      name: "enforce-blocking",
      status: "success",
      results: [{
        status: "success-block",
        values: {
                  "attributes": ["badv"],
                  "adomain": ["bad.com"]
        },
        appliedto: {
          "bidder": "bidderA",
           impids: ["1"]
        }
    },{
        status: "success-allow",
        appliedto: {
          "bidder": "bidderA",
          "impids": ["2","3","4"]
        }
    }]
 }]
},{
  "stage": "all-processed-bid-responses",
  "module": "vendorA-brand-safety",
  "analyticstags": [{
   activities: [{
    name: "brand-safety",
    status: "success",
    results: [{
        status: "success-allow",
        appliedto: {
          "bidder": "bidderA",
          "impids": ["1,","2","3","4"]
        }
    }]
}]

[bsardo]

@bretg the behavior here seems reasonable and complete. The only nitpick is whether the response should contain ext.prebid.analyticstags or if it should be ext.prebid.analytics.tags if we want to leave the door open to add additional analytics fields on ext.prebid.analytics.

[bretg]

Thanks - @bsardo . Agree that ext.prebid.analytics.tags leaves the door open for future additions. Changed.

[bretg]

released with PBS-Java 3.3