updated sizeMapping to use sizeConfig and support labels

[snapwich]

Type of change

• Feature
• Refactoring (no functional changes, no api changes)

Description of change

Labels

Labels can now be specified as a property on either an adUnit or on adUnit.bids[]. The presence of a label will disable the adUnit or bidder unless a sizeConfig rule has matched and enabled the label or the label has been enabled manually through pbjs.setConfig({labels:[]}). Defining labels on the adUnit look like the following:

pbjs.addAdUnits([{
  "code": "ad-slot-1",
  "sizes": [ [ 970,90 ], [ 728,90 ], [ 300,250 ], [ 300,100 ] ],
  "labelAll": ["visitor-uk", "category"] 
  "bids": [  // the full set of bids, not all of which are relevant on all devices
    {
      "bidder": "pulsepoint",
      "labelsAny": [ "desktop", "tablet" ], // flags this bid as relevant only on these screen sizes
      "params": {
        "cf": "728X90",
        "cp": 123456,
        "ct": 123456
      }
    },
    {
      "bidder": "pulsepoint",
      "labelAny": [ "desktop", "phone" ],
      "params": {
        "cf": "300x250",
        "cp": 123456,
        "ct": 123456
      }
    },
    {
      "bidder": "sovrn",
      "labelAny": [ "desktop", "tablet" ],
      "params": {
        "tagid": "123456"
      }
    },
    {
      "bidder": "sovrn",
      "labelAny": [ "phone" ],
      "params": {
        "tagid": "111111"
      }
    }
  ]
}];

Size Configuration

To set size configuration rules, you can use pbjs.setConfig as follows

pbjs.setConfig({
  sizeConfig: [{
    'mediaQuery': '(min-width: 1200px)',
    'sizesSupported': [
      [970, 90],
      [728, 90],
      [300, 250]
    ],
    'labels': ['desktop']
  }, {
    'mediaQuery': '(min-width: 768px) and (max-width: 1199px)',
    'sizesSupported': [
      [728, 90],
      [300, 250]
    ],
    'labels': ['tablet', 'phone']
  }, {
    'mediaQuery': '(min-width: 0px)',
    'sizesSupported': [
      [300, 250],
      [300, 100]
    ],
    'labels': ['phone']
  }]
});

The sizeConfig configuration accepts an array of sizeConfig objects. The sizeConfig.mediaQuery property allows media queries in the form described here. They are tested using the window.matchMedia API. If the sizeConfig.mediaQuery rule matches, the listed sizeConfig.labels will be enabled and filtering will be performed on adUnit.sizes for the matching adUnits and/or bidders using the sizes listed in sizeConfig.sizesSupported. If multiple rules match, the sizes will be filtered to the intersection of all matching rules' sizeConfig.sizesSupported arrays.

Manual Label Configuration

You can manually turn on labels by passing the labels to pbjs.requestBids

pbjs.requestBids({
  adUnits,
  labels: ['visitor-uk']
});

If an adUnit and/or adUnit.bids[] bidder has labelsAny or labelsAll defined they will be disabled by default. Manually setting active labels using pbjs.requestBids labels can re-enable the selected adUnits and/or bidders.

[snapwich]

@jaiminpanchal27 I have good unit tests for the sizeMapping module, but I want to add some integration (kinda) tests to make sure that adUnits/bidders are properly disabled/enabled when passing labels to pbjs.requestBids. Where should those tests go? The actual logic for enabling/disabling is within the adapterManager.js inside makeBidRequests (when it calls the private getBids function), but there doesn't any tests for that code yet, unless I'm missing it being tested as part of another module.

[jaiminpanchal27]

@snapwich the best way to test this would be to use adaptermanager.makeBidRequests and assert on bidRequests.bids
makeBidRequest arguments auctionStart, auctionId, cbTimeout can be anything since we are only interested in checking bidRequests.bids

[snapwich]

new tests added, should be ready for review now.

[snapwich]

updated pull-request comment to specify that adUnit/bidder labels are specified w/ labelAny and labelAll, I had it plural before, which is incorrect.

[mkendall07]

Overall looks great. Just a couple of minor thing to update and can be merged. Thanks!

[mkendall07]

in my experience, creating objects on the fly like this is better done more formally, at least in a function were you can use @param and also reduces chances to code to a single place.

[snapwich]

Updated some names and added a typedef to help. I tried to use a constructor function but my IDEs linter was not having it, claiming a type mismatch; so left as factory function.

[mkendall07]

obj could use a better name bidOrAdUnit ?

[mkendall07]

Maybe add a hint in the log here that it could be because labels didn't match / didn't exist? Or even better if there was an easy code point to detect that condition (I don't see one).

[snapwich]

Added the hint

[mkendall07]

💯 for dropping all this code!

[snapwich]

updated

[mkendall07]

@bretg can you take this for updating docs for this feature on prebid.org?

[bretg]

will work on submitting the docs next week