New optional bid parameter

modules/nanointeractiveBidAdapter.js

@@ -9,18 +9,20 @@ export const DATA_PARTNER_PIXEL_ID = 'pid';
 export const NQ = 'nq';
 export const NQ_NAME = 'name';
 export const CATEGORY = 'category';
+export const CATEGORY_NAME = 'categoryName';
 export const SUB_ID = 'subId';
+export const REF = 'ref';
 
 export const spec = {
 
   code: BIDDER_CODE,
   supportedMediaTypes: [BANNER],
 
-  isBidRequestValid(bid) {
+  isBidRequestValid (bid) {
     const pid = bid.params[DATA_PARTNER_PIXEL_ID];
     return !!(pid);
   },
-  buildRequests(bidRequests) {
+  buildRequests (bidRequests) {
     let payload = [];
     bidRequests.forEach(bid => payload.push(createSingleBidRequest(bid)));
     return {
@@ -29,7 +31,7 @@ export const spec = {
       data: JSON.stringify(payload)
     };
   },
-  interpretResponse(serverResponse) {
+  interpretResponse (serverResponse) {
     const bids = [];
     serverResponse.body.forEach(serverBid => {
       if (isEngineResponseValid(serverBid)) {
@@ -40,18 +42,20 @@ export const spec = {
   }
 };
 
-function createSingleBidRequest(bid) {
+function createSingleBidRequest (bid) {
   return {
     [DATA_PARTNER_PIXEL_ID]: bid.params[DATA_PARTNER_PIXEL_ID],
-    [NQ]: [createNqParam(bid), createCategoryParam(bid)],
+    [NQ]: [createNqParam(bid)],
+    [CATEGORY]: [createCategoryParam(bid)],
     [SUB_ID]: createSubIdParam(bid),
+    [REF]: createRefParam(bid),
     sizes: bid.sizes.map(value => value[0] + 'x' + value[1]),
     bidId: bid.bidId,
-    cors: utils.getOrigin()
+    cors: utils.getOrigin(),
   };
 }
 
-function createSingleBidResponse(serverBid) {
+function createSingleBidResponse (serverBid) {
   return {
     requestId: serverBid.id,
     cpm: serverBid.cpm,
@@ -65,19 +69,23 @@ function createSingleBidResponse(serverBid) {
   };
 }
 
-function createNqParam(bid) {
+function createNqParam (bid) {
   return bid.params[NQ_NAME] ? utils.getParameterByName(bid.params[NQ_NAME]) : bid.params[NQ] || null;
 }
 
-function createCategoryParam(bid) {
-  return bid.params[CATEGORY] || null;
+function createCategoryParam (bid) {
+  return bid.params[CATEGORY_NAME] ? utils.getParameterByName(bid.params[CATEGORY_NAME]) : bid.params[CATEGORY] || null;
 }
 
-function createSubIdParam(bid) {
+function createSubIdParam (bid) {
   return bid.params[SUB_ID] || null;
 }
 
-function isEngineResponseValid(response) {
+function createRefParam (bid) {
+  return bid.params[REF] ? null : utils.getTopWindowReferrer() || null;
+}
+
+function isEngineResponseValid (response) {
   return !!response.cpm && !!response.ad;
 }
 

modules/nanointeractiveBidAdapter.md

@@ -1,7 +1,7 @@
 # Overview
 
 ```
-Module Name:  NanoInteractive Bid Adapter
+Module Name:  Nano Interactive Bid Adapter
 Module Type:  Bidder Adapter
 Maintainer: rade@nanointeractive.com
 ```
@@ -10,70 +10,143 @@ Maintainer: rade@nanointeractive.com
 
 Connects to Nano Interactive search retargeting Ad Server for bids.
 
-Besides standard params, please provide, if exist, user search params. 
 
-Three examples calling the Ad Server. 
 
-**First** is basic 
+<br>
+### Requirements:
+To be able to get identification key (`pid`), please contact us at <br> 
+`https://www.nanointeractive.com/publishers` <br>
+<br><br><br>
 
-**Second** is with hardcoded nq (user search) params 
+#### Send All Bids Ad Server Keys:
+(truncated to 20 chars due to [DFP limit](https://support.google.com/dfp_premium/answer/1628457?hl=en#Key-values))
 
-**Third** is with the search query param name of the current url
+`hb_adid_nanointeract`
+`hb_bidder_nanointera`
+`hb_pb_nanointeractiv`
+`hb_format_nanointera`
+`hb_size_nanointeract`
+`hb_source_nanointera`
 
-# Test Parameters
-```
-var adUnits = [
-   // Basic call
-   {
-       code: 'basic-div',
-       sizes: [[300, 250], [300,600]],
-       bids: [{
-         bidder: 'nanointeractive',
-         params: {
-            // required
-            pid: '58bfec94eb0a1916fa380163',
-            // optional parameters
-            category: 'some category',
-            subId: '123'
-         }
-       }]
-   },
-   // Hardcoded user search 
-   {
-       code: 'nq-div',
-       sizes: [[300, 250], [300,600]],
-       bids: [{
-         bidder: 'nanointeractive',
-         params: {
-            // required
-            pid: '58bfec94eb0a1916fa380163',
-            // optional parameters
-            nq: 'user search',
-            category: 'some category',
-            subId: '123'
-         }
-       }]
-   },
-   // URL user search 
-   {
-       code: 'url-div',
-       sizes: [[300, 250], [300,600]],
-       bids: [{
-         bidder: 'nanointeractive',
-         params: {
-            // required
-            pid: '58bfec94eb0a1916fa380163',
-            // optional parameters
-            name: 'search',
-            category: 'some category',
-            subId: '123'
-         }
-       }]
-   }
-];
-```
+#### Default Deal ID Keys:
+`hb_deal_nanointeract`
 
-### Requirements:
-To be able to get identification key (`pid`), you must register at <br> 
-`https://audiencemanager.de/public/data-partners-register` <br>
-and follow further instructions.
+### bid params
+
+{: .table .table-bordered .table-striped }
+| Name           | Scope    | Description                                      | Example                      |
+| :------------- | :------- | :----------------------------------------------- | :--------------------------- |
+| `pid`          | required | Identification key, provided by Nano Interactive | `'5afaa0280ae8996eb578de53'` |
+| `category`     | optional | Contextual taxonomy                              | `'automotive'`               |
+| `categoryName` | optional | Contextual taxonomy (from URL query param)       | `'cat_name'`                 |
+| `nq`           | optional | User search query                                | `'automobile search query'`  |
+| `name`         | optional | User search query (from URL query param)         | `'search_param'`             |
+| `subId`        | optional | Channel - used to separate traffic sources       | `'123'`                      |
+
+#### Configuration
+The `category` and `categoryName` are mutually exclusive. If you pass both, `categoryName` takes precedence.
+<br>
+The `nq` and `name` are mutually exclusive. If you pass both, `name` takes precedence.
+
+#### Example with only required field `pid`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53'
+            }
+        }]
+    }];
+
+#### Example with `category`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                category: 'automotive',
+                subId: '123'
+            }
+        }]
+    }];
+
+#### Example with `categoryName`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                // Category "automotive" is in the URL like:
+                // https://www....?cat_name=automotive&...
+                categoryName: 'cat_name',
+                subId: '123'
+            }
+        }]
+    }];
+
+#### Example with `nq`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                // User searched "automobile search query" (extracted from search text field) 
+                nq: 'automobile search query',
+                subId: '123'
+            }
+        }]
+    }];
+
+#### Example with `name`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                // User searched "automobile search query" and it is in the URL like:
+                // https://www....?search_param=automobile%20search%20query&... 
+                name: 'search_param',
+                subId: '123'
+            }
+        }]
+    }];
+
+#### Example with `category` and `nq`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                category: 'automotive',
+                nq: 'automobile search query',
+                subId: '123'
+            }
+        }]
+    }];
+
+#### Example with `categoryName` and `name`
+    var adUnits = [{
+        code: 'nano-div',
+        sizes: [[300, 250], [300,600]],
+        bids: [{
+            bidder: 'nanointeractive',
+            params: {
+                pid: '5afaa0280ae8996eb578de53',
+                categoryName: 'cat_name',
+                name: 'search_param',
+                subId: '123'
+            }
+        }]
+    }];