Prebid 7: update docs on refererInfo, publisherDomain

dev-docs/bidder-adaptor.md

@@ -275,10 +275,14 @@ Here is a sample bidderRequest object:
   bids: [{...}],
   gdprConsent: {consentString: "BOtmiBKOtmiBKABABAENAFAAAAACeAAA", vendorData: {...}, gdprApplies: true},
   refererInfo: {
-    canonicalUrl: undefined,
+    canonicalUrl: null,
+    page: "http://mypage.org?pbjs_debug=true",
+    domain: "mypage.org",
+    ref: null,
     numIframes: 0,
     reachedTop: true,
-    referer: "http://mypage?pbjs_debug=true"
+    isAmp: false,
+    stack: ["http://mypage.org?pbjs_debug=true"]
   }
 }
 {% endhighlight %}
@@ -303,23 +307,26 @@ There are a number of important values that a publisher expects to be handled in
 | COPPA | If your endpoint supports the Child Online Privacy Protection Act, you should read this value. | config.getConfig('coppa'); |
 | First Party Data | The publisher may provide [first party data](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd) (e.g. page type). | config.getConfig('fpd'); |
 | Floors | Adapters that accept a floor parameter must also support the [floors module](https://docs.prebid.org/dev-docs/modules/floors.html) | [`getFloor()`](/dev-docs/modules/floors.html#bid-adapter-interface) |
-| Page Referrer | Intead of building your own function to find the page referrer, look in the standard bidRequest location. | bidderRequest.refererInfo.referer |
-| Publisher Domain | The page may declare its domain, useful in cross-iframe scenarios. | config.getConfig('publisherDomain') |
+| Page URL and referrer | Instead of building your own function to find the page location, domain, or referrer, look in the standard bidRequest location. | bidderRequest.refererInfo.page |
 | [Supply Chain](/dev-docs/modules/schain.html) | Adapters cannot accept an schain parameter. Rather, they must look for the schain parameter at bidRequest.schain. | bidRequest.schain |
 | Video Parameters | Video params must be read from AdUnit.mediaType.video when available; however bidder config can override the ad unit. | AdUnit.mediaType.video |
 
-#### Referrers
+#### Location and referrers
 
 Referrer information should be passed to your endpoint in contexts where the original page referrer isn't available directly to the adapter. Use the `bidderRequest.refererInfo` property to pass in referrer information. This property contains the following parameters:
 
-- `referer`: a string containing the detected top-level URL.
+- `location`: a string containing the detected top-level URL, or null when the top window is inaccessible.
+- `topmostLocation`: a string containing the URL of the topmost accessible frame.
+- `canonicalUrl`: a string containing the canonical (search engine friendly) URL, as set by the publisher.
+- `page`: the best candidate for the top level URL - or null when the top window is inaccessible. Equivalent to `canonicalUrl` || `location`.
+- `domain`: the domain (hostname and port) portion of `page`.
+- `ref`: referrer to the top window (`window.top.document.referrer`), or null when the top window is inaccessible. 
 - `reachedTop`: a boolean specifying whether Prebid was able to walk up to the top window.
 - `numIframes`: the number of iFrames.
 - `stack`: an array of URLs of all windows from the top window down to the current window.
-- `canonicalUrl`: a string containing the canonical (search engine friendly) URL defined in top-most window.
 - `isAmp`: a boolean specifying whether the detected referer was determined based on AMP page information.
 
-The URL returned by `refererInfo` is in raw format. We recommend encoding the URL before adding it to the request payload to ensure it will be sent and interpreted correctly.
+The URLs returned by `refererInfo` are in raw format. We recommend encoding the URL before adding it to the request payload to ensure it will be sent and interpreted correctly.
 
 #### The output of buildRequests: ServerRequest Objects
 
@@ -584,10 +591,14 @@ Sample data received by this function:
             bids: [{...}],
             gdprConsent: {consentString: "BOtmiBKOtmiBKABABAENAFAAAAACeAAA", vendorData: {...}, gdprApplies: true},
             refererInfo: {
-                canonicalUrl: undefined,
+                canonicalUrl: null,
+                page: "http://mypage.org?pbjs_debug=true",
+                domain: "mypage.org",
+                ref: null,
                 numIframes: 0,
                 reachedTop: true,
-                referer: "http://mypage?pbjs_debug=true"
+                isAmp: false,
+                stack: ["http://mypage.org?pbjs_debug=true"]
             }
         }
     }

dev-docs/bidders/kobler.md

@@ -45,7 +45,7 @@ Please reach out to <[email protected]> for more information.
 ```
 
 In order to see a sample bid from Kobler (without a proper setup), you have to also do the following:
-- Change the [`refererInfo` function](https://github.com/prebid/Prebid.js/blob/master/src/refererDetection.js) to return `'https://www.tv2.no/a/11734615'` as a [`referer`](https://github.com/prebid/Prebid.js/blob/caead3ccccc448e4cd09d074fd9f8833f56fe9b3/src/refererDetection.js#L169). This is necessary because Kobler only bids on recognized articles. 
+- Change the [`refererInfo` function](https://github.com/prebid/Prebid.js/blob/master/src/refererDetection.js) to return `'https://www.tv2.no/a/11734615'` as a `page`. This is necessary because Kobler only bids on recognized articles. 
 - Change the adapter's [`BIDDER_ENDPOINT`](https://github.com/prebid/Prebid.js/blob/master/modules/koblerBidAdapter.js#L8) to `'https://bid-service.dev.essrtb.com/bid/prebid_rtb_call'`. This endpoint belongs to the development server that is set up to always return a bid for the correct `placementId` and page URL combination. 
 
 ### Example With Optional Parameters

dev-docs/modules/enrichmentFpdModule.md

@@ -45,9 +45,9 @@ pbjs.refreshFpd();
 {: .table .table-bordered .table-striped }
 | Page Source | ortb2 field | Notes |
 |---+---+---|
-| page URL | site.page | Uses pbjs getRefererInfo().canonicalUrl |
-| referer URL | site.ref | Uses pbjs getRefererInfo().referer |
-| host domain | site.domain | Pulled from the getRefererInfo().canonicalUrl the host domain is used with the www component dropped. |
+| page URL | site.page | Uses pbjs getRefererInfo().page |
+| referer URL | site.ref | Uses pbjs getRefererInfo().ref |
+| host domain | site.domain | Pulled from the getRefererInfo().page the host domain is used with the www component dropped. |
 | aggregated domain | site.publisher.domain | The highest level domain in which cookies can be set. |
 | viewport width | device.w | Hunts for window.innerWidth, window.document.documentElement.clientWidth, window.document.body.clientWidth |
 | viewport height | device.w | Hunts for window.innerHeight, window.document.documentElement.clientHeight, window.document.body.clientHeight |

dev-docs/plugins/bc/bc-prebid-plugin-prebid-options.md

@@ -305,7 +305,7 @@ None
 
 **Example:**
 
-`options.prebidConfigOptions = { publisherDomain: "https://www.theverge.com"};`
+`options.prebidConfigOptions = { pageUrl: "https://www.theverge.com"};`
 
 <a name="dfpParameters"></a>
 ### dfpParameters

dev-docs/plugins/cross-player-prebid-component/cross-player-config.md

@@ -193,7 +193,7 @@ None
 
 **Example:**
 
-`options.prebidConfigOptions = { publisherDomain: "https://www.mydomain.com"};`
+`options.prebidConfigOptions = { pageUrl: "https://www.mydomain.com"};`
 
 <a name="dfpParameters"></a>
 ## dfpParameters

dev-docs/publisher-api-reference/setConfig.md

@@ -24,7 +24,6 @@ Core config:
 + [Bid cache](#setConfig-Use-Bid-Cache)
 + [Set the order in which bidders are called](#setConfig-Bidder-Order)
 + [Set the page URL](#setConfig-Page-URL)
-+ [Set the publisher's domain](#setConfig-Publisher-Domain)
 + [Set price granularity](#setConfig-Price-Granularity)
 + [Set media type price granularity](#setConfig-MediaType-Price-Granularity)
 + [Configure server-to-server header bidding](#setConfig-Server-to-Server)
@@ -280,18 +279,6 @@ Override the Prebid.js page referrer for some bidders.
 pbjs.setConfig({ pageUrl: "https://example.com/index.html" })
 {% endhighlight %}
 
-<a name="setConfig-Publisher-Domain" />
-
-#### Publisher Domain
-
-{: .alert.alert-warning :}
-This API is deprecated. Please use 'pageUrl' instead.
-
-Set the publisher's domain where Prebid is running, for cross-domain iframe communication:
-
-{% highlight js %}
-pbjs.setConfig({ publisherDomain: "https://www.theverge.com" )
-{% endhighlight %}
 
 <a name="setConfig-Price-Granularity" />