first party data docs

_data/sidebar.yml

@@ -627,6 +627,14 @@
   sectionTitle:
   subgroup: 8
 
+- sbSecId: 1
+  title: First Party Data
+  link: /features/firstPartyData.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 8
+
 
 #--------------Prebid Mobile--------------|
 
@@ -1801,6 +1809,14 @@
   sectionTitle:
   subgroup: 3
 
+- sbSecId: 5
+  title: First Party Data
+  link: /prebid-server/features/pbs-fpd.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 3
+
 - sbSecId: 5
   title: Developers
   link:

dev-docs/publisher-api-reference.md

@@ -2278,14 +2278,13 @@ pbjs.setConfig({coppa: true});
 
 #### First Party Data
 
-A number of adapters support taking key/value pairs as arguments, but they're all different. For example:
+Historically, a number of adapters supported taking key/value pairs as arguments, but they were all different. For example:
 
-- RubiconProject takes `keywords`, `inventory` and `visitor` parameters
-- AppNexus takes `keywords` and `user`
-- OpenX takes `customParams`
+- RubiconProject took `keywords`, `inventory` and `visitor` parameters
+- AppNexus took `keywords` and `user`
+- OpenX took `customParams`
 
-This feature allows publishers a way to specify key/value data in one place where each compatible bid adapter
-can read it.
+First party data 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.
@@ -2352,6 +2351,8 @@ pbjs.setBidderConfig({
 
 <a name="setConfig-vast-cache" />
 
+See [Prebid Server First Party Data](/prebid-server/features/pbs-fpd.html) for details about passing data server-side.
+
 #### Client-side Caching of VAST XML
 
 When serving video ads, VAST XML creatives must be cached on the network so the

features/firstPartyData.md

@@ -0,0 +1,160 @@
+---
+layout: page_v2
+title: Prebid.js First Party Data
+description: First Party Data - Prebid.js
+sidebarType: 1
+---
+
+# First Party Data - Prebid.js
+{: .no_toc}
+
+* TOC
+{:toc}
+
+Prebid allows publishers to supply attributes related to their content
+and users, and to apply permissions so only certain bidders are allowed
+to access those attributes.
+
+{: .alert.alert-warning :}
+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.
+
+## How It Works
+
+Here's a summary of how first party data (FPD) works:
+
+![First Party Data Summary](/assets/images/flowcharts/FirstPartyData-Summary.png){: .pb-lg-img :}
+
+This diagram shows a page that can provide:
+
+- 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
+
+## 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.
+
+### 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: {
+           keywords: "power tools", // keywords is a standard OpenRTB field
+           search: "drill",         // same with search and content
+           content: { userrating: 4 },
+           data: {
+               pageType: "article",
+               category: "tools"
+           }
+        },
+        user: {
+           keywords: "a,b", // keywords is a standard OpenRTB field
+           data: {
+              registered: true,
+              interests: ["cars"]
+           }
+        }
+    }
+});
+{% endhighlight %}
+
+{: .alert.alert-warning :}
+Note that supplying first party **user** data may require special
+consent in certain regions. Prebid does **not** police the passing
+of user data as part of its GDPR or CCPA modules.
+
+### Supplying AdUnit-Specific Data
+
+If an attribute is specific to an AdUnit, it can be passed this way:
+
+{% highlight js %}
+pbjs.addAdUnits({
+    code: "test-div",
+    mediaTypes: {
+        banner: {
+            sizes: [[300,250]]
+        }
+    },
+    fpd: {
+         context: {
+            pbAdSlot: "homepage-top-rect",
+            adUnitSpecificContextAttribute: "123"
+         }
+    },
+    ...
+});
+{% endhighlight %}
+
+{: .alert.alert-info :}
+Prebid does not support AdUnit-Specific **user** data.
+
+### Supplying Bidder-Specific Data
+
+Use the [`setBidderConfig()`](/dev-docs/publisher-api-reference.html#module_pbjs.setBidderConfig) function to supply bidder-specific data. In this example, only bidderA and bidderB will get access to the supplied
+global data.
+
+{% highlight js %}
+pbjs.setBidderConfig({
+   bidders: ['bidderA', 'bidderB'],
+   config: {
+       fpd: {
+           context: {
+               data: {
+                  pageType: "article",
+                  category: "tools"
+               }
+            },
+            user: {
+               data: {
+                  registered: true,
+                  interests: ["cars"]
+               }
+          }
+      }
+   }
+});
+
+pbjs.setBidderConfig({ // different bidders can receive different data
+   bidders: ['bidderC'],
+   config: {
+     fpd: { ... }
+   }
+});
+{% 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'))
+{% endhighlight %}
+
+AdUnit-specific values must be parsed out of the AdUnit object.
+
+The assumption is that bid adapters will copy the values to the appropriate protocol location for their endpoint.
+
+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
+
+- The [Prebid.js Publisher API](/dev-docs/publisher-api-reference.html)
+- The [AdUnit Reference](/dev-docs/adunit-reference.html)
+- [Prebid Server First Party Data support](/prebid-server/features/pbs-fpd.html)

prebid-server/endpoints/openrtb2/pbs-endpoint-amp.md

@@ -27,7 +27,7 @@ For a more general reference, see the [Prebid AMP Implementation Guide
 | curl | optional | `String` | Added to OpenRTB request as site.page |
 | slot | optional | `String` | Added to OpenRTB request as imp[0].tagid |
 | timeout | optional | `String` | Added to OpenRTB request as tmax |
-| targeting | optional | `String` | First Party Data |
+| targeting | optional | `String` | First Party Data (PBS-Java only) |
 | gdpr_consent | optional | `String` | Consent string passed from CMP. Note this is used for both GDPR and CCPA. |
 | account | optional | `String` | Can be used to pass the Prebid-Server specific account ID. This is useful if `tag_id` parameters aren't unique across accounts. |
 | debug | optional | `integer` | If 1, returns additional debug info. |
@@ -80,6 +80,84 @@ An example Stored Request is given below:
 }
 ```
 
+#### First Party Data
+
+(Currently only supported in PBS-Java)
+
+You can send first party data into an AMP request by encoding a JSON
+targeting block like this:
+
+```
+GET /openrtb2/amp?tag_id=7470-Eater_AMP_ROS_ATF&w=300&h=250&ow=&oh=&ms=&slot=%2F172968584%2Feater%2Fgoogle%2Famp_med_rec_02&targeting=%7B%22site%22%3A%7B%22keywords%22%3A%22article%2C%20las%20vegas%22%2C%22cat%22%3A%7B%22blah%22%3A%221%22%7D%2C%22other-attribute%22%3A%22other-value%22%2C%22ext%22%3A%7B%22data%22%3A%7B%22entry_group%22%3A%5B%22front-page%22%2C%22featured-stories%22%5D%2C%22page_type%22%3A%22AMP%22%7D%7D%7D%2C%22user%22%3A%7B%22gender%22%3A%22m%22%7D%2C%22bidders%22%3A%5B%22rubicon%22%2C%22appnexus%22%5D%2C%22keywords%22%3A%22las%20vegas%20hospitality%20employees%22%2C%22foo%22%3A%7B%22bar%22%3A%22baz%22%7D%7D...
+```
+
+Prebid Server will expand the targeting value and merge the data into
+the resulting OpenRTB JSON for the appropriate bidders.
+
+For example, if this AMP targeting is provided:
+```
+{
+    "site": {
+      "keywords": "article, las vegas", // (1)
+      "cat": { "blah": "1" }, // invalid data type, will be dropped
+      "other-attribute": "other-value", // not openrtb2, remove
+      "ext": {
+        "data": {
+          "entry_group": ["front-page","featured-stories"], // (4)
+          "page_type": "AMP" // (5)
+        } 
+     }
+    },
+    "user": {
+      "gender": "m", // (2)
+    },
+    "bidders": ["rubicon","appnexus"], // (3)
+    "keywords": "las vegas hospitality employees", // (6)
+    "foo": { // (7)
+      "bar": "baz"
+    }
+}
+```
+The numbered elements from the raw targeting data above are merged into the resulting OpenRTB like this:
+```
+{
+  "imp": [...],
+  "site": {
+    "publisher": { … },
+    "keywords": "article, las vegas" // (1)
+    "ext":{
+      "data": {
+        "entry_group": ["front-page","featured-stories"], // (4)
+        "page_type": "AMP" // (5)
+      }
+    }
+  },
+  "user": {
+    "gender": "m" // (2)
+  },
+  "ext": {
+    "prebid": {
+      "data": {
+        "bidders": ["rubicon",appnexus"], // (3)
+      }
+    }
+  },
+  "imp": [
+    ...
+    "ext": {
+       "context": {
+         "data": {
+           "keywords": "las vegas hospitality employees", // (6)
+           "foo": { // (7)
+             "bar": "baz"
+           }
+         }
+       }
+    }
+  ]
+}
+```
+
 ### Response
 
 A sample response payload looks like this:
@@ -198,3 +276,4 @@ Specifically:
 ## Further Reading
 - [Prebid and AMP](/formats/amp.html)
 - [Prebid Server AMP Use Case Overview](/prebid-server/use-cases/pbs-amp.html)
+- [Prebid Server First Party Data](/prebid-server/features/pbs-fpd.html)

prebid-server/features/pbs-feature-idx.md

@@ -35,8 +35,8 @@ title: Prebid Server | Features
 | [Stored Requests](/prebid-server/features/pbs-storedreqs.html) | Core | Accepts a stored request ID in the OpenRTB, looks it up against a local data store, and merges with the OpenRTB request record. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Stored Responses | Stored Responses | Accepts a stored response ID in the OpenRTB, looks it up against a local data store, and merges with the OpenRTB response record. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | First Party Data | Core | Accepts core first party data attributes and supports ext.prebid.data.bidders. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
-| First Party Data | Bidder-specific data | Accepts bidder-specific first party data attributes. | | |
-| First Party Data | AMP first party data | Accepts first party data attributes on an AMP request. | | |
+| First Party Data | Bidder-specific data | Accepts bidder-specific first party data attributes. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
+| First Party Data | AMP first party data | Accepts first party data attributes on an AMP request. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | [Supply Chain](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#supply-chain-support) | Bidder-specific schains | Accepts bidder-specific schain | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Publisher Accounts | Core | Ability to enforce that requests coming in have a valid account ID. | <img src="/assets/images/icons/icon-check-green.png" width="30"> | <img src="/assets/images/icons/icon-check-green.png" width="30"> |
 | Publisher Accounts | AMP account parameter | Accept the account parameter on the AMP request. | | <img src="/assets/images/icons/icon-check-green.png" width="30"> |