diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 5a509cee5d..1e2ab8ffb8 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -257,14 +257,6 @@ sectionTitle: subgroup: 1 -- sbSecId: 1 - title: Legacy Browser Example - link: /dev-docs/examples/legacy-browser-example.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 1 - - sbSecId: 1 title: Using Prebid.js with Microsoft Monetize Ad Server link: /dev-docs/examples/use-prebid-with-appnexus-ad-server.html diff --git a/dev-docs/analytics/concert.md b/dev-docs/analytics/concert.md index 31c3e77971..78c7b33ebf 100644 --- a/dev-docs/analytics/concert.md +++ b/dev-docs/analytics/concert.md @@ -4,8 +4,21 @@ title: Concert description: Concert Analytics Adapter modulecode: concert enable_download: false +prebid_member: false +tcfeu_supported: false +usp_supported: true +gvl_id: N/A +coppa_supported: false --- #### Registration -Please visit [concert.io](https://concert.io/) for more information. +The Concert analytics adapter requires setup and approval from the Concert team. Please reach out to or visit [concert.io](https://concert.io/) for more information. + +### Example Configuration + +```javascript + pbjs.enableAnalytics({ + provider: 'concert', + }); +``` diff --git a/dev-docs/bidders/adnuntius.md b/dev-docs/bidders/adnuntius.md index d0a04091e8..d720931716 100644 --- a/dev-docs/bidders/adnuntius.md +++ b/dev-docs/bidders/adnuntius.md @@ -86,9 +86,9 @@ pbjs.setBidderConfig({ }); ``` -### Disable cookies for adnuntius +### Disable cookies for Adnuntius -You have the option to tell adnuntius not to set cookies in your browser. This does not mean that third party ads being served through the ad server will not set cookies. Just that Adnuintius will not set it for internal ads. +You have the option to tell adnuntius not to set cookies in your browser. This does not mean that third party ads being served through the ad server will not set cookies. Just that Adnuntius will not set it for internal ads. ```js pbjs.setBidderConfig({ @@ -101,6 +101,21 @@ pbjs.setBidderConfig({ Use cookie will always be set to true by default. Changing it to false will disable cookies. +### Trigger Advertiser Transparency Mode in Adnuntius + +You have the option to tell Adnuntius to only serve ads that have their Advertiser's legal name specified. + +```js +pbjs.setBidderConfig({ + bidders: ['adnuntius'], + config: { + advertiserTransparency: true + } +}); +``` + +By default, `advertiserTransparency` is set to `false`, meaning there is no restriction on which ads can deliver. By setting `advertiserTransparency` to `true`, ad delivery is restricted to those that have their Advertiser's legal name specified. + ### Prebid Server Test Request The following test parameters can be used to verify that Prebid Server is working properly with the server-side Adnuntius adapter. the `auId` below will not return a creative. Please substitute it with your own. diff --git a/dev-docs/bidders/blasto.md b/dev-docs/bidders/blasto.md index 215257b2e9..cda556c3a6 100644 --- a/dev-docs/bidders/blasto.md +++ b/dev-docs/bidders/blasto.md @@ -25,17 +25,18 @@ userIds: all ### Note -The Example Bidding adapter requires setup before beginning. Please contact us at . Blasto will only respond to the first impression and that multiple ad formats of that single impression are not supported. +The Example Bidding adapter requires setup before beginning. Please contact us at . +Blasto will only respond to the first impression. -### Bid Params for Prebid Server and Prebid Mobile +### Bid Params for Prebid Server +Blasto supports diffrent regions for the prebid server. By default US East. +Please deploy the prebid config in each of your datacenters with the appropriate regional subdomain. {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|-----------------------|-----------|-----------| | `sourceId` | required | Unique hash provided by blasto | `'6dllcEHSxYdSb6yLmCqE'` | `string` | | `accountId` | required | Unique name provided by blasto | `'blasto-test'` | `string` | -| `host` | optional | Blasto server region. US East by default | `'us-e-node1'` | `string` | -| `placementId` | required | Deprecated parameter. Please use sourceId instead |`'6dllcEHSxYdSb6yLmCqE'`|`string` | ### Bid Params for Prebid.js diff --git a/dev-docs/bidders/cointraffic.md b/dev-docs/bidders/cointraffic.md index 336d71f251..e97e89fdf6 100644 --- a/dev-docs/bidders/cointraffic.md +++ b/dev-docs/bidders/cointraffic.md @@ -3,6 +3,7 @@ layout: bidder title: Cointraffic description: Prebid Cointraffic Bidder Adaptor pbjs: true +pbs: true biddercode: cointraffic sidebarType: 1 --- diff --git a/dev-docs/bidders/colossus.md b/dev-docs/bidders/colossus.md index a377f317eb..4b16843149 100644 --- a/dev-docs/bidders/colossus.md +++ b/dev-docs/bidders/colossus.md @@ -14,10 +14,6 @@ pbs_app_supported: true sidebarType: 1 --- -### Disclosure - -This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. - ### Prebid.Server Bid Params {: .table .table-bordered .table-striped } diff --git a/dev-docs/bidders/colossusssp.md b/dev-docs/bidders/colossusssp.md index 4edb102200..57d78f1ab9 100644 --- a/dev-docs/bidders/colossusssp.md +++ b/dev-docs/bidders/colossusssp.md @@ -22,4 +22,4 @@ sidebarType: 1 | `group_id` | optional | Group Id will be generated on Colossus SSP Platform. Use instead of placement_id | `0` | `integer` | | `traffic` | optional | Type traffic | `'banner'` | `string` | -*For colossus prebid server parametres, look into colossus.md* +*For colossus prebid server parameters, look into colossus.md* diff --git a/dev-docs/bidders/concert.md b/dev-docs/bidders/concert.md index 40f627720a..fa2c3f1bdf 100644 --- a/dev-docs/bidders/concert.md +++ b/dev-docs/bidders/concert.md @@ -4,8 +4,11 @@ title: Concert description: Prebid Concert Bidder Adaptor hide: true pbjs: true +pbs: true biddercode: concert -media_types: banner +media_types: banner, audio, video +pbs_app_supported: true +deals_supported: true tcfeu_supported: false usp_supported: true gpp_supported: true diff --git a/dev-docs/bidders/copper6ssp.md b/dev-docs/bidders/copper6ssp.md new file mode 100644 index 0000000000..d9cb4b2f49 --- /dev/null +++ b/dev-docs/bidders/copper6ssp.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: Copper6SSP +description: Prebid Copper6SSP Bidder Adapter +biddercode: copper6ssp +gpp_sids: usstate_all +tcfeu_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true +deals_supported: false +floors_supported: true +fpd_supported: false +ortb_blocking_supported: false +media_types: banner, video, native +multiformat_supported: will-bid-on-one +userIds: all +pbjs: true +pbs: false +pbs_app_supported: true +safeframes_ok: true +sidebarType: 1 +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|--------------|---------------------------------|------------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | + +### Note + +For the prebid server and prebid.js you only need to use one parameter: either placementId or endpointId diff --git a/dev-docs/bidders/inmobi.md b/dev-docs/bidders/inmobi.md index be796ccfc0..456433b46b 100644 --- a/dev-docs/bidders/inmobi.md +++ b/dev-docs/bidders/inmobi.md @@ -21,9 +21,11 @@ For queries, write to us at ### User Sync Disclosure -InMobi has partnered with a third party, ID5, to use their ID as our primary user identifier for mobile web supply. We will also rely on ID5 IDs to handle compliance flows related to Data Subject Right requests in our systems. Hence, we require the publisher to use ID5’s sync URL for user syncing and passing the corresponding ID5 ID to InMobi in the bid request. For this purpose, we provide ID5’s sync URL in our Prebid adapter for User ID sync. Note that, InMobi has a direct contract with ID5 for consuming ID5 ID and the user sync via Prebid does not require the publisher to get into a contractual relationship with ID5. +Third-party cookie syncing helps publishers leverage their audience data, enhance targeting capabilities, and drive better ad performance. InMobi third party cookie syncing improves monetization for publishers by giving them a competitive positioning in the digital advertising ecosystem. +Ids for third parties can be synced through our pixel: `https://sync.inmobi.com/prebid?gdpr={GDPR}&gdpr_consent={GDPR_CONSENT}&us_privacy={US_PRIVACY}&redirect={RedirectURL}` . +The RedirectURL should contain uuid macro, which is {ID5UID}. -To opt out of InMobi ads on mobile web inventory or for any other requests, the user needs to visit the Opt-out page on InMobi website (). For opting out of ID5 ID entirely, the user needs to visit ID5’s opt out page: . +To opt out of InMobi ads on web inventory the user needs to visit the Opt-out page on InMobi website `https://www.inmobi.com/page/opt-out/`. ### Bid Params diff --git a/dev-docs/bidders/kargo.md b/dev-docs/bidders/kargo.md index 9a3d684579..0f83489e7a 100644 --- a/dev-docs/bidders/kargo.md +++ b/dev-docs/bidders/kargo.md @@ -25,10 +25,6 @@ pbjs_version_notes: if you require schains, avoid versions 7.46 to 7.53 sidebarType: 1 --- -### Disclosure - -This adapter is known to use an HTTP 1 endpoint. Header bidding often generates multiple requests to the same host and bidders are encouraged to change to HTTP 2 or above to help improve publisher page performance via multiplexing. - ### Note Kargo is an invitation-only marketplace. Please reach out to your Kargo account manager to get setup. Also, you *must* test on a mobile device, or emulate a mobile device by manipulating the user agent string sent to the server. diff --git a/dev-docs/bidders/markapp.md b/dev-docs/bidders/markapp.md new file mode 100644 index 0000000000..3e427f8119 --- /dev/null +++ b/dev-docs/bidders/markapp.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: MarkApp +description: MarkApp Bidder Adapter +biddercode: markapp +aliasCode : smarthub +usp_supported: true +coppa_supported: true +schain_supported: true +dchain_supported: true +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +floors_supported: true +fpd_supported: false +pbjs: true +pbs: true +pbs_app_supported: true +multiformat_supported: will-bid-on-any +--- + +### Prebid.js Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------|-------------------------------------|-----------| +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | +| `iabCat` | optional | Array of IAB content categories that describe the content producer | `['IAB1-1', 'IAB3-1', 'IAB4-3']` | `Array(String)` | +| `minBidfloor` | optional | Minimal CPM value | `0.03` | `float` | +| `pos` | optional | The position of the placement on the page, see Open RTB spec v2.5. | `4` | `number` | + +### Prebid Server Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------|--------------------------------------|----------| +| `seat` | required | Seat value | `'9Q20EdGxzgWdfPYShScl'` | `string` | +| `token` | required | Token | `'eKmw6alpP3zWQhRCe3flOpz0wpuwRFjW'` | `string` | diff --git a/dev-docs/bidders/mgidX.md b/dev-docs/bidders/mgidX.md index 93bbca96db..d3388edb5a 100644 --- a/dev-docs/bidders/mgidX.md +++ b/dev-docs/bidders/mgidX.md @@ -3,14 +3,18 @@ layout: bidder title: MgidX description: Prebid MgidX Bidder Adapter biddercode: mgidX -usp_supported: true -gdpr_supported: true +gpp_sids: usstate_all tcfeu_supported: true +usp_supported: true coppa_supported: true schain_supported: true +deals_supported: false floors_supported: true +fpd_supported: false +ortb_blocking_supported: false media_types: banner, video, native multiformat_supported: will-not-bid +userIds: all pbjs: true pbs: true pbs_app_supported: true diff --git a/dev-docs/bidders/openweb.md b/dev-docs/bidders/openweb.md index 59c7e50ab1..8f0554cfe7 100644 --- a/dev-docs/bidders/openweb.md +++ b/dev-docs/bidders/openweb.md @@ -13,7 +13,7 @@ gpp_supported: true gpp_sids: tcfeu, usstate_all, usp usp_supported: true safeframes_ok: false -pbs: false +pbs: true floors_supported: true userIds: all fpd_supported: true diff --git a/dev-docs/bidders/admixerwl.md b/dev-docs/bidders/rtbstack.md similarity index 54% rename from dev-docs/bidders/admixerwl.md rename to dev-docs/bidders/rtbstack.md index 8232989500..f5b30d9950 100644 --- a/dev-docs/bidders/admixerwl.md +++ b/dev-docs/bidders/rtbstack.md @@ -1,9 +1,9 @@ --- layout: bidder -title: AdmixerWL +title: RTB Stack description: Prebid AdMixer Bidder Adaptor pbjs: true -biddercode: admixerwl +biddercode: rtbstack aliasCode: admixer media_types: banner, video, native tcfeu_supported: true @@ -18,11 +18,37 @@ multiformat_supported: will-bid-on-any safeframes_ok: true --- +#### Bidder Configuration + +RTB Stack bidder requires bidderURL to be set. Please note that rtbstack bids will not be requested without this config. It must be set before auction starts. + +```js +pbjs.setBidderConfig({ + bidders: ['rtbstack'], + config: { + bidderURL: 'https://us-adx-example.rtb-stack.com/prebid?client=44e2d241-5051-4b58-8ac6-f17e13732339&ssp=3&endpoint=777' + } +}); +``` + ### Bid Params {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------------|----------|--------------------------------------------------------------------------------------------|------------------------------|----------| -| `endpointId` | required | Unique Entity ID. Could be obtained from your account manager. | 51772 | `int` | -| `clientId` | required | Unique Entity ID. Could be obtained from your account manager. | 312 | `int` | +| `tagId` | required |The unique identifier of the ad placement. Will be used for comparison of statistics. | 51772 | `int` | | `kvTargeting` | optional | Key/Value - a pair of the unique values that will be used for the custom targeting option. | {key1: value2, key2: value2} | `object` | + +#### Bid Example + +```js +{ + bidder: 'rtbstack', + params: { + tagId: '12345', + kvTargeting: { + example: 'test' + } + } +} +``` diff --git a/dev-docs/bidders/smilewanted.md b/dev-docs/bidders/smilewanted.md index 42429175b0..4cedc9c33c 100644 --- a/dev-docs/bidders/smilewanted.md +++ b/dev-docs/bidders/smilewanted.md @@ -2,14 +2,22 @@ layout: bidder title: Smile Wanted description: SmileWanted Bidder Adapter -media_types: banner, video -pbjs: true -pbs: true biddercode: smilewanted tcfeu_supported: false +gvl_id: 639 usp_supported: true +coppa_supported: true +schain_supported: true userIds: all -gvl_id: 639 +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +floors_supported: true +pbjs: true +pbs: true +prebid_member: false +multiformat_supported: will-bid-on-one +privacy_sandbox: no sidebarType: 1 --- @@ -37,7 +45,7 @@ You can add `#sw_test_campaign` to the end of any URL. This will have the effect Add the following code to enable user sync. Smile Wanted strongly recommends enabling user syncing through iFrames. This functionality improves partners' user match rates and increases the Smile Wanted bid rate and bid price. Be sure to call `pbjs.setConfig()` only once. -``` +```javascript pbjs.setConfig({ userSync: { iframeEnabled: true, diff --git a/dev-docs/bidders/stailamedia.md b/dev-docs/bidders/stailamedia.md new file mode 100644 index 0000000000..4b09273bbf --- /dev/null +++ b/dev-docs/bidders/stailamedia.md @@ -0,0 +1,31 @@ +--- +layout: bidder +title: stailamedia +description: stailamedia Bidder Adapter +biddercode: stailamedia +aliasCode: appnexus +tcfeu_supported: true +gvl_id: 32 +schain_supported: true +userId: all +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: true +pbs: true +prebid_member: false +multiformat_supported: will-bid-on-any +sidebarType: 1 +--- +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|-----------| +| `placement_id` (PBS+PBJS) or `placementId` (PBJS) | required | Placement id | `'33037108'` | `string` | + +stailamedia is an aliased bidder for AppNexus. + +### Note + +For setup with stailamedia, please reach out to [prebid@stailamedia.com](mailto:prebid@stailamedia.com) diff --git a/dev-docs/bidders/teads.md b/dev-docs/bidders/teads.md index c3f623978a..52b57d77d0 100644 --- a/dev-docs/bidders/teads.md +++ b/dev-docs/bidders/teads.md @@ -25,9 +25,10 @@ fpd_supported: false sidebarType: 1 --- -### Note +### Notes -The Teads Bidding adapter requires setup before beginning. Please contact us on +1. The Teads Bidding adapter requires setup before beginning. Please contact us on +2. When this adapter is enabled and Prebid.js is used in an iOS WebView, the WebView should allow videos to play inline. This is required because the Teads adapter delivers video ads and starts by detecting the autoplay capability of the device. ### Bid Params diff --git a/dev-docs/bidders/vidazoo.md b/dev-docs/bidders/vidazoo.md index a058e6d9af..84cca015f8 100644 --- a/dev-docs/bidders/vidazoo.md +++ b/dev-docs/bidders/vidazoo.md @@ -10,6 +10,7 @@ tcfeu_supported: true gpp_supported: true usp_supported: true pbjs: true +pbs: true sidebarType: 1 --- @@ -19,6 +20,6 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |------------|----------|------------------------------------------------------------------------------------------|------------------------------|----------| | `cId` | required | The connection ID from Vidazoo. | `'562524b21b1c1f08117fc7f9'` | `string` | -| `pId` | required | The publisher ID from Vidazoo. | `'59ac17c192832d0011283fe3'` | `string` | +| `pId` | required | The publisher ID from Vidazoo (pbjs only). | `'59ac17c192832d0011283fe3'` | `string` | | `bidFloor` | optional | The minimum bid value desired. Vidazoo will not respond with bids lower than this value. | `0.90` | `float` | | `subDomain`| optional | Sets the server subdomain, default: 'prebid'. | `'prebid'` | `string` | diff --git a/dev-docs/conditional-ad-units.md b/dev-docs/conditional-ad-units.md index c9069fc25e..ab20a32401 100644 --- a/dev-docs/conditional-ad-units.md +++ b/dev-docs/conditional-ad-units.md @@ -14,7 +14,7 @@ sidebarType: 1 {:.no_toc} -The [global sizeConfig](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-Responsive-Ads) and [Advanced Size Mapping](/dev-docs/modules/sizeMappingV2.html) features are useful for standard responsive ad designs, but a number of other scenarios are supported as well. +The [Size Mapping](/dev-docs/modules/sizeMapping.html) and [Advanced Size Mapping](/dev-docs/modules/sizeMappingV2.html) features are useful for standard responsive ad designs, but a number of other scenarios are supported as well. * TOC {:toc} @@ -31,7 +31,7 @@ See the [Publisher API reference](/dev-docs/publisher-api-reference/setConfig.ht ## Some Bidders Should Be Skipped for Some Devices {: .alert.alert-info :} -See the [Advanced Size Mapping module](/dev-docs/modules/sizeMappingV2.html) for another way to handle this scenario. Note that you must use Advanced Size Mapping for mediaTypes other than banner. +The following example uses [Size Mapping](/dev-docs/modules/sizeMapping.html). See the [Advanced Size Mapping module](/dev-docs/modules/sizeMappingV2.html) for another way to handle this scenario. Note that you must use Advanced Size Mapping for mediaTypes other than banner. Say a particular bidder is focused on mobile phone demand, so it's really not worthwhile to send them requests from display or tablets. @@ -108,7 +108,7 @@ For instance, say that a given bidder wants to define different placements for d | Display | 1111 | | Phones and tablets | 2222 | -### Using the Global sizeConfig Approach (Banner only) +### Using the Size Mapping Approach (Banner only) Assuming the same `sizeConfig` as in the first use case above, the AdUnit would contain bids for both placements, but the conditional `labelAny` is added to them both. This will cause the bid to be fired only if one @@ -191,7 +191,7 @@ var AdUnits = [{ ## Some Ad Unit Auctions Should Be Skipped Entirely for Some Devices Say there's a responsive page where one of the ad units only supports larger sizes, so it doesn't make sense -on phones. To suppress the ad unit for mobile users, we can apply conditional logic to the entire ad unit. Here's an example using the global sizeConfig approach (banner only): +on phones. To suppress the ad unit for mobile users, we can apply conditional logic to the entire ad unit. Here's an example using the size mapping approach (banner only): ```javascript @@ -218,11 +218,10 @@ var AdUnits = [{ } ] }] +``` See the [Advanced Size Mapping module](/dev-docs/modules/sizeMappingV2.html) if you need to do something like this for video. -``` - ## Some Bid Requests Apply Only to Users Originating from Certain Countries Labels aren't constrained to describing device size -- they can be used for many types of conditions the page maywant to define. Besides being defined as part of `sizeConfig`, labels can also be passed into the [`requestBids()`](/dev-docs/publisher-api-reference/requestBids.html) function as an argument. @@ -271,6 +270,6 @@ labels: ## Further Reading -* [Responsive ad designs](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-Responsive-Ads) +* [Size Mapping Module](/dev-docs/modules/sizeMapping.html) * [Advanced Size Mapping Module](/dev-docs/modules/sizeMappingV2.html) * [Using Media Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) diff --git a/dev-docs/examples/legacy-browser-example.md b/dev-docs/examples/legacy-browser-example.md deleted file mode 100644 index cae6e4c6c0..0000000000 --- a/dev-docs/examples/legacy-browser-example.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: example -title: Legacy Browser Support -description: Legacy Browser Support - -sidebarType: 1 - -about: -- In Prebid 6.0, support for legacy browsers is no longer assured. -- Publishers may conditionally deploy the 5.x branch and add polyfills -- One strategy to do this is simply the module/nomodule approach discussed here https://philipwalton.com/articles/deploying-es2015-code-in-production-today/ -- Another strategy is to detect the user agent or the 'currentScript' mechanism as described here https://stackoverflow.com/questions/29987969/how-to-load-a-script-only-in-ie -- Another strategy is to conditionally serve one file or another based on instructions to your cdn - -jsfiddle_link: jsfiddle.net/Prebid_Examples/kqe8L2jf/embedded/html,result - -code_height: 3050 - ---- diff --git a/dev-docs/faq.md b/dev-docs/faq.md index bfa14e5e4f..41d2426188 100644 --- a/dev-docs/faq.md +++ b/dev-docs/faq.md @@ -10,7 +10,7 @@ sidebarType: 1 This page has answers to some frequently asked questions about Prebid.js. If you don't find what you're looking for here, there are other ways to [get help](/support/index.html). -* TOC +- TOC {:toc} ## General @@ -19,8 +19,8 @@ This page has answers to some frequently asked questions about Prebid.js. If yo Nope. The only approval process is a code review. There are separate instructions for: -* [adding a bidder in Prebid.js](/dev-docs/bidder-adaptor.html) -* [adding an analytics adapter in Prebid.js](/dev-docs/integrate-with-the-prebid-analytics-api.html) +- [adding a bidder in Prebid.js](/dev-docs/bidder-adaptor.html) +- [adding an analytics adapter in Prebid.js](/dev-docs/integrate-with-the-prebid-analytics-api.html) As for [membership](https://prebid.org/membership/) in Prebid.org, that's entirely optional -- we'd be happy to have you join and participate in the various committees, but it's not necessary for contributing code as a community member. @@ -37,8 +37,8 @@ Prebid.org does not support any version of Prebid.js prior to the previous versi We would love for Amazon to contribute a TAM adapter, but so far that's not happened. Publishers that want to sync IDs across multiple header bidding wrappers should be aware of these resources: -* You can generate the auctionId parameter outside of Prebid and pass it when calling [pbjs.requestBids()](/dev-docs/publisher-api-reference/requestBids.html) -* [Example of Synchronizing Transaction IDs with Another Library](/dev-docs/examples/sync-tid.html) +- You can generate the auctionId parameter outside of Prebid and pass it when calling [pbjs.requestBids()](/dev-docs/publisher-api-reference/requestBids.html) +- [Example of Synchronizing Transaction IDs with Another Library](/dev-docs/examples/sync-tid.html) ### Should Prebid bidders be in ads.txt? @@ -55,34 +55,47 @@ To get started, first talk to your lawyers to determine your legal obligations. After you’ve determined your legal obligations, consider the tools Prebid makes available to publishers so that their pages can determine what actions are needed based on their interpretation of the user’s actions and the company’s policies: -* Consider utilizing an [Activity Control](/dev-docs/activity-controls.html). These are available with Prebid.js 7.48 and may help cover a number of common privacy concerns. -* Turn off Prebid.js usersync: - * [for client-side adapters](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) - either completely or for certain bidders. - * [for server-side adapters](/dev-docs/modules/prebidServer.html) - override the s2sConfig.syncEndpoint -* [Disable User ID modules](/dev-docs/modules/userId.html) - there are controls for different ID modules and which bidders can get which IDs. -* [Disable device access](/dev-docs/publisher-api-reference/setConfig.html#setConfig-deviceAccess) - no adapter or module will be able to create a cookie or HTML5 localstorage object. -* For GDPR: - * Consider the [TCF](/dev-docs/modules/consentManagementTcf.html) and [TCF Control](/dev-docs/modules/tcfControl.html) modules, which flexibly support various actions like cancelling usersyncs, auctions, and analytics. Using these modules, bid adapters can receive the IAB TCF string from the CMP. - * Note that TCF 2.2 is functionally the same as TCF 2.0 from the Prebid.js perspective. The code has always relied on event listeners to get the TCF string, so when `getTCData` was deprecated in 2.2 the modules were unaffected. There are still references in the code only because it is still accepted as a place for statically-supplied data. - * Alternatively, the page can just avoid turning on certain bidders or modules. -* For CCPA / CPRA / US-Privacy: - * Consider the [US-Privacy](/dev-docs/modules/consentManagementUsp.html) module, which passes the IAB USP string through to bid adapters and supports data deletion events for User ID modules and other interested adapters and modules. - * Also consider implementing an [Activity Control](/dev-docs/activity-controls.html) to suppress activities upon opt-out or in environments without legal notice. An example implementation is available on the activity control documentation page. - * Also consider implementing the [GPP control module - usnat section](/dev-docs/modules/gppControl_usnat.html) to implement reasonable default expressions of activity controls when a usnat string is available as section 7 of a GPP string. -* Set the [COPPA flag](/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa), which passes this value through to modules and bid adapters. - * Also consider implementing an [Activity Control](/dev-docs/activity-controls.html) to suppress activities when COPPA applies. The implementation is very similar to the example CCPA implementation available on the activity control documentation page. -* The IAB is still refining the definition of [GPP](https://iabtechlab.com/gpp/). Prebid has built a GPP module that supports GPP 1.0, with 1.1 support coming soon after the specification is finalized and merged. Many bid adapters support both statically setting GPP strings, e.g. `pbjs.setConfig({ortb2: {regs: {gpp: "blah", gpp_sid: [1,2]}}});` and module-read consent. -* Avoid adding certain bidders or modules to the AdUnit. -* Turn off header bidding altogether. +- Consider utilizing an [Activity Control](/dev-docs/activity-controls.html). These are available with Prebid.js 7.48 and may help cover a number of common privacy concerns. +- Turn off Prebid.js usersync: + - [for client-side adapters](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) - either completely or for certain bidders. + - [for server-side adapters](/dev-docs/modules/prebidServer.html) - override the s2sConfig.syncEndpoint +- [Disable User ID modules](/dev-docs/modules/userId.html) - there are controls for different ID modules and which bidders can get which IDs. +- [Disable device access](/dev-docs/publisher-api-reference/setConfig.html#setConfig-deviceAccess) - no adapter or module will be able to create a cookie or HTML5 localstorage object. +- For GDPR: + - Consider the [TCF](/dev-docs/modules/consentManagementTcf.html) and [TCF Control](/dev-docs/modules/tcfControl.html) modules, which flexibly support various actions like cancelling usersyncs, auctions, and analytics. Using these modules, bid adapters can receive the IAB TCF string from the CMP. + - Note that TCF 2.2 is functionally the same as TCF 2.0 from the Prebid.js perspective. The code has always relied on event listeners to get the TCF string, so when `getTCData` was deprecated in 2.2 the modules were unaffected. There are still references in the code only because it is still accepted as a place for statically-supplied data. + - Alternatively, the page can just avoid turning on certain bidders or modules. +- For CCPA / CPRA / US-Privacy: + - Consider the [US-Privacy](/dev-docs/modules/consentManagementUsp.html) module, which passes the IAB USP string through to bid adapters and supports data deletion events for User ID modules and other interested adapters and modules. + - Also consider implementing an [Activity Control](/dev-docs/activity-controls.html) to suppress activities upon opt-out or in environments without legal notice. An example implementation is available on the activity control documentation page. + - Also consider implementing the [GPP control module - usnat section](/dev-docs/modules/gppControl_usnat.html) to implement reasonable default expressions of activity controls when a usnat string is available as section 7 of a GPP string. +- Set the [COPPA flag](/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa), which passes this value through to modules and bid adapters. + - Also consider implementing an [Activity Control](/dev-docs/activity-controls.html) to suppress activities when COPPA applies. The implementation is very similar to the example CCPA implementation available on the activity control documentation page. +- The IAB is still refining the definition of [GPP](https://iabtechlab.com/gpp/). Prebid has built a GPP module that supports GPP 1.0, with 1.1 support coming soon after the specification is finalized and merged. Many bid adapters support both statically setting GPP strings, e.g. `pbjs.setConfig({ortb2: {regs: {gpp: "blah", gpp_sid: [1,2]}}});` and module-read consent. +- Avoid adding certain bidders or modules to the AdUnit. +- Turn off header bidding altogether. Prebid relies on the IAB and community members to determine what tools are needed to support publishers in meeting their legal obligations. As noted above, if there’s another tool you need, please open an issue in the appropriate repository, or join the org and help us improve the system! +### Why doesn't Prebid.org have a GVL ID? + +Back when there was a 3rd party component to [SharedID](/identity/sharedid.html), Prebid did have a Global Vendor List ID. But that 3rd party aspect of SharedID has been shut down for a long time, so Prebid.org is completely out of the user data path and has not renewed the GVL registration. + +Because Prebid.org doesn't touch data, the only TCF Purpose that's relevant for Prebid.js functionality is Purpose 1: Device Access. The way it works is that several Prebid-based modules support a "VENDORLESS_GVLID". These are seen as the publisher asking Prebid.js to store stuff on their behalf: + +- shared ID - requests to store the sharedId to local storage +- pubProvided ID - requests to store the pubProvidedId to local storage +- consentManagement module - requests to store the CMP state to local storage so PBJS can tell when a change was made to the state. +- geo location module - requests to retrieve the user's location from the browser. + +When the TCF Purpose 1 check is made for one of these VENDORLESS_GVLID scenarios, only the user's purpose consent is checked -- no vendor check is made. This makes sense because the 'vendor' in these scenarios is the publisher, and they're a first party, not a third party. + ### What happened to the allowAuctionWithoutConsent flag? This option to the ConsentManagement module was removed a long time ago in PBJS 4.0. Why? -* It was a poorly named flag. What it did was let the auction happen on the first page before the user had responded to the CMP. -* It was replaced by a combination of the "defaultGdprScope" flag and the ability for a publisher to disable enforcement of the `basicAds` TCF purpose. +- It was a poorly named flag. What it did was let the auction happen on the first page before the user had responded to the CMP. +- It was replaced by a combination of the "defaultGdprScope" flag and the ability for a publisher to disable enforcement of the `basicAds` TCF purpose. See the [TCF Control Module](/dev-docs/modules/tcfControl.html) documentation for more details. @@ -92,8 +105,8 @@ See the [TCF Control Module](/dev-docs/modules/tcfControl.html) documentation fo Below is a set of recommended best practice starting points for your timeout settings: -* 1,000 milliseconds or less for the internal auction timeout -* 3,000 milliseconds or less for the Prebid tag's overall failsafe timeout +- 1,000 milliseconds or less for the internal auction timeout +- 3,000 milliseconds or less for the Prebid tag's overall failsafe timeout The former setting is used to track the auction once it started; if it expires, we will use whichever bidders have responded and select the winner(s) accordingly. @@ -121,10 +134,10 @@ It can. Versions 1.x of Prebid.js would re-consider previous bids under limited The "limited bid caching" feature applies only: -* for the same AdUnit, -* on the same page view, -* for the same user, and -* up to a certain Time-to-Live (TTL) or until the bid wins and is displayed. +- for the same AdUnit, +- on the same page view, +- for the same user, and +- up to a certain Time-to-Live (TTL) or until the bid wins and is displayed. Since the storage is in the browser, cached bids only apply to a single page context. If the user refreshes the page, the bid is lost. @@ -133,9 +146,9 @@ This setting is called “Time to Live” (TTL), documented in the pbjs.ge Examples of scenarios where a bid may be reconsidered in Prebid.js: -* Auto-refresh: Some pages will reload an AdUnit on a set interval (often 60-240 seconds). Previous bids for that particular AdUnit can be reconsidered for subsequent refreshes of that unit up to the TTL or until they win the unit. -* Infinite scroll: As the user scrolls, the same AdUnit may be dynamically created over and over. The bid can be reconsidered for dynamically-created AdUnits with the same name. Again, the bid is only re-considered on that AdUnit up to the bid TTL or until it's displayed. -* Galleries: Some pages feature carousel-style galleries that contain an AdUnit that refreshes as the user cycles through the content in the gallery. +- Auto-refresh: Some pages will reload an AdUnit on a set interval (often 60-240 seconds). Previous bids for that particular AdUnit can be reconsidered for subsequent refreshes of that unit up to the TTL or until they win the unit. +- Infinite scroll: As the user scrolls, the same AdUnit may be dynamically created over and over. The bid can be reconsidered for dynamically-created AdUnits with the same name. Again, the bid is only re-considered on that AdUnit up to the bid TTL or until it's displayed. +- Galleries: Some pages feature carousel-style galleries that contain an AdUnit that refreshes as the user cycles through the content in the gallery. Here's how it works: @@ -162,13 +175,13 @@ Therefore, it requires Prebid.js to run in a blocking/synchronous fashion. **Thi Here are a couple of alternative workarounds: -* **Option 1:** +- **Option 1:** Load a blocking script that has a load time of 300-500ms. This script does nothing but keep the page waiting. In the meantime Prebid.js can run asynchronously and return the bids. After the blocking script finishes loading, GPT can start synchronously; at this point there will be header bidding bids available. For the best user experience, you probably want to insert this blocking script after the above the fold page content has loaded. Or if you're okay with additional 500ms latency added to your page load time, this can be easily done. -* **Option 2:** +- **Option 2:** Use post-bid. The downsides are that post-bid no longer allows your header bidding partners to compete with Google Ad Manager/AdX, but they can still compete with each other. For more information, see [What is post-bid?]({{site.baseurl}}/overview/what-is-post-bid.html). @@ -209,9 +222,9 @@ what's sent to the ad server with [targetingControls.auctionKeyMaxChars](/dev-do It's technically possible, but we don't recommend doing this: -* The code isn't small. For performance reasons you don't want to run two versions if you can help it -* We don't test concurrent versions -* We won't specifically support debugging problems caused by running two concurrent versions. But will take take PRs if someone finds an issue. +- The code isn't small. For performance reasons you don't want to run two versions if you can help it +- We don't test concurrent versions +- We won't specifically support debugging problems caused by running two concurrent versions. But will take take PRs if someone finds an issue. If all this wasn't enough to warn you away from trying, it should work if you name the PBJS global differently for each instance (Update the value of 'globalVarName' in ) @@ -259,6 +272,6 @@ Sometimes the owner of a bid adapter or other kind of module wants to rename the ## Related Reading -* [Prebid.js Troubleshooting Guide](/troubleshooting/troubleshooting-guide.html) -* [Prebid.js Common Issues](/dev-docs/common-issues.html) -* [Prebid.js issues tagged 'question'](https://github.com/prebid/Prebid.js/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20) +- [Prebid.js Troubleshooting Guide](/troubleshooting/troubleshooting-guide.html) +- [Prebid.js Common Issues](/dev-docs/common-issues.html) +- [Prebid.js issues tagged 'question'](https://github.com/prebid/Prebid.js/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20) diff --git a/dev-docs/modules/akamaiDapRtdProvider.md b/dev-docs/modules/akamaiDapRtdProvider.md deleted file mode 100644 index b4efb216d6..0000000000 --- a/dev-docs/modules/akamaiDapRtdProvider.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -layout: page_v2 -title: Akamai DAP Real Time Data Provider Module -display_name: Akamai DAP Real Time Data Provider Module -description: Akamai DAP Real Time Data Provider Module -page_type: module -module_type: rtd -module_code : akamaiDapRtdProvider -enable_download : true -vendor_specific: true -sidebarType : 1 ---- - -# Akamai DAP Real Time Data Provider Module - -{:.no_toc} - -* TOC -{:toc} - -The Akamai Data Activation Platform (DAP) is a privacy-first system that protects end-user privacy by only allowing them to be targeted as part of a larger cohort. Akamai DAP Real time data Provider automatically invokes the DAP APIs and submit audience segments and the Secure Ad ID(SAID) to the bid-stream. SAID is a JWT/JWE which carries with it the cohorts and only a side-car or trusted server in the demand-side platform is allowed to see its contents. - -## Publisher Usage - -1. Build the akamaiDapRTD module into the Prebid.js package with: - - ```bash - gulp build --modules=akamaiDapRtdProvider,... - ``` - -2. Use `setConfig` to instruct Prebid.js to initilaize the akamaiDapRtdProvider module, as specified below. - -### Configuration - -```javascript -pbjs.setConfig({ - realTimeData: { - auctionDelay: 2000, - dataProviders: [ - { - name: "dap", - waitForIt: true, - params: { - apiHostname: '', - apiVersion: "x1", - domain: 'your-domain.com', - identityType: 'email' | 'mobile' | ... | 'dap-signature:1.3.0', - segtax: 504, - dapEntropyUrl: 'https://dap-dist.akamaized.net/dapentropy.js', - dapEntropyTimeout: 1500 - } - } - ] - } -}); -``` - -Please reach out to your Akamai account representative() to get provisioned on the DAP platform. - -**Config Syntax details:** - -{: .table .table-bordered .table-striped } -| Name |Type | Description | Notes | -| :------------ | :------------ | :------------ |:------------ | -| name | String | Akamai Dap Rtd module name | 'dap' always| -| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | -| apiHostname | String | Hostname provided by Akamai | Please reach out to your Akamai account representative() for this value| -| apiVersion | String | This holds the API version | It should be "x1" always | -| domain | String | The domain name of your webpage | | -| identityType | String | Something like this 'email', 'mobile', ... 'dap-signature:1.3.0' | | -| segtax | Integer | The taxonomy for Akamai | The value should be 504 | -| dapEntropyUrl | String | URL to dap entropy script | Optional if the script is directly included on the webpage. Contact your Akamai account rep for more details | -| dapEntropyTimeout | Integer | Maximum time allotted for the entropy calculation to happen | | - -### Testing - -To view an example of available segments returned by dap: - -```bash -gulp serve --modules=rtdModule,akamaiDapRtdProvider,appnexusBidAdapter,sovrnBidAdapter -``` - -and then point your browser at: -"" diff --git a/dev-docs/modules/anonymisedRtdProvider.md b/dev-docs/modules/anonymisedRtdProvider.md index d266b01d6f..72e678faa9 100644 --- a/dev-docs/modules/anonymisedRtdProvider.md +++ b/dev-docs/modules/anonymisedRtdProvider.md @@ -21,10 +21,10 @@ Anonymised’s Real-time Data Provider automatically obtains segment IDs from th - Build the anonymisedRtd module into the Prebid.js package with: ```bash -gulp build --modules=anonymisedRtdProvider,... +gulp build --modules=rtdModule,anonymisedRtdProvider,... ``` -- Use `setConfig` to instruct Prebid.js to initilaize the anonymisedRtdProvider module, as specified below. +- Use `setConfig` to instruct Prebid.js to initialize the anonymisedRtdProvider module, as specified below. ### Configuration diff --git a/dev-docs/modules/symitriDapRtdProvider.md b/dev-docs/modules/symitriDapRtdProvider.md new file mode 100644 index 0000000000..99914d3b7b --- /dev/null +++ b/dev-docs/modules/symitriDapRtdProvider.md @@ -0,0 +1,84 @@ +--- +layout: page_v2 +title: Symitri DAP Real Time Data Provider Module +display_name: Symitri DAP Real Time Data Provider Module +description: Symitri DAP Real Time Data Provider Module +page_type: module +module_type: rtd +module_code : symitriDapRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Symitri DAP Real Time Data Provider Module + +{:.no_toc} + +* TOC +{:toc} + +The Symitri Data Activation Platform (DAP) is a privacy-first system that protects end-user privacy by only allowing them to be targeted as part of a larger cohort. Symitri DAP Real time data Provider automatically invokes the DAP APIs and submit audience segments and the Secure Ad ID(SAID) to the bid-stream. SAID is a JWT/JWE which carries with it the cohorts and only a side-car or trusted server in the demand-side platform is allowed to see its contents. + +## Publisher Usage + +1. Build the symitriDapRTD module into the Prebid.js package with: + + ```bash + gulp build --modules=symitriDapRtdProvider,... + ``` + +2. Use `setConfig` to instruct Prebid.js to initilaize the symitriDapRtdProvider module, as specified below. + +### Configuration + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 2000, + dataProviders: [ + { + name: "dap", + waitForIt: true, + params: { + apiHostname: '', + apiVersion: "x1", + domain: 'your-domain.com', + identityType: 'email' | 'mobile' | ... | 'dap-signature:1.3.0', + segtax: 504, + dapEntropyUrl: 'https://sym-dist.symitri.net/dapentropy.js', + dapEntropyTimeout: 1500 + } + } + ] + } +}); +``` + +Please reach out to your Symitri account representative() to get provisioned on the DAP platform. + +**Config Syntax details:** + +{: .table .table-bordered .table-striped } +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| name | String | Symitri Dap Rtd module name | 'dap' always| +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | +| apiHostname | String | Hostname provided by Symitri | Please reach out to your Symitri account representative() for this value| +| apiVersion | String | This holds the API version | It should be "x1" always | +| domain | String | The domain name of your webpage | | +| identityType | String | Something like this 'email', 'mobile', ... 'dap-signature:1.3.0' | | +| segtax | Integer | The taxonomy for Symitri | The value should be 504 | +| dapEntropyUrl | String | URL to dap entropy script | Optional if the script is directly included on the webpage. Contact your Symitri account rep for more details | +| dapEntropyTimeout | Integer | Maximum time allotted for the entropy calculation to happen | | + +### Testing + +To view an example of available segments returned by dap: + +```bash +gulp serve --modules=rtdModule,symitriDapRtdProvider,appnexusBidAdapter,sovrnBidAdapter +``` + +and then point your browser at: +"" diff --git a/dev-docs/modules/userid-submodules/id5.md b/dev-docs/modules/userid-submodules/id5.md index e6f65a7bfd..1ab7dc315f 100644 --- a/dev-docs/modules/userid-submodules/id5.md +++ b/dev-docs/modules/userid-submodules/id5.md @@ -35,9 +35,10 @@ The following configuration parameters are available: | params.abTesting.enabled | Optional | Boolean | Set this to `true` to turn on this feature | `true` or `false` | | params.abTesting.controlGroupPct | Optional | Number | Must be a number between `0.0` and `1.0` (inclusive) and is used to determine the percentage of requests that fall into the control group (and thus not exposing the ID5 ID). For example, a value of `0.20` will result in 20% of requests without an ID5 ID and 80% with an ID. | `0.1` | | params.disableExtensions | Optional | Boolean | Set this to `true` to force turn off extensions call. Default `false` | `true` or `false` | +| params.provider | Optional | String | An identifier provided by ID5 to technology partners who manage API deployments on behalf of their clients. Reach out to ID5 if you have questions about this parameter. | `"providerName"` | {: .alert.alert-info :} -**NOTE:** The ID5 ID that is delivered to Prebid will be encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `8` hours (`8*3600` seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. +**NOTE:** The ID5 ID that is delivered to Prebid will be encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Therefore, we strongly recommend setting `storage.refreshInSeconds` to `2` hours (`7200` seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it. ### A Note on A/B Testing @@ -70,7 +71,7 @@ pbjs.setConfig({ type: 'html5', // "html5" is the required storage type name: 'id5id', // "id5id" is the required storage name expires: 90, // storage lasts for 90 days - refreshInSeconds: 8*3600 // refresh ID every 8 hours to ensure it's fresh + refreshInSeconds: 7200 // refresh ID every 2 hours to ensure it's fresh } }], auctionDelay: 50 // 50ms maximum auction delay, applies to all userId modules @@ -80,3 +81,64 @@ pbjs.setConfig({ {: .alert.alert-warning :} **ATTENTION:** As of Prebid.js v4.14.0, ID5 requires `storage.type` to be `"html5"` and `storage.name` to be `"id5id"`. Using other values will display a warning today, but in an upcoming release, it will prevent the ID5 module from loading. This change is to ensure the ID5 module in Prebid.js interoperates properly with the [ID5 API](https://github.com/id5io/id5-api.js) and to reduce the size of publishers' first-party cookies that are sent to their web servers. For the same reasons it is very important as of Prebid.js v8.33.0 to provide the `externalModuleUrl` parameter and set it to the latest available module version at `https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js`. If you have any questions, please reach out to us at [prebid@id5.io](mailto:prebid@id5.io). + +### Provided eids +The module provides following eids: + +```javascript +[ + { + source: 'id5-sync.com', + uids: [ + { + id: 'some-random-id-value', + atype: 1, + ext: { + linkType: 2, + abTestingControlGroup: false + } + } + ] + }, + { + source: 'true-link-id5-sync.com', + uids: [ + { + id: 'some-publisher-true-link-id', + atype: 1 + } + ] + }, + { + source: 'uidapi.com', + uids: [ + { + id: 'some-uid2', + atype: 3, + ext: { + provider: 'id5-sync.com' + } + } + ] + } +] +``` + +The id from `id5-sync.com` should be always present (though the id provided will be '0' in case of no consent or optout) + +The id from `true-link-id5-sync.com` will be available if the page is integrated with TrueLink (if you are an ID5 partner you can learn more at [ID5 wiki](https://wiki.id5.io/en/identitycloud/retrieve-id5-ids/true-link-integration)) + +The id from `uidapi.com` will be available if the partner that is used in ID5 user module has the EUID2 integration enabled (it has to be enabled on the ID5 side) + +### Providing TrueLinkId as a Google PPID + +TrueLinkId can be provided as a PPID - to use, it the `true-link-id5-sync.com` needs to be provided as a ppid source in prebid userSync configuration: + +```javascript +pbjs.setConfig({ + userSync: { + ppid: 'true-link-id5-sync.com', + userIds: [], //userIds modules should be configured here + } +}); +``` diff --git a/dev-docs/modules/userid-submodules/intentiq.md b/dev-docs/modules/userid-submodules/intentiq.md index e99228ef2a..d6540a0326 100644 --- a/dev-docs/modules/userid-submodules/intentiq.md +++ b/dev-docs/modules/userid-submodules/intentiq.md @@ -31,15 +31,16 @@ Please find below list of parameters that could be used in configuring Intent IQ {: .table .table-bordered .table-striped } -| Param under userSync.userIds[] | Scope | Type | Description | Example | -| ------------------------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | -| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` | -| params | Required | Object | Details for IntentIqId initialization. | | -| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` | -| params.percentage | Required | Number | This a percentage value for our A/B testing group distribution. The values supposed to be in range of 0 to 100. We suggest to set it to 95 percent for optimal balance ofbetween prefromance and preceision. | `95` | -| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` | -| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` | -| params.enableCookieStorage | Optional | Boolean | This is a parameter allowing to enable or disable cookie storage. Defaults to false. | `"true"` | +| Param under userSync.userIds[] | Scope | Type | Description | Example | +| ------------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` | +| params | Required | Object | Details for IntentIqId initialization. | | +| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` | +| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` | +| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` | +| params.callback | Required | Function | This is a callback which is trigered with data and AB group | `(data, group) => console.log({ data, group })` | +| params.timeoutInMillis | Optional | Number | This is the timeout in milliseconds, which defines the maximum duration before the callback is triggered. The default value is 500. | `450` | +| params.browserBlackList | Optional |  String | This is the name of a browser that can be added to a blacklist. | `"chrome"` | ### Configuration example @@ -51,14 +52,13 @@ pbjs.setConfig({ name: "intentIqId", params: { partner: 123456, // valid partner id - percentage: 95, - enableCookieStorage: true + callback: (data, group) => window.pbjs.requestBids(), }, storage: { type: "html5", name: "intentIqId", // set localstorage with this name - expires: 60, - refreshInSeconds: 4 * 3600, // refresh ID every 4 hours to ensure it's fresh + expires: 0, + refreshInSeconds: 0, }, }, ], @@ -76,13 +76,14 @@ pbjs.setConfig({ partner: 123456 // valid partner id pcid: PCID_VARIABLE, // string value, dynamically loaded into a variable before setting the configuration pai: PAI_VARIABLE , // string value, dynamically loaded into a variable before setting the configuration - percentage: 95, - enableCookieStorage: false + timeoutInMillis: 500, + browserBlackList: "chrome", + callback: (data, group) => window.pbjs.requestBids() }, storage: { type: "html5", name: "intentIqId", // set localstorage with this name - expires: 60 + expires: 0 } }], syncDelay: 3000 diff --git a/dev-docs/show-prebid-ads-on-amp-pages.md b/dev-docs/show-prebid-ads-on-amp-pages.md index 555b42648b..b9244d2611 100644 --- a/dev-docs/show-prebid-ads-on-amp-pages.md +++ b/dev-docs/show-prebid-ads-on-amp-pages.md @@ -6,7 +6,6 @@ sidebarType: 2 --- # Prebid AMP Implementation Guide - {: .no_toc} This page has instructions for showing ads on Accelerated Mobile Pages (AMP) using Prebid.js. @@ -15,11 +14,11 @@ Through this implementation, [Prebid Server][PBS] fetches demand and returns key For more information about AMP RTC, see: -* [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) -* [Prebid Server AMP Endpoint Technical Documentation](/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.html) -* [Prebid Server Stored Bid Requests](https://github.com/prebid/prebid-server/blob/master/docs/developers/stored-requests.md#stored-bidrequests) -* [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) -* [AMP RTC Publisher Integration Guide](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-publisher-implementation-guide.md) +- [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) +- [Prebid Server AMP Endpoint Technical Documentation](/prebid-server/endpoints/openrtb2/pbs-endpoint-amp.html) +- [Prebid Server Stored Bid Requests](https://github.com/prebid/prebid-server/blob/master/docs/developers/stored-requests.md#stored-bidrequests) +- [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) +- [AMP RTC Publisher Integration Guide](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-publisher-implementation-guide.md) {% capture tipNote %} For ad ops setup instructions, see [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html). @@ -27,25 +26,25 @@ For ad ops setup instructions, see [Google Ad Manager with Prebid Step by Step]( {% include alerts/alert_note.html content=tipNote %} -* TOC +- TOC {:toc } ## Prerequisites To set up Prebid to serve ads into your AMP pages, you'll need: -* An account with a [Prebid Server][PBS] instance -* One or more Prebid Server Stored Bid Requests. A Stored Bid Request is a partial OpenRTB JSON request which: - * Specifies properties like currency, schain, price granularity, etc. - * Contains a list of demand partners and their respective parameters -* An AMP page containing at least one amp-ad element for an AMP ad network that supports Fast Fetch and AMP RTC +- An account with a [Prebid Server][PBS] instance +- One or more Prebid Server Stored Bid Requests. A Stored Bid Request is a partial OpenRTB JSON request which: + - Specifies properties like currency, schain, price granularity, etc. + - Contains a list of demand partners and their respective parameters +- An AMP page containing at least one amp-ad element for an AMP ad network that supports Fast Fetch and AMP RTC ## Implementation -* [Prebid Server Stored Request](#prebid-server-stored-request): This is the Prebid Server Stored Bid Request. -* [AMP content page](#amp-content-page): This is where your content lives. -* [HTML Creative](#html-creative): This is the creative your Ad Ops team puts in your ad server. -* [User Sync in AMP](#user-sync): This is the `amp-iframe` pixel that must be added to your AMP page to sync users with Prebid Server. +- [Prebid Server Stored Request](#prebid-server-stored-request): This is the Prebid Server Stored Bid Request. +- [AMP content page](#amp-content-page): This is where your content lives. +- [HTML Creative](#html-creative): This is the creative your Ad Ops team puts in your ad server. +- [User Sync in AMP](#user-sync): This is the `amp-iframe` pixel that must be added to your AMP page to sync users with Prebid Server. ### Prebid Server Stored Request @@ -54,12 +53,12 @@ You will have to create at least one Stored Request for Prebid Server. Valid St An example Stored Request is given below. You'll see that the Stored Request contains some important info that doesn't come from /amp parameters: -* cur -* schain -* ext.prebid.cache.bids - needed to let Prebid Server know that you want it to store the result in PBC -* ext.prebid.targeting.pricegranularity - needed to let Prebid Server know how to calculate the price bucket -* ext.prebid.aliases -* bidders and their parameters +- cur +- schain +- ext.prebid.cache.bids - needed to let Prebid Server know that you want it to store the result in PBC +- ext.prebid.targeting.pricegranularity - needed to let Prebid Server know how to calculate the price bucket +- ext.prebid.aliases +- bidders and their parameters ```json { @@ -129,10 +128,10 @@ This script provides code libraries that will convert `` properties to t The `amp-ad` elements in the page body need to be set up as shown below, especially the following attributes: -* `data-slot`: Identifies the ad slot for the auction. -* `rtc-config`: Used to pass JSON configuration data to [Prebid Server][PBS], which handles the communication with AMP RTC. - * `vendors` is an object that defines any vendors that will be receiving RTC callouts (including Prebid Server) up to a maximum of five. The list of supported RTC vendors is maintained in [callout-vendors.js](https://github.com/ampproject/amphtml/blob/master/src/service/real-time-config/callout-vendors.js). We recommend working with your Prebid Server hosting company to set up which bidders and parameters should be involved for each AMP ad unit. - * `timeoutMillis` is an optional integer that defines the timeout in milliseconds for each individual RTC callout. The configured timeout must be greater than 0 and less than 1000ms. If omitted, the timeout value defaults to 1000ms. +- `data-slot`: Identifies the ad slot for the auction. +- `rtc-config`: Used to pass JSON configuration data to [Prebid Server][PBS], which handles the communication with AMP RTC. + - `vendors` is an object that defines any vendors that will be receiving RTC callouts (including Prebid Server) up to a maximum of five. The list of supported RTC vendors is maintained in [callout-vendors.js](https://github.com/ampproject/amphtml/blob/master/src/service/real-time-config/callout-vendors.js). We recommend working with your Prebid Server hosting company to set up which bidders and parameters should be involved for each AMP ad unit. + - `timeoutMillis` is an optional integer that defines the timeout in milliseconds for each individual RTC callout. The configured timeout must be greater than 0 and less than 1000ms. If omitted, the timeout value defaults to 1000ms. e.g. for the AppNexus cluster of Prebid Servers: @@ -222,15 +221,15 @@ Replace `MACRO` in the preceding example with the appropriate macro for the ad s ### User Sync -To sync user IDs with Prebid Server, the `amp-iframe` below may be added to your AMP pages referring to `load-cookie.html` or if you're running an IAB-compliant AMP CMP you can use `load-cookie-with-consent.html`. +To sync user IDs with Prebid Server, the `amp-iframe` below may be added to your AMP pages referring to `load-cookie.html`. -Note that AMP constrains syncing as described in the [amp-iframe](https://amp.dev/documentation/components/amp-iframe) documentation. You may only have *one* amp-iframe on your page that is small, e.g. 1x1. Many publishers already have some kind of analytics or tracking frame on their page, so they may find it difficult to manage this. Several hacks are possible, including building a 'frankenstein' script that combines all of your required tracking into one or tying the sync to an image that's large enough to be visible. +AMP constrains syncing as described in the [amp-iframe](https://amp.dev/documentation/components/amp-iframe) documentation. You may only have *one* amp-iframe on your page that is small, e.g. 1x1. Many publishers already have some kind of analytics or tracking frame on their page, so they may find it difficult to manage this. Several hacks are possible, including building a 'frankenstein' script that combines all of your required tracking into one or tying the sync to an image that's large enough to be visible. Notes: -* The following examples include a transparent image as a placeholder which will allow you to place the example at the top within the HTML body. If this is not included the iFrame must be either 600px away from the top or not within the first 75% of the viewport when scrolled to the top – whichever is smaller. For more information on this, see [amp-iframe](https://amp.dev/documentation/components/amp-iframe/) -* Note that the `sandbox` parameter to the amp-iframe must include both "allow-scripts" and "allow-same-origin". -* The load-cookie-with-consent.html file has the same argument syntax as load-cookie.html. It's a different file because it's larger and depends on the existence of an AMP Consent Management Platform. +- The following examples include a transparent image as a placeholder which will allow you to place the example at the top within the HTML body. If this is not included the iFrame must be either 600px away from the top or not within the first 75% of the viewport when scrolled to the top – whichever is smaller. For more information on this, see [amp-iframe](https://amp.dev/documentation/components/amp-iframe/) +- The `sandbox` parameter to the amp-iframe must include both "allow-scripts" and "allow-same-origin". +- If your PBS host company is using a version of `load-cookie.html` older than July of 2024 and if your AMP page is using a CMP, you should consider using `load-cookie-with-consent.html` instead. It's the same functionality, but older versions of `load-cookie.html` cannot read from CMPs. If you're using AppNexus' managed service, you would enter something like this: @@ -268,44 +267,44 @@ Or you can specify a full URL to another Prebid Server location (including a QA ``` -See [manually initiating a sync](/prebid-server/developers/pbs-cookie-sync.html#manually-initiating-a-sync) for more information about the available parameters. +See [manually initiating a sync](/prebid-server/developers/pbs-cookie-sync.html#manually-initiating-a-sync) for more information about the available parameters and for how to host the load-cookie script. ### AMP RTC If you're using a custom RTC callout rather than one of the pre-defined [vendor callouts](https://github.com/ampproject/amphtml/blob/main/src/service/real-time-config/callout-vendors.js), here are the parameters that can be passed through the RTC string: -* tag_id (this correspondes to the Prebid Server stored request ID) -* w=ATTR(width) -* h=ATTR(height) -* ow=ATTR(data-override-width) -* oh=ATTR(data-override-height) -* ms=ATTR(data-multi-size) -* slot=ATTR(data-slot) -* targeting=TGT -* curl=CANONICAL_URL -* timeout=TIMEOUT -* adc=ADCID -* purl=HREF -* gdpr_consent=CONSENT_STRING -* consent_type=CONSENT_METADATA(consentStringType) -* gdpr_applies=CONSENT_METADATA(gdprApplies) -* attl_consent=CONSENT_METADATA(additionalConsent) +- tag_id (this correspondes to the Prebid Server stored request ID) +- w=ATTR(width) +- h=ATTR(height) +- ow=ATTR(data-override-width) +- oh=ATTR(data-override-height) +- ms=ATTR(data-multi-size) +- slot=ATTR(data-slot) +- targeting=TGT +- curl=CANONICAL_URL +- timeout=TIMEOUT +- adc=ADCID +- purl=HREF +- gdpr_consent=CONSENT_STRING +- consent_type=CONSENT_METADATA(consentStringType) +- gdpr_applies=CONSENT_METADATA(gdprApplies) +- attl_consent=CONSENT_METADATA(additionalConsent) ## Debugging Tips To review that Prebid on AMP is working properly the following aspects can be looked at: -* Include `#development=1` to the URL to review AMP specifc debug messages in the browser console. -* Look for the Prebid server call in the network panel. You can open this URL in a new tab to view additional debugging information relating to the Prebid Server Stored Bid Request. If working properly, Prebid server will display the targeting JSON for AMP to use. -* Look for the network call from the Ad Server to ensure that key values are being passed. (For Google Ad Manager these are in the `scp` query string parameter in the network request) -* Most of the debugging information is omitted from the Prebid Server response unless the `debug=1` parameter is present in the Prebid Server query string. AMP won't add this parameter, so you'll need to grab the Prebid Server URL and manually add it to see the additional information provided. +- Include `#development=1` to the URL to review AMP specifc debug messages in the browser console. +- Look for the Prebid server call in the network panel. You can open this URL in a new tab to view additional debugging information relating to the Prebid Server Stored Bid Request. If working properly, Prebid server will display the targeting JSON for AMP to use. +- Look for the network call from the Ad Server to ensure that key values are being passed. (For Google Ad Manager these are in the `scp` query string parameter in the network request) +- Most of the debugging information is omitted from the Prebid Server response unless the `debug=1` parameter is present in the Prebid Server query string. AMP won't add this parameter, so you'll need to grab the Prebid Server URL and manually add it to see the additional information provided. ## Further Reading -* [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) -* [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html) (Ad Ops Setup) -* [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) -* [callout-vendors.js] +- [Prebid Server and AMP](/prebid-server/use-cases/pbs-amp.html) +- [Google Ad Manager with Prebid Step by Step](/adops/step-by-step.html) (Ad Ops Setup) +- [AMP RTC Overview](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/rtc-documentation.md) +- [callout-vendors.js] diff --git a/prebid-server/developers/pbs-cookie-sync.md b/prebid-server/developers/pbs-cookie-sync.md index 96bcb5e483..fa178b4be4 100644 --- a/prebid-server/developers/pbs-cookie-sync.md +++ b/prebid-server/developers/pbs-cookie-sync.md @@ -33,73 +33,116 @@ Here's how these IDs get placed in the cookie from Prebid.js: ![Prebid Server Cookie Sync](/assets/images/prebid-server/pbs-cookie-sync.png){:class="pb-lg-img"} -1. Prebid.js starts by calling the Prebid Server [`/cookie_sync`](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), letting it know which server-side bidders will be participating in the header bidding auction. +1. When the [s2sConfig](/dev-docs/modules/prebidServer.html) is set, Prebid.js initiates a call to the Prebid Server [`/cookie_sync`](/prebid-server/endpoints/pbs-endpoint-cookieSync.html), letting it know which server-side bidders will be participating in the header bidding auction. - ```text +```text POST https://prebid-server.example.com/cookie_sync {"bidders":["bidderA","bidderB"], "gdpr":1, "gdpr_consent":"...", "us_privacy": "..."} - ``` +``` +{:start="2"} 2. If privacy regulations allow, Prebid Server will look at the `uids` cookie in the host domain and determine whether any bidders are missing or need to be refreshed. It responds with an array of pixel syncs. e.g. - ```javascript +```javascript {"status":"ok","bidder_status":[{"bidder":"bidderA","no_cookie":true,"usersync":{"url":"//biddera.com/getuid?https%3A%2F%2Fprebid-server.example.com%2Fsetuid%3Fbidder%3DbidderA%26gdpr%3D%26gdpr_consent%3D%26us_privacy%3D%26uid%3D%24UID","type":"redirect","supportCORS":false}},{"bidder":"bidderB","no_cookie":true,"usersync":{"url":"https://bidderB.com/u/match?gdpr=&euconsent=&us_privacy=&redir=https%3A%2F%2Fprebid-server.example.com%2Fsetuid%3Fbidder%3DbidderB%26gdpr%3D%26gdpr_consent%3D%26us_privacy%3D%26uid%3D","type":"redirect","supportCORS":false}}]} - ``` +``` -3. When it receives the response, Prebid.js loops through each element of `bidder_status[]`, dropping a pixel for each `bidder_status[].usersync.url`. +{:start="3"} +3. When it receives the response, Prebid.js loops through each element of `bidder_status[]`, creating a pixel for each `bidder_status[].usersync.url`. +{:start="4"} 4. The bidder-specific endpoints read the users' cookie for the bidder's domain and respond with a redirect back to Prebid Server's [`/setuid` endpoint](/prebid-server/endpoints/pbs-endpoint-setuid.html) . This allows that endpoint to read the 3rd party cookie and reflect it back to Prebid Server. Note that if this user doesn't yet have an ID in that 3rd party domain, the sync endpoint is expected to create one. +{:start="5"} 5. When the browser receives this redirect, it contacts Prebid Server, which will once again check the privacy settings and if allowed, update the `uids` cookie. -### Setting the uids cookie from AMP +### Cooperative Syncing + +Prebid Server supports a 'Cooperative Syncing' mode where all enabled bidders may be returned in a sync request even if they aren't on this particular page. This allows bidders to get their IDs in place for the next page where they are utilized. + +Cooperative sync defaults can be configured at the host and account level. See the docs for [PBS-Java](https://github.com/prebid/prebid-server-java/blob/master/docs/config-app.md) and [PBS-Go](https://github.com/prebid/prebid-server/blob/master/config/usersync.go). + +This is how to control the coop syncing behavior from Prebid.js: + +```javascript + pbjs.setConfig({ + s2sConfig: { + ... + coopSync: true, + userSyncLimit: 5 + ... + } + }); +``` + +### Manually initiating a sync -Cookie sync for AMP works in a way quite similar to Prebid.js. +Where Prebid.js isn't present, like on [AMP](/prebid-server/use-cases/pbs-amp.html) pages, the call to [/cookie_sync](/endpoints/pbs-endpoint-cookieSync.html) doesn't happen automatically. +If there are scenarios where Prebid.js isn't around to initiate the /cookie_sync call, publishers can choose to put an iframe on their page. + +This approach works in a way quite similar to Prebid.js except that the [/cookie_sync endpoint](/endpoints/pbs-endpoint-cookieSync.html) is initiated by a separate script that's part of `load-cookie.html'. This file must be placed on a CDN by the publisher's Prebid Server host company. Up until July 2024, the script existed in the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative) repository, but has since been moved to the [user-sync](https://github.com/prebid/user-sync) repo. -1. The Prebid Server hosting company places the [load-cookie.html](#manually-initiating-a-sync) file onto a CDN. This script is part of the [Prebid Universal Creative](https://github.com/prebid/prebid-universal-creative/blob/master/src/cookieSync.js) repo. +1. The Prebid Server hosting company places the [load-cookie.html](#manually-initiating-a-sync) file onto a CDN. See [the AMP implementation guide](/dev-docs/show-prebid-ads-on-amp-pages.html#user-sync) for more information. -2. The publisher places the 'load-cookie' iframe into the page: +2. The publisher places a 'load-cookie' iframe into the page: - ```html +For AMP pages: + +```html + src="https://HOST/load-cookie.html?source=amp&endpoint=PBSHOST&max_sync_count=5"> - ``` +``` - {: .alert.alert-info :} - If the publisher has an AMP Consent Management Platform, they should use `load-cookie-with-consent.html`. +On regular web pages: -3. At runtime, the `load-cookie` script just calls the Prebid Server /cookie_sync endpoint. The rest works similar to what's described for Prebid.js above. One difference is that the bidders are not known on the AMP page so those aren't passed. Another difference is that AMP doesn't support iframe syncs, so load-cookie passes instructions to PBS so only pixel syncs are returned. +```html +