Updated docs for Index Exchange's Prebid 1.0 adapter + GDPR support (prebid#748)

jas-singh · mkendall07 · commit 72b9c8a64a8e · 2018-05-10T12:08:37.000-04:00
diff --git a/_includes/send-all-bids-keyword-targeting.md b/_includes/send-all-bids-keyword-targeting.md
@@ -1,10 +1,10 @@
 {: .alert.alert-info :}
-**Important:** DFP has a key-value key character [limit](https://support.google.com/dfp_premium/answer/1628457?hl=en#Key-values) of up to **20 characters**. Some of the keys without truncation will exceed 20 chars (To date only Index Exchange's keys need attention). Prebid.js automatically truncates the key length to 20 characters. For example, `hb_adid_indexExchange` is truncated to `hb_adid_indexExchang` (the 21st character `e` is truncated). Note that the key is case-sensitive. To get the exact key-value keys for each bidder, find them at [Bidder Params](/dev-docs/bidders.html).
+**Important:** DFP has a key-value key character [limit](https://support.google.com/dfp_premium/answer/1628457?hl=en#Key-values) of up to **20 characters**. Some of the keys without truncation will exceed 20 chars. Prebid.js automatically truncates the key length to 20 characters. For example, `hb_adid_longBidderName` is truncated to `hb_adid_longBidderNa` (`me` is truncated). Note that the key is case-sensitive. To get the exact key-value keys for each bidder, find them at [Bidder Params](/dev-docs/bidders.html).
 
 {: .table .table-bordered .table-striped }
 | Default Key   | Scope    | Description                                                                                     | Example   |
 | :----         |:----     | :----                                                                                           | :----     |
 | `hb_pb_BIDDERCODE`       | Required | The price bucket. Used by the line item to target. Case sensitive and truncated to 20 chars. The `BIDDERCODE` is documented at [Bidder Params](/dev-docs/bidders.html). | `hb_pb_rubicon` = `2.10`    |
-| `hb_adid_BIDDERCODE`     | Required | The ad Id. Used by the ad server creative to render ad. Case sensitive and truncated to 20 chars. The `BIDDERCODE` is documented at [Bidder Params](/dev-docs/bidders.html). | `hb_adid_indexExchang` = `234234`  |
+| `hb_adid_BIDDERCODE`     | Required | The ad Id. Used by the ad server creative to render ad. Case sensitive and truncated to 20 chars. The `BIDDERCODE` is documented at [Bidder Params](/dev-docs/bidders.html). | `hb_adid_longBidderNa` = `234234`  |
 | `hb_size_BIDDERCODE`   | Optional | This is not required for adops. Case sensitive and truncated to 20 chars. | `hb_size_appnexus` = `300x250` |
 
diff --git a/adops/deals.md b/adops/deals.md
@@ -58,7 +58,6 @@ Whether your Ad Ops setup [sends all bids to the ad server](/adops/send-all-bids
 
 For each header bidding partner you work with, create a keyword in the format of `hb_deal_BIDDERCODE`, e.g., `hb_deal_pubmatic`. For more examples of the keyword format, see the [API Reference for `pbjs.getAdserverTargeting`]({{site.github.url}}/dev-docs/publisher-api-reference.html#module_pbjs.getAdserverTargeting).
 
-Note that due to [DFP's character length limit on keys](https://support.google.com/dfp_premium/answer/1628457?hl=en#Key-values), Index Exchange's key is truncated to `hb_deal_indexExchang`.
 <br>
 
 {: .pb-img.pb-lg-img :}
@@ -77,7 +76,7 @@ Enter all the **Inventory sizes** for your deal (or deals):
 
 <br />
 
-Set the **priority** to the level you prefer. 
+Set the **priority** to the level you prefer.
 
 {: .pb-img.pb-lg-img :}
 ![Inventory Sizes]({{ site.github.url }}/assets/images/demo-setup/deals/deal-priority.png)
@@ -101,7 +100,7 @@ Then you'll need to target the **inventory** that you want to this deal to run o
 
 There are two ways to target deal IDs using *Key-values* targeting:
 
-1. If you would like the deals to have the same priority and target the same inventory, you can include multiple deal IDs (as shown below). 
+1. If you would like the deals to have the same priority and target the same inventory, you can include multiple deal IDs (as shown below).
 2. Otherwise, you must create a separate line item for each deal ID you want to target.
 
 {: .pb-img.pb-lg-img :}
diff --git a/dev-docs/bidders/indexExchange.md b/dev-docs/bidders/indexExchange.md
@@ -1,64 +1,290 @@
 ---
 layout: bidder
-title: Index Exchange (Casale)
-description: Prebid Index Exchange (Casale) Bidder Adaptor
-
+title: Index Exchange
+description: Prebid Index Exchange Bidder Adapter
 top_nav_section: dev_docs
 nav_section: reference
-
+biddercode: ix
+biddercode_longer_than_12: false
 hide: true
+prebid_1_0_supported : true
+gdpr_supported: true
+---
 
-biddercode: indexExchange
+Overview
+========
 
-biddercode_longer_than_12: true
-media_types: video
+```
+Module Name: Index Exchange Adapter
+Module Type: Bidder Adapter
+Maintainer: prebid.support@indexexchange.com
+```
 
----
+Description
+===========
+
+This module connects publishers to Index Exchange's (IX) network of demand
+sources through Prebid.js. This module is GDPR compliant.
+
+It is compatible with both the older ad unit format where the `sizes` and
+`mediaType` properties are placed at the top-level of the ad unit, and the newer
+format where this information is encapsulated within the `mediaTypes` object. We
+recommend that you use the newer format when possible as it will be better able
+to accommodate new feature additions.
+
+If a mix of properties from both formats are present within an ad unit, the
+newer format's properties will take precedence.
+
+Here are examples of both formats.
+
+##### Older Format
+```javascript
+var adUnits = [{
+    // ...
+
+    mediaType: 'banner',
+
+    sizes: [
+        [300, 250],
+        [300, 600]
+    ]
+
+    // ...
+}];
+```
+
+##### Newer Format
+```javascript
+var adUnits = [{
+    // ...
+
+    mediaTypes: {
+        banner: {
+            sizes: [
+                [300, 250],
+                [300, 600]
+            ]
+        }
+    }
+
+    // ...
+}];
+```
+
+### Supported Media Types
+
+| Type | Support
+| --- | ---
+| Banner | Fully supported for all IX approved sizes.
+| Video  | Only in-stream supported.
+| Native | Not supported.
+
+# Bid Parameters
+
+Each of the IX-specific parameters provided under the `adUnits[].bids[].params`
+object are detailed here.
+
+### Banner
+
+| Key | Scope | Type | Description
+| --- | --- | --- | ---
+| siteId | Required | String | <p>An IX-specific identifier that is associated with a specific size on this ad unit. This is similar to a placement ID or an ad unit ID that some other modules have.</p><p>Examples:<ul><li>`'3723'`</li><li>`'6482'`</li><li>`'3639'`</li></ul></p>
+| size | Required | Number[] | <p>The single size associated with the site ID. It should be one of the sizes listed in the ad unit under `adUnits[].sizes` or `adUnits[].mediaTypes.banner.sizes`.</p><p>Examples:<ul><li>`[300, 250]`</li><li>`[300, 600]`</li><li>`[728, 90]`</li></ul></p>
+| bidFloor | Optional<sup>1</sup> | Number | <p>The minimum bid required to participate in an auction for this ad unit. Assuming the bid floor currency that is set has a main unit (e.g. dollars, pounds) and a sub-unit (e.g. cents, pence), the bid floor should be in decimal-point format. If the currency only has main a unit (e.g. JPY), then the bid floor should be a whole number.</p><p>Examples:<ul><li>10.26 USD => `bidFloor: 10.26`</li><li>13.41 GBP => `bidFloor: 13.41`</li><li>600 JPY => `bidFloor: 600`</li></ul></p> | N/A
+| bidFloorCur | Optional<sup>1</sup> | String | <p>The currency of the bid floor.</p><p>Examples:<ul><li>`'USD'`</li><li>`'GBP'`</li><li>`'JPY'`</li></ul></p>
+
+<p>
+    <sup>1</sup> <code>bidFloor</code> and <code>bidFloorCur</code> <b>must</b>
+    both be set when a bid floor is being configured.
+</p>
+
+Setup Guide
+===========
+
+Follow these steps to configure and add the IX module to your Prebid.js
+integration.
+
+The examples in this guide assume the following starting configuration:
+
+```javascript
+var adUnits = [{
+    code: 'banner-div-a',
+    mediaTypes: {
+        banner: {
+            sizes: [
+                [300, 250],
+                [300, 600]
+            ]
+        }
+    },
+    bids: []
+}];
+```
+
+##### 1. Add IX to the appropriate ad units
+
+For each size in an ad unit that IX will be bidding on, add one of the following
+bid objects under `adUnits[].bids`:
+
+```javascript
+{
+    bidder: 'ix',
+    params: {
+        siteId: '',
+        size: []
+    }
+}
+```
+
+Set `params.siteId` and `params.size` in each bid object to the values provided
+by your IX representative.
+
+**Example**
+```javascript
+var adUnits = [{
+    code: 'banner-div-a',
+    mediaTypes: {
+        banner: {
+            sizes: [
+                [300, 250],
+                [300, 600]
+            ]
+        }
+    },
+    bids: [{
+        bidder: 'ix',
+        params: {
+            siteId: '4622',
+            size: [300, 250]
+        }
+    }, {
+        bidder: 'ix',
+        params: {
+            siteId: '6242',
+            size: [300, 600]
+        }
+    }]
+}];
+```
+
+##### 2. Include `ixBidAdapter` in your build process
+
+When running the build command, include `ixBidAdapter` as a module.
+
+```
+gulp build --modules=ixBidAdapter,fooBidAdapter,bazBidAdapter
+```
+
+If a JSON file is being used to specify the bidder modules, add `"ixBidAdapter"`
+to the top-level array in that file.
+
+```json
+[
+    "ixBidAdapter",
+    "fooBidAdapter",
+    "bazBidAdapter"
+]
+```
+
+And then build.
+
+```
+gulp build --modules=bidderModules.json
+```
+
+Setting First Party Data (FPD)
+==============================
+
+FPD allows you to specify key-value pairs which will be passed as part of the
+query string to IX for use in Private Marketplace Deals which rely on query
+string targeting for activation. For example, if a user is viewing a
+news-related page, you can pass on that information by sending `category=news`.
+Then in the IX Private Marketplace setup screens you can create Deals which
+activate only on pages which contain `category=news`. Please reach out to your
+IX representative if you have any questions or need help setting this up.
+
+To include FPD in a bid request, it must be set before `pbjs.requestBids` is
+called. To set it, call `pbjs.setConfig` and provide it with a map of FPD keys
+to values as such:
+
+```javascript
+pbjs.setConfig({
+    ix: {
+        firstPartyData: {
+            '<key name>': '<key value>',
+            '<key name>': '<key value>',
+            // ...
+        }
+    }
+});
+```
+
+The values can be updated at any time by calling `pbjs.setConfig` again. The
+changes will be reflected in any proceeding bid requests.
+
+Setting a Server Side Timeout
+=============================
+
+Setting a server-side timeout allows you to control the max length of time the
+servers will wait on DSPs to respond before generating the final bid response
+and returning it to this module.
+
+This is distinctly different from the global bidder timeout that can be set in
+Prebid.js in the browser.
+
+To add a server-side timeout, it must be set before `pbjs.requestBids` is
+called. To set it, call `pbjs.setConfig` and provide it with a timeout value as
+such:
+
+```javascript
+pbjs.setConfig({
+    ix: {
+        timeout: 500
+    }
+});
+```
+
+The timeout value must be a positive whole number in milliseconds.
+
+Additional Information
+======================
+
+### Bid Request Limit
+
+If a single bid request to IX contains more than 20 impression requests (i.e.
+more than 20 objects in `bidRequest.imp`), only the first 20 will be accepted,
+the rest will be ignored.
+
+To avoid this situation, ensure that when `pbjs.requestBid` is invoked, that the
+number of bid objects (i.e. `adUnits[].bids`) with `adUnits[].bids[].bidder` set
+to `'ix'` across all ad units that bids are being requested for does not exceed
+20.
+
+### Time-To-Live (TTL)
+
+All bids received from IX have a TTL of 60 seconds, after which time they become
+invalid.
+
+If an invalid bid wins, and its associated ad is rendered, it will not count
+towards total impressions on IX's side.
+
+FAQs
+====
+
+### Why do I have to input size in `adUnits[].bids[].params` for IX when the size is already in the ad unit?
+
+There are two important reasons why we require it:
+
+1. An IX site ID maps to a single size, whereas an ad unit can have multiple
+sizes. To ensure that the right site ID is mapped to the correct size in the ad
+unit we require the size to be explicitly stated.
+
+2. An ad unit may have sizes that IX does not support. By explicitly stating the
+size, you can choose not to have IX bid on certain sizes that are invalid.
+
+### How do I view IX's bid request in the network?
 
-### Prebid Server Note:
-Before configuring the Index Exchange adapter as S2S, you must reach out to the Index Exchange team for approval and setup steps.
-
-#### 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))
-
-`hb_pb_indexExchange`
-`hb_adid_indexExchang`
-`hb_size_indexExchang`
-
-#### Default Deal ID Keys:
-`hb_deal_indexExchang`
-
-### bid params
-
-{: .table .table-bordered .table-striped }
-| Name | Scope | Description | Example |
-| :--- | :---- | :---------- | :------ |
-| `id` | required | The placement ID |  |
-| `siteID` | required | the site ID | |
-| `tier2SiteID` | optional | | |
-| `tier3SiteID` | optional | | |
-
-### bid params: Video
-
-{: .table .table-bordered .table-striped }
-| Name | Scope | Description | Example |
-| :--- | :---- | :---------- | :------ |
-| `video` | required | Video parameters.  See [video params table](#index-video) | `{"siteID": 12345, "playerType":"HTML5", "protocols":[2,3,5,6], "maxduration":15}`  |
-
-<a name="index-video"></a>
-
-### Video params
-
-{: .table .table-bordered .table-striped }
-| Name | Scope | Description | Example |
-| :--- | :---- | :---------- | :------ |
-| `siteID` | required | Publisher site ID | `12345` |
-| `playerType` | required | String representing video player type, either HTML5 or FLASH | `"HTML5"` |
-| `protocols` | required | Array of integers representing VAST versions supported by the player, as defined in OpenRTB 2.3 section 5.6 | `[2, 3, 5, 6]` |
-| `maxduration` | required | Integer representing allowable max duration of the video ad, in seconds | `15` |
-| `minduration` | optional | Integer representing allowable min duration of the video ad, in seconds.  Default of 0 assumed if none is specified. | `5` |
-| `startdelay` | optional | Defines the start of the ad, when a string is specified then generic RTB values are used, when a number is specified then is interpreted as the number of seconds into the content video at which the ad should play.  Default assumed to be `preroll` if none specified | `"preroll"` |
-| `linearity` | optional |  String representing whether video ad is linear or overlay.  Defaults to `"linear"` if not defined | `"linear"` |
-| `mimes` | optional | Array of strings representing player supported mime types. Overrides the supported MIME types otherwise inferred by `playerType` setting. | `["video/mp4", "video/webm"]` |
-| `allowVPAID` | optional | Boolean defining whether player supports any version of VPAID.  Which versions are supported is inferred from `playerType`.  Defaults to false | `false` |
-| `apiList` | optional | Array of integers representing player supported VPAID versions, as defined in OpenRTB 2.3 section 5.6.  Overrides versions inferred from `playerType`.  | `[1, 2]` |
+In your browser of choice, create a new tab and open the developer tools. In
+developer tools, select the network tab. Then, navigate to a page where IX is
+setup to bid. Now, in the network tab, search for requests to
+`casalemedia.com/cygnus`. These are the bid requests.
diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md
