prebid.js 7.22.0 → 7.24.0

package/modules/openxOrtbBidAdapter.js

@@ -1,14 +1,12 @@
 import {config} from '../src/config.js';
 import {registerBidder} from '../src/adapters/bidderFactory.js';
 import * as utils from '../src/utils.js';
+import {mergeDeep} from '../src/utils.js';
 import {BANNER, VIDEO} from '../src/mediaTypes.js';
-import {includes} from '../src/polyfill.js';
+import {ortbConverter} from '../libraries/ortbConverter/converter.js';
 
 const bidderConfig = 'hb_pb_ortb';
 const bidderVersion = '1.0';
-const VIDEO_TARGETING = ['startdelay', 'mimes', 'minduration', 'maxduration', 'delivery',
-  'startdelay', 'skip', 'playbackmethod', 'api', 'protocol', 'boxingallowed', 'maxextended',
-  'linearity', 'delivery', 'protocols', 'placement', 'minbitrate', 'maxbitrate', 'battr', 'ext'];
 export const REQUEST_URL = 'https://rtb.openx.net/openrtbb/prebidjs';
 export const SYNC_URL = 'https://u.openx.net/w/1.0/pd';
 export const DEFAULT_PH = '2d1251ae-7f3a-47cf-bd2a-2f288854a0ba';
@@ -24,6 +22,118 @@ export const spec = {
 
 registerBidder(spec);
 
+const converter = ortbConverter({
+  context: {
+    netRevenue: true,
+    ttl: 300
+  },
+  imp(buildImp, bidRequest, context) {
+    const imp = buildImp(bidRequest, context);
+    if (bidRequest.mediaTypes[VIDEO]?.context === 'outstream') {
+      imp.video.placement = imp.video.placement || 4;
+    }
+    if (imp.ext?.ae && !context.bidderRequest.fledgeEnabled) {
+      // TODO: we may want to standardize this and move fledge logic to ortbConverter
+      delete imp.ext.ae;
+    }
+    mergeDeep(imp, {
+      tagid: bidRequest.params.unit,
+      ext: {
+        divid: bidRequest.adUnitCode
+      }
+    });
+    if (bidRequest.params.customParams) {
+      utils.deepSetValue(imp, 'ext.customParams', bidRequest.params.customParams);
+    }
+    if (bidRequest.params.customFloor && !imp.bidfloor) {
+      imp.bidfloor = bidRequest.params.customFloor;
+    }
+    return imp;
+  },
+  request(buildRequest, imps, bidderRequest, context) {
+    const req = buildRequest(imps, bidderRequest, context);
+    mergeDeep(req, {
+      at: 1,
+      ext: {
+        bc: `${bidderConfig}_${bidderVersion}`
+      }
+    })
+    const bid = context.bidRequests[0];
+    if (bid.params.doNotTrack) {
+      utils.deepSetValue(req, 'device.dnt', 1);
+    }
+    if (bid.params.platform) {
+      utils.deepSetValue(req, 'ext.platform', bid.params.platform);
+    }
+    if (bid.params.delDomain) {
+      utils.deepSetValue(req, 'ext.delDomain', bid.params.delDomain);
+    }
+    if (bid.params.response_template_name) {
+      utils.deepSetValue(req, 'ext.response_template_name', bid.params.response_template_name);
+    }
+    if (bid.params.test) {
+      req.test = 1
+    }
+    return req;
+  },
+  bidResponse(buildBidResponse, bid, context) {
+    const bidResponse = buildBidResponse(bid, context);
+    if (bid.ext) {
+      bidResponse.meta.networkId = bid.ext.dsp_id;
+      bidResponse.meta.advertiserId = bid.ext.buyer_id;
+      bidResponse.meta.brandId = bid.ext.brand_id;
+    }
+    const {ortbResponse} = context;
+    if (ortbResponse.ext && ortbResponse.ext.paf) {
+      bidResponse.meta.paf = Object.assign({}, ortbResponse.ext.paf);
+      bidResponse.meta.paf.content_id = utils.deepAccess(bid, 'ext.paf.content_id');
+    }
+    return bidResponse;
+  },
+  response(buildResponse, bidResponses, ortbResponse, context) {
+    // pass these from request to the responses for use in userSync
+    const {ortbRequest} = context;
+    if (ortbRequest.ext) {
+      if (ortbRequest.ext.delDomain) {
+        utils.deepSetValue(ortbResponse, 'ext.delDomain', ortbRequest.ext.delDomain);
+      }
+      if (ortbRequest.ext.platform) {
+        utils.deepSetValue(ortbResponse, 'ext.platform', ortbRequest.ext.platform);
+      }
+    }
+    const response = buildResponse(bidResponses, ortbResponse, context);
+    // TODO: we may want to standardize this and move fledge logic to ortbConverter
+    let fledgeAuctionConfigs = utils.deepAccess(ortbResponse, 'ext.fledge_auction_configs');
+    if (fledgeAuctionConfigs) {
+      fledgeAuctionConfigs = Object.entries(fledgeAuctionConfigs).map(([bidId, cfg]) => {
+        return Object.assign({
+          bidId,
+          auctionSignals: {}
+        }, cfg);
+      });
+      return {
+        bids: response.bids,
+        fledgeAuctionConfigs,
+      }
+    } else {
+      return response.bids
+    }
+  },
+  overrides: {
+    imp: {
+      bidfloor(setBidFloor, imp, bidRequest, context) {
+        // enforce floors should always be in USD
+        // TODO: does it make sense that request.cur can be any currency, but request.imp[].bidfloorcur must be USD?
+        const floor = {};
+        setBidFloor(floor, bidRequest, {...context, currency: 'USD'});
+        if (floor.bidfloorcur === 'USD') {
+          Object.assign(imp, floor);
+        }
+      }
+    }
+  }
+});
+
 function transformBidParams(params, isOpenRtb) {
   return utils.convertTypes({
     'unit': 'string',
@@ -47,190 +157,21 @@ function isBidRequestValid(bidRequest) {
 function buildRequests(bids, bidderRequest) {
   let videoBids = bids.filter(bid => isVideoBid(bid));
   let bannerBids = bids.filter(bid => isBannerBid(bid));
-  let requests = bannerBids.length ? [createBannerRequest(bannerBids, bidderRequest)] : [];
+  let requests = bannerBids.length ? [createRequest(bannerBids, bidderRequest, BANNER)] : [];
   videoBids.forEach(bid => {
-    requests.push(createVideoRequest(bid, bidderRequest));
+    requests.push(createRequest([bid], bidderRequest, VIDEO));
   });
   return requests;
 }
 
-function createBannerRequest(bids, bidderRequest) {
-  let data = getBaseRequest(bids[0], bidderRequest);
-  data.imp = bids.map(bid => {
-    const floor = getFloor(bid, BANNER);
-    let imp = {
-      id: bid.bidId,
-      tagid: bid.params.unit,
-      banner: {
-        format: toFormat(bid.mediaTypes.banner.sizes),
-        topframe: utils.inIframe() ? 0 : 1
-      },
-      ext: {divid: bid.adUnitCode}
-    };
-
-    if (bidderRequest.fledgeEnabled) {
-      imp.ext.ae = bid?.ortb2Imp?.ext?.ae
-    }
-
-    enrichImp(imp, bid, floor);
-    return imp;
-  });
+function createRequest(bidRequests, bidderRequest, mediaType) {
   return {
     method: 'POST',
     url: config.getConfig('openxOrtbUrl') || REQUEST_URL,
-    data: data
-  }
-}
-
-function toFormat(sizes) {
-  return sizes.map((s) => {
-    return { w: s[0], h: s[1] };
-  });
-}
-
-function enrichImp(imp, bid, floor) {
-  if (bid.params.customParams) {
-    utils.deepSetValue(imp, 'ext.customParams', bid.params.customParams);
-  }
-  if (floor > 0) {
-    imp.bidfloor = floor;
-    imp.bidfloorcur = 'USD';
-  } else if (bid.params.customFloor) {
-    imp.bidfloor = bid.params.customFloor;
-  }
-  if (bid.ortb2Imp && bid.ortb2Imp.ext && bid.ortb2Imp.ext.data) {
-    imp.ext.data = bid.ortb2Imp.ext.data;
+    data: converter.toORTB({bidRequests, bidderRequest, context: {mediaType}})
   }
 }
 
-function createVideoRequest(bid, bidderRequest) {
-  let width;
-  let height;
-  const videoMediaType = utils.deepAccess(bid, `mediaTypes.video`);
-  const playerSize = utils.deepAccess(bid, 'mediaTypes.video.playerSize');
-  const context = utils.deepAccess(bid, 'mediaTypes.video.context');
-  const floor = getFloor(bid, VIDEO);
-
-  // normalize config for video size
-  if (utils.isArray(bid.sizes) && bid.sizes.length === 2 && !utils.isArray(bid.sizes[0])) {
-    width = parseInt(bid.sizes[0], 10);
-    height = parseInt(bid.sizes[1], 10);
-  } else if (utils.isArray(bid.sizes) && utils.isArray(bid.sizes[0]) && bid.sizes[0].length === 2) {
-    width = parseInt(bid.sizes[0][0], 10);
-    height = parseInt(bid.sizes[0][1], 10);
-  } else if (utils.isArray(playerSize) && playerSize.length === 2) {
-    width = parseInt(playerSize[0], 10);
-    height = parseInt(playerSize[1], 10);
-  }
-
-  let data = getBaseRequest(bid, bidderRequest);
-  data.imp = [{
-    id: bid.bidId,
-    tagid: bid.params.unit,
-    video: {
-      w: width,
-      h: height,
-      topframe: utils.inIframe() ? 0 : 1
-    },
-    ext: {divid: bid.adUnitCode}
-  }];
-
-  enrichImp(data.imp[0], bid, floor);
-
-  if (context) {
-    if (context === 'instream') {
-      data.imp[0].video.placement = 1;
-    } else if (context === 'outstream') {
-      data.imp[0].video.placement = 4;
-    }
-  }
-
-  // backward compatability for video params
-  let videoParams = bid.params.video || bid.params.openrtb || {};
-  if (utils.isArray(videoParams.imp)) {
-    videoParams = videoParams[0].video;
-  }
-
-  Object.keys(videoParams)
-    .filter(param => includes(VIDEO_TARGETING, param))
-    .forEach(param => data.imp[0].video[param] = videoParams[param]);
-  Object.keys(videoMediaType)
-    .filter(param => includes(VIDEO_TARGETING, param))
-    .forEach(param => data.imp[0].video[param] = videoMediaType[param]);
-
-  return {
-    method: 'POST',
-    url: REQUEST_URL,
-    data: data
-  };
-}
-
-function getBaseRequest(bid, bidderRequest) {
-  let req = {
-    id: bidderRequest.auctionId,
-    cur: [config.getConfig('currency.adServerCurrency') || 'USD'],
-    at: 1,
-    tmax: config.getConfig('bidderTimeout'),
-    site: {
-      page: config.getConfig('pageUrl') || bidderRequest.refererInfo.referer
-    },
-    regs: {
-      coppa: (config.getConfig('coppa') === true || bid.params.coppa) ? 1 : 0,
-    },
-    device: {
-      dnt: (utils.getDNT() || bid.params.doNotTrack) ? 1 : 0,
-      h: screen.height,
-      w: screen.width,
-      ua: window.navigator.userAgent,
-      language: window.navigator.language.split('-').shift()
-    },
-    ext: {
-      bc: `${bidderConfig}_${bidderVersion}`
-    }
-  };
-
-  if (bid.params.platform) {
-    utils.deepSetValue(req, 'ext.platform', bid.params.platform);
-  }
-  if (bid.params.delDomain) {
-    utils.deepSetValue(req, 'ext.delDomain', bid.params.delDomain);
-  }
-  if (bid.params.response_template_name) {
-    utils.deepSetValue(req, 'ext.response_template_name', bid.params.response_template_name);
-  }
-  if (bid.params.test) {
-    req.test = 1;
-  }
-  if (bidderRequest.gdprConsent) {
-    if (bidderRequest.gdprConsent.gdprApplies !== undefined) {
-      utils.deepSetValue(req, 'regs.ext.gdpr', bidderRequest.gdprConsent.gdprApplies === true ? 1 : 0);
-    }
-    if (bidderRequest.gdprConsent.consentString !== undefined) {
-      utils.deepSetValue(req, 'user.ext.consent', bidderRequest.gdprConsent.consentString);
-    }
-    if (bidderRequest.gdprConsent.addtlConsent !== undefined) {
-      utils.deepSetValue(req, 'user.ext.ConsentedProvidersSettings.consented_providers', bidderRequest.gdprConsent.addtlConsent);
-    }
-  }
-  if (bidderRequest.uspConsent) {
-    utils.deepSetValue(req, 'regs.ext.us_privacy', bidderRequest.uspConsent);
-  }
-  if (bid.schain) {
-    utils.deepSetValue(req, 'source.ext.schain', bid.schain);
-  }
-  if (bid.userIdAsEids) {
-    utils.deepSetValue(req, 'user.ext.eids', bid.userIdAsEids);
-  }
-  const commonFpd = bidderRequest.ortb2 || {};
-  if (commonFpd.site) {
-    utils.mergeDeep(req, {site: commonFpd.site});
-  }
-  if (commonFpd.user) {
-    utils.mergeDeep(req, {user: commonFpd.user});
-  }
-  return req;
-}
-
 function isVideoBid(bid) {
   return utils.deepAccess(bid, 'mediaTypes.video');
 }
@@ -239,107 +180,11 @@ function isBannerBid(bid) {
   return utils.deepAccess(bid, 'mediaTypes.banner') || !isVideoBid(bid);
 }
 
-function getFloor(bid, mediaType) {
-  let floor = 0;
-
-  if (typeof bid.getFloor === 'function') {
-    const floorInfo = bid.getFloor({
-      currency: 'USD',
-      mediaType: mediaType,
-      size: '*'
-    });
-
-    if (typeof floorInfo === 'object' &&
-      floorInfo.currency === 'USD' &&
-      !isNaN(parseFloat(floorInfo.floor))) {
-      floor = Math.max(floor, parseFloat(floorInfo.floor));
-    }
-  }
-
-  return floor;
-}
-
-function interpretOrtbResponse(resp, req) {
+function interpretResponse(resp, req) {
   if (!resp.body) {
     resp.body = {nbr: 0};
   }
-
-  // pass these from request to the responses for use in userSync
-  if (req.data.ext) {
-    if (req.data.ext.delDomain) {
-      utils.deepSetValue(resp, 'body.ext.delDomain', req.data.ext.delDomain);
-    }
-    if (req.data.ext.platform) {
-      utils.deepSetValue(resp, 'body.ext.platform', req.data.ext.platform);
-    }
-  }
-
-  const respBody = resp.body;
-  if (!respBody || 'nbr' in respBody || !Array.isArray(respBody.seatbid)) {
-    return [];
-  }
-
-  let bids = [];
-  respBody.seatbid.forEach(seatbid => {
-    bids = [...bids, ...seatbid.bid.map(bid => {
-      let response = {
-        requestId: bid.impid,
-        cpm: bid.price,
-        width: bid.w,
-        height: bid.h,
-        creativeId: bid.crid,
-        dealId: bid.dealid,
-        currency: respBody.cur || 'USD',
-        netRevenue: true,
-        ttl: 300,
-        mediaType: 'banner' in req.data.imp[0] ? BANNER : VIDEO,
-        meta: { advertiserDomains: bid.adomain }
-      };
-
-      if (response.mediaType === VIDEO) {
-        if (bid.nurl) {
-          response.vastUrl = bid.nurl;
-        } else {
-          response.vastXml = bid.adm;
-        }
-      } else {
-        response.ad = bid.adm;
-      }
-
-      if (bid.ext) {
-        response.meta.networkId = bid.ext.dsp_id;
-        response.meta.advertiserId = bid.ext.buyer_id;
-        response.meta.brandId = bid.ext.brand_id;
-      }
-
-      if (respBody.ext && respBody.ext.paf) {
-        response.meta.paf = Object.assign({}, respBody.ext.paf);
-        response.meta.paf.content_id = utils.deepAccess(bid, 'ext.paf.content_id');
-      }
-
-      return response;
-    })];
-  });
-
-  return bids;
-}
-
-function interpretResponse(resp, req) {
-  const bids = interpretOrtbResponse(resp, req);
-  let fledgeAuctionConfigs = utils.deepAccess(resp, 'body.ext.fledge_auction_configs');
-  if (fledgeAuctionConfigs) {
-    fledgeAuctionConfigs = Object.entries(fledgeAuctionConfigs).map(([bidId, cfg]) => {
-      return Object.assign({
-        bidId,
-        auctionSignals: {}
-      }, cfg);
-    });
-    return {
-      bids,
-      fledgeAuctionConfigs,
-    }
-  }
-  return bids;
+  return converter.fromORTB({request: req.data, response: resp.body});
 }
 
 /**

package/modules/oxxionRtdProvider.js

@@ -0,0 +1,119 @@
+import { submodule } from '../src/hook.js'
+import { deepAccess, logInfo } from '../src/utils.js'
+
+const oxxionRtdSearchFor = [ 'adUnitCode', 'auctionId', 'bidder', 'bidderCode', 'bidId', 'cpm', 'creativeId', 'currency', 'width', 'height', 'mediaType', 'netRevenue', 'originalCpm', 'originalCurrency', 'requestId', 'size', 'source', 'status', 'timeToRespond', 'transactionId', 'ttl', 'sizes', 'mediaTypes', 'src', 'userId', 'labelAny', 'adId' ];
+const LOG_PREFIX = 'oxxionRtdProvider submodule: ';
+
+const allAdUnits = [];
+
+/** @type {RtdSubmodule} */
+export const oxxionSubmodule = {
+  name: 'oxxionRtd',
+  init: init,
+  onAuctionEndEvent: onAuctionEnd,
+  getBidRequestData: getAdUnits,
+};
+
+function init(config, userConsent) {
+  if (!config.params || !config.params.domain || !config.params.contexts || !Array.isArray(config.params.contexts) || config.params.contexts.length == 0) {
+    return false
+  }
+  return true;
+}
+
+function getAdUnits(reqBidsConfigObj, callback, config, userConsent) {
+  const reqAdUnits = reqBidsConfigObj.adUnits;
+  if (Array.isArray(reqAdUnits)) {
+    reqAdUnits.forEach(adunit => {
+      if (config.params.contexts.includes(deepAccess(adunit, 'mediaTypes.video.context'))) {
+        allAdUnits.push(adunit);
+      }
+    });
+  }
+}
+
+function insertVideoTracking(bidResponse, config, maxCpm) {
+  if (bidResponse.mediaType === 'video') {
+    const trackingUrl = getImpUrl(config, bidResponse, maxCpm);
+    if (!trackingUrl) {
+      return;
+    }
+    // Vast Impression URL
+    if (bidResponse.vastUrl) {
+      bidResponse.vastImpUrl = bidResponse.vastImpUrl
+        ? trackingUrl + '&url=' + encodeURI(bidResponse.vastImpUrl)
+        : trackingUrl
+    }
+    // Vast XML document
+    if (bidResponse.vastXml !== undefined) {
+      const doc = new DOMParser().parseFromString(bidResponse.vastXml, 'text/xml');
+      const wrappers = doc.querySelectorAll('VAST Ad Wrapper, VAST Ad InLine');
+      let hasAltered = false;
+      if (wrappers.length) {
+        wrappers.forEach(wrapper => {
+          const impression = doc.createElement('Impression');
+          impression.appendChild(doc.createCDATASection(trackingUrl));
+          wrapper.appendChild(impression)
+        });
+        bidResponse.vastXml = new XMLSerializer().serializeToString(doc);
+        hasAltered = true;
+      }
+      if (hasAltered) {
+        logInfo(LOG_PREFIX + 'insert into vastXml for adId ' + bidResponse.adId);
+      }
+    }
+  }
+}
+
+function getImpUrl(config, data, maxCpm) {
+  const adUnitCode = data.adUnitCode;
+  const adUnits = allAdUnits.find(adunit => adunit.code === adUnitCode &&
+  'mediaTypes' in adunit &&
+  'video' in adunit.mediaTypes &&
+  typeof adunit.mediaTypes.video.context === 'string');
+  const context = adUnits !== undefined
+    ? adUnits.mediaTypes.video.context
+    : 'unknown';
+  if (!config.params.contexts.includes(context)) {
+    return false;
+  }
+  let trackingImpUrl = 'https://' + config.params.domain + '.oxxion.io/analytics/vast_imp?';
+  trackingImpUrl += oxxionRtdSearchFor.reduce((acc, param) => {
+    switch (typeof data[param]) {
+      case 'string':
+      case 'number':
+        acc += param + '=' + data[param] + '&'
+        break;
+    }
+    return acc;
+  }, '');
+  const cpmIncrement = Math.round(100000 * (data.cpm - maxCpm)) / 100000;
+  return trackingImpUrl + 'cpmIncrement=' + cpmIncrement + '&context=' + context;
+}
+
+function onAuctionEnd(auctionDetails, config, userConsent) {
+  const transactionsToCheck = {}
+  auctionDetails.adUnits.forEach(adunit => {
+    if (config.params.contexts.includes(deepAccess(adunit, 'mediaTypes.video.context'))) {
+      transactionsToCheck[adunit.transactionId] = {'bids': {}, 'maxCpm': 0.0, 'secondMaxCpm': 0.0};
+    }
+  });
+  for (const key in auctionDetails.bidsReceived) {
+    if (auctionDetails.bidsReceived[key].transactionId in transactionsToCheck) {
+      transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['bids'][auctionDetails.bidsReceived[key].adId] = {'key': key, 'cpm': auctionDetails.bidsReceived[key].cpm};
+      if (auctionDetails.bidsReceived[key].cpm > transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['maxCpm']) {
+        transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['secondMaxCpm'] = transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['maxCpm'];
+        transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['maxCpm'] = auctionDetails.bidsReceived[key].cpm;
+      } else if (auctionDetails.bidsReceived[key].cpm > transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['secondMaxCpm']) {
+        transactionsToCheck[auctionDetails.bidsReceived[key].transactionId]['secondMaxCpm'] = auctionDetails.bidsReceived[key].cpm;
+      }
+    }
+  };
+  Object.keys(transactionsToCheck).forEach(transaction => {
+    Object.keys(transactionsToCheck[transaction]['bids']).forEach(bid => {
+      insertVideoTracking(auctionDetails.bidsReceived[transactionsToCheck[transaction]['bids'][bid].key], config, transactionsToCheck[transaction].secondMaxCpm);
+    });
+  });
+}
+
+submodule('realTimeData', oxxionSubmodule);

package/modules/oxxionRtdProvider.md

@@ -0,0 +1,48 @@
+# Overview
+
+Module Name: Oxxion Rtd Provider
+Module Type: Rtd Provider
+Maintainer: tech@oxxion.io
+
+# Oxxion Real-Time-Data submodule
+
+Oxxion helps you to understand how your prebid stack performs.
+This Rtd module is to use in order to improve video events tracking.
+
+# Integration
+
+Make sure to have the following modules listed while building prebid : `rtdModule,oxxionRtdProvider`
+`rtbModule` is required to activate real-time-data submodules.
+For example :
+```
+gulp build --modules=schain,priceFloors,currency,consentManagement,appnexusBidAdapter,rubiconBidAdapter,rtdModule,oxxionRtdProvider
+```
+
+Then add the oxxion Rtd module to your prebid configuration :
+```
+pbjs.setConfig(
+  ...
+  realTimeData: {
+    auctionDelay: 200,
+    dataProviders: [
+      {
+          name: "oxxionRtd",
+          waitForIt: true,
+          params: {
+            domain: "test.endpoint",
+            contexts: ["instream"],
+          }
+       }
+    ]
+  }
+  ...
+)
+```
+
+# setConfig Parameters
+
+| Name                             | Type     | Description                                                                                                 |
+|:---------------------------------|:---------|:------------------------------------------------------------------------------------------------------------|
+| domain                           | String   | This string identifies yourself in Oxxion's systems and is provided to you by your Oxxion representative.   |
+| contexts                         | Array    | Array defining which video contexts to add tracking events into. Values can be instream and/or outstream.   |
+

package/modules/permutiveRtdProvider.js

@@ -238,7 +238,8 @@ function getDefaultBidderFn (bidder) {
         deepSetValue(bid, 'params.visitor.p_standard', data.ac)
       }
       if (data.rubicon && data.rubicon.length) {
-        deepSetValue(bid, 'params.visitor.permutive', data.rubicon)
+        const rubiconCohorts = deepAccess(bid, 'params.video') ? data.rubicon.map(String) : data.rubicon
+        deepSetValue(bid, 'params.visitor.permutive', rubiconCohorts)
       }
 
       return bid

package/modules/permutiveRtdProvider.md

@@ -45,17 +45,52 @@ as well as enabling settings for specific use cases mentioned above (e.g. acbidd
 | params.acBidders       | String[] | An array of bidders which should receive AC cohorts.                                          | `[]`    |
 | params.maxSegs         | Integer  | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500`   |
 | params.transformations | Object[] | An array of configurations for ORTB2 user data transformations                                |         |
+| params.overwrites      | Object   | An object specifying functions for custom targeting logic for bidders.                        | -       |
 
 ##### The `transformations` parameter
 
 This array contains configurations for transformations we'll apply to the Permutive object in the ORTB2 `user.data` array. The results of these transformations will be appended to the `user.data` array that's attached to ORTB2 bid requests.
 
-##### Supported transformations
+###### Supported transformations
 
 | Name           | ID  | Config structure                                  | Description                                                                          |
 |----------------|-----|---------------------------------------------------|--------------------------------------------------------------------------------------|
 | IAB taxonomies | iab | { segtax: number, iabIds: Object<number, number>} | Transform segment IDs from Permutive to IAB (note: alpha version, subject to change) |
 
+##### The `overwrites` parameter
+
+The keys for this object should match a bidder (e.g. `rubicon`), which then can define a function to overwrite the customer targeting logic.
+
+```javascript
+{
+  params: {
+    overwrites: {
+      rubicon: function customTargeting(bid, data, acEnabled, utils, defaultFn) {
+        if (defaultFn) {
+          bid = defaultFn(bid, data, acEnabled)
+        }
+        if (data.gam && data.gam.length) {
+          utils.deepSetValue(bid, 'params.visitor.permutive', data.gam)
+        }
+      } 
+    }
+  }
+}
+```
+
+###### `customTargeting` function parameters
+
+| Name         | Description                                                                    |
+|--------------|--------------------------------------------------------------------------------|
+| `bid`        | The bid request object.                                                        |
+| `data`       | Permutive's targeting data read from localStorage.                             |
+| `acEnabled`  | Boolean stating whether Audience Connect is enabled via `acBidders`.           |
+| `utils`      | An object of helpful utilities. `(deepSetValue, deepAccess, isFn, mergeDeep)`. |
+| `defaultFn`  | The default targeting function.                                                |
+
+
+
+
 #### Context
 
 Permutive is not listed as a TCF vendor as all data collection is on behalf of the publisher and based on consent the publisher has received from the user.