[AD-963] Add documentation for JW Player RTD Provider

dev-docs/modules/jwplayerRtdProvider.md

@@ -0,0 +1,145 @@
+---
+layout: page_v2
+title: JW Player Real Time Data Provider
+display_name: JW Player video ad targeting
+description: makes JW Player's video ad targeting information accessible to Bid Adapters.
+page_type: module
+module_type: rtd
+module_code : jwplayer
+enable_download : true
+sidebarType : 1
+---
+
+# JW Player RTD Provider
+{:.no_toc}
+
+* TOC
+{:toc}
+
+## Overview
+
+The purpose of this Real Time Data Provider is to allow publishers to target against their JW Player media without 
+being forced to integrate with the Player Bidding product. This prebid module makes JW Player's video ad targeting information accessible 
+to Bid Adapters.
+
+## Implementation for Publishers:
+
+1) Compile the JW Player RTD Provider into your Prebid build:
+
+`gulp build --modules=jwplayerRtdProvider`
+
+2) Publishers must register JW Player as a Real Time Data provider by using `setConfig` to load a Prebid Config containing a `realTimeData.dataProviders` array:
+
+```javascript
+pbjs.setConfig({
+    ...,
+    realTimeData: {
+      auctionDelay: 100,
+      dataProviders: [{
+          name: "jwplayer",
+          waitForIt: true,
+          params: {
+            mediaIDs: ['abc', 'def', 'ghi', 'jkl']
+          }
+      }]
+    }
+});
+``` 
+
+3) In order to prefetch targeting information for certain media, include the media IDs in the `jwplayer` var and set `waitForIt` to `true` before calling `setConfig`:
+
+**Note:** `waitForIt` is required to ensure the auction waits for the prefetching of the relvant targeting information to complete. It signals to Prebid that you allow the module to delay the auction if necessary.
+
+**Note:** setting an `auctionDelay` in the `realTimeData` object is required to ensure the auction waits for prefetching to complete. The `auctionDelay` is the max time in ms that the auction will wait for the requested targeting information.
+
+**Config Syntax details:**
+
+{: .table .table-bordered .table-striped }
+| Name  |Type | Description   | Notes  |
+| :------------ | :------------ | :------------ |:------------ |
+| name | String | Real time data module name | Always 'jwplayer' |
+| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false |
+| params | Object | | |
+| params.mediaIDs | Array of Strings | Media Ids for prefetching | Optional |
+
+4) Include the content's media ID and/or the player's ID in the matching AdUnit's `fpd.context.data.jwTargeting` before calling `addAdUnits`:
+
+```javascript
+   const adUnit = {
+     code: '/19968336/prebid_native_example_1',
+     ...,
+     fpd: {
+       context: {
+         data: {
+           jwTargeting: {
+             // Note: the following Ids are placeholders and should be replaced with your Ids.
+             playerID: 'abcd',
+             mediaID: '1234'
+           }
+         }
+       }
+     }
+   };
+
+   pbjs.que.push(function() {
+       pbjs.addAdUnits([adUnit]);
+       pbjs.requestBids({...});
+   });
+```
+**Note**: You may also include `jwTargeting` information in the prebid config's `fpd.context.data`. Information provided in the adUnit will always supersede the information in the config; use the config to set fallback information or information that applies to all adUnits.
+
+**AdUnit Syntax details:**
+
+{: .table .table-bordered .table-striped }
+| Name  |Type | Description   | Notes  |
+| :------------ | :------------ | :------------ |:------------ |
+| fpd.context.data.jwTargeting | Object | | |
+| fpd.context.data.jwTargeting.mediaID | String | Media Id of the content associated to the Ad Unit | Optional but highly recommended |
+| fpd.context.data.jwTargeting.playerID | String | Id of the JW Player instance which will render the content associated to the Ad Unit | Optional but recommended |
+
+## Implementation for Bid Adapters:
+
+Implement the `buildRequests` function. When it is called, the `bidRequests` param will be an array of bids.
+Each bid for which targeting information was found will conform to the following object structure:
+
+```json
+{
+    adUnitCode: 'xyz',
+    bidId: 'abc',
+    ...,
+    fpd: {
+      context: {
+         data: {
+           jwTargeting: {
+             segments: ['123', '456'],
+             content: {
+               id: 'jw_abc123'
+           }
+        }
+    }
+}
+```
+
+**Bid Syntax details:**
+
+{: .table .table-bordered .table-striped }
+| Name  |Type | Description   | Notes  |
+| :------------ | :------------ | :------------ |:------------ |
+| jwTargeting | Object | | |
+| jwTargeting.segments | Array of Strings | jwpseg targeting segments | |
+| jwTargeting.content | Object | | |
+| jwTargeting.content.id | String | Unique identifier for the specific media asset | |
+
+## Example
+
+To view an example:
+
+- in the Prebid repo, run in your cli:
+
+`gulp serve --modules=jwplayerRtdProvider`
+
+- in your browser, navigate to:
+
+`http://localhost:9999/integrationExamples/gpt/jwplayerRtdProvider_example.html`
+
+**Note:** the mediaIds in the example are placeholder values; replace them with your existing IDs.