From c877a20a4e727adbf570ec8a084b7fed83807f8d Mon Sep 17 00:00:00 2001 From: karimJWP Date: Fri, 16 Oct 2020 13:03:48 -0400 Subject: [PATCH 1/7] adds docs for JW Player RTD Provider --- dev-docs/modules/jwplayerRtdProvider.md | 144 ++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 dev-docs/modules/jwplayerRtdProvider.md diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md new file mode 100644 index 0000000000..4fe012e629 --- /dev/null +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -0,0 +1,144 @@ +--- +layout: page_v2 +title: JW Player Real Time Data Provider +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` object: + +```javascript +const jwplayerRtdProvider = { + name: "jwplayer" +}; + +pbjs.setConfig({ + ..., + realTimeData: { + dataProviders: [ + jwplayerRtdProvider + ] + } +}); +``` + +3) In order to prefetch targeting information for certain media, include the media IDs in the `jwplayerRtdProvider` var before calling `setConfig`: + +```javascript +const jwplayerRtdProvider = { + name: "jwplayer", + auctionDelay: 1000, + params: { + mediaIDs: ['abc', 'def', 'ghi', 'jkl'] + } +}; +``` + +**Note:** `auctionDelay` is required to ensure the auction waits for prefetching to complete. + +**Config Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Real time data module name | Always 'jwplayer' | +| auctionDelay | Number | Max time in ms that auction will wait for the requested targeting information | Optional. Default to 0. Required to ensure that the auction is delayed until prefetch is complete | +| 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 before calling `addAdUnits`: + +```javascript + const adUnit = { + code: '/19968336/prebid_native_example_1', + ... + jwTargeting: { + waitForIt: true, + playerID: 'abcd', + mediaID: '1234' + } + }; + + pbjs.que.push(function() { + pbjs.addAdUnits([adUnit]); + pbjs.requestBids({...}); + }); +``` + +**Note:** `waitForIt` is required to ensure the auction waits for prefetching to complete. + +**AdUnit Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| jwTargeting | Object | | | +| jwTargeting.mediaID | String | Media Id of the content associated to the Ad Unit | Optional but highly recommended | +| jwTargeting.playerID | String | Id of the JW Player instance which will render the content associated to the Ad Unit | Optional but recommended | +| jwTargeting.waitForIt | Boolean | Media Ids for prefetching | Optional. Defaults to false. Required to ensure that the auction is delayed until prefetch is complete | + +## 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: + +```javascript +{ + adUnitCode: 'xyz', + bidId: 'abc', + ..., + 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 | | | +| 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. \ No newline at end of file From ada392ca866a0382148d9f045f326c44bb515fdd Mon Sep 17 00:00:00 2001 From: karimJWP Date: Fri, 16 Oct 2020 15:46:23 -0400 Subject: [PATCH 2/7] moves auctionDelay to rtd --- dev-docs/modules/jwplayerRtdProvider.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 4fe012e629..7e236533d7 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -28,7 +28,7 @@ to Bid Adapters. `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` object: +2) Publishers must register JW Player as a Real Time Data provider by using `setConfig` to load a Prebid Config containing a `realTimeData.dataProviders` object: ```javascript const jwplayerRtdProvider = { @@ -38,6 +38,7 @@ const jwplayerRtdProvider = { pbjs.setConfig({ ..., realTimeData: { + auctionDelay: 1000, dataProviders: [ jwplayerRtdProvider ] @@ -50,14 +51,13 @@ pbjs.setConfig({ ```javascript const jwplayerRtdProvider = { name: "jwplayer", - auctionDelay: 1000, params: { mediaIDs: ['abc', 'def', 'ghi', 'jkl'] } }; ``` -**Note:** `auctionDelay` is required to ensure the auction waits for prefetching to complete. +**Note:** setting an `auctionDelay` in the `realTimeData` object is required to ensure the auction waits for prefetching to complete. **Config Syntax details:** @@ -65,7 +65,6 @@ const jwplayerRtdProvider = { | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | | name | String | Real time data module name | Always 'jwplayer' | -| auctionDelay | Number | Max time in ms that auction will wait for the requested targeting information | Optional. Default to 0. Required to ensure that the auction is delayed until prefetch is complete | | params | Object | | | | params.mediaIDs | Array of Strings | Media Ids for prefetching | Optional. | From b757686ba562463c3090a9e26a104879b2a86bc5 Mon Sep 17 00:00:00 2001 From: karimJWP Date: Fri, 16 Oct 2020 15:56:18 -0400 Subject: [PATCH 3/7] explains fileds required for async reqs --- dev-docs/modules/jwplayerRtdProvider.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 7e236533d7..602008e468 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -28,7 +28,7 @@ to Bid Adapters. `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` object: +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 const jwplayerRtdProvider = { @@ -57,7 +57,7 @@ const jwplayerRtdProvider = { }; ``` -**Note:** setting an `auctionDelay` in the `realTimeData` object is required to ensure the auction waits for prefetching to complete. +**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:** @@ -87,7 +87,7 @@ const jwplayerRtdProvider = { }); ``` -**Note:** `waitForIt` is required to ensure the auction waits for prefetching to complete. +**Note:** `waitForIt` is required to ensure the auction waits for prefetching to complete. It signals to prebid that you allow the module to delay the auction if necessary. **AdUnit Syntax details:** @@ -126,7 +126,7 @@ Each bid for which targeting information was found will conform to the following | jwTargeting | Object | | | | jwTargeting.segments | Array of Strings | jwpseg targeting segments | | | jwTargeting.content | Object | | | -| content.id | String | Unique identifier for the specific media asset. | | +| jwTargeting.content.id | String | Unique identifier for the specific media asset | | ## Example From 6380cd2f5f27e603212bd4bac8b0b7c5e4493107 Mon Sep 17 00:00:00 2001 From: karimJWP Date: Fri, 23 Oct 2020 12:33:18 -0400 Subject: [PATCH 4/7] updates docs for fpd --- dev-docs/modules/jwplayerRtdProvider.md | 33 +++++++++++++++---------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 602008e468..440bbcd721 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -38,7 +38,7 @@ const jwplayerRtdProvider = { pbjs.setConfig({ ..., realTimeData: { - auctionDelay: 1000, + auctionDelay: 100, dataProviders: [ jwplayerRtdProvider ] @@ -46,16 +46,18 @@ pbjs.setConfig({ }); ``` -3) In order to prefetch targeting information for certain media, include the media IDs in the `jwplayerRtdProvider` var before calling `setConfig`: +3) In order to prefetch targeting information for certain media, include the media IDs in the `jwplayerRtdProvider` var and set `waitForIt` to `true` before calling `setConfig`: ```javascript const jwplayerRtdProvider = { name: "jwplayer", + waitForIt: true, params: { mediaIDs: ['abc', 'def', 'ghi', 'jkl'] } }; ``` +**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. @@ -65,19 +67,26 @@ const jwplayerRtdProvider = { | 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. | +| 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 before calling `addAdUnits`: +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', - ... - jwTargeting: { - waitForIt: true, - playerID: 'abcd', - mediaID: '1234' + ..., + fpd: { + context: { + data: { + jwTargeting: { + // Note: the following Ids are placeholders and should be replaced with your Ids. + playerID: 'abcd', + mediaID: '1234' + } + } + } } }; @@ -86,8 +95,7 @@ const jwplayerRtdProvider = { pbjs.requestBids({...}); }); ``` - -**Note:** `waitForIt` is required to ensure the auction waits for prefetching to complete. It signals to prebid that you allow the module to delay the auction if necessary. +**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:** @@ -97,14 +105,13 @@ const jwplayerRtdProvider = { | jwTargeting | Object | | | | jwTargeting.mediaID | String | Media Id of the content associated to the Ad Unit | Optional but highly recommended | | jwTargeting.playerID | String | Id of the JW Player instance which will render the content associated to the Ad Unit | Optional but recommended | -| jwTargeting.waitForIt | Boolean | Media Ids for prefetching | Optional. Defaults to false. Required to ensure that the auction is delayed until prefetch is complete | ## 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: -```javascript +```json { adUnitCode: 'xyz', bidId: 'abc', From 6b5f3b98f30f421d82903edba9a4d0dccec787f9 Mon Sep 17 00:00:00 2001 From: bretg Date: Wed, 28 Oct 2020 14:14:21 -0400 Subject: [PATCH 5/7] making syntax consistent --- dev-docs/modules/jwplayerRtdProvider.md | 53 +++++++++++-------------- 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 440bbcd721..b32b5bacb4 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -1,8 +1,8 @@ --- layout: page_v2 title: JW Player Real Time Data Provider -description: makes JW Player's video ad targeting information accessible - to Bid Adapters. +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 @@ -31,33 +31,24 @@ to Bid Adapters. 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 -const jwplayerRtdProvider = { - name: "jwplayer" -}; - pbjs.setConfig({ ..., realTimeData: { auctionDelay: 100, - dataProviders: [ - jwplayerRtdProvider - ] + 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 `jwplayerRtdProvider` var and set `waitForIt` to `true` before calling `setConfig`: +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`: -```javascript -const jwplayerRtdProvider = { - name: "jwplayer", - waitForIt: true, - params: { - mediaIDs: ['abc', 'def', 'ghi', 'jkl'] - } -}; -``` -**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:** `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. @@ -102,9 +93,9 @@ const jwplayerRtdProvider = { {: .table .table-bordered .table-striped } | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | -| jwTargeting | Object | | | -| jwTargeting.mediaID | String | Media Id of the content associated to the Ad Unit | Optional but highly recommended | -| jwTargeting.playerID | String | Id of the JW Player instance which will render the content associated to the Ad Unit | Optional but recommended | +| 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: @@ -116,11 +107,15 @@ Each bid for which targeting information was found will conform to the following adUnitCode: 'xyz', bidId: 'abc', ..., - jwTargeting: { - segments: ['123', '456'], - content: { - id: 'jw_abc123' - } + fpd: { + context: { + data: { + jwTargeting: { + segments: ['123', '456'], + content: { + id: 'jw_abc123' + } + } } } ``` @@ -147,4 +142,4 @@ To view an example: `http://localhost:9999/integrationExamples/gpt/jwplayerRtdProvider_example.html` -**Note:** the mediaIds in the example are placeholder values; replace them with your existing IDs. \ No newline at end of file +**Note:** the mediaIds in the example are placeholder values; replace them with your existing IDs. From 401f465c3cb1096fcc79622995cecdf646f99133 Mon Sep 17 00:00:00 2001 From: karimJWP Date: Wed, 28 Oct 2020 15:56:22 -0400 Subject: [PATCH 6/7] reverts bid interface --- dev-docs/modules/jwplayerRtdProvider.md | 29 +++++++++++-------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index b32b5bacb4..1f4709ffd2 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -46,11 +46,12 @@ pbjs.setConfig({ }); ``` -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`: +3) Optionally, if you would like to prefetch the targeting information for certain media, you must include the media IDs in `params.mediaIDs`, as displayed above. You must also set `waitForIt` to `true` and make sure that a value is set to `realTimeData.auctionDelay`. -**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. +`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. +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. -**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. +**Note:** Though prefetch is optional, we highly recommend enabling it to ensure that the targeting information is available before bids are requested. **Config Syntax details:** @@ -104,19 +105,15 @@ Each bid for which targeting information was found will conform to the following ```json { - adUnitCode: 'xyz', - bidId: 'abc', - ..., - fpd: { - context: { - data: { - jwTargeting: { - segments: ['123', '456'], - content: { - id: 'jw_abc123' - } - } - } + adUnitCode: 'xyz', + bidId: 'abc', + ..., + jwTargeting: { + segments: ['123', '456'], + content: { + id: 'jw_abc123' + } + } } ``` From 296c876cb1b259cdd24b545a2974156bf5f83b91 Mon Sep 17 00:00:00 2001 From: bretg Date: Wed, 28 Oct 2020 17:22:18 -0400 Subject: [PATCH 7/7] added transition for bid adapters --- dev-docs/modules/jwplayerRtdProvider.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index 1f4709ffd2..bb34f2b6c1 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -100,8 +100,10 @@ Setting an `auctionDelay` in the `realTimeData` object is required to ensure the ## 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: +This section contains guidelines for bid adapters that are working with JW Player to utilize the additional targeting. + +Those bidders should implement the `buildRequests` function. When it is called, the `bidRequests` param will be an array of bids. +Each bidRequest for which targeting information was found will conform to the following object structure: ```json { @@ -116,8 +118,10 @@ Each bid for which targeting information was found will conform to the following } } ``` + +Read the bidRequest.jwTargeting object and pass the values to your endpoint as appropriate. -**Bid Syntax details:** +**BidRequest Syntax details:** {: .table .table-bordered .table-striped } | Name |Type | Description | Notes |