First Party Data 2.0 doc updates (#2722)

* fpd2.0 updates * minor edits * table tuning * removed diagram * review comments from taxonomy team * adding in version number also added notes about PBJS 4.29 and before Co-authored-by: Jean Stemp <[email protected]>
prebid · Mar 10, 2021 · 8e41e88 · 8e41e88
1 parent c7334f8
commit 8e41e88
Show file tree

Hide file tree

Showing 6 changed files with 148 additions and 134 deletions.
diff --git a/assets/images/flowcharts/FirstPartyData-Detailed.png b/assets/images/flowcharts/FirstPartyData-Detailed.png
diff --git a/assets/images/flowcharts/FirstPartyData-Summary.png b/assets/images/flowcharts/FirstPartyData-Summary.png
diff --git a/dev-docs/adunit-reference.md b/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

diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md
@@ -2421,13 +2421,8 @@ 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.
+See the [First Party Data Feature](/features/firstPartyData.html) for more detailed examples.
 
 {: .alert.alert-warning :}
 Not all bid adapters currently support reading first party data in this way, but support should increase over time.
@@ -2436,66 +2431,35 @@ Not all bid adapters currently support reading first party data in this way, but
 
 {% highlight js %}
 pbjs.setConfig({
-   fpd: {
-       context: {
-           keywords: "power tools",
-           search: "drill",
-           content: { userrating: 4 },
-           data: {
-               pageType: "article",
-               category: "tools"
-           }
-        },
-        user: {
-           keywords: "a,b",
-           gender: "M",
-           yob: 1984,
-           geo: { country: "ca" },
-           data: {
-              registered: true,
-              interests: ["cars"]
-           }
-        }
+   ortb2: {
+       site: {
+	 ...
+       },
+       user: {
+         ...
+       }
     }
 });
 {% 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 `ortb2` JSON structure reflects the OpenRTB standard:
+- Fields that like keywords, search, content, gender, yob, and geo are values defined in OpenRTB, so should go directly under the site or user objects.
+- Arbitrary values should go in site.ext.data or user.ext.data.
+- Segments should go in site.content.data[] or user.data[].
+- Any other OpenRTB 2.5 field could be added here as well, e.g. site.content.language.
 
 **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
@@ -2728,20 +2692,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>