From bb84d001a74cdd1518bfd602fbf18f052f15a832 Mon Sep 17 00:00:00 2001 From: bretg Date: Tue, 25 Aug 2020 12:43:06 -0400 Subject: [PATCH] moving docs to website repo (#1443) --- README.md | 14 +- docs/bidders/adtarget.md | 5 - docs/bidders/appnexus.md | 45 - docs/bidders/audienceNetwork.md | 8 - docs/bidders/avocet.md | 5 - docs/bidders/beachfront.md | 13 - docs/bidders/emx_digital.md | 10 - docs/bidders/kidoz.md | 9 - docs/bidders/openx.md | 65 -- docs/bidders/pubmatic.md | 33 - docs/bidders/pubnative.md | 62 -- docs/bidders/rubicon.md | 7 - docs/bidders/smaato.md | 42 - docs/bidders/smartAdserver.md | 59 -- docs/bidders/smartrtb.md | 39 - docs/bidders/sovrn.md | 3 - docs/bidders/tappx.md | 13 - ...Server Event Notifications - Tech Spec.pdf | Bin 89983 -> 0 bytes docs/developers/add-new-analytics-module.md | 33 - docs/developers/add-new-bidder.md | 117 --- docs/developers/cookie-syncs.md | 30 - docs/developers/currency-converter.md | 56 -- docs/developers/default-request.md | 44 - docs/developers/features.md | 12 + docs/developers/gdpr.md | 31 - docs/developers/stored-requests.md | 4 +- docs/endpoints.md | 1 + docs/endpoints/bidders/params.md | 24 - docs/endpoints/cookieSync.md | 55 -- docs/endpoints/currency_rates.md | 111 --- docs/endpoints/info/bidders.md | 23 - docs/endpoints/info/bidders/bidderName.md | 43 - docs/endpoints/openrtb2/amp.md | 127 --- docs/endpoints/openrtb2/auction.md | 789 ------------------ docs/endpoints/setuid.md | 26 - docs/endpoints/status.md | 9 - 36 files changed, 22 insertions(+), 1945 deletions(-) delete mode 100644 docs/bidders/adtarget.md delete mode 100644 docs/bidders/appnexus.md delete mode 100644 docs/bidders/audienceNetwork.md delete mode 100644 docs/bidders/avocet.md delete mode 100644 docs/bidders/beachfront.md delete mode 100644 docs/bidders/emx_digital.md delete mode 100644 docs/bidders/kidoz.md delete mode 100644 docs/bidders/openx.md delete mode 100644 docs/bidders/pubmatic.md delete mode 100644 docs/bidders/pubnative.md delete mode 100644 docs/bidders/rubicon.md delete mode 100644 docs/bidders/smaato.md delete mode 100644 docs/bidders/smartAdserver.md delete mode 100644 docs/bidders/smartrtb.md delete mode 100644 docs/bidders/sovrn.md delete mode 100644 docs/bidders/tappx.md delete mode 100644 docs/developers/Prebid Server Event Notifications - Tech Spec.pdf delete mode 100644 docs/developers/add-new-analytics-module.md delete mode 100644 docs/developers/add-new-bidder.md delete mode 100644 docs/developers/cookie-syncs.md delete mode 100644 docs/developers/currency-converter.md delete mode 100644 docs/developers/default-request.md create mode 100644 docs/developers/features.md delete mode 100644 docs/developers/gdpr.md create mode 100644 docs/endpoints.md delete mode 100644 docs/endpoints/bidders/params.md delete mode 100644 docs/endpoints/cookieSync.md delete mode 100644 docs/endpoints/currency_rates.md delete mode 100644 docs/endpoints/info/bidders.md delete mode 100644 docs/endpoints/info/bidders/bidderName.md delete mode 100644 docs/endpoints/openrtb2/amp.md delete mode 100644 docs/endpoints/openrtb2/auction.md delete mode 100644 docs/endpoints/setuid.md delete mode 100644 docs/endpoints/status.md diff --git a/README.md b/README.md index b69e7e76db4..673c2b1bdeb 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ It is managed by [Prebid.org](http://prebid.org/overview/what-is-prebid-org.html and upholds the principles from the [Prebid Code of Conduct](http://prebid.org/wrapper_code_of_conduct.html). This project does not support the same set of Bidders as Prebid.js, although there is overlap. -The current set can be found in the [adapters](./adapters) package. If you don't see the one you want, feel free to [contribute it](docs/developers/add-new-bidder.md). +The current set can be found in the [adapters](./adapters) package. If you don't see the one you want, feel free to [contribute it](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html). For more information, see: -- [What is Prebid?](http://prebid.org/overview/intro.html) -- [Getting started with Prebid Server](http://prebid.org/dev-docs/get-started-with-prebid-server.html) -- [Current Bidders](http://prebid.org/dev-docs/prebid-server-bidders.html) +- [What is Prebid?](https://prebid.org/overview/intro.html) +- [Prebid Server Overview](https://docs.prebid.org/prebid-server/overview/prebid-server-overview.html) +- [Current Bidders](http://prebid.org/dev-docs/pbs-bidders.html) ## Installation @@ -45,14 +45,12 @@ go build . ``` Load the landing page in your browser at `http://localhost:8000/`. -For the full API reference, see [docs/endpoints](docs/endpoints) +For the full API reference, see [the endpoint documentation](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html) ## Contributing -Want to [add an adapter](docs/developers/add-new-bidder.md)? Found a bug? Great! -This project is in its infancy, and many things can be improved. - +Want to [add an adapter](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html)? Found a bug? Great! Report bugs, request features, and suggest improvements [on Github](https://github.com/prebid/prebid-server/issues). diff --git a/docs/bidders/adtarget.md b/docs/bidders/adtarget.md deleted file mode 100644 index b658a728a2b..00000000000 --- a/docs/bidders/adtarget.md +++ /dev/null @@ -1,5 +0,0 @@ -# Adtarget bidder - -To use the Adtarget bidder you will need an aid from an exchange account on [https://console.adtarget.com.tr](adtarget.com.tr). - -For further information, please contact kamil@adtarget.com.tr \ No newline at end of file diff --git a/docs/bidders/appnexus.md b/docs/bidders/appnexus.md deleted file mode 100644 index e4032313f25..00000000000 --- a/docs/bidders/appnexus.md +++ /dev/null @@ -1,45 +0,0 @@ -# Appnexus Bidder - -## Using Keywords - -The `keywords` [bidder param](../../static/bidder-params/appnexus.json) will only work if -it's enabled for your Account with Appnexus. - -**This permission is _distinct_ from the keywords feature used by Prebid.js.** - -If you want to enable Appnexus keywords, contact your account manager. - -## Display Manager Version - -The AppNexus endpoint expects `imp.displaymanagerver` to be populated for mobile app sources -requests, however not all SDKs will populate this field. If the `imp.displaymanagerver` field -is not supplied for an `imp`, but `request.app.ext.prebid.source` -and `request.app.ext.prebid.version` are supplied, the adapter will fill in a value for -`diplaymanagerver`. It will concatenate the two `app` fields as `-` fo fill in -the empty `displaymanagerver` before sending the request to AppNexus. - -## Test Request - -The following test parameters can be used to verify that Prebid Server is working properly with the -Appnexus adapter. This example includes an `imp` object with an Appnexus test placement ID and sizes -that would match with the test creative. - -``` - "imp": [{ - "id": "some-impression-id", - "banner": { - "format": [{ - "w": 600, - "h": 500 - }, { - "w": 300, - "h": 600 - }] - }, - "ext": { - "appnexus": { - "placementId": 13144370 - } - } - }] -``` \ No newline at end of file diff --git a/docs/bidders/audienceNetwork.md b/docs/bidders/audienceNetwork.md deleted file mode 100644 index d55e8218a81..00000000000 --- a/docs/bidders/audienceNetwork.md +++ /dev/null @@ -1,8 +0,0 @@ -# Audience Network Bidder - -## Mobile Bids - -Audience Network will not bid on requests made from device simulators. -When testing for Mobile bids, you must make bid requests using a real device. - -**Note:** Audience Network is disabled by default. Please enable it in the app config if you wish to use it. Make sure you provide the partnerID for the auctions to run correctly. \ No newline at end of file diff --git a/docs/bidders/avocet.md b/docs/bidders/avocet.md deleted file mode 100644 index 6aa67391af4..00000000000 --- a/docs/bidders/avocet.md +++ /dev/null @@ -1,5 +0,0 @@ -# Avocet Bidder - -Please contact Avocet at info@avocet.io if you would like to get started selling inventory via the Avocet platform. - -**Note:** Avocet is disabled by default. Please enable it in the app config if you wish to use it. This can be done by setting `adapters.avocet.disabled` to `false` and by setting `adapters.avocet.endpoint` to a valid Avocet endpoint url. \ No newline at end of file diff --git a/docs/bidders/beachfront.md b/docs/bidders/beachfront.md deleted file mode 100644 index ecd7a8f95d1..00000000000 --- a/docs/bidders/beachfront.md +++ /dev/null @@ -1,13 +0,0 @@ -# Beachfront bidder - -To use the beachfront bidder you will need an appId (Exchange Id) from an exchange -account on [platform.beachfront.io](https://platform.beachfront.io). - -For further information, please contact adops@beachfront.com. - -As seen in the JSON response from \{your PBS server\}\/bidder\/params [(example)](https://prebid.adnxs.com/pbs/v1/bidders/params), the beachfront bidder can take either an "appId" parameter, or an "appIds" parameter. If the request is for one media type, the appId parameter should be used with the value of the Exchange Id on the Beachfront platform. - -The appIds parameter is for requesting a mix of banner and video. It has two parameters, "banner", and "video" for the appIds of two appropriately configured exchanges on the platform. The appIds parameter can be sent with just one of its two parameters and it will behave like the appId parameter. - -If the request includes an appId configured for a video response, the videoResponseType parameter can be defined as "nurl", "adm" or "both". These will apply to all video returned. If it is not defined, the response type will be a nurl. The definitions for "nurl" vs. "adm" are here: (https://github.com/mxmCherry/openrtb/blob/master/openrtb2/bid.go). - diff --git a/docs/bidders/emx_digital.md b/docs/bidders/emx_digital.md deleted file mode 100644 index 0ba81d59fea..00000000000 --- a/docs/bidders/emx_digital.md +++ /dev/null @@ -1,10 +0,0 @@ -# EMX Digital Bidder - -[EMX Digital](https://emxdigital.com/) supports the following parameters to be present in the `ext` object of impression requests: - -- "tagid" type string - Required. Unique inventory ID. -- "bidfloor" type string - Optional. The minimum acceptable bid for the unit, in CPM and USD. - -To use this bidder you will need an account and a valid tagid from our exchange. - -For further information, please contact your Account Manager or adops@emxdigital.com. diff --git a/docs/bidders/kidoz.md b/docs/bidders/kidoz.md deleted file mode 100644 index 433dd71c2ca..00000000000 --- a/docs/bidders/kidoz.md +++ /dev/null @@ -1,9 +0,0 @@ -# Kidoz Bidder - -Kidoz is exclusively for Mobile app COPPA compatible ads, 100% kid relevant and appropriate. - -In order for a company to receive bids from Kidoz, they must first open a publisher account at Kidoz.net -(https://accounts.kidoz.net/publishers/register) and accept the Kidoz Terms and Conditions and Privacy Policy. -Kidoz publishers must confirm that all of their content properties are COPPA and GDPR compliant and perform no monitoring -or tracking of U13 users in their operations. New publishers are provided a Publisher ID and AccessToken, this can also -be used to login to their dashboard at the Kidoz.net portal to monitor their account activity. diff --git a/docs/bidders/openx.md b/docs/bidders/openx.md deleted file mode 100644 index 54a0a5b1e72..00000000000 --- a/docs/bidders/openx.md +++ /dev/null @@ -1,65 +0,0 @@ -# OpenX Bidder - -OpenX supports the following parameters: - -| property | type | required? | description | example | -|----------|------|-----------|-------------|---------| -| unit | string | required | The ad unit id | "10092842" | -| delDomain | string | required\* | The delivery domain for the customer | "sademo-d.openx.net" | -| platform | uuid | required\* | The platform id for the customer | "a3aece0c-9e80-4316-8deb-faf804779bd1" | -| customFloor | number | optional | The minimum CPM price in USD | 1.50 - sets a $1.50 floor | -| customParams | object | optional | User-defined targeting key-value pairs | {key1: "v1", key2: ["v2","v3"]} | - -\* At least one of `delDomain` or `platform` parameters is required. - -If you have any questions regarding setting up, please reach out to your account manager or - - -## Test Request - -### App Impression Object -``` -{ - "id": "test-impression-id", - "banner": { - "format": [ - { - "w": 480, - "h": 300 - }, - { - "w": 480, - "h": 320 - } - ] - }, - "ext": { - "openx": { - "delDomain": "mobile-d.openx.net", - "unit": "541028953" - } - } -} -``` - - -### Web -``` -{ - "id": "div1", - "banner": { - "format": [ - { - "w": 728, - "h": 90 - } - ] - }, - "ext": { - "openx": { - "unit": "540949380", - "delDomain": "sademo-d.openx.net" - }, - } -} -``` diff --git a/docs/bidders/pubmatic.md b/docs/bidders/pubmatic.md deleted file mode 100644 index 610108b2e07..00000000000 --- a/docs/bidders/pubmatic.md +++ /dev/null @@ -1,33 +0,0 @@ -# PubMatic Bidder - -## Test Request - -The following test parameters can be used to verify that Prebid Server is working properly with the -PubMatic adapter. This example includes an `imp` object with an PubMatic test publisher ID, ad slot, -and sizes that would match with the test creative. - -``` -"imp":[ - { - "id":“"some-impression-id”, - "banner":{ - "format":[ - { - "w":300, - "h":250 - }, - { - "w":300, - "h":600 - } - ] - }, - "ext":{ - "pubmatic":{ - "publisherId":“156276”, - "adSlot":"pubmatic_test" - } - } - } - ] -``` \ No newline at end of file diff --git a/docs/bidders/pubnative.md b/docs/bidders/pubnative.md deleted file mode 100644 index a25cafe0cd5..00000000000 --- a/docs/bidders/pubnative.md +++ /dev/null @@ -1,62 +0,0 @@ -# Pubnative Bidder - -## Prerequisite -Before adding PubNative as a new bidder, there are 3 prerequisites: -- As a Publisher, you need to have Prebid Mobile SDK integrated. -- You need a configured Prebid Server (either self-hosted or hosted by 3rd party). -- You need to be integrated with Ad Server SDK (e.g. Mopub) or internal product which communicates with Prebid Mobile SDK. - -Please see [documentation](https://developers.pubnative.net/docs/prebid-adding-pubnative-as-a-bidder) for more info. - -## Configuration - -- bidder should be always set to "pubnative" (`imp.ext.pubnative`) -- zone_id (int) should be always set to 1, unless special use case agreed with our account manager. (`imp.ext.pubnative.zone_id`) -- app_auth_token (string) is unique per publisher app. Please contact our account manager to obtain yours. (`imp.ext.pubnative.app_auth_token`) - -An example is illustrated in a section below. - -## Testing - -Please consult with our Account Manager for testing. -We need to confirm that your ad request is correctly received by our system. - -The following test parameters can be used to verify that Prebid Server is working properly with the -Pubnative adapter. - -The following json can be used to do a request to prebid server for verifying its integration with Pubnative adapter. - -```json -{ - "id": "some-impression-id", - "site": { - "page": "https://good.site/url" - }, - "imp": [ - { - "id": "test-imp-id", - "banner": { - "format": [ - { - "w": 300, - "h": 250 - } - ] - }, - "ext": { - "pubnative": { - "zone_id": 1, - "app_auth_token": "b620e282f3c74787beedda34336a4821" - } - } - } - ], - "device": { - "os": "android", - "h": 700, - "w": 375 - }, - "tmax": 500, - "test": 1 -} -``` \ No newline at end of file diff --git a/docs/bidders/rubicon.md b/docs/bidders/rubicon.md deleted file mode 100644 index ea376da427d..00000000000 --- a/docs/bidders/rubicon.md +++ /dev/null @@ -1,7 +0,0 @@ -# Rubicon Bidder - -Please contact your Rubicon Project account manager or globalsupport@rubiconproject.com to get set up with a login and cookie-sync URL to run your own Prebid Server. You will be given instructions, including the available endpoints. - -**Note:** Rubicon is disabled by default. Please enable it in the app config if you wish to use it. Make sure you provide the correct cookie-sync URL in order for cookie-syncs to work properly. - -[Rubicon Project Prebid.js test parameters](https://github.com/prebid/Prebid.js/blob/master/modules/rubiconBidAdapter.md) will work for server as well. diff --git a/docs/bidders/smaato.md b/docs/bidders/smaato.md deleted file mode 100644 index 881f8f2ab54..00000000000 --- a/docs/bidders/smaato.md +++ /dev/null @@ -1,42 +0,0 @@ - -# Smaato Bidder - -``` -Module Name: Smaato Bidder Adapter -Module Type: Bidder Adapter -Maintainer: prebid@smaato.com -``` - -### Description - -Please contact Smaato Support or prebid@smaato.com to get set up with a publisherId and adspaceId. - -### Test Parameters: - -Following example includes sample `imp` object with publisherId and adSlot which can be used to test Smaato Adapter - -``` -"imp":[ - { - "id":“1C86242D-9535-47D6-9576-7B1FE87F282C, - "banner":{ - "format":[ - { - "w":300, - "h":50 - }, - { - "w":300, - "h":250 - } - ] - }, - "ext":{ - "smaato":{ - "publisherId":"100042525", - "adspaceId":"130563103" - } - } - } - ] -``` diff --git a/docs/bidders/smartAdserver.md b/docs/bidders/smartAdserver.md deleted file mode 100644 index 4d2663f8a3b..00000000000 --- a/docs/bidders/smartAdserver.md +++ /dev/null @@ -1,59 +0,0 @@ -# Smart Adserver Bidder - -## Parameters -The `ext.smartadserver` object of impression bid requests supports the following parameters : -- "networkId" - Required. The network identifier you have been provided with. -- "siteId" - Optional. The site identifier from your campaign configuration. -- "pageId" - Optional. The page identifier from your campaign configuration. -- "formatId" - Optional. The format identifier from your campaign configuration. - -The network identifier is provided by your Account Manager. -**Note:** The site, page and format identifiers have to all be provided or all empty. - -## Examples - -Without site/page/format : -``` - "imp": [{ - "id": "some-impression-id", - "banner": { - "format": [{ - "w": 600, - "h": 500 - }, { - "w": 300, - "h": 600 - }] - }, - "ext": { - "smartadserver": { - "networkId": 73 - } - } - }] -``` - -With site/page/format : - -``` - "imp": [{ - "id": "some-impression-id", - "banner": { - "format": [{ - "w": 600, - "h": 500 - }, { - "w": 300, - "h": 600 - }] - }, - "ext": { - "smartadserver": { - "networkId": 73 - "siteId": 1, - "pageId": 2, - "formatId": 3 - } - } - }] -``` \ No newline at end of file diff --git a/docs/bidders/smartrtb.md b/docs/bidders/smartrtb.md deleted file mode 100644 index ffa88f663e8..00000000000 --- a/docs/bidders/smartrtb.md +++ /dev/null @@ -1,39 +0,0 @@ -# SmartRTB Bidder - -[SmartRTB](https://smrtb.com/) supports the following parameters to be present in the `ext` object of impression requests: - -- "pub_id" type string - Required. Publisher ID assigned to you. -- "zone_id" type string - Optional. Enables mapping for further settings and reporting in the Marketplace UI. -- "force_bid" type bool - Optional. If zone ID is mapped, this may be set to always return fake sample bids (banner, video) - -Please contact us to create a new Smart RTB Marketplace account, and for any assistance in configuration. -You may email info@smrtb.com for inquiries. - -## Test Request - -This sample request is our global test placement and should always return a branded banner bid. - -``` - { - "id": "abc", - "site": { - "page": "prebid.org" - }, - "imp": [{ - "id": "test", - "banner": { - "format": [{ - "w": 300, - "h": 250 - }] - }, - "ext": { - "smartrtb": { - "pub_id": "test", - "zone_id": "N4zTDq3PPEHBIODv7cXK", - "force_bid": true - } - } - }] - } -``` diff --git a/docs/bidders/sovrn.md b/docs/bidders/sovrn.md deleted file mode 100644 index bc6d42333e8..00000000000 --- a/docs/bidders/sovrn.md +++ /dev/null @@ -1,3 +0,0 @@ -Sovrn supports 2 parameters to be present in the `ext` object of impressions sent to it: -- tagid: a string containing the sovrn-specific id(s) for the publisher's ad tag(s) they would like to bid with. This is a required field -- bidfloor: The minimum acceptable bid, in CPM, using US Dollars. This is an optional field. \ No newline at end of file diff --git a/docs/bidders/tappx.md b/docs/bidders/tappx.md deleted file mode 100644 index f92e1cd4fe8..00000000000 --- a/docs/bidders/tappx.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tappx Bidder - -## Parameters -Please contact [Tappx](../../static/bidder-info/tappx.yaml) to get set up. Our operations team will provide the 3 required parameters: -- Tappx Key -- Tappx Publisher Endpoint -- Tappx Host URL - -**Note:** The Tappx prebid bidder only supports in app traffic at the moment - -As for test parameters, use the official test parameter specified in the oRTB standard (https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#object_request) - -For any additional information contact tappx@tappx.com diff --git a/docs/developers/Prebid Server Event Notifications - Tech Spec.pdf b/docs/developers/Prebid Server Event Notifications - Tech Spec.pdf deleted file mode 100644 index c0bcca753fdf8810619f620f2e24dff43fe346e4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 89983 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%0DCsRI^6cmj=zGAiQ^ZNlW+!;qMkYS zIOyPzwaYjsPWpmBc98v^rAwYtmVxRN^YH`k8J7f4c*VR>>&kXgiy(Q1m!9B6GI38` z%jD%9oAL-Ig(Zx<6a`7ccC4xR7pK1x(6y+MmkP1f{(v+m^x_`Jn32$QaiyQf3Q4P~ zD{^pc#k7pLzli~7^3H?an)xfry%KI9wbqz*s;(V`_9P*nz+foE4JR8hpKLeG@SMG~ z|6l`(Fe+P!H=-Xd65HHR;XU6BmjHb58T&zN)1^<-yAQ;DVJnu^;o)@5ZkQZo%@Jia z%59D~XYYo1ohL*-a$Kc2;TW2sL{vKhrqS^l;+{H?Mkw&GF@&8Lwds*OMs0h{GYc*v zdJoFE@bNDNsHFQJ<4Kx&^xDC!a6|dz`sfgRe6vt3!!uTlE+y0~v!ZSt3HBKTag-Pe zSf^VdNLr!WoVzZG1u5dLky_R{q+h~X_BcaUBrOi>lg!Os37fNB;nsp2htAKK_c6y#ob&>Hl# z`m?K2&L?WFBlpGLB<~bQn|omE;Fs{Ma+$YSknn`PciV^R8TVf#)xJSPJTBzbZ{H6z ziDE_rl;5Vi%`5MU{xa@0LzGIIIq2&5GyzhuPY0bxF!>Rx6wI5Xs6+M`;8dRjNO%y? z^gs;0Y1&=tIqF-|VZdsHhFJ|miS1!Ez=0{P-M|im0CrW5huL(Y9uygdd6A1P7~c%B zdVX1y^a9Zfzc%dXhbiM5B+}|+r@PK%gt<@L4a?DMT84PdgRe?b?bT2xnCF18>~?66 z{CK@?)8qTQUy~E`Cf{{fV3i)j3PJL6MNp2yy7#~x=!{3GL=?j+)TkE5jZ3BN!G+#j zch~v}nbAFEEc{5ls*f+r4WmpA7H(vykCaSl*(JTA#9A9^qMYWFb2Vf>Wi9=@``GIpk!m*(}&^( z9jU`n@4KOcNe7y@e`;fD-rnv_XQj-^(s$v$Hh`S-5#SpIkCxelech_^U*(sw=G zUYlQbwQMFE?4rL6yl0(m?+o}hgLx2Ie?w*oJohp$2hjRYgtFYDHlqFM?K1+!PF0@H z))KA^*P~jenz;zYKi|E^y2Jd-5;7Oc;d27w z&puF(fi#A6#kRNs&AZt3vkT3DdOdp!E(v#EqttJ2@^SbG7nd$%Bj8;)mzwq^`-}%5*s(-0&4goxSKDXL&>oK785S zCwqXqOw$wCPTj)|dM&hEdVS8}m&EP5gWG_ep_q54D)jA{;*Z@vtA`U1E3I}(*ilEr z=vfzXJ0IRq#bmj?hda{DzA(zC%Mx@>9o>P96p7o4Lj#Xyr}ib5W2Q2OYy}*&2oNIR z6Eh7X-=eDjDj&f@&L_Rsb`SI>MHE0x^jCG2Dn&+zwg^H<3wAODT?RZddqj71>lkpY z@II2h39M6f(tJ|rB$yf1F{V@oRhC#*T4q*iJ*HY#TeewtSQc1joP(}Ft>jE{O!95G zw+vi34*mVOG`VziN&Xx3w|irBW0Gf+r>|r4que7x>|WTdGTSv~Yi@jQjcNL>^0yFo zRLa2Fp7c$!t4BK(FC{PO=jLfPQ}B;6W(LT71!n4>{C`(H^FtwP0CBitJw394l_Iu6 z;O#GAfUWJVS?#Usu91nQhTLoYEGabyRqCD2SycKu^-}uH?Q)*uTv>WKVyFRBZz-97 zPb(d(?JU;ituxl5GJlCq8vnT?&cq4G^nl`MIbofAxLv;d-}6(| zKJDI)Ug+H|ML=7bP+JRpd=NM1OHVmDUY}DnY?(RXZA(a|s#B_2KKExMM}wIj&z=`8 zWk(n}Yqr)aE5^T+w{I;Jo%97wq za3uSbI>)-hvVTpP7eux`SkZpdUtz~e1U$ke?fXtdC_<=zt`m()(C6mLJPLvAmwP` zE6LpoveW!5*RvXj>D%V>41AlOeLqVd2*qF^`V;eDWGo)Ct}zBqBpP^g#aqb*afUUr z@sx9DCnn2hVb7FxO`uu+X(gSqRu9ttqd`BK9x=Jcg&qUF55yIiwbvaMsXVr-VcV<~ z+9yQh8h1QI$QHc1JE9iKJ3w~_yE1_08owP>Qy&sGsE8gmy4ThfBf2}}n%5I(Xxjr5 zn4r(@8B!-8?iz+0DyN71nsW3M;TnY-*ier-GRTgi1ECii6XAd!m`o5%Dp-PIPH_jB zJ8<@co*N`4KeG$oLLZzPJc%B~J1|F|PF*ycI1w@s3F$O9o0^vtwIbl$ zOJM7-6bEL6u_FB#yCeZOgN(QG%RDR_Gc+!Bo7+=5KQ!%}_$@3*ZA9=E+${kY05PJu zk60IHx(vQR61+UJwoe~M3Xd$7xo@+N_l#oQ&2~*=hs1Uh>v~J;7K2MDHuAO)+L%Uw zOeX>0-6bCy5!*Msg?dT!3`P(3foEXT(06Wgj`v9G5rd~Mw(@ok>Ky4c9NiGJJamroNck3-rANMUbX?SFRI+U5 z9PBkPS?_Sp{g&?4*J+HgEb@r=maT2TS4*%Wd;Z%w?W4E4w&MKiT=fy>@1QsNRy@o( z=NrUZz{iMnE$1>kmnqsv@J21f=HSMR%raQWj-4yaVIIvX**)qX7@k00LEXF@IqG|4 z_r9xr5BFFe@Hc%hEzt>2tZbs7+Q3FK#o>fwx@FvQ5i7{|!?KdRFK*4yhUpj#_3D!< zwPGvg&B0Y7vLEr&TEj@*D9`xv;M32!sdC)YT;uR6&{BybXp%`91q&x|qKb(t22CPE z%Z7M%GAU~)SJKxnC>bQAC55b3$;sJqX-OO0+hZs*qb&>J1s?huPcWAm7tgYMzu^5uCN3>1zi7W3X; zH;NVWy)H+Nro~L9^ZdSSf00$9QEN55i7%4neYj_uqV=$T2~V1;ao-tOuvo12F#8y* zY5$|YS3J?1TvcOLvDs;ORK4M$Q?sJ^*X9ey2A}mti#i_8B010mYW^_}?n zIYE|>%kK7$u9Ms8bzJrL)J7EE)nK%X;n3f@y^ZA?>vLB&=XM;f%_zLD-*tw$PG|i3 z6&}zU&BIe;R@qreX>r+$m1gFW_6iBYU35J-S9X6h?V{B@q#7s88N|{e!8>Fsx}G*YGH%;l=+R+2i*hShqeL!jY!okO6VlskY_PhMi7!pD zAX{M9EhS(tK`2bqPib%eRKzsh{jm`L!XHT0nV;0$t?r~Q`YU--q@WRD76ZZ68j&y7 zxNkv3jT2(sW3=K^q zQ@(m>rK*ItXEpR&j^;TW9HHWJv!Jz9yK+czmbodt5$_aF0dA9Z;T5$Esxc|JEV-#F z`Bz`7*j-chBM)74R!YVe6#Cj zRa2dyvi!X%+mwp(goA3$iM*#pRS3Z^$!px@l-Jc1<))!L3?dY+C;L59M;Qq_mb3t& zKQBqw70|j{wl+v~lsJ3UD(-8pV#-mJeMNPu%0g2iJY46G-J8>HwHR#`?ie0C3qf_8 z@jVx~YZGz{cRN`Oz%Jt#EYgZCIFb5;)=MYEP*IPI{nr^z3X=#$~>^DMvhJOR_aN4V01?x6(R(Kp~_taR&;kd zpD&N`J#olsQ`cPABq<3Q`N0oSC#Q*tr~5{v#xc9Ln{Yw~F8lzRqQdm#oAiJvmSo=c;`+KnlP5+x z$y-{prQc;L&o-aOaEqn+@-*dP4}3}p2um)P2N&xFK6QUf%c*XTu~ zt7uOV{yarbGjWPYT)U&O8QWszkxueOG4Wn)bNMR&xnSi)VZH;*B?>9YeNX$?x~3vT zFfT>$IUfjrXqVWp0ugI$Qj#TT5x z8BLIEW5e(mY!)cRVP*Q}x5g^=<+CREmR1APAH+X`pj=7r>5rj+F)ER$<)U)^sTGhB zrMOVu(<%@kVd-%ZA%lymrv?1Zr?HtdD@;RmfKghH>F(`YgLO8`m`tjzH^RI@*AO8P zK|a8{bmwaH!Fgh^bB7EG4On)8cG-8K1x2U!o^ZXVW*e4IslMYT4Pi5*Vb!?4AO@?7=b4C@~(MpfbgKRGEu8ytbD#k0N174U(N(5#;7&@m`~e z%DkNOXQmNlp{|V+8M`X8EE&E4^B)5}ynP8i;MT$}!dM0%g2818shm(rp+%uAq2__G zZ<+nP{ScuEvC)u#Kg6i_1$gXIa6FxTTZ0R$l6-|%{%~pTk)7l-2*+H=UOAuA z`C_r0ari}7=eB=xo3PJ--!NmbV~h1W#J5({^z4H)a87`YVqjv-LIs7{`T_mOfsy#R zH(bGOQm*k{wo1Uu_7LxY8CAV35D-HxU?0sy1~$HD&Gi6E?n>vH$2ni073lHX0G}Jh z)Ln?L^Pqp~#ij<;;zv;xP5?{P-Wv8_5$0!U>}Vh4xfsm4GB~g%jc=sKQxkdr+47h62N6;c$}r29_nN z!l%a3`8`~oVR?k`CWwVkAp96&K?PdhsP&tjK?WI_Jr^>J;JXP8qi7p1Ixifq&Zx0# z)=VLKt=ty*$j!lo_9*h{y*fk&NIOJ3FeJg@S|@H9&oIaNJq9@WP|UzozgGWPiMcla zTzX!{0jt^mS)zo?L5F**_rbj-As#>WfWBCRR#mlKfIIogAuNX(t=bFimXQ*sT}$&3 z!7ATp9+z4FbKFX~m9G=KjO^{#**EkS(o;A>M+p|mQ5ZoN=R(V+S_mG2Qoe)Ns+(*Fb}{k$ zN|=Ejh#!1UDr0iI+$iRx zD{_e9o^Rk}D{^RRfBP6%gHqS>FIsT)h7-6_6%uSWm7zvZegYvJ|9d9kK|6SX>#MVEf1+=9X%esYeeKO>u zP8)=LS*Gkq&irJFlH>*E&PB5-32M_?b}XQ&t}Rc{Tv6X)YxS@cVeQ#d0mp(AH)$2O zN#&Mxp{kG!9)i`5vyiMG9=&yK6VRPF*K_)9s47Fdw8f}Yn@iNG|dbdn= z;PZ;LNk$rUZmG`b2($%}=oS%7JX($+g@vZA&C!3c$=gU$FL0d#hs7B_*V9+=tG#bc z8R4PX!N!JTTUQBTdx56oqPfpEe{*0B;zw}H+6?1#{V-Rn_Q)jsMuUS5&RJN7p|Q&s z2Km{fZ1Tj=Y3v(axr3V%1g{D$0aZ%O0^zg(HVg^Yl}@`hu$3hJdE&85xk_Gp@_@VK zsu~=MhD7h$EXs$PCCwh)V;KYV(sr~=#I~}uCY#kng%Q83g0JFHPyhkW@oenAWl{Cr&BHMP`gX# zHr!uh&!oyNrqqfR5%lY@7_5E0=`DbR&D4?vtC>h-4bL1 zB4KhD=j$2yl*f2s=x3uD6v9mMB?ZLyypSPf?P#eepONFZTf25JAq zUa`9i@S0W%YeEdDji?cXy%S>QKlbP+l?f;iN^#{Wxfiq4LILguUzQZ@Q(*@R8CKqQ zd3@}p-A0n-QUjaY!AcF$spL!M2Ije;GI(JkA!~%0)uVZ>YqEu1dkh%LMXw~`yayfk z<>)P0wtzP!#McmV!9<70^tSQ#T4kG_9lljO{kl_zaHGxv(zs$E6z5XLN;@AFQQLGVcQS; z4j(Wxe0AXZ*g(PJQ5uYop<|Gto<&XT%3IincGGuv4bm>s=vrj0Ab?L!KGM=igD0F* zvIRL+8+DHIqSt=vM-PwQWAY5a5XU_mur4bacVdL^7GDV%8W!6}wvzUktGf@Um!!bh z)U&!?i%_mr-_^47J6EV>cV&OJyC%pRpVm6|yQN3@{YBj#s@jYZ-Iwyr1F?k|R~iQ2 z^P9epT8jcvGVq4I!mU@~{Sv*?#MwDBD0V7sm(i}NRbZVOe|KtbKc?WMEt zA{dh_GcBttMIT*Y4Kzmnj(H6KI{3Bkv7bXZ`mC+A3|F)DS{jgvVFE4EYpo{Lpay%X z#w+ZG|D!Lk8kIE38gO?~V1yx!ND$vtNHgMPi`McuHSKb2?w-|*`X_#}5F>J@t8A2y zk!i2%MZ0@5c+8SdXD!6_FvJM^7PEtBt{a}{W0UzMBX&|D@M$N}HhOqPgMC7&UzB!E zHRzH8%%)bwfWb9T`8r)r20v({5t3iIL@m_blVBy#Igf3G#0Qcv()~(^aulsINS!{} z8#qNi=BUrX2onb?f-piVBLiBtb#H z=p6b3nXJ#Q*uS9{J@dovHGMis8_gqLz7#m7SBnB+A~0mY;1LQ73giTa*BQTR&5f)U7S6@UIxqY<^ARj>^H0fD8+SxzvN0cbuRfx*D&@$GjhruwSgh>@~%+sdE* z#OqYJftA}{jvl2Q^uRSwxc879*!Do0 ziar91D0R3uSibFeK%*2Cbrt1`n5QA1aJ+9Y>CXD54!zSfpwl%V^z$H?OFPNrXm#L# zQ%+wuLSND=^l^w<{jK9q{r+p+rasi7#K>zUvE+>w+oE zd{A+7(AY@B;&CwXft!r{Bgt#m0#ih_&-Cj|dwt-$eBm6&dSbZP{kL+{1uIzyK}+OQp$l*2 zEN?GBR+C2sA`hsC0V&--2l2xUl4|D<`d|i4Gy*dNpP>vs1A_y5!m37dw4(48l)^c^ ziH*BtaF68WM%0tLLWf_3c>eWh?Hn63%`l%RGNK{GXvB~ILcN`FNkYxTLQY=QQ4&+) zp7mOa`yz!4moKE1NE@FLT~MaY%Zr5tKnl>6XSxeUaRbIMUyFR_Q`G(PMe)a+JSIcE%8?SU3;RNW< zh5-$;hBOiJYQi?I(4Q#3Tu8kn8>2PiL!?u#Om%i@pzvTzrCv@xeYw@)$r-Aup^p}yPV`!GsYYr5m#F_2kqT-6vsKHRGt!!uNnPMxomN z-k+MDa&2V>BXjJO-rZ?+2KjeXtypM|{p@a!Ick(D6sx&(>0cQZUZfXPa?}wXBa%7d z8A(FFIZQl`X{jh1;2z~FNcHeQd&!O{sj6(1`e#NS!|EIvxebbxo7L+a3l3PQvJNWk z=YB3wLwId{$Pn?E@Sy&(xVTC^InLCe!n4B376~bd>r@A|H+`%8q+MNDB}*<|yVIU0 z$k;BPZY*msV@iTHs9I!?STlF}YoRPX@l#pRC*IG9oI?}xbh*uL)6ZBQC4W&E%1qvm z0^5nqT7o&OI`0ECI#p#d?2;WhB_)N~HY(Y4$q3eQEX-5N`o+GwsVJo;$)57B?S(xh zvXriGFH8yyox{uwk2yQ_659BjodHEGGS*4qeGVUD9&g$>PEP1pX2KW-7dh3OIYR^q z`4U;e9UA%Ut@~b46Pd8aUFA6Lj@k(MTxT|q^O}Xw8m^E2ir==Z@Fuf~uKUzZ5<(0N zCpiY(>9k$#(yu?@Puwg9H+wwI)_9zbFZXD7vQO!)trO=h7AD^BQnns9g=7#VQyo4M z9{MsfrM;5@;LQfT)d>n|JJTMbrETQEXJV1|o+?VAT zda-oLUcODm{lb5T(VPSIwqU0|Z-^3QIpPOh^Z2y3W53c6i}OWyo7UZGP*W*q#1Yup4+ z@*;EC{Q2g@7EHxJA9rR4P$xh0K>`h=tQ}4*i&|H36&#EsUCmOpS(2?k?vbm9L~%1OGSMe4 z)|$qGud&BbGKvy;u@{39QDH`ijP_>r>>{7<;F!L$j(GE~(&V{A&u}6Bx{RzdfQv~V zpTeK2bYXEKs02dgiEXh2jvUUsoW8sgbIMbyip}Mh(k9C=SQ&bV!PUZso?vmQ@T%}I zp8}69r`9iroG7iJJ}`f9uh_pZ_Qf45-WQ%1zBX=JyD-k2&zoDJjrtB{WL1;oGE65+OVE1|*jEa%IQj+8&ja+Xqo}Sb@R-(uB^f8AP7ICx%X39c=uO0kSCng~EC%S8%>Ynf5Y_$#J&X(aOWsW~+|g=Bt#CS7HuB{iI*)l^ zk7d;8_K>1Xz0q3rOxA<%NqUv!QM}@$dWjPkum4EZ_l#!fg=6Q9U*=a`k!6l6f3xgo z^=_!pro3YQNfk~7R&j<&I{HJPS=UMahrzk>-$UQm2MTNpTg+WpnSk?&Y30~G5USXp zLaLz7C8N2qBhj4aCLw**w#)K|sLmm|PT2IgD=QP?kt`(cEsJ4!Aq~NoFvm~}r9Ulm zc0Hfn!35)bo?j0j8RqCHqdC2g5wxJ&taf>SZo{Iod_JAP8qicXqF002OAVyU zrzfRHr4wVRhPeKHxN;+Z)3^^o{0M8#qf+&tI%=k&%O?0Pwa z*{P!8(!@lI;o>XUcuT#0$BypQskX!%z8ZCCAu@?NB+3YI)o>m@@XJyqtt-O@m}?iywtfmE$*pt12VPALPTf)HG{c;F*tF2yI14v=jBe0UVvSk`79M@7F&`L zGc-iC2M-o5Kx&jQ+3m-4)9gMAdqQnhs`h_&b@3b83-p_WPzJR!M1}?3D5W)Q_w?p= z7ibCf*X_nr4A@VtE;!D(oukFHdWn+*Gekj#=hmFjB+axdDJrm^q`w8T(_lh=JgCai zsAF`u8Ry&l%H;o2AK-A-aEOeQp^rLQ%{Lw$6Viy(>2M5sSS};brPO3Q>69@>_>r@R z3(vA$UG~FR8=i9)7FL?65J&W;eC6!Vl>7mT)Y&`Y6e4Kv>$A9sdYiKl;O}NQr%JGfxgJ7 z=>#C}7L8}`m|QIZ*Z%^{&m|60J0PMHN3Vdw9-1?YHd$^0Is zI#Bv-{ME-U*>HE_c zaulW?PJN|Sb-B>Cx>DeCLtBi2daKdskN6spk%7!u*FGO{IZNdlND;Fwn>YfN{=h)< zY3|T>XVFFCqdUX98ArOfX)5~&u{QH*w6a+ifu6fgD-`w${9+*-lMc%Sx`AbJb#aEb zQzbX4GAg=89)XgGcB;Nh-9$Z8j+&2>khREO#5lSyB_ksVB9@8Lwr|fFl^gmv=Kl7M z?O~odN8^?>o0tqrq95;EyYyGbnmG?Lk)-o%RF>&*4-6%NW>>sE68}D0%lBDctfM~x zi#6Aqu3W@KZJxd(@|CS!m%(5^ll0@~mIkJ0`Z^O+jpET`Ocy4%^dQ`Q%f(jyQv*zZ z=D=!vM;}CId{S$d{r+P;Y+lI>XTHVIjf9iMetLV|g$HkDkJnu2^wTctdw4#!+Fx(gkHoErPnwzXzr&dZ2cSmk$p(!=))oZT zme!|c*-R4ISuc_1K;|U%gRF}TLDgm1FlCSPyJ4LJR`h;z^RLd3Bnn2?=aG`2JOBny6SrhMjFRQQ zOhuLhdm%$aLvHaU!`H3V4!MNt^t!RXzB_7(YYv%=oll0Shv(_ISp(kd%y^q+OEl3c z^N8Sn9ub-S{r2*dQSD}~eLb4+=Fg{eAy#ombgJi*h{SXI+qwJ7Ij%YUx)%pdhKIs7 zUoyY(?=Ebdlgnq*<$B_})_tVoI>ixWoqdoL;m=h65rh1T8Kq(sGbN2AK!e)EB1Hut z0?iWNV0MR4W9J&NV)WP#wG%>Sa7u~@3hL5# zt(eEnQpT2R#OL-PGQWC?$98LR8^WN9w0bOd`=+l3JOBscxAnvb#p_Pe)o0xKzCta$ zlV6v1W$+s)dfKrP#lAfvW|v&jY#De^W=&e3-e~d@I%k`*HI4F0lN45)x%AjuAIv}> zu~}KQws@Q3HiI{-J9ReXVqM@XMo{7_O0Q*|vqi1#FS)--Q$M13G6I<71&{danG;A` zn=CV7WsH(=40R+gPBRKBG~ine9oKC{!D%}j_ThR}A27_Egj{&dBdXwtuVMG(ARhDK zpSL6Uy__(f0|prD|(8CFUWY#oUjIGp^4C>4=+W$#J1o#Bt-)q-!j`$vW2 zF^^m-LVphO-G7RfU6@md$RCF*@=MDm7^N@?joNRBU2j8)6yV(ra-K(Hh5+WC;dmpq z4pg60x6UFK2i>~MV{Y{f9TGL8+gxXk2;o^qLsvo}N@n-`egGrP{yqL5jJ;E=Fg(;? zeQevdZQHhO+qP}nHlJhLwr!vDzu%usGLyNPG`(rBnw_R;yZ2fY)Qi5!qwwii%Soqv zN48o)+-GJeD`v8YAp`XmK^+zM)a8PBa%vu)+RH|7syoIuNgbGzn4P;{8Zp)NW}URFBRMmNiwmA zittrFDWutua-~+Wm&B;5kttQE6)<+4I%-;#q*_&Q^c3i<&~2ifPS%myTe{k1xdo=Q z(nZQrQ;h3LDb>$jfhcx`At&i&l2~F&3=B+O2zoqq{37-^T+0N=*4TQ5KlUx<+}K@* z6Y%@XW`{K(9%k(63oLiFeXk0U<$p1GRCMjQD$|gys-t#F8?)X$?0<06;$ZAX3EWQm!}pe zR#eoFO&neJO-&1Oc#1Bot#g&B3n;@(pG>3R`zjr?BClLJ-4Zj!5~!H=B~ef^)U3SE zJd%LGkf1+Px>mL7B}{?B64Np%WY(2M*aA{aZjtt)FcT0JtkOx``Dq1YSK6Cs#CR-g z3)nDxDPF*Kzo5YV(XzWMyGEHB6wt;nyLHQBB*YXM%?u7l@lX`$7*!hr4hiq3Q;)Y};pM_4XU{~3OxabG`EmtZ%tjH7o zt)q#xQm+yZKY6=8I%ajLTf3;z#0=h25MmSx`qUWq#!V-uNN~~=k4Q&ONrJa>ZDR%x z^20uZJ=+1J#?sWqAd4D$!P;STd5GEbGihoI^yJM3yQat=Uwj zhg;||!y3&D!4Q9d)2pi1FGXkqB ztEyo?%+>;R7KB)zpjq(jajZ+TVY8=Suy5I!T1O%SAlfeL&KciO-CJ_^V|cZ(7IM?I zhFYGKU{>tB;_D?MhfEi7OfMcW8GRSFmW#@|_#Rcq>HCTMK9A$S=+fOL({Ox*tCuoE zZ!ufwHWuqd38Bnj(@p!M$Wg-4Bl^R0?_ayaC>~Y`{;m0=B4=6^n*%!A@7cO$^)#9` zR?-jcD9|>v-@3zeZE?R!jq&a4{CYkj8Dw-QXi;;6Qii-XXmbA`uS7d6x-o3sBPbJS z+E6qr-&LNO{vi3EG?RZeR(<@(&g0^U)DzpA`|FF=*T)w37WnJxtMj|{zbza?Ol$rS z|BS|r{w~g$e=(q?ZsOK`_P-Xrjh-qEY>CFR--~NIEQkMX(kbNuG7elUL#rh2r%>Pg zR>&>i%GJq~P2llEWpj~TtVY0YV8X4JM9?1I+I$#HGvP4eK#DssBvOlgh~W1pXH#^K z2tGi7OFPGGpbT*`U=dI=ujP;X<+C&XjiBp&Zgmg*Y*k4vB)&<0&A_wyv>R@phWmRw zPVKXkyiQjDzQOw!vY6`q62IY-0L%GGhOP9W`g|mR3vr!WDUOy?Y{HgY(PS zU zjC|6&jeZQhtnVTe_V6hLLgv>c7bkb8dj%Nh7#BSf?hJi$R(*V)wP3%neoA-Uy@2J4 z9kE@`h!yWvtWn4|E*rO3nUEC=RwEXtN>$I`9kp!yL#CH>acR-3SLXQXQf*Rl9}EeZ z1R*5k<09JFO~d|$igKVdq7!+tNYVZm5%2`g|6#d!lXJg=^Kg1IHcsxtE>sF}{`3-t zCZ-Hsmt3O5n+oVn7S7-4~p{<=D|D|+EF<}+HPaTU=#ZYHA8V3r@lyhv72B{ zTg&x5&{CZ5X1iD}eZE=92mfk)dGXDv$!)&jJJ*XMgKpj3`*vTI?ARCbMFu`4IeH!H zY2`U&LP-5~09Rbn?GG%p*PPGbB^_>Hu%ci{QH?;xcq(l}cg(#Bg?plV7^QQAv`PMo zBy|jY_{r)?B()}TC0_t3R75YHe`9+_Ep>Hwdv$ZKj zmu0{8b}#M_Vg3DzU5B|x7v3JPpcN;Dl6qC5nVGmF5cF&!({*JQdmTYzmYup$va%m_ zihtkbHt!uDx3^sV6_7Rn?iGXgv0gvd^L(b$sMhal{IdDY^JwaL($eWl--G>a3;MBr zzhC5MOSOp_`@9KOe%#06^Q}E3=FgzqZtyVu)op4TYrE+5mNGF$P4*M8mJp}bsn+GZ zKwE%XiM#>4h_9lwIv8j>=N)N5Bz~*=Q}$Ou525NPhkW#Oix5(ir9$q*7MXkj)#@5lu7 z;P@VIx`DiMqBeZ~i&IyYpWB=L;IE)N@=4p%eMFt}!Lz&{NOlOmq)MwxbIC`tOOxEalp!q&t%?uKJJn~i(kQ^o z->%)VL=z6|VvK6MT5P+l=`zZWiEOJZEY@_@iE5R(CajUGGWT`Fk+W;)k@T+Qvbzn^ z5z-y^GL_$Sx73h7PZmL229XO_Em}s57BOX&6s-DKtCb)!sZuf~;8>-qqN42r5lVF^ zm1L(sKt6@8Vd!g~zYUJVmh+fT$0R zA01ra?i}xW`v(6`#^Z(FCu?Ihqqr2USpR%~r{v}ssv)$doJn|c0eR6SN$==9!gti{h zwIuKxhGML?z0k5hF)xC$OwqM5a(q6Fee8V76-rMJXbB>ZlR5^DNYyfNidoCcEs~KR z=`AKh9WtMXmeJFpKM=`Q%i)Rqh5^kkkFp9%VVdaY? z<5+eH?I7(~=}M5-t=cZ>E z4C-6oe}ew%5Pq8hvmrr+-QYIc`iDn(XUFrhCYhklYHb zS}d~O>^6OM?=YjPJJ8h;?Abq_&5#3YM^r43N6d^6Dbl#8c2`WH-i(=OAmqsbsHuf!Z&GU&p1h}RA3SI@j2G`NEmfMsY^+kSeygE;}JD%whs>f){ zER|<2jR^S)To>KZ#UaR#{LI>6uz*F!O;8MTDHy4uh0EdQ-X~^ZECX(js#RrrA=yC? zO5ZDbB^ao*hN&c1hjdC1UWkDp9bG42yRn@hfB3dr^XO5<+Xz9GV&5X2HDXQj>OHSw z5FG5z0_?tv03H?BOphZ=FFvp6BDceDsNq5UevbY&vUJZSE4TIVcut}!8U zR?2<@#U{S{akFxtpX~R3c$K-%mXY~$Zm-4fHDkmi?&jr)B(99ga1f6RwL7Szg2! z)tT|K=p*W;JR>>@L{qm8g&Vzl){QRs(TqiKYkD(?ZOyGrbo2EzF3zv2Z!>W-y6LW# zeVjEnPy-})vp{@8X(~3Lh_s@(8R9+0D}UfVF%csM&^WVkaXcnj1`_;u?Bwj2kn^bL ziVXdjarXKaap2MmQ&h@Jy>vea1=Q)AR7`;kI-|q~dZR>(Z{JybM0B?`5_U9*%g9tC)>Tv5989 zxjE2~&OyThzfgrn^;HobeKhJQb!Y_&7$YK(EUOR2KBIo?1hWi{5i@SJtnPI+4zCQ5 zkry{u_UJko7k&b-NvC|R7}kK)t9E8}XL3ky;BuaxwT4k4IBsVq~81aPFJW_v?T5p?A)Hl2<+g}fxEULMh? z9Bev?AT_Od1w91MMI6Vr6J+er*t@p@i!|>Nhb)ipBwZA+)w18FxA1*bBR=P#bBQ0) zl{ijebhex#UKUT^{EWWD=hohq=#F_b3yI|Yjs1MEx3*2idI}f$)DG>I zf!Tni8j{b9mW<~Nf$5NpGuG-B>{h7mw#YWFQv;aj1NF7x+sQa(3((lzLL#&*qd23W z|Gq?LhH;{x7_#F71@eg&eOq%eJvSDASW|~mdr`)`D7nn|D?#CP$f^D@oN(FImZDRA zDBn$$`Y0XZqj8~wZC$1wfW2)fnv`alG=HcDIA;)&*W7wZ(_ zJ+`tqxC6S@=;fN^vzAH+Z1l|J-NNOktI^TmW9#&+=48*7npU zb(7S|>LOFkJDQNBlCiC~yQ7r4yt&9_(c)WXW~roUWqMILB%Pz*rH&NKRyC_E+;V4i z6qz7}Hgh;COW3NH;()*hOs^9Mt`!XzuBVD}w@^`&PNSDTiH`dn7lUaFsGU}`G;Wjh zIt=zu9|Zhy{NePKnA7~a9b>XDt0xIdby~E_v^9vYf%r&*LymR zr`Gdy`3$RF!rN4^xjUG`S>Y(4n2;C$9vzuao-(X$puJ{l>AGVry%J zWy9bkK?5|3FwQm*HVy)A;%Ni*!jNop6hd0(kyvCYy|@9|Df4uETDOISf0AiFXp?Nq z9)sN=nIZdGOrUR(-CUfy{g1RMOuP4≧}THO>bd-n0iX-;CFoZX&% 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

2^svq`#;l1 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 GET some-bidder-domain.com/usersync-url?redirectUri=www.prebid-domain.com%2Fsetuid%3Fbidder%3Dsomebidder%26uid%3D%24UID - -This example endpoint would URL-decode the `redirectUri` param to get `www.prebid-domain.com/setuid?bidder=somebidder&uid=$UID`. -It would then replace the `$UID` macro with the user's ID from their cookie. Supposing this user's ID was "132", -it would then return a redirect to `www.prebid-domain.com/setuid?bidder=somebidder&uid=132`. - -Prebid Server would then save this ID mapping of `somebidder: 132` under the cookie at `prebid-domain.com`. - -When the client then calls `www.prebid-domain.com/openrtb2/auction`, the ID for `somebidder` will be available in the Cookie. -Prebid Server will then stick this into `request.user.buyeruid` in the OpenRTB request it sends to `somebidder`'s Bidder. diff --git a/docs/developers/currency-converter.md b/docs/developers/currency-converter.md deleted file mode 100644 index 64f770608bd..00000000000 --- a/docs/developers/currency-converter.md +++ /dev/null @@ -1,56 +0,0 @@ -**For the time being, currency conversion is not enabled, feature is still under dev (check #280).** - -# Currency Converter Mechanics - -Prebid server supports currency conversions when receiving bids. - -## Default currency - -The default currency is `USD`. It means that any bids coming without an explicit currency will be interpreted as being `USD`. - -## Setup - -By default, the currency converter uses https://cdn.jsdelivr.net/gh/prebid/currency-file@1/latest.json for currency conversion. This data is updated every 24 hours on prebid.org side. -By default, currency conversions are updated from the endpoint every 30 minutes in prebid server. - -Default configuration: -``` -v.SetDefault("currency_converter.fetch_url", "https://cdn.jsdelivr.net/gh/prebid/currency-file@1/latest.json") -v.SetDefault("currency_converter.fetch_interval_seconds", 1800) // 30 minutes -``` - -This configuration can be changed: -- currency_converter.fetch_url can be any URL exposing currency using the following JSON schema: - ``` - { - "dataAsOf":"2018-09-12", - "conversions":{ - "USD":{ - "GBP":0.77208 - }, - "GBP":{ - "USD":1.2952 - } - } - } - ``` -- currency_converter.fetch_interval_seconds can be anything from 0 to max int. - **The currency conversion mechanism can be disable by setting it to 0, in this case, there will be no currency conversions at all and all bidders will need to provide bids as `USD`** - - ## Examples - - Here are couple examples showing the logic behind the currency converter: - -| Bidder bid price | Currency | Rate to USD | Rate converter is active | Converted bid price (USD) | Valid bid | -| :--------------- | :------------ |:--------------| :------------------------| :-------------------------|:----------| -| 1 | USD | 1 | YES | 1 | YES | -| 1 | N/A | 1 | YES | 1 | YES | -| 1 | USD | 1 | NO | 1 | YES | -| 1 | EUR | 1.13 | YES | 1.13 | YES | -| 1 | EUR | N/A | YES | N/A | NO | -| 1 | EUR | 1.13 | NO | N/A | NO | - -## Debug - -A dedicated endpoint will allow you to see what's happening within the currency converter. -See [currency rates endpoint](../endpoints/currency_rates.md) for more details. diff --git a/docs/developers/default-request.md b/docs/developers/default-request.md deleted file mode 100644 index f071d91bad6..00000000000 --- a/docs/developers/default-request.md +++ /dev/null @@ -1,44 +0,0 @@ -# Server Based Global Default Request - -This allows a default stored request to be defined that allows the server to set up some defaults for all incoming requests. A request specified stored request will override these defaults, and of course any options specified directly in the stored request override both. The default stored request is only read on server startup, it is meant as an installation static default rather than a dynamic tuning option. - -A common use case is to "hard code" aliases into the server. This saves having to specify them on all incoming requests, and/or on all stored requests. To help support automation and alias discovery we can flag that any aliases found in the file be added to the bidder info endpoints. - -## Config Options - -Three config options are exposed to support this feature. -``` -default_request: - type: "file" - file: - name : /path/to/aliases.json - alias_info : false -``` - -The `filename` option is the path/filename of a JSON file containing the default stored request JSON as documented in the [openrtb2 docs](../endpoints/openrtb2/auction.md) and [stored request docs](stored-request.md) -``` -{ - "tmax": "", - "regs": { - "ext": { - "gdpr": 1 - } - }, - "ext": { - "prebid": { - "aliases": { - "districtm": "appnexus" - } - } - } -} -``` -This will be JSON merged into the incoming requests at the top level. These will be used as fallbacks which can be overridden by both Stored Requests _and_ the incoming HTTP request payload. - -The `info` option determines if the aliased bidders will be exposed on the `/info` endpoints. If true the alias name will be added to the list returned by -`/info/bidders` and the info JSON for the core bidder will be copied into `/info/bidder/{biddername}` with the addition of the field -`"alias_of": "{coreBidder}"` to indicate that it is an aliases, and of which core bidder. Turning the info support on may be useful for hosts -that want to support automation around the `/info` endpoints that will include the predefined aliases. This config option may be deprecated in a future -version to promote a consistency in the endpoint functionality, depending on the perceived need for the option. - - diff --git a/docs/developers/features.md b/docs/developers/features.md new file mode 100644 index 00000000000..b9bb9053ed5 --- /dev/null +++ b/docs/developers/features.md @@ -0,0 +1,12 @@ +# Features + +Prebid Server documentation has been moved to the prebid.org website: + +- [Adding a new bidder](https://docs.prebid.org/prebid-server/developers/add-new-bidder-go.html) +- [Adding a new analytics module](https://docs.prebid.org/prebid-server/developers/pbs-build-an-analytics-adapter.html) +- [Currency](https://docs.prebid.org/prebid-server/features/pbs-currency.html) +- [Prebid Server and GDPR](https://docs.google.com/document/d/1g0zAYc_EfqyilKD8N2qQ47uz0hdahY-t8vfb-vxZL5w/edit#heading=h.8zebax5ncz0t) +- [Prebid and TCF2](https://docs.google.com/document/d/1fBRaodKifv1pYsWY3ia-9K96VHUjd8kKvxZlOsozm8E/edit#heading=h.hlpacpauqwkx) +- [Prebid Server User ID Sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) +- [Cookie Sync](https://docs.prebid.org/prebid-server/developers/pbs-cookie-sync.html) +- [Default Request](https://docs.prebid.org/prebid-server/features/pbs-default-request.html) diff --git a/docs/developers/gdpr.md b/docs/developers/gdpr.md deleted file mode 100644 index 8da2e917623..00000000000 --- a/docs/developers/gdpr.md +++ /dev/null @@ -1,31 +0,0 @@ -# GDPR Mechanics - -Within the framework of [GDPR](https://www.gdpreu.org/), Prebid Server behaves like a [data processor](https://www.gdpreu.org/the-regulation/key-concepts/data-controllers-and-processors/). -[Cookie syncs](./cookie-syncs.md) save the user ID for each Bidder in the cookie, and each Bidder's ID is sent back to that Bidder during the [auction](../endpoints/openrtb2/auction.md). -Prebid Server does not use this ID for any other reason. - -## IDs during Auction - -The [`/openrtb2/auction`](../endpoints/openrtb2/auction.md#gdpr) endpoint accepts `user.regs.gdpr` and `user.ext.consent` fields, -[as recommended by the IAB](https://iabtechlab.com/wp-content/uploads/2018/02/OpenRTB_Advisory_GDPR_2018-02.pdf). - -## IDs during Cookie Syncs - -The [`POST /cookie_sync`](../endpoints/cookieSync.md) endpoint accepts `gdpr` and `gdpr_consent` properties in the request body. - -If the Prebid Server host company does not have consent to read/write cookies, `/cookie_sync` will return an empty response with no syncs. -Otherwise, it will return a response limited to syncs for Bidders that have consent to read/write cookies. -This limitation is in place for performance reasons; it results in fewer syncs called on the page, and their -sync endpoints will almost certainly read from the cookie anyway. - -The [`/setuid`](../endpoints/setuid.md) endpoint accepts `gdpr` and `gdpr_consent` query params. This endpoint -will no-op if the Prebid Server host company does not have consent to read/write cookies. - -## Handling the params - -For all endpoints, `gdpr` should be `1` if GDPR is in effect, `0` if not, and omitted if the caller isn't sure. -`gdpr_consent` should be an [unpadded base64-URL](https://tools.ietf.org/html/rfc4648#page-7) encoded [Vendor Consent String](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md#vendor-consent-string-format-). - -`gdpr_consent` is required if `gdpr` is `1` and ignored if `gdpr` is `0`. If `gdpr` is omitted, the Prebid Server -host company can decide whether it behaves like a `1` or `0` through the [app configuration](./configuration.md). -Callers are encouraged to send the `gdpr_consent` param if `gdpr` is omitted. diff --git a/docs/developers/stored-requests.md b/docs/developers/stored-requests.md index 8b7177160c3..9adf4ed1309 100644 --- a/docs/developers/stored-requests.md +++ b/docs/developers/stored-requests.md @@ -1,6 +1,8 @@ # Stored Requests -This document gives a technical overview of the Stored Requests feature. +See https://docs.prebid.org/prebid-server/features/pbs-storedreqs.html + +This document gives a technical overview of the Stored Requests feature in PBS-Go. Docs outlining the motivation and uses will be added sometime in the future. diff --git a/docs/endpoints.md b/docs/endpoints.md new file mode 100644 index 00000000000..88116144a41 --- /dev/null +++ b/docs/endpoints.md @@ -0,0 +1 @@ +Endpoint documentation has been moved to prebid.org: [https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html](https://docs.prebid.org/prebid-server/endpoints/pbs-endpoint-overview.html) diff --git a/docs/endpoints/bidders/params.md b/docs/endpoints/bidders/params.md deleted file mode 100644 index ebe0401c2a5..00000000000 --- a/docs/endpoints/bidders/params.md +++ /dev/null @@ -1,24 +0,0 @@ -## GET /bidders/params - -This endpoint gets information about all the custom bidders params that Prebid Server supports. - -### Returns - -A JSON object whose keys are bidder codes, and values are Draft 4 JSON schemas which describe that bidders' params. - -For example: - -``` -{ - "appnexus": { /* A json-schema describing AppNexus' bidder params */ }, - "rubicon": { /* A json-schema describing Rubicon's bidder params */ } - ... all other bidders will have similar keys & values here ... -} -``` - -The exact contents of the json-schema values can be found [here](../../../static/bidder-params). - -### See also - -- [JSON schema homepage](http://json-schema.org/specification-links.html#draft-4) -- [Understanding JSON schema](https://spacetelescope.github.io/understanding-json-schema/) diff --git a/docs/endpoints/cookieSync.md b/docs/endpoints/cookieSync.md deleted file mode 100644 index 2378aaa1cdc..00000000000 --- a/docs/endpoints/cookieSync.md +++ /dev/null @@ -1,55 +0,0 @@ -# Starting Cookie Syncs - -This endpoint is used during cookie syncs. For technical details, see the -[Cookie Sync developer docs](../developers/cookie-syncs.md). - -## POST /cookie_sync - -### Sample Request -This returns a set of URLs to enable cookie syncs across bidders. (See Prebid.js documentation?) The request -must supply a JSON object to define the list of bidders that may need to be synced. - -``` -{ - "bidders": ["appnexus", "rubicon"], - "gdpr": 1, - "gdpr_consent": "BONV8oqONXwgmADACHENAO7pqzAAppY", - "limit": 2 -} -``` - -`bidders` is optional. If present, it limits the endpoint to return syncs for bidders defined in the list. - -`gdpr` is optional. It should be 1 if GDPR is in effect, 0 if not, and omitted if the caller is unsure. - -`gdpr_consent` is required if `gdpr` is `1`, and optional otherwise. If present, it should be an [unpadded base64-URL](https://tools.ietf.org/html/rfc4648#page-7) encoded [Vendor Consent String](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md#vendor-consent-string-format-). - -If `gdpr` is omitted, callers are still encouraged to send `gdpr_consent` if they have it. -Depending on how the Prebid Server host company has configured their servers, they may or may not require it for cookie syncs. - -`limit` is optional. If present and greater than zero, it will limit the number of syncs returned to `limit`, dropping some syncs to -get the count down to limit if more would otherwise have been returned. This is to facilitate clients not overloading a user with syncs -the first time they are encountered. - -If the `bidders` field is an empty list, it will not supply any syncs. If the `bidders` field is omitted completely, it will attempt -to sync all bidders. - -### Sample Response - -This will return a JSON object that will allow the client to request cookie syncs with bidders that still need to be synced: - -``` -{ - "status": "ok", - "bidder_status": [ - { - "bidder": "appnexus", - "usersync": { - "url": "someurl.com", - "type": "redirect", - "supportCORS": false - } - } - ] -} -``` diff --git a/docs/endpoints/currency_rates.md b/docs/endpoints/currency_rates.md deleted file mode 100644 index 537713b147e..00000000000 --- a/docs/endpoints/currency_rates.md +++ /dev/null @@ -1,111 +0,0 @@ -## `GET /currency/rates` - -This endpoint exposes active currency rate converter information in the server. -Information are: -- `info.active`: true if currency converter is active -- `info.source`: URL from which rates are fetched -- `info.fetchingIntervalNs`: Fetching interval from source in nanoseconds -- `info.lastUpdated`: Datetime when the rates where updated -- `info.rates`: Internal rates values - -### Sample responses -#### Rate converter active -```json -{ - "active": true, - "info": { - "source": "https://cdn.jsdelivr.net/gh/prebid/currency-file@1/latest.json", - "fetchingIntervalNs": 60000000000, - "lastUpdated": "2019-03-02T14:18:41.221063+01:00", - "rates": { - "GBP": { - "AUD": 1.8611576401, - "BGN": 2.2750325703, - "BRL": 5.0061650847, - "CAD": 1.7414619393, - "CHF": 1.3217708915, - "CNY": 8.8791178113, - "CZK": 29.8203982877, - "DKK": 8.6791596873, - "EUR": 1.163223525, - "GBP": 1, - "HKD": 10.3927042621, - "HRK": 8.645077238, - "HUF": 367.6484273218, - "IDR": 18689.5123766983, - "ILS": 4.8077191513, - "INR": 93.8663223525, - "ISK": 158.0820770519, - "JPY": 148.1365159129, - "KRW": 1491.3921459148, - "MXN": 25.5839382096, - "MYR": 5.394332775, - "NOK": 11.3144425833, - "NZD": 1.9374651033, - "PHP": 68.6139028476, - "PLN": 5.0130281035, - "RON": 5.5172855016, - "RUB": 87.2333891681, - "SEK": 12.2141959799, - "SGD": 1.7908989391, - "THB": 42.0074911595, - "TRY": 7.1224176438, - "USD": 1.3240973385, - "ZAR": 18.7774520752 - }, - "USD": { - "AUD": 1.4056048493, - "BGN": 1.7181762277, - "BRL": 3.7808134938, - "CAD": 1.3152068875, - "CHF": 0.9982429939, - "CNY": 6.705789335, - "CZK": 22.5213036985, - "DKK": 6.554774664, - "EUR": 0.8785030308, - "GBP": 0.7552314855, - "HKD": 7.8488974787, - "HRK": 6.5290345252, - "HUF": 277.6596679259, - "IDR": 14114.9081964333, - "ILS": 3.6309408767, - "INR": 70.8908020733, - "ISK": 119.3885618905, - "JPY": 111.8773609769, - "KRW": 1126.3463058948, - "MXN": 19.3217956602, - "MYR": 4.0739699552, - "NOK": 8.5450232803, - "NZD": 1.4632346482, - "PHP": 51.8193797769, - "PLN": 3.7859966617, - "RON": 4.1668277256, - "RUB": 65.8814020908, - "SEK": 9.2245453747, - "SGD": 1.3525432663, - "THB": 31.7253799526, - "TRY": 5.3790740578, - "USD": 1, - "ZAR": 14.1813230256 - } - } - } -} -``` - -#### Rate converter set with constant rates -```json -{ - "active": true, - "source": "", - "fetchingIntervalNs": 0, - "lastUpdated": "0001-01-01T00:00:00Z" -} -``` - -#### Rate converter not set -```json -{ - "active": false -} -``` \ No newline at end of file diff --git a/docs/endpoints/info/bidders.md b/docs/endpoints/info/bidders.md deleted file mode 100644 index 7c6ce960479..00000000000 --- a/docs/endpoints/info/bidders.md +++ /dev/null @@ -1,23 +0,0 @@ -# Prebid Server Bidder List - -## `GET /info/bidders` - -This endpoint returns a list of Bidders supported by Prebid Server. -These are the core values allowed to be used as `request.imp[i].ext.{bidder}` -keys in [Auction](../openrtb2/auction.md) requests. - -For detailed info about a specific Bidder, use [`/info/bidders/{bidderName}`](./bidders/bidderName.md) - -### Sample Response - -This endpoint returns JSON like: - -``` -[ - "appnexus", - "audienceNetwork", - "pubmatic", - "rubicon", - "other-bidders-here" -] -``` diff --git a/docs/endpoints/info/bidders/bidderName.md b/docs/endpoints/info/bidders/bidderName.md deleted file mode 100644 index cd525e640f6..00000000000 --- a/docs/endpoints/info/bidders/bidderName.md +++ /dev/null @@ -1,43 +0,0 @@ -# Prebid Server Bidders - -## `GET /info/bidders/{bidderName}` - -This endpoint returns some metadata about the Bidder whose name is `{bidderName}`. -Legal values for `{bidderName}` can be retrieved from the [/info/bidders](../bidders.md) endpoint. - -### Sample Response - -This endpoint returns JSON like: - -``` -{ - "maintainer": { - "email": "info@prebid.org" - }, - "capabilities": { - "app": { - "mediaTypes": [ - "banner", - "native" - ] - }, - "site": { - "mediaTypes": [ - "banner", - "video", - "native" - ] - } - } -} -``` - -The fields hold the following information: - -- `maintainer.email`: A contact email for the Bidder's maintainer. In general, Bidder bugs should be logged as [issues](https://github.com/prebid/prebid-server/issues)... but this contact email may be useful in case of emergency. -- `capabilities.app.mediaTypes`: A list of media types this Bidder supports from Mobile Apps. -- `capabilities.site.mediaTypes`: A list of media types this Bidder supports from Web pages. - -If `capabilities.app` or `capabilities.site` do not exist, then this Bidder does not support that platform. -OpenRTB Requests which define a `request.app` or `request.site` property will fail if a -`request.imp[i].ext.{bidderName}` exists for a Bidder which doesn't support them. diff --git a/docs/endpoints/openrtb2/amp.md b/docs/endpoints/openrtb2/amp.md deleted file mode 100644 index 16fa451ef36..00000000000 --- a/docs/endpoints/openrtb2/amp.md +++ /dev/null @@ -1,127 +0,0 @@ -# Prebid Server AMP Endpoint - -This document describes the behavior of the Prebid Server AMP endpoint in detail. -For a User's Guide, see the [AMP feature docs](http://prebid.org/dev-docs/show-prebid-ads-on-amp-pages.html). - -## `GET /openrtb2/amp?tag_id={ID}` - -The `tag_id` ID must reference a [Stored BidRequest](../../developers/stored-requests.md#stored-bidrequests). -For a thorough description of BidRequest JSON, see the [/openrtb2/auction](./auction.md) docs. - -To be compatible with AMP, this endpoint behaves slightly different from normal `/openrtb2/auction` requests. - -1. The Stored `request.imp` data must have exactly one element. -2. `request.imp[0].secure` will be always be set to `1`, because AMP requires all content to be `https`. -3. AMP query params will overwrite parts of your Stored Request. For details, see the Query Params section. - -### Request - -Valid Stored Requests for AMP pages must contain an `imp` array with exactly one element. It is not necessary to include a `tmax` field in the Stored Request, as Prebid Server will always use the smaller of the AMP default timeout (1000ms) and the value passed via the `timeoutMillis` field of the `amp-ad.rtc-config`. - -An example Stored Request is given below: - -``` -{ - "id": "some-request-id", - "site": { - "page": "prebid.org" - }, - "ext": { - "prebid": { - "targeting": { - "pricegranularity": { // This is equivalent to the deprecated "pricegranularity": "medium" - "precision": 2, - "ranges": [{ - "max": 20.00, - "increment": 0.10 - }] - } - } - } - }, - "imp": [ - { - "id": "some-impression-id", - "banner": {}, // The sizes are defined is set by your AMP tag query params - "ext": { - "appnexus": { - // Insert parameters here - }, - "rubicon": { - // Insert parameters here - } - } - } - ] -} -``` - -### Response - -A sample response payload looks like this: - -``` -{ - "targeting": { - "hb_bidder": "appnexus", - "hb_bidder_appnexus": "appnexus", - "hb_cache_id": "420d7329-30e8-4c4e-8eaa-fe937172e4e0", - "hb_cache_id_appnexus": "420d7329-30e8-4c4e-8eaa-fe937172e4e0", - "hb_pb": "0.50", - "hb_pb_appnexus": "0.50", - "hb_size": "300x250", - "hb_size_appnexus": "300x250" - } - "errors": { - "openx":[ - { - "code": 1, - "message": "The request exceeded the timeout allocated" - } - ] - } -} -``` - -In [the typical AMP setup](http://prebid.org/dev-docs/show-prebid-ads-on-amp-pages.html), -these targeting params will be sent to DFP. - -Note that "errors" will only appear if there were any errors generated. They are identical to the "errors" field in the response.ext of the OpenRTB endpoint. - -### Query Parameters - -This endpoint supports the following query parameters: - -1. `h` - `amp-ad` `height` -2. `w` - `amp-ad` `width` -3. `oh` - `amp-ad` `data-override-height` -4. `ow` - `amp-ad` `data-override-width` -5. `ms` - `amp-ad` `data-multi-size` -6. `curl` - the canonical URL of the page -7. `timeout` - the publisher-specified timeout for the RTC callout - - A configuration option `amp_timeout_adjustment_ms` may be set to account for estimated latency so that Prebid Server can handle timeouts from adapters and respond to the AMP RTC request before it times out. -8. `debug` - When set to `1`, the response will contain extra info for debugging. - -For information on how these get from AMP into this endpoint, see [this pull request adding the query params to the Prebid callout](https://github.com/ampproject/amphtml/pull/14155) and [this issue adding support for network-level RTC macros](https://github.com/ampproject/amphtml/issues/12374). - -If present, these will override parts of your Stored Request. - -1. `ow`, `oh`, `w`, `h`, and/or `ms` will be used to set `request.imp[0].banner.format` if `request.imp[0].banner` is present. -2. `curl` will be used to set `request.site.page` -3. `timeout` will generally be used to set `request.tmax`. However, the Prebid Server host can [configure](../../developers/configuration.md) their deploy to reduce this timeout for technical reasons. -4. `debug` will be used to set `request.test`, causing the `response.debug` to have extra debugging info in it. - -### Resolving Sizes - -We strive to return ads with sizes which are valid for the `amp-ad` on your page. This logic intends to -track the logic used by `doubleclick` when resolving sizes used to fetch ads from their ad server. - -Specifically: - -1. If `ow` and `oh` exist, `request.imp[0].banner.format` will be a single element with `w: ow` and `h: oh` -2. If `ow` and `h` exist, `request.imp[0].banner.format` will be a single element with `w: ow` and `h: h` -3. If `oh` and `w` exist, `request.imp[0].banner.format` will be a single element with `w: w` and `h: oh` -4. If `ms` exists, `request.imp[0].banner.format` will contain an element for every size it uses. -5. If `w` and `h` exist, `request.imp[0].banner.format` will be a single element with `w: w` and `h: h` -6. If `w` _or_ `h` exist, it will be used to override _one_ of the dimensions inside each element of `request.imp[0].banner.format` -7. If none of these exist then the Stored Request values for `request.imp[0].banner.format` will be used without modification. diff --git a/docs/endpoints/openrtb2/auction.md b/docs/endpoints/openrtb2/auction.md deleted file mode 100644 index b532923e793..00000000000 --- a/docs/endpoints/openrtb2/auction.md +++ /dev/null @@ -1,789 +0,0 @@ -# Prebid Server Auction Endpoint - -This document describes the behavior of the Prebid Server auction endpoint, including: - -- Request/response formats -- OpenRTB extensions -- Debugging and performance tips -- How user syncing works -- Departures from OpenRTB - -## `POST /openrtb2/auction` - -This endpoint runs an auction with the given OpenRTB 2.5 bid request. - -### Sample request - -This is a sample OpenRTB 2.5 bid request for a Xandr (formerly AppNexus) test placement. Please note, the Xandr Ad Server will only -respond with a bid if the "test" field is set to 1. - -``` -{ - "id": "some-request-id", - "test": 1, - "site": { - "page": "prebid.org" - }, - "imp": [{ - "id": "some-impression-id", - "banner": { - "format": [{ - "w": 600, - "h": 500 - }, { - "w": 300, - "h": 600 - }] - }, - "ext": { - "appnexus": { - "placementId": 12883451 - } - } - }], - "tmax": 500 -} -``` - -Additional examples can be found in [endpoints/openrtb2/sample-requests/valid-whole](../../../endpoints/openrtb2/sample-requests/valid-whole). - -### Sample Response - -This endpoint will respond with either: - -- An OpenRTB 2.5 bid response, or -- HTTP 400 if the request is malformed, or -- HTTP 503 if the account or app specified in the request is blacklisted - -This is the corresponding response to the above sample OpenRTB 2.5 bid request, with the `ext.debug` field removed and the `seatbid.bid.adm` field simplified. - -``` -{ - "id": "some-request-id", - "seatbid": [{ - "seat": "appnexus", - "bid": [{ - "id": "145556724130495288", - "impid": "some-impression-id", - "price": 0.01, - "adm": "", - "adid": "107987536", - "adomain": [ - "appnexus.com" - ], - "iurl": "https://nym1-ib.adnxs.com/cr?id=107987536", - "cid": "3532", - "crid": "107987536", - "w": 600, - "h": 500, - "ext": { - "prebid": { - "type": "banner", - "video": { - "duration": 0, - "primary_category": "" - } - }, - "bidder": { - "appnexus": { - "brand_id": 1, - "auction_id": 7311907164510136364, - "bidder_id": 2, - "bid_ad_type": 0 - } - } - } - }] - }], - "cur": "USD", - "ext": { - "responsetimemillis": { - "appnexus": 10 - }, - "tmaxrequest": 500 - } -} -``` - -### OpenRTB Extensions - -#### Conventions - -OpenRTB 2.5 permits exchanges to define their own extensions to any object from the spec. -These fall under the `ext` field of JSON objects. - -If `ext` is defined on an object, Prebid Server uses the following conventions: - -1. `ext` in "request objects" uses `ext.prebid` and/or `ext.{anyBidderCode}`. -2. `ext` on "response objects" uses `ext.prebid` and/or `ext.bidder`. -The only exception here is the top-level `BidResponse`, because it's bidder-independent. - -`ext.{anyBidderCode}` and `ext.bidder` extensions are defined by bidders. -`ext.prebid` extensions are defined by Prebid Server. - -Exceptions are made for extensions with "standard" recommendations: - -- `request.user.ext.digitrust` -- To support Digitrust -- `request.regs.ext.gdpr` and `request.user.ext.consent` -- To support GDPR -- `request.regs.us_privacy` -- To support CCPA -- `request.site.ext.amp` -- To identify AMP as the request source -- `request.app.ext.source` and `request.app.ext.version` -- To support identifying the displaymanager/SDK in mobile apps. If given, we expect these to be strings. - -#### Bid Adjustments - -Bidders [are encouraged](../../developers/add-new-bidder.md) to make Net bids. However, there's no way for Prebid to enforce this. -If you find that some bidders use Gross bids, publishers can adjust for it with `request.ext.prebid.bidadjustmentfactors`: - -``` -{ - "ext": { - "prebid": { - "bidadjustmentfactors": { - "appnexus": 0.8, - "rubicon": 0.7 - } - } - } -} -``` - -This may also be useful for publishers who want to account for different discrepancies with different bidders. - -#### Targeting - -Targeting refers to strings which are sent to the adserver to -[make header bidding possible](http://prebid.org/overview/intro.html#how-does-prebid-work). - -`request.ext.prebid.targeting` is an optional property which causes Prebid Server -to set these params on the response at `response.seatbid[i].bid[j].ext.prebid.targeting`. - -**Request format** (optional param `request.ext.prebid.targeting`) - -``` -{ - "ext": { - "prebid": { - "targeting": { - "pricegranularity": { - "precision": 2, - "ranges": [{ - "max": 20.00, - "increment": 0.10 // This is equivalent to the deprecated "pricegranularity": "medium" - }] - }, - "includewinners": false, // Optional param defaulting to true - "includebidderkeys": false // Optional param defaulting to true - "includeformat": false // Optional param defaulting to false - } - } - } -} -``` -The list of price granularity ranges must be given in order of increasing `max` values. If `precision` is omitted, it will default to `2`. The minimum of a range will be 0 or the previous `max`. Any cmp above the largest `max` will go in the `max` pricebucket. - -For backwards compatibility the following strings will also be allowed as price granularity definitions. There is no guarantee that these will be honored in the future. "One of ['low', 'med', 'high', 'auto', 'dense']" See [price granularity definitions](http://prebid.org/prebid-mobile/adops-price-granularity.html) - -One of "includewinners" or "includebidderkeys" must be true (both default to true if unset). If both were false, then no targeting keys would be set, which is better configured by omitting targeting altogether. - -The parameter "includeformat" indicates the type of the bid (banner, video, etc) for multiformat requests. It will add the key `hb_format` and/or `hb_format_{bidderName}` as per "includewinners" and "includebidderkeys" above. - -MediaType PriceGranularity (PBS-Java only) - when a single OpenRTB request contains multiple impressions with different mediatypes, or a single impression supports multiple formats, the different mediatypes may need different price granularities. If `mediatypepricegranularity` is present, `pricegranularity` would only be used for any mediatypes not specified. - -``` -{ - "ext": { - "prebid": { - "targeting": { - "mediatypepricegranularity": { - "banner": { - "ranges": [ - {"max": 20, "increment": 0.5} - ] - }, - "video": { - "ranges": [ - {"max": 10, "increment": 1}, - {"max": 20, "increment": 2}, - {"max": 50, "increment": 5} - ] - } - } - }, - "includewinners": true - } - } -} -``` - -**Response format** (returned in `bid.ext.prebid.targeting`) - -``` -{ - "seatbid": [{ - "bid": [{ - ... - "ext": { - "prebid": { - "targeting": { - "hb_bidder_{bidderName}": "The seatbid.seat which contains this bid", - "hb_size_{bidderName}": "A string like '300x250' using bid.w and bid.h for this bid", - "hb_pb_{bidderName}": "The bid.cpm, rounded down based on the price granularity." - } - } - } - }] - }] -} -``` - -The winning bid for each `request.imp[i]` will also contain `hb_bidder`, `hb_size`, and `hb_pb` -(with _no_ {bidderName} suffix). To prevent these keys, set `request.ext.prebid.targeting.includeWinners` to false. - -**NOTE**: Targeting keys are limited to 20 characters. If {bidderName} is too long, the returned key -will be truncated to only include the first 20 characters. - -#### Cookie syncs - -Each Bidder should receive their own ID in the `request.user.buyeruid` property. -Prebid Server has three ways to populate this field. In order of priority: - -1. If the request payload contains `request.user.buyeruid`, then that value will be sent to all Bidders. -In most cases, this is probably a bad idea. - -2. The request payload can store a `buyeruid` for each Bidder by defining `request.user.ext.prebid.buyeruids` like so: - -``` -{ - "user": { - "ext": { - "prebid": { - "buyeruids": { - "appnexus": "some-appnexus-id", - "rubicon": "some-rubicon-id" - } - } - } - } -} -``` - -Prebid Server's core logic will preprocess the request so that each Bidder sees their own value in the `request.user.buyeruid` field. - -3. Prebid Server will use its Cookie to map IDs for each Bidder. - -If you're using [Prebid.js](https://github.com/prebid/Prebid.js), this is happening automatically. - -If you're using another client, you can populate the Cookie of the Prebid Server host with User IDs -for each Bidder by using the `/cookie_sync` endpoint, and calling the URLs that it returns in the response. - -#### Native Request - -For each native request, the `assets` object's `id` field must not be defined. Prebid Server will set this automatically, using the index of the asset in the array as the ID. - - -#### Bidder Aliases - -Requests can define Bidder aliases if they want to refer to a Bidder by a separate name. -This can be used to request bids from the same Bidder with different params. For example: - -``` -{ - "imp": [{ - "id": "some-impression-id", - "video": { - "mimes": ["video/mp4"] - }, - "ext": { - "appnexus": { - "placementId": 123 - }, - "districtm": { - "placementId": 456 - } - } - }], - "ext": { - "prebid": { - "aliases": { - "districtm": "appnexus" - } - } - } -} -``` - -For all intents and purposes, the alias will be treated as another Bidder. This new Bidder will behave exactly -like the original, except that the Response will contain separate SeatBids, and any Targeting keys -will be formed using the alias' name. - -If an alias overlaps with a core Bidder's name, then the alias will take precedence. -This prevents breaking API changes as new Bidders are added to the project. - -For example, if the Request defines an alias like this: - -``` - "aliases": { - "appnexus": "rubicon" - } -``` - -then any `imp.ext.appnexus` params will actually go to the **rubicon** adapter. -It will become impossible to fetch bids from AppNexus within that Request. - -#### Bidder Response Times - -`response.ext.responsetimemillis.{bidderName}` tells how long each bidder took to respond. -These can help quantify the performance impact of "the slowest bidder." - -#### Bidder Errors - -`response.ext.errors.{bidderName}` contains messages which describe why a request may be "suboptimal". -For example, suppose a `banner` and a `video` impression are offered to a bidder -which only supports `banner`. - -In cases like these, the bidder can ignore the `video` impression and bid on the `banner` one. -However, the publisher can improve performance by only offering impressions which the bidder supports. - -For example, a request may return this in `response.ext` - -``` -{ - "ext": { - "errors": { - "appnexus": [{ - "code": 2, - "message": "A hybrid Banner/Audio Imp was offered, but Appnexus doesn't support Audio." - }], - "rubicon": [{ - "code": 1, - "message": "The request exceeded the timeout allocated" - }] - } - } -} -``` - -The codes currently defined are: - -``` -0 NoErrorCode -1 TimeoutCode -2 BadInputCode -3 BadServerResponseCode -999 UnknownErrorCode -``` - -#### Debugging - -`response.ext.debug.httpcalls.{bidder}` will be populated **only if** `request.test` **was set to 1**. - -This contains info about every request and response sent by the bidder to its server. -It is only returned on `test` bids for performance reasons, but may be useful during debugging. - -`response.ext.debug.resolvedrequest` will be populated **only if** `request.test` **was set to 1**. - -This contains the request after the resolution of stored requests and implicit information (e.g. site domain, device user agent). - -#### Stored Requests - -`request.imp[i].ext.prebid.storedrequest` incorporates a [Stored Request](../../developers/stored-requests.md) from the server. - -A typical `storedrequest` value looks like this: - -``` -{ - "imp": [{ - "ext": { - "prebid": { - "storedrequest": { - "id": "some-id" - } - } - } - }] -} -``` - -For more information, see the docs for [Stored Requests](../../developers/stored-requests.md). - -#### Cache bids - -Bids can be temporarily cached on the server by sending the following data as `request.ext.prebid.cache`: - -``` -{ - "ext": { - "prebid": { - "cache": { - "bids": {}, - "vastxml": {} - } - } - } -} -``` - -Both `bids` and `vastxml` are optional, but one of the two is required if you want to cache bids. This property will have no effect -unless `request.ext.prebid.targeting` is also set in the request. - -If `bids` is present, Prebid Server will make a _best effort_ to include these extra -`bid.ext.prebid.targeting` keys: - -- `hb_cache_id`: On the highest overall Bid in each Imp. -- `hb_cache_id_{bidderName}`: On the highest Bid from {bidderName} in each Imp. - -Clients _should not assume_ that these keys will exist, just because they were requested, though. -If they exist, the value will be a UUID which can be used to fetch Bid JSON from [Prebid Cache](https://github.com/prebid/prebid-cache). -They may not exist if the host company's cache is full, having connection problems, or other issues like that. - -If `vastxml` is present, PBS will try to add analogous keys `hb_uuid` and `hb_uuid_{bidderName}`. -In addition to the caveats above, these will exist _only if the relevant Bids are for Video_. -If they exist, the values can be used to fetch the bid's VAST XML from Prebid Cache directly. - -These options are mainly intended for certain limited Prebid Mobile setups, where bids cannot be cached client-side. - -#### GDPR - -Prebid Server supports the IAB's GDPR recommendations, which can be found [here](https://iabtechlab.com/wp-content/uploads/2018/02/OpenRTB_Advisory_GDPR_2018-02.pdf). - -This adds two optional properties: - -- `request.user.ext.consent`: Is the consent string required by the IAB standards. -- `request.regs.ext.gdpr`: Is 0 if the caller believes that the user is *not* under GDPR, 1 if the user *is* under GDPR, and undefined if we're not certain. - -These fields will be forwarded to each Bidder, so they can decide how to process them. - -#### Interstitial support -Additional support for interstitials is enabled through the addition of two fields to the request: -device.ext.prebid.interstitial.minwidthperc and device.ext.interstial.minheightperc -The values will be numbers that indicate the minimum allowed size for the ad, as a percentage of the base side. For example, a width of 600 and "minwidthperc": 60 would allow ads with widths from 360 to 600 pixels inclusive. - -Example: -``` -{ - "imp": [{ - ... - "banner": { - ... - } - "instl": 1, - ... - }] - "device": { - ... - "h": 640, - "w": 320, - "ext": { - "prebid": { - "interstitial": { - "minwidthperc": 60, - "minheightperc": 60 - } - } - } - } -} -``` - -PBS receiving a request for an interstitial imp and these parameters set, it will rewrite the format object within the interstitial imp. If the format array's first object is a size, PBS will take it as the max size for the interstitial. If that size is 1x1, it will look up the device's size and use that as the max size. If the format is not present, it will also use the device size as the max size. (1x1 support so that you don't have to omit the format object to use the device size) -PBS with interstitial support will come preconfigured with a list of common ad sizes. Preferentially organized by weighing the larger and more common sizes first. But no guarantees to the ordering will be made. PBS will generate a new format list for the interstitial imp by traversing this list and picking the first 10 sizes that fall within the imp's max size and minimum percentage size. There will be no attempt to favor aspect ratios closer to the original size's aspect ratio. The limit of 10 is enforced to ensure we don't overload bidders with an overlong list. All the interstitial parameters will still be passed to the bidders, so they may recognize them and use their own size matching algorithms if they prefer. - -#### Currency Support - -To set the desired 'ad server currency', use the standard OpenRTB `cur` attribute. Note that Prebid Server only looks at the first currency in the array. - -``` - "cur": ["USD"] -``` - -If you want or need to define currency conversion rates (e.g. for currencies that your Prebid Server doesn't support), -define ext.prebid.currency.rates. (Currently supported in PBS-Java only) - -``` -"ext": { - "prebid": { - "currency": { - "rates": { - "USD": { "UAH": 24.47, "ETB": 32.04 } - } - } - } -} -``` - -If it exists, a rate defined in ext.prebid.currency.rates has the highest priority. -If a currency rate doesn't exist in the request, the external file will be used. - -#### Supply Chain Support - - -Basic supply chains are passed to Prebid Server on `source.ext.schain` and passed through to bid adapters. Prebid Server does not currently offer the ability to add a node to the supply chain. - -Bidder-specific schains (PBS-Java only): - -``` -ext.prebid.schains: [ - { bidders: ["bidderA"], schain: { SCHAIN OBJECT 1}}, - { bidders: ["*"], schain: { SCHAIN OBJECT 2}} -] -``` -In this scenario, Prebid Server sends the first schain object to `bidderA` and the second schain object to everyone else. - -If there's already an source.ext.schain and a bidder is named in ext.prebid.schains (or covered by the wildcard condition), ext.prebid.schains takes precedent. - -#### Rewarded Video (PBS-Java only) - -Rewarded video is a way to incentivize users to watch ads by giving them 'points' for viewing an ad. A Prebid Server -client can declare a given adunit as eligible for rewards by declaring `imp.ext.prebid.is_rewarded_inventory:1`. - -#### Stored Responses (PBS-Java only) - -While testing SDK and video integrations, it's important, but often difficult, to get consistent responses back from bidders that cover a range of scenarios like different CPM values, deals, etc. Prebid Server supports a debugging workflow in two ways: - -- a stored-auction-response that covers multiple bidder responses -- multiple stored-bid-responses at the bidder adapter level - -**Single Stored Auction Response ID** - -When a storedauctionresponse ID is specified: - -- the rest of the ext.prebid block is irrelevant and ignored -- nothing is sent to any bidder adapter for that imp -- the response retrieved from the stored-response-id is assumed to be the entire contents of the seatbid object corresponding to that impression. - -This request: -``` -{ - "test":1, - "tmax":500, - "id": "test-auction-id", - "app": { ... }, - "ext": { - "prebid": { - "targeting": {}, - "cache": { "bids": {} } - } - }, - "imp": [ - { - "id": "a", - "ext": { "prebid": { "storedauctionresponse": { "id": "1111111111" } } } - }, - { - "id": "b", - "ext": { "prebid": { "storedauctionresponse": { "id": "22222222222" } } } - } - ] -} -``` - -Will result in this response, assuming that the ids exist in the appropriate DB table read by Prebid Server: -``` -{ - "id": "test-auction-id", - "seatbid": [ - { - // BidderA bids from storedauctionresponse=1111111111 - // BidderA bids from storedauctionresponse=22222222 - }, - { - // BidderB bids from storedauctionresponse=1111111111 - // BidderB bids from storedauctionresponse=22222222 - } - ] -} -``` - -**Multiple Stored Bid Response IDs** - -In contrast to what's outlined above, this approach lets some real auctions take place while some bidders have test responses that still exercise bidder code. For example, this request: - -``` -{ - "test":1, - "tmax":500, - "id": "test-auction-id", - "app": { ... }, - "ext": { - "prebid": { - "targeting": {}, - "cache": { "bids": {} } - } - }, - "imp": [ - { - "id": "a", - "ext": { - "prebid": { - "storedbidresponse": [ - { "bidder": "BidderA", "id": "333333" }, - { "bidder": "BidderB", "id": "444444" }, - ] - } - } - }, - { - "id": "b", - "ext": { - "prebid": { - "storedbidresponse": [ - { "bidder": "BidderA", "id": "5555555" }, - { "bidder": "BidderB", "id": "6666666" }, - ] - } - } - } - ] -} -``` -Could result in this response: - -``` -{ - "id": "test-auction-id", - "seatbid": [ - { - "bid": [ - // contents of storedbidresponse=3333333 as parsed by bidderA adapter - // contents of storedbidresponse=5555555 as parsed by bidderA adapter - ] - }, - { - // contents of storedbidresponse=4444444 as parsed by bidderB adapter - // contents of storedbidresponse=6666666 as parsed by bidderB adapter - } - ] -} -``` - -Setting up the storedresponse DB entries is the responsibility of each Prebid Server host company. - -See Prebid.org troubleshooting pages for how to utilize this feature within the context of the browser. - - -#### User IDs (PBS-Java only) - -Prebid Server adapters can support the [Prebid.js User ID modules](http://prebid.org/dev-docs/modules/userId.html) by reading the following extensions and passing them through to their server endpoints: - -``` -{ - "user": { - "ext": { - "eids": [{ - "source": "adserver.org", - "uids": [{ - "id": "111111111111", - "ext": { - "rtiPartner": "TDID" - } - }] - }, - { - "source": "pubcommon", - "id":"11111111" - } - ], - "digitrust": { - "id": "11111111111", - "keyv": 4 - } - } - } -} -``` - -#### First Party Data Support (PBS-Java only) - -This is the Prebid Server version of the Prebid.js First Party Data feature. It's a standard way for the page (or app) to supply first party data and control which bidders have access to it. - -It specifies where in the OpenRTB request non-standard attributes should be passed. For example: - -``` -{ - "ext": { - "prebid": { - "data": { "bidders": [ "rubicon", "appnexus" ] } // these are the bidders allowed to see protected data - } - }, - "site": { - "keywords": "", - "search": "", - "ext": { - data: { GLOBAL CONTEXT DATA } // only seen by bidders named in ext.prebid.data.bidders[] - } - }, - "user": { - "keywords": "", - "gender": "", - "yob": 1999, - "geo": {}, - "ext": { - data: { GLOBAL USER DATA } // only seen by bidders named in ext.prebid.data.bidders[] - } - }, - "imp": [ - "ext": { - "context": { - "keywords": "", - "search": "", - "data": { ADUNIT SPECFIC CONTEXT DATA } // can be seen by all bidders - } - } - ] -``` - -Prebid Server enforces the data permissioning - -So before passing the values to the bidder adapters, core will: - -1. check for ext.prebid.data.bidders -1. if it exists, store it locally, but remove it from the OpenRTB before being sent to the adapters -1. As the OpenRTB request is being sent to each adapter: - 1. if ext.prebid.data.bidders exists in the original request, and this bidder is on the list then copy site.ext.data, app.ext.data, and user.ext.data to their bidder request -- otherwise don't copy those blocks - 1. copy other objects as normal - -Each adapter must be coded to read the values from these locations and pass it to their endpoints appropriately. - -### OpenRTB Ambiguities - -This section describes the ways in which Prebid Server **implements** OpenRTB spec ambiguous parts. - -- `request.cur`: If `request.cur` is not specified in the bid request, Prebid Server will consider it as being `USD` whereas OpenRTB spec doesn't mention any default currency for bid request. -```request.cur: ['USD'] // Default value if not set``` - - -### OpenRTB Differences - -This section describes the ways in which Prebid Server **breaks** the OpenRTB spec. - -#### Allowed Bidders - -Prebid Server returns a 400 on requests which define `wseat` or `bseat`. -We may add support for these in the future, if there's compelling need. - -Instead, an impression is only offered to a bidder if `bidrequest.imp[i].ext.{bidderName}` exists. - -This supports publishers who want to sell different impressions to different bidders. - -#### Deprecated Properties - -This endpoint returns a 400 if the request contains deprecated properties (e.g. `imp.wmin`, `imp.hmax`). - -The error message in the response should describe how to "fix" the request to make it legal. -If the message is unclear, please [log an issue](https://github.com/prebid/prebid-server/issues) -or [submit a pull request](https://github.com/prebid/prebid-server/pulls) to improve it. - -#### Determining Bid Security (http/https) - -In the OpenRTB spec, `request.imp[i].secure` says: - -> Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, -> where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure -> HTTP support can be assumed. - -In Prebid Server, an `https` request which does not define `secure` will be forwarded to Bidders with a `1`. -Publishers who run `https` sites and want insecure ads can still set this to `0` explicitly. - -### See also - -- [The OpenRTB 2.5 spec](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) diff --git a/docs/endpoints/setuid.md b/docs/endpoints/setuid.md deleted file mode 100644 index c1746806371..00000000000 --- a/docs/endpoints/setuid.md +++ /dev/null @@ -1,26 +0,0 @@ -# Saving User Syncs - -This endpoint is used during cookie syncs. For technical details, see the -[Cookie Sync developer docs](../developers/cookie-syncs.md). - -## `GET /setuid` - -This endpoint saves a UserID for a Bidder in the Cookie. Saved IDs will be recognized for 7 days before being considered "stale" and being re-synced. - -### Query Params - -- `bidder`: The FamilyName of the [Usersyncer](../../usersync/usersync.go) which is being synced. -- `uid`: The ID which the Bidder uses to recognize this user. If undefined, the UID for `bidder` will be deleted. -- `gdpr`: This should be `1` if GDPR is in effect, `0` if not, and undefined if the caller isn't sure -- `gdpr_consent`: This is required if `gdpr` is one, and optional (but encouraged) otherwise. If present, it should be an [unpadded base64-URL](https://tools.ietf.org/html/rfc4648#page-7) encoded [Vendor Consent String](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md#vendor-consent-string-format-). - -If the `gdpr` and `gdpr_consent` params are included, this endpoint will _not_ write a cookie unless: - -1. The Vendor ID set by the Prebid Server host company has permission to save cookies for that user. -2. The Prebid Server host company did not configure it to run with GDPR support. - -If in doubt, contact the company hosting Prebid Server and ask if they're GDPR-ready. - -### Sample request - -`GET http://prebid.site.com/setuid?bidder=adnxs&uid=12345&gdpr=1&gdpr_consent=BONciguONcjGKADACHENAOLS1rAHDAFAAEAASABQAMwAeACEAFw` diff --git a/docs/endpoints/status.md b/docs/endpoints/status.md deleted file mode 100644 index 0c252397423..00000000000 --- a/docs/endpoints/status.md +++ /dev/null @@ -1,9 +0,0 @@ -## `GET /status` - -This endpoint will return a 2xx response whenever Prebid Server is ready to serve requests. -Its exact response can be [configured](../developers/configuration.md) with the `status_response` -config option. For example, in `pbs.yaml`: - -```yaml -status_response: "ok" -```