Mediakeys documentation improvements

dev-docs/bidders/mediakeys.md

@@ -22,6 +22,8 @@ fpd_supported: true
 - [Table of Contents](#table-of-contents)
 - [Important Notice](#important-notice)
 - [Bid Params](#bid-params)
+  - [First Party Data](#first-party-data)
+  - [Required and Recommended Modules](#required-and-recommended-modules)
 - [MediaType Banner](#mediatype-banner)
 - [MediaType Video](#mediatype-video)
   - [Instream video](#instream-video)
@@ -45,7 +47,134 @@ Please contact us at [email protected].
 |-------------|---------------------|------------------------------|-----------|-----------|
 | `context`   | required for native | Native context               | `1`       | `integer` |
 | `plcmttype` | required for native | Native placement type        | `2`       | `integer` |
-| | | | | |
+
+<a name="first-party-data"></a>
+
+#### First Party Data
+
+Publishers should use the `ortb2` method of setting [First Party Data](https://docs.prebid.org/features/firstPartyData.html).
+
+Global site or user data using `setConfig()`, or Bidder-specific using `setBidderConfig()` supports following fields:
+
+- `ortb2.site.*`: Standard IAB OpenRTB 2.5 site fields
+- `ortb2.site.content.data[]`: Standard IAB segment taxonomy site data
+- `ortb2.site.ext.data.*`: Non standard arbitrary site data
+- `ortb2.user.*`: Standard IAB OpenRTB 2.5 user fields
+- `ortb2.user.data[]`: Standard IAB segment taxonomy user data
+- `ortb2.user.ext.data.*`: Non standard arbitrary user data
+
+Please note that field `ortb2.app.*`, in a webview context, is **not supported**.
+
+AdUnit-specific data using `AdUnit.ortb2Imp` supports following fields:
+
+- `ortb2.imp[].ext.data.*`
+
+Example first party data that's available to all bidders and all adunits:
+
+```javascript
+pbjs.setConfig({
+  ortb2: {
+      site: {
+          // standard IAB OpenRTB 2.5 site fields are passed in `ortb2.site.*`
+          name: "example",
+          cat: ["IAB2"],
+          domain: "page.example.com",
+
+          // standard IAB segment taxonomy site data is passed in `ortb2.site.content.data[]`
+          content: {
+              userrating: "4",
+              data: [{ name: "www.sitedataprovider1.com" }]
+          },
+
+          // any non standard arbitrary site data is passed in `ortb2.site.ext.data.*`
+          ext: { data: { arbitrarySiteKey: "arbitrary" } }
+      },
+      user: {
+          // standard IAB OpenRTB 2.5 user fields are passed in `ortb2.user.*`
+          keywords: "a,b",
+          geo: { country: "FRA", lat: 48.9, lon: 2.2 },
+
+          // standard IAB segment taxonomy user data are passed in `ortb2.user.data[]`
+          data: [{ name: "www.userdataprovider1.com" }],
+
+          // any non standard arbitrary user data is passed in `ortb2.user.ext.data.*`
+          ext: { data: { arbitraryUserKey: "arbitrary" } }
+      }
+  }
+});
+```
+
+Example of first party data available only to the Mediakeys bidder and applies across all ad units:
+
+```javascript
+pbjs.setBidderConfig({
+    bidders: ['mediakeys'],
+    config: {
+        ortb2: {
+            site: {
+                ext: {
+                    data: {
+                        pageType: "article",
+                        category: "tools"
+                    }
+                }
+            },
+            user: {
+                ext: {
+                    data: {
+                        registered: true,
+                        interests: ["cars"]
+                    }
+                }
+            }
+        }
+    }
+});
+```
+
+Example of an adunit-specific with first party data:
+
+```javascript
+var adUnit = {
+    // applies to all bidders
+    ortb2Imp: {
+        instl:1
+    },
+    bids: [{
+      bidder: 'mediakeys',
+      params: {},
+      // applies to mediakeys bidder only
+      ortb2Imp: {
+          ext: {
+              data: {
+                  pbadslot: "homepage-top-rect",
+                  adUnitSpecificAttribute: "123"
+              }
+          }
+      }
+    }]
+};
+```
+
+<a name="required-and-recommended-modules"></a>
+
+#### Required and Recommended Modules
+
+Mediakeys fully supports the following [Prebid.js Modules](https://docs.prebid.org/dev-docs/modules/):
+
+{: .table .table-bordered .table-striped }
+| Module                                                                                                | Scope                       |
+|-------------------------------------------------------------------------------------------------------|-----------------------------|
+| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagement.html)          | Required in Europe          |
+| [Consent Management - US Privacy](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | Required in US - California |
+| [Instream Tracking](https://docs.prebid.org/dev-docs/modules/instreamTracking.html)                   | Required for Instream Video |
+| [First Party Data Enrichment](https://docs.prebid.org/dev-docs/modules/enrichmentFpdModule.html)      | Recommended for all traffic |
+| [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html)                           | Recommended for all traffic |
+
+Publishers must utilize the required modules in described scope to be able to receive bid responses.
+
+Before using [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html) Module, please confirm with the Mediakeys team
+the proper `asi` and `sid` field values that you should pass.
 
 <a name="mediatype-banner"></a>
 
@@ -89,15 +218,14 @@ Please refer to the following table to find acceptable values for mediakeys bidd
 | protocols      | recommended | Array of supported video protocols: <br />2: VAST 2.0 <br />3: VAST 3.0 | [2,3]<br />default: [3] | array&lt;integers&gt;|
 | maxduration    | recommended | Maximum video ad duration in seconds. | 30<br />default: not set | integer |
 | skip           | recommended | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. | 1<br />default: 0 | integer |
-| | | | | |
 
 (*) Mediakeys bidder will adapt the bid response to send the video format closest to the `playerSize` (from an aspect ratio point of view). To maximize the responses, please consider requesting formats like:
 
 - small video: `360x268` (minimal bandwidth, low quality)
 - medium video: `640x360` (low bandwidth, medium quality)
 - standard video: `640×480` (medium bandwidth, good quality)
 - full wide video: `854×480` (high bandwidth, superior quality)
-- HD video: `1280x720` (miximum bandwidth, best quality)
+- HD video: `1280x720` (maximum bandwidth, best quality)
 
 <a name="instream-video"></a>