Ability to specify PBS Stored Request IDs

[bretg]

Type of issue

Enhancement

Description

It's come up a few times that it might be useful to support specifying Prebid Server stored request IDs from Prebid.js

There are several issues/constraints:

1. s2sConfig is global, not per-adunit.
2. stored requests don't make sense client-side, so can't be used in A/B test scenarios.
3. s2sConfig currently determines which adunits to send to PBS based on the s2sConfig.bidders array.
4. While Stored Requests are meant to define the bidders/params, there could be a scenario (e.g. A/B client/server testing) where bidders are defined both in the page and in the server.

In the end, what needs to get passed to PBS would be similar to what Prebid SDK sends:

{
  "id": "auction-id",
  "site": {
       ... any details provided by the page ...
  },
  "imp": [
    {
      "id": "imp-id",
      "banner": {     // or video
         "format": [
            {
                "h": 250,
                "w": 300
            }
        ]
      },
      "ext": {
        "prebid": {
          "storedrequest": {     // this pulls in the bidders and params for the first ad slot
            "id": "IMP_LEVEL_PREBID_SERVER_STOREDREQUEST_ID"
          }
        }
      }
    }
  ],
  "ext": {
    "prebid": {
	"storedrequest": {   // this maps to the "top-level" stored request
          "id": "TOP_LEVEL_PREBID_SERVER_STOREDREQUEST_ID"  // Pulls in global behavior (cache, targeting)
	}
    }
  }
}

Proposal

1. Add a new field to the AdUnit that defines the serverImpStoredRequest

pbjs.addAdUnits({
    code: slot.code,
    serverImpStoredRequest: "1234abcd",
    mediaTypes: {
        banner: {
            sizes: [[300, 250]]
        }
    },
    bids: [
        {
            bidder: 'appnexus',
            params: {
                placementId: 13144370
            }
        }
    ]
});

2. Add a convention to s2sConfig to define serverTopStoredRequest

pbjs.setConfig({
    s2sConfig: [{
        accountId: '1',
        serverTopStoredRequest: "1234-top-level",
        bidders: ['bidderA', 'bidderB'],
        defaultVendor: 'appnexus',
        ...

3. Update the pbsBidAdapter to support these two new conventions:

1. While scanning AdUnits, if serverImpStoredRequest is defined, that AdUnit will go to PBS with no specific bidders in the imp -- just the imp-level stored request(s) and of course any specified serverTopStoredRequest. See the example above for how to structure the OpenRTB in this scenario.
2. Otherwise, if serverImpStoredRequest isn't found, follow the normal logic of looking in the AdUnit for biddercodes that are in s2sConfig.bidders.

[bretg]

Merging this effort with #5795

The top Level Stored Request could be specified with extPrebid:

    s2sConfig: [{
       extPrebid: {
	   "storedrequest": {   // this maps to the "top-level" stored request
             "id": "TOP_LEVEL_PREBID_SERVER_STOREDREQUEST_ID"  // Pulls in global behavior (cache, targeting)
	   }
       }
    }]

The impression level stored requests can be set with ortb2ImpExt:

pbjs.addAdUnits({
    code: "test-div",
    mediaTypes: {
        banner: {
            sizes: [[300,250]]
        }
    },
    ortb2ImpExt: {
           "prebid": {
             "storedrequest": {     // this pulls in the bidders and params for the first ad slot
               "id": "IMP_LEVEL_PREBID_SERVER_STOREDREQUEST_ID"
             }
         }
    },
    ...
});