Blockthrough Bid Adapter: initial release (prebid#10870)

PavloMalashnyak · web-flow · commit ab7068eef0da · 2024-02-23T22:50:38.000-05:00
* PE-87: Implement Prebid Adapter (#1) * PE-87: implement BT Bid Adapter * PE-87: rework adapter to use ortbConverter lib, make requested changes * PE-87: update imports * PE-110: Add user sync logic to the Prebid Adapter (prebid#3) * PE-110: add user sync logic * PE-110: update userSync url * PE-110: check if iframe is enabled before setting params * PE-111: BT Prebid Adapter can request AA ads or regular ads (#2) * PE-120: Send Prebid Bidder info to BT Server (prebid#4) * PE-120: add btBidderCode to the bid object * PE-120: use single quotes for logs string * PE-123: Add More Metadata in site.ext.blockthrough (prebid#5) * PE-123: send additional meta data * PE-123: send auctionID under imp.ext.prebid.blockthrough * PE-123: use ortb2 config to set site.ext params * PE-123: sent auctionId in ext.prebid.blockthrough.auctionID * PE-123: update logs for bidderConfig setup * PE-000: check if blockthrough is defined (prebid#6) * PE-87: remove BT specific logic (prebid#7) * Implement Blockthrough Prebid Adapter * PE-87: Implement Prebid Adapter - misc fixes (prebid#9) * PE-87: rename test file, add bidder config * PE-87: increase ttl * PE-000: fix test * BP-74: Change the way we enable debug (prebid#10) * BP-79: Send GPID as a part of `imp[].ext` (prebid#11) * BP-79: send gpid in imp.ext * BP-79: add optional operator * BP-90: Update Cookie Sync Logic (prebid#12) * BP-90: pass bidder to cookie sync * BP-90: update sync logic, fix typo * BP-90: use const for syncs variable * BP-55: Re-add endpoint URLs (prebid#13) * BP-91: Add prebid JS version to auction request (prebid#14)
diff --git a/modules/BTBidAdapter.js b/modules/BTBidAdapter.js
@@ -0,0 +1,204 @@
+import { registerBidder } from '../src/adapters/bidderFactory.js';
+import { deepSetValue, isPlainObject, logWarn } from '../src/utils.js';
+import { BANNER } from '../src/mediaTypes.js';
+import { ortbConverter } from '../libraries/ortbConverter/converter.js';
+
+const BIDDER_CODE = 'blockthrough';
+const GVLID = 815;
+const ENDPOINT_URL = 'https://pbs.btloader.com/openrtb2/auction';
+const SYNC_URL = 'https://cdn.btloader.com/user_sync.html';
+
+const CONVERTER = ortbConverter({
+  context: {
+    netRevenue: true,
+    ttl: 60,
+  },
+  imp,
+  request,
+  bidResponse,
+});
+
+/**
+ * Builds an impression object for the ORTB 2.5 request.
+ *
+ * @param {function} buildImp - The function for building an imp object.
+ * @param {Object} bidRequest - The bid request object.
+ * @param {Object} context - The context object.
+ * @returns {Object} The ORTB 2.5 imp object.
+ */
+function imp(buildImp, bidRequest, context) {
+  const imp = buildImp(bidRequest, context);
+  const { params, ortb2Imp } = bidRequest;
+
+  if (params) {
+    deepSetValue(imp, 'ext', params);
+  }
+  if (ortb2Imp?.ext?.gpid) {
+    deepSetValue(imp, 'ext.gpid', ortb2Imp.ext.gpid);
+  }
+
+  return imp;
+}
+
+/**
+ * Builds a request object for the ORTB 2.5 request.
+ *
+ * @param {function} buildRequest - The function for building a request object.
+ * @param {Array} imps - An array of ORTB 2.5 impression objects.
+ * @param {Object} bidderRequest - The bidder request object.
+ * @param {Object} context - The context object.
+ * @returns {Object} The ORTB 2.5 request object.
+ */
+function request(buildRequest, imps, bidderRequest, context) {
+  const request = buildRequest(imps, bidderRequest, context);
+  deepSetValue(request, 'ext.prebid.channel', {
+    name: 'pbjs',
+    version: '$prebid.version$',
+  });
+
+  if (window.location.href.includes('btServerTest=true')) {
+    request.test = 1;
+  }
+
+  return request;
+}
+
+/**
+ * Processes a bid response using the provided build function, bid, and context.
+ *
+ * @param {Function} buildBidResponse - The function to build the bid response.
+ * @param {Object} bid - The bid object to include in the bid response.
+ * @param {Object} context - The context object containing additional information.
+ * @returns {Object} - The processed bid response.
+ */
+function bidResponse(buildBidResponse, bid, context) {
+  const bidResponse = buildBidResponse(bid, context);
+  const { seat } = context.seatbid || {};
+  bidResponse.btBidderCode = seat;
+
+  return bidResponse;
+}
+
+/**
+ * Checks if a bid request is valid.
+ *
+ * @param {Object} bid - The bid request object.
+ * @returns {boolean} True if the bid request is valid, false otherwise.
+ */
+function isBidRequestValid(bid) {
+  if (!isPlainObject(bid.params) || !Object.keys(bid.params).length) {
+    logWarn('BT Bid Adapter: bid params must be provided.');
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Builds the bid requests for the BT Service.
+ *
+ * @param {Array} validBidRequests - An array of valid bid request objects.
+ * @param {Object} bidderRequest - The bidder request object.
+ * @returns {Array} An array of BT Service bid requests.
+ */
+function buildRequests(validBidRequests, bidderRequest) {
+  const data = CONVERTER.toORTB({
+    bidRequests: validBidRequests,
+    bidderRequest,
+  });
+
+  return [
+    {
+      method: 'POST',
+      url: ENDPOINT_URL,
+      data,
+      bids: validBidRequests,
+    },
+  ];
+}
+
+/**
+ * Interprets the server response and maps it to bids.
+ *
+ * @param {Object} serverResponse - The server response object.
+ * @param {Object} request - The request object.
+ * @returns {Array} An array of bid objects.
+ */
+function interpretResponse(serverResponse, request) {
+  if (!serverResponse || !request) {
+    return [];
+  }
+
+  return CONVERTER.fromORTB({
+    response: serverResponse.body,
+    request: request.data,
+  }).bids;
+}
+
+/**
+ * Generates user synchronization data based on provided options and consents.
+ *
+ * @param {Object} syncOptions - Synchronization options.
+ * @param {Object[]} serverResponses - An array of server responses.
+ * @param {Object} gdprConsent - GDPR consent information.
+ * @param {string} uspConsent - US Privacy consent string.
+ * @param {Object} gppConsent - Google Publisher Policies (GPP) consent information.
+ * @returns {Object[]} An array of user synchronization objects.
+ */
+function getUserSyncs(
+  syncOptions,
+  serverResponses,
+  gdprConsent,
+  uspConsent,
+  gppConsent
+) {
+  if (!syncOptions.iframeEnabled || !serverResponses?.length) {
+    return [];
+  }
+
+  const bidderCodes = new Set();
+  serverResponses.forEach((serverResponse) => {
+    if (serverResponse?.body?.ext?.responsetimemillis) {
+      Object.keys(serverResponse.body.ext.responsetimemillis).forEach(
+        bidderCodes.add,
+        bidderCodes
+      );
+    }
+  });
+
+  if (!bidderCodes.size) {
+    return [];
+  }
+
+  const syncs = [];
+  const syncUrl = new URL(SYNC_URL);
+  syncUrl.searchParams.set('bidders', [...bidderCodes].join(','));
+
+  if (gdprConsent) {
+    syncUrl.searchParams.set('gdpr', Number(gdprConsent.gdprApplies));
+    syncUrl.searchParams.set('gdpr_consent', gdprConsent.consentString);
+  }
+  if (gppConsent) {
+    syncUrl.searchParams.set('gpp', gppConsent.gppString);
+    syncUrl.searchParams.set('gpp_sid', gppConsent.applicableSections);
+  }
+  if (uspConsent) {
+    syncUrl.searchParams.set('us_privacy', uspConsent);
+  }
+
+  syncs.push({ type: 'iframe', url: syncUrl.href });
+
+  return syncs;
+}
+
+export const spec = {
+  code: BIDDER_CODE,
+  gvlid: GVLID,
+  supportedMediaTypes: [BANNER],
+  isBidRequestValid,
+  buildRequests,
+  interpretResponse,
+  getUserSyncs,
+};
+
+registerBidder(spec);
diff --git a/modules/BTBidAdapter.md b/modules/BTBidAdapter.md
@@ -0,0 +1,70 @@
+# Overview
+
+**Module Name**: BT Bidder Adapter
+**Module Type**: Bidder Adapter  
+**Maintainer**: engsupport@blockthrough.com
+
+# Description
+
+The BT Bidder Adapter provides an interface to the BT Service. The BT Bidder Adapter sends one request to the BT Service per ad unit. Behind the scenes, the BT Service further disperses requests to various configured exchanges. This operational model closely resembles that of Prebid Server, where a single request is made from the client side, and responses are gathered from multiple exchanges.
+
+The BT adapter requires setup and approval from the Blockthrough team. Please reach out to marketing@blockthrough.com for more information.
+
+# Bid Params
+
+| Key    | Scope    | Type   | Description                                                    |
+| ------ | -------- | ------ | -------------------------------------------------------------- |
+| bidder | Required | Object | Bidder configuration. Could configure several bidders this way |
+
+# Bidder Config
+
+Make sure to set required ab, orgID, websiteID values received after approval using `pbjs.setBidderConfig`.
+
+## Example
+
+```javascript
+pbjs.setBidderConfig({
+  bidders: ['blockthrough'],
+  config: {
+    ortb2: {
+      site: {
+        ext: {
+          blockthrough: {
+            ab: false,
+            orgID: '4829301576428910',
+            websiteID: '5654012389765432',
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+## AdUnits configuration example
+
+```javascript
+var adUnits = [
+  {
+    code: 'banner-div-1',
+    mediaTypes: {
+      banner: {
+        sizes: [[728, 90]],
+      },
+    },
+    bids: [
+      {
+        bidder: 'blockthrough',
+        params: {
+          bidderA: {
+            publisherId: 55555,
+          },
+          bidderB: {
+            zoneId: 12,
+          },
+        },
+      },
+    ],
+  },
+];
+```
diff --git a/test/spec/modules/BTBidAdapter_spec.js b/test/spec/modules/BTBidAdapter_spec.js
