First Party Data 2.0 doc updates

dev-docs/adunit-reference.md

@@ -37,7 +37,7 @@ See the table below for the list of properties on the ad unit.  For example ad u
 | `mediaTypes` | Optional | Object                                | Defines one or more media types that can serve into the ad unit.  For a list of properties, see [`adUnit.mediaTypes`](#adUnit.mediaTypes) below.                                           |
 | `labelAny`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds].  Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                    |
 | `labelAll`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                     |
-| `fpd`   | Optional | Object                         | Similar to [global first party data configuration](/dev-docs/publisher-api-reference.html#setConfig-fpd), but specific to this adunit. |
+| `ortb2Imp`   | Optional | Object                         | Similar to [global first party data configuration](/dev-docs/publisher-api-reference.html#setConfig-fpd), but specific to this adunit. Note that the setConfig data is global to the logical OpenRTB object, but AdUnit-specific data is defined in the scope of a particular imp object. |
 
 <a name="adUnit.bids" />
 
@@ -531,18 +531,20 @@ pbjs.addAdUnits({
             sizes: [[300,250]]
         }
     },
-    fpd: {
-         context: {
-            pbAdSlot: "homepage-top-rect",
-            adUnitSpecificContextAttribute: "123"
+    ortb2Imp: {
+         ext: {
+	    data: {
+                pbAdSlot: "homepage-top-rect",
+                adUnitSpecificContextAttribute: "123"
+	    }
          }
     },
     ...
 });
 {% endhighlight %}
 
 Notes:
-- Only contextual data is supported on the AdUnit; user-related data goes in the [global first party data](/dev-docs/publisher-api-reference.html#setConfig-fpd).
+- Only contextual data should be added on the AdUnit; user-related data goes in the [global first party data](/dev-docs/publisher-api-reference.html#setConfig-fpd) config.
 - For additional help with analytics and reporting you can use the [Prebid Ad Slot](/features/pbAdSlot.html), a special type of first party data.
 
 ## Related Topics

dev-docs/publisher-api-reference.md

@@ -2404,13 +2404,7 @@ pbjs.setConfig({coppa: true});
 
 #### First Party Data
 
-Historically, a number of adapters supported taking key/value pairs as arguments, but they were all different. For example:
-
-- RubiconProject took `keywords`, `inventory` and `visitor` parameters
-- AppNexus took `keywords` and `user`
-- OpenX took `customParams`
-
-First party data allows publishers to specify key/value data in one place where each compatible bid adapter can read it.
+The First Party Data feature allows publishers to specify key/value data in one place where each compatible bid adapter can read it.
 
 {: .alert.alert-warning :}
 Not all bid adapters currently support reading first party data in this way, but support should increase over time.
@@ -2419,66 +2413,50 @@ Not all bid adapters currently support reading first party data in this way, but
 
 {% highlight js %}
 pbjs.setConfig({
-   fpd: {
-       context: {
+   ortb2: {
+       site: {
            keywords: "power tools",
            search: "drill",
            content: { userrating: 4 },
-           data: {
-               pageType: "article",
-               category: "tools"
+           ext: {
+               data: {
+                   pageType: "article",
+                   category: "tools"
+               }
            }
         },
         user: {
            keywords: "a,b",
            gender: "M",
            yob: 1984,
            geo: { country: "ca" },
-           data: {
-              registered: true,
-              interests: ["cars"]
+           ext: {
+               data: {
+                  registered: true,
+                  interests: ["cars"]
+               }
            }
         }
     }
 });
 {% endhighlight %}
 
 {: .alert.alert-info :}
-The First Party Data JSON structure reflects the OpenRTB standard. Arbitrary values should go in context.data or
-user.data. Keywords, search, content, gender, yob, and geo are special values in OpenRTB.
+The First Party Data JSON structure reflects the OpenRTB standard. Arbitrary values should go in site.ext.data or
+user.ext.data. Keywords, search, content, gender, yob, and geo are special values in OpenRTB.
 
 **Scenario 2** - Global (cross-adunit) First Party Data open only to a subset of bidders
 
-If a publisher only wants certain bidders to receive the data, use the [setBidderConfig](#module_pbjs.setBidderConfig) function like this:
-
-{% highlight js %}
-pbjs.setBidderConfig({
-   bidders: ['bidderA', 'bidderB'],
-   config: {
-       fpd: {
-           context: {
-               data: {
-                  pageType: "article",
-                  category: "tools"
-               }
-            },
-            user: {
-               data: {
-                  registered: true,
-                  interests: ["cars"]
-               }
-          }
-      }
-   }
-});
-{% endhighlight %}
+If a publisher only wants certain bidders to receive the data, use the [setBidderConfig](#module_pbjs.setBidderConfig) function.
 
-**Scenario 3** - See the [AdUnit Reference](/dev-docs/adunit-reference.html) for AdUnit-specific first party data.
+**Scenario 3** - AdUnit-specific First Party Data
 
-<a name="setConfig-vast-cache" />
+See the [AdUnit Reference](/dev-docs/adunit-reference.html) for AdUnit-specific first party data.
 
 See [Prebid Server First Party Data](/prebid-server/features/pbs-fpd.html) for details about passing data server-side.
 
+<a name="setConfig-vast-cache" />
+
 #### Client-side Caching of VAST XML
 
 When serving video ads, VAST XML creatives must be cached on the network so the
@@ -2693,20 +2671,45 @@ The page usage is:
 
 {% highlight js %}
 pbjs.setBidderConfig({
-   bidders: ["bidderA"],  // one or more bidders
-   config: {              // the bidder-specific config
-      bidderA: {
-         customArg: 'value'
+   bidders: ['bidderA'],
+   config: {
+      customArg: "customVal"
+   }
+});
+{% endhighlight %}
+or
+{% highlight js %}
+pbjs.setBidderConfig({
+   bidders: ['bidderB'],
+   config: {
+       ortb2: {
+           site: {
+               ext: {
+                   data: {
+                      pageType: "article",
+                      category: "tools"
+                   }
+               }
+            },
+            user: {
+               ext: {
+                   data: {
+                      registered: true,
+                      interests: ["cars"]
+                   }
+               }
+          }
       }
    }
 });
 {% endhighlight %}
 
-When 'bidderA' calls `getConfig('bidderA')`, it will receive the object that contains 'customArg'.
-If any other bidder calls `getConfig('bidderA')`, it will receive nothing.
+How to interpret these examples:
+- When 'bidderA' calls `getConfig('customArg')`, it will receive the object that contains 'customArg'. If any other bidder calls `getConfig('customArg')`, it will receive nothing.
+- When 'bidderB' calls `getConfig('ortb2')`, it will receive this override definition rather than whatever else might have been defined globally. If any other bidder calls `getConfig('ortb2')`, it will receive the globally defined objects.
 
 {: .alert.alert-info :}
-This function is currently used by the `schain` feature. Refer to the [schain]({{site.baseurl}}/dev-docs/modules/schain.html) documentation for examples.
+This function is also used by the `schain` feature. Refer to the [schain](/dev-docs/modules/schain.html) documentation for examples.
 
 <a name="module_pbjs.getConfig"></a>
 

features/firstPartyData.md

@@ -20,37 +20,39 @@ These conventions aren't implemented by all adapters. Please
 check with each of your bidders to make sure they're reading first
 party data from the standard Prebid locations.
 
+{: .alert.alert-warning :}
+This document covers the method of specifying First Party Data as of Prebid.js 4.xx, which
+we recommend all publishers use. In previous versions of Prebid.js, the interface was
+to set `fpd` values. We now use the more generic `ortb2` interface,
+which can be used for more than just First Party Data.
+
 ## How It Works
 
-Here's a summary of how first party data (FPD) works:
+Publishers supply First Party Data (FPD) by specifying attributes as
+configuration or on a Prebid.js AdUnit. Here's a summary of how it works:
 
 ![First Party Data Summary](/assets/images/flowcharts/FirstPartyData-Summary.png){: .pb-lg-img :}
 
-This diagram shows a page that can provide:
+This diagram highlights the scenarios a page can implement:
 
-- Global context (site) data that applies to all AdUnits and all bidders
-- Global user data that applies to all AdUnits and all bidders
-- AdUnit-specific data that applies to all bidders
-- Bidder-specific context data that applies to all AdUnits
-- Bidder-specific user data that applies to all AdUnits
+- Global site or user data that applies to all AdUnits and all bidders. Use [`setConfig()`](/dev-docs/publisher-api-reference.html#setConfig-fpd)
+- AdUnit-specific data that applies to all bidders. Define [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#first-party-data)
+- Bidder-specific site or user data that applies to all AdUnits. Use [`setBidderConfig()`](/dev-docs/publisher-api-reference.html#module_pbjs.setBidderConfig)
 
 ## In-Page Examples
 
 The Prebid First Party Data JSON structure reflects the OpenRTB standard.
-Arbitrary values should go in fpd.context.data or fpd.user.data. Fields
-that are meant to be standard [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) values should be in fpd.context or fpd.user. Specfically, the standard values for `site` are: name, domain, cat, sectioncat, pagecat, page, ref, search, keywords. For `user` these are: yob, gender, keywords.
-
-{: .alert.alert-info :}
-'Context' corresponds to the OpenRTB 'site' object.
+- Arbitrary attributes should go in `ortb2.site.ext.data` or `ortb2.user.data`.
+- Fields that are meant to be standard [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) should be in `ortb2.site` or `ortb2.user`. Specfically, the standard values for 'site' are: name, domain, cat, sectioncat, pagecat, page, ref, search, keywords. For 'user' these are: yob, gender, keywords.
 
 ### Supplying Global Data
 
 Here's how a publisher can let all bid adapters have access
 to first party data that might be useful in ad targeting:
 {% highlight js %}
 pbjs.setConfig({
-   fpd: {
-       context: {
+   ortb2: {
+       site: {
            name: "example",
            domain: "page.example.com",
            cat: ["IAB2"],
@@ -61,18 +63,29 @@ pbjs.setConfig({
            keywords: "power tools, drills",
            search: "drill",
            content: { userrating: 4 },
-           data: {   // fields that aren't part of openrtb 2.5
-               pageType: "article",
-               category: "repair"
-           }
+	   ext: {
+               data: {   // fields that aren't part of openrtb 2.5
+                   pageType: "article",
+                   category: "repair"
+               }
+	   }
         },
         user: {
            yob: 1985,
            gender: "m",
            keywords: "a,b",
-           data: {
-              registered: true,
-              interests: ["cars"]
+	   data: [{
+	       name: "dataprovider.com",
+	       ext: { taxonomyname: "IAB" },
+               segment: [
+		  { id: "1" }
+               ]
+	   }],
+	   ext: {
+               data: {
+                  registered: true,
+                  interests: ["cars"]
+	       }
            }
         }
     }
@@ -81,7 +94,7 @@ pbjs.setConfig({
 
 {: .alert.alert-warning :}
 Note that supplying first party **user** data may require special
-consent in certain regions. Prebid does **not** police the passing
+consent in certain regions. Prebid.js does **not** police the passing
 of user data as part of its GDPR or CCPA modules.
 
 ### Supplying AdUnit-Specific Data
@@ -96,20 +109,22 @@ pbjs.addAdUnits({
             sizes: [[300,250]]
         }
     },
-    fpd: {
-        context: {
-            pbAdSlot: "homepage-top-rect",
-            data: {
+    ortb2Imp: {
+        ext: {
+	    data: {
+                pbAdSlot: "homepage-top-rect",
                 adUnitSpecificAttribute: "123"
             }
-         }
+        }
     },
     ...
 });
 {% endhighlight %}
 
 {: .alert.alert-info :}
-Prebid does not support AdUnit-Specific **user** data.
+Prebid does not support AdUnit-specific **user** data, nor does it support
+bidder-specific AdUnit First Party Data. You could implement either of
+these scenarios with a publisher-specific callback on the [`requestBids` event](/dev-docs/publisher-api-reference.html#module_pbjs.onEvent)
 
 ### Supplying Bidder-Specific Data
 
@@ -120,42 +135,41 @@ global data.
 pbjs.setBidderConfig({
    bidders: ['bidderA', 'bidderB'],
    config: {
-       fpd: {
-           context: {
-               data: {
-                  pageType: "article",
-                  category: "tools"
+       ortb2: {
+           site: {
+               ext: {
+                   data: {
+                      pageType: "article",
+                      category: "tools"
+                   }
                }
             },
             user: {
-               data: {
-                  registered: true,
-                  interests: ["cars"]
+               ext: {
+                   data: {
+                      registered: true,
+                      interests: ["cars"]
+                   }
                }
-          }
-      }
+           }
+       }
    }
 });
 
 pbjs.setBidderConfig({ // different bidders can receive different data
    bidders: ['bidderC'],
    config: {
-     fpd: { ... }
+     ortb2: { ... }
    }
 });
 {% endhighlight %}
 
-{: .alert.alert-info :}
-Applying permissions to AdUnit-specific First Party Data has
-to be done manually by using an event handler -- [pbjs.onEvent('beforeRequestBids', function())](/dev-docs/publisher-api-reference.html#module_pbjs.onEvent)
-
 ## How Bid Adapters Should Read First Party Data
 
 To access global data, a Prebid.js bid adapter needs only to call [`getConfig()`](/dev-docs/publisher-api-reference.html#module_pbjs.getConfig), like this:
 
 {% highlight js %}
-config.getConfig('fpd.context'))
-config.getConfig('fpd.user'))
+config.getConfig('ortb2'))
 {% endhighlight %}
 
 AdUnit-specific values must be parsed out of the AdUnit object.
@@ -164,7 +178,7 @@ The assumption is that bid adapters will copy the values to the appropriate prot
 
 See [Prebid Server First Party Data](/prebid-server/features/pbs-fpd.html) for a discussion of this feature for Prebid Server bid adapters.
 
-## Further Reading
+## Related Topics
 
 - The [Prebid.js Publisher API](/dev-docs/publisher-api-reference.html)
 - The [AdUnit Reference](/dev-docs/adunit-reference.html)