diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f72c668240..53536e800d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,15 +15,15 @@ jobs: name: run markdownlint runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: tj-actions/changed-files@v41 + - uses: tj-actions/changed-files@v44 id: changed-files with: files: '**/*.md' separator: "," - - uses: DavidAnson/markdownlint-cli2-action@v15 + - uses: DavidAnson/markdownlint-cli2-action@v16 if: steps.changed-files.outputs.any_changed == 'true' with: globs: "${{ steps.changed-files.outputs.all_changed_files }},!_includes" diff --git a/Gemfile b/Gemfile index 4d0186505c..752b337f20 100755 --- a/Gemfile +++ b/Gemfile @@ -1,4 +1,4 @@ source 'https://rubygems.org' gem 'github-pages', '>= 228' - +gem 'ffi', '1.16.3' gem "webrick", "~> 1.7" diff --git a/_data/dropdown_v2.yml b/_data/dropdown_v2.yml index 9e8f7102dc..8fb1b03039 100644 --- a/_data/dropdown_v2.yml +++ b/_data/dropdown_v2.yml @@ -61,8 +61,8 @@ - subsectionId: 0 sectionId: 1 sectionName: Product - title: Analytics - link: /overview/analytics.html + title: Modules + link: /dev-docs/modules/index.html needsDivider: 0 isHeader: 0 isSubHeader: 0 @@ -71,8 +71,8 @@ - subsectionId: 0 sectionId: 1 sectionName: Product - title: Modules - link: /dev-docs/modules/index.html + title: Publisher API + link: /dev-docs/publisher-api-reference.html needsDivider: 0 isHeader: 0 isSubHeader: 0 @@ -81,8 +81,8 @@ - subsectionId: 0 sectionId: 1 sectionName: Product - title: Publisher API - link: /dev-docs/publisher-api-reference.html + title: Bidder Params + link: /dev-docs/bidders.html needsDivider: 0 isHeader: 0 isSubHeader: 0 @@ -91,8 +91,8 @@ - subsectionId: 0 sectionId: 1 sectionName: Product - title: Bidder Params - link: /dev-docs/bidders.html + title: Analytics + link: /overview/analytics.html needsDivider: 0 isHeader: 0 isSubHeader: 0 @@ -276,6 +276,15 @@ sectionName: Support title: Prebid Server link: /faq/prebid-server-faq.html + needsDivider: 0 + isHeader: 0 + isSubSectionStart: 0 + + - subsectionId: 3 + sectionId: 2 + sectionName: Support + title: Prebid Mobile + link: /faq/prebid-mobile-faq.html needsDivider: 1 isHeader: 0 isSubSectionStart: 0 diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 8dd030909a..5a509cee5d 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -184,6 +184,14 @@ sectionTitle: subgroup: 0 +- sbSecId: 1 + title: Analytics For Prebid + link: /overview/analytics.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + - sbSecId: 1 title: Consent Management Best Practices link: /dev-docs/cmp-best-practices.html @@ -507,31 +515,6 @@ sectionTitle: subgroup: 6 -- sbSecId: 1 - title: Analytics - link: - isHeader: 1 - headerId: analytics - isSectionHeader: 0 - sectionTitle: - subgroup: 7 - -- sbSecId: 1 - title: Analytics For Prebid - link: /overview/analytics.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 7 - -- sbSecId: 1 - title: Prebid Analytics for GA - link: /overview/ga-analytics.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 7 - - sbSecId: 1 title: Features link: @@ -743,6 +726,14 @@ sectionTitle: subgroup: 2 +- sbSecId: 2 + title: Global Parameters + link: /prebid-mobile/pbm-api/ios/pbm-targeting-ios.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 2 + - sbSecId: 2 title: GAM Original Integration link: /prebid-mobile/pbm-api/ios/ios-sdk-integration-gam-original-api.html @@ -783,14 +774,6 @@ sectionTitle: subgroup: 2 -- sbSecId: 2 - title: Targeting Parameters - link: /prebid-mobile/pbm-api/ios/pbm-targeting-ios.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 2 - - sbSecId: 2 title: Ad Experience Controls link: /prebid-mobile/modules/rendering/combined-ad-experience-controls.html @@ -824,6 +807,14 @@ sectionTitle: subgroup: 3 +- sbSecId: 2 + title: Global Parameters + link: /prebid-mobile/pbm-api/android/pbm-targeting-params-android.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 3 + - sbSecId: 2 title: GAM Original Integration link: /prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.html @@ -864,14 +855,6 @@ sectionTitle: subgroup: 3 -- sbSecId: 2 - title: Targeting Parameters - link: /prebid-mobile/pbm-api/android/pbm-targeting-params-android.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 3 - - sbSecId: 2 title: Ad Experience Controls link: /prebid-mobile/modules/rendering/combined-ad-experience-controls.html @@ -1503,14 +1486,6 @@ sectionTitle: subgroup: 3 -- sbSecId: 5 - title: Programmatic Guaranteed - link: /prebid-server/features/pg/pbs-pg-idx.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 3 - - sbSecId: 5 title: Modules link: /prebid-server/pbs-modules/ @@ -1818,7 +1793,7 @@ subgroup: 1 - sbSecId: 7 - title: Prebid and MSPA + title: Prebid US Compliance link: /features/mspa-usnat.html isHeader: 0 isSectionHeader: 0 diff --git a/adops/before-you-start.md b/adops/before-you-start.md index 23b075abe2..056e917932 100644 --- a/adops/before-you-start.md +++ b/adops/before-you-start.md @@ -7,7 +7,6 @@ sbUUID: 3.2 --- # Ad Ops and Prebid - {: .no_toc } Ad Operations (Ad Ops) are the people who work directly with the ad server software to create, analyze, and update ad campaigns. In companies that use automated processes rather than working directly in the ad server UI, people in Ad Ops define the inputs to the automation that ensure campaigns run as expected. Whatever your actual job title or exact job description, when we refer to “Ad Ops” we’re talking about the non-engineering tasks involved in running and managing ad campaigns. diff --git a/adops/js-dynamic-creative.md b/adops/js-dynamic-creative.md index 3eb5fc493a..8ead0d2d7e 100644 --- a/adops/js-dynamic-creative.md +++ b/adops/js-dynamic-creative.md @@ -40,6 +40,6 @@ To render native ads, you also need to include the [nativeRendering](/dev-docs/m ## Further reading -- [Creative Considerations](/adops/creative-considerations.md) +- [Creative Considerations](/adops/creative-considerations.html) - [Prebid Universal Creative](/overview/prebid-universal-creative.html) - [Native rendering module](/dev-docs/modules/nativeRendering.html) diff --git a/assets/js/download.js b/assets/js/download.js index 09197ae3e7..e5cc8f7538 100644 --- a/assets/js/download.js +++ b/assets/js/download.js @@ -8,7 +8,7 @@ // show all adapters $(".adapters .col-md-4").show(); setPrepickedModules(); - + document.getElementById('download-button').addEventListener('click', function (event) { event.preventDefault(); submit_download(); @@ -112,6 +112,23 @@ }); } + const renameModules = (function() { + const RENAMES = [ + [ + /^8\./, + { + tcfControl: 'gdprEnforcement', + consentManagementTcf: 'consentManagement', + paapiForGpt: 'fledgeForGpt' + } + ] + ]; + return function(version, modules) { + const renames = RENAMES.find(([pat]) => pat.test(version))?.[1] || {}; + return modules.map(mod => renames.hasOwnProperty(mod) ? renames[mod] : mod) + } + })(); + function get_form_data() { var modules = []; var version = $(".selectpicker").val(); @@ -138,7 +155,7 @@ }); return { - modules, + modules: renameModules(version, modules), version, removedModules, }; diff --git a/dev-docs/activity-controls.md b/dev-docs/activity-controls.md index ef227c9d9b..f1f55285bb 100644 --- a/dev-docs/activity-controls.md +++ b/dev-docs/activity-controls.md @@ -152,7 +152,7 @@ For example, this rule would allow bidderX to perform the activity if no higher Activity control rules in Prebid.js can be created by two main sources: * Publisher `setConfig({allowActivities})` as in the examples shown here. When set this way, rules are considered the highest priority value of 1. -* Modules can set activity control rules, e.g. [usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing), [bidderSettings](/dev-docs/publisher-api-reference/bidderSettings.html), the [GPP](/dev-docs/modules/consentManagementGpp.html) or [GDPR](/dev-docs/modules/gdprEnforcement.html) modules. Rules set by modules have a less urgent priority of 10. +* Modules can set activity control rules, e.g. [usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing), [bidderSettings](/dev-docs/publisher-api-reference/bidderSettings.html), the [GPP](/dev-docs/modules/consentManagementGpp.html) or [GDPR](/dev-docs/modules/tcfControl.html) modules. Rules set by modules have a less urgent priority of 10. When rules are processed, they are sorted by priority, and all rules of the same priority are considered to happen at the same time. The details: @@ -234,7 +234,7 @@ If `allow` is not defined, the rule is assumed to assert **true** (i.e. allow th #### Always include a particular bidder in auctions -This is similiar to the 'vendor exception' feature of the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html). This would always allow bidderA to participate in the auction, even without explicit consent in GDPR scenarios. It might indicate, for instance, that this is a 'first party bidder'. +This is similiar to the 'vendor exception' feature of the [TCF Control Module](/dev-docs/modules/tcfControl.html). This would always allow bidderA to participate in the auction, even without explicit consent in GDPR scenarios. It might indicate, for instance, that this is a 'first party bidder'. ```javascript pbjs.setConfig({ diff --git a/dev-docs/add-rtd-submodule.md b/dev-docs/add-rtd-submodule.md index fbf85669cf..b17f43f36e 100644 --- a/dev-docs/add-rtd-submodule.md +++ b/dev-docs/add-rtd-submodule.md @@ -123,7 +123,7 @@ submodule('realTimeData', subModuleObject); Several of the interfaces get a `userConsent` object. It's an object that carries these attributes: -* [gdpr](/dev-docs/modules/consentManagement.html#bidder-adapter-gdpr-integration) - GDPR +* [gdpr](/dev-docs/modules/consentManagementTcf.html#bidder-adapter-gdpr-integration) - GDPR * [usp](/dev-docs/modules/consentManagementUsp.html#bidder-adapter-us-privacy-integration) - US Privacy (aka CCPA) * [coppa](/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa) - the Child Online Privacy Protection Act diff --git a/dev-docs/analytics/prebidmanager.md b/dev-docs/analytics/AsteriobidPbm.md similarity index 59% rename from dev-docs/analytics/prebidmanager.md rename to dev-docs/analytics/AsteriobidPbm.md index 40f7936fd4..fa22aa4553 100644 --- a/dev-docs/analytics/prebidmanager.md +++ b/dev-docs/analytics/AsteriobidPbm.md @@ -1,8 +1,8 @@ --- layout: analytics -title: PrebidManager -description: PrebidManager Analytics Adapter -modulecode: prebidmanager +title: Asteriobid PBM +description: Asteriobid PBM Analytics Adapter +modulecode: asteriobidpbm --- #### Registration diff --git a/dev-docs/analytics/eplanning.md b/dev-docs/analytics/eplanning.md index 674a616eb5..70fc8a36b7 100644 --- a/dev-docs/analytics/eplanning.md +++ b/dev-docs/analytics/eplanning.md @@ -3,6 +3,7 @@ layout: analytics title: ePlanning description: ePlanning Analytics Adapter modulecode: eplanning +pbjs_version_notes: removed in 9.0 --- #### Registration diff --git a/dev-docs/analytics/growthcode.md b/dev-docs/analytics/growthcode.md index 37ac5e3647..c1947aff27 100644 --- a/dev-docs/analytics/growthcode.md +++ b/dev-docs/analytics/growthcode.md @@ -16,6 +16,7 @@ Please visit [growthcode.io](https://growthcode.io/) for more information. #### Analytics Options +{: .table .table-bordered .table-striped } | Param enableAnalytics | Scope | Type | Description | Example | |-----------------------|----------|--------|---------------------------------------------------------|--------------------------| | provider | Required | String | The name of this Adapter. | `"growthCodeAnalytics"` | diff --git a/dev-docs/analytics/marsmedia.md b/dev-docs/analytics/marsmedia.md deleted file mode 100644 index c1ebc51008..0000000000 --- a/dev-docs/analytics/marsmedia.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: analytics -title: MarsMedia -description: MarsMedia Analytics Adapter -modulecode: marsmedia ---- - -#### Registration - -Please visit [mars.media](https://mars.media/#!group) for more information. diff --git a/dev-docs/analytics/sharethrough.md b/dev-docs/analytics/sharethrough.md index 4c50e6a3ed..a3fb0791db 100644 --- a/dev-docs/analytics/sharethrough.md +++ b/dev-docs/analytics/sharethrough.md @@ -36,7 +36,7 @@ gulp bundle --modules=gptPreAuction,sharethroughBidAdapter,sharethroughAnalytics Please note that the above snippet is a "bare bones" example - you will likely want to include other modules as well. A more realistic example might look something like the example below (with other bid adapters also included in the list as needed): ```sh -gulp bundle --modules=gptPreAuction,consentManagement,consentManagementGpp,consentManagementUsp,enrichmentFpdModule,gdprEnforcement,sharethroughBidAdapter,sharethroughAnalyticsAdapter +gulp bundle --modules=gptPreAuction,consentManagementTcf,consentManagementGpp,consentManagementUsp,enrichmentFpdModule,tcfControl,sharethroughBidAdapter,sharethroughAnalyticsAdapter ``` Enable the Sharethrough Analytics Adapter in Prebid.js using the analytics provider `sharethrough` as seen in the **Example Configuration** section. diff --git a/dev-docs/analytics/sigmoid.md b/dev-docs/analytics/sigmoid.md index 33596e9fc4..cf4bc79a83 100644 --- a/dev-docs/analytics/sigmoid.md +++ b/dev-docs/analytics/sigmoid.md @@ -2,6 +2,7 @@ layout: analytics title: Sigmoid description: Sigmoid Analytics Adapter +pbjs_version_notes: removed in 9.0 modulecode: sigmoid --- diff --git a/dev-docs/analytics/smartyads.md b/dev-docs/analytics/smartyads.md new file mode 100644 index 0000000000..1d522cd655 --- /dev/null +++ b/dev-docs/analytics/smartyads.md @@ -0,0 +1,16 @@ +--- +layout: analytics +title: Smartyads +description: Smartyads Analytics Adapter +modulecode: smartyads +--- + +#### Example Configuration + +```javascript +pbjs.que.push(function () { + pbjs.enableAnalytics({ + provider: 'smartyads' + }); +}); +``` diff --git a/dev-docs/analytics/sonobi.md b/dev-docs/analytics/sonobi.md index 3cf0340b71..c60b4f49de 100644 --- a/dev-docs/analytics/sonobi.md +++ b/dev-docs/analytics/sonobi.md @@ -3,6 +3,7 @@ layout: analytics title: Sonobi description: Sonobi Analytics Adapter modulecode: sonobi +pbjs_version_notes: removed in 9.0 enable_download: false --- diff --git a/dev-docs/analytics/sovrn.md b/dev-docs/analytics/sovrn.md index e9dea298b0..c68bdc5e39 100644 --- a/dev-docs/analytics/sovrn.md +++ b/dev-docs/analytics/sovrn.md @@ -4,6 +4,7 @@ title: Sovrn description: Sovrn Analytics Adapter modulecode: sovrn prebid_member: true +pbjs_version_notes: removed in 9.0 enable_download: false --- diff --git a/dev-docs/analytics/staq.md b/dev-docs/analytics/staq.md index d5e866f490..35ca122e06 100644 --- a/dev-docs/analytics/staq.md +++ b/dev-docs/analytics/staq.md @@ -2,6 +2,7 @@ layout: analytics title: STAQ description: STAQ Analytics Adapter +pbjs_version_notes: removed in 9.0 modulecode: staq --- diff --git a/dev-docs/analytics/tercept.md b/dev-docs/analytics/tercept.md index 009d640164..1fdfaeaefc 100644 --- a/dev-docs/analytics/tercept.md +++ b/dev-docs/analytics/tercept.md @@ -3,8 +3,25 @@ layout: analytics title: Tercept description: Tercept Analytics Adapter modulecode: tercept +enable_download: true --- - #### Registration +To start using Prebid Analytics, please, email us at to provide us with your billing info and get your personal publisher ID & Key along with other details which are used in the prebid config on your site/s. +Add the following code to your prebid.js config to activate Prebid Analytics: +#### Example Configuration + +```text +pbjs.que.push(function() { + pbjs.enableAnalytics({ + provider: 'tercept', + options: { + pubId: , + pubKey: , + host: + pathName: + } +}); +}); +``` -Please visit [www.tercept.com](https://www.tercept.com/) for more information. +Please visit for more information. diff --git a/dev-docs/bidder-adaptor.md b/dev-docs/bidder-adaptor.md index 49fbc7e540..aaeb9dae4c 100644 --- a/dev-docs/bidder-adaptor.md +++ b/dev-docs/bidder-adaptor.md @@ -352,7 +352,7 @@ Notes on parameters in the bidderRequest object: Some of the data in `ortb2` is also made available through other `bidderRequest` fields: * **refererInfo** is provided so you don't have to call any utils functions. See below for more information. -* **gdprConsent** is the object containing data from the [GDPR ConsentManagement](/dev-docs/modules/consentManagement.html) module. For TCF2+, it will contain both the tcfString and the addtlConsent string if the CMP sets the latter as part of the TCData object. +* **gdprConsent** is the object containing data from the [TCF ConsentManagement](/dev-docs/modules/consentManagementTcf.html) module. For TCF2+, it will contain both the tcfString and the addtlConsent string if the CMP sets the latter as part of the TCData object. * **uspConsent** is the object containing data from the [US Privacy ConsentManagement](/dev-docs/modules/consentManagementUsp.html) module. diff --git a/dev-docs/bidders/33across.md b/dev-docs/bidders/33across.md index 4076fae58b..c5dea1516c 100644 --- a/dev-docs/bidders/33across.md +++ b/dev-docs/bidders/33across.md @@ -68,7 +68,7 @@ var adUnits = [ context: 'outstream', // required mimes: ['video/mp4','video/x-flv'], // required protocols: [ 2, 3 ], // required, set at least 1 value in array - placement: 2, // optional, defaults to 2 when context = outstream + plcmt: 2, // optional, defaults to 2 when context = outstream api: [ 1, 2 ], // optional skip: 0, // optional minduration: 5, // optional @@ -104,7 +104,7 @@ var adUnits = [ context: 'instream', // required mimes: ['video/mp4','video/x-flv'], // required protocols: [ 2, 3 ], // required, set at least 1 value in array - placement: 1, // optional, defaults to 1 when context = instream + plcmt: 1, // optional, defaults to 1 when context = instream startdelay: 0, // optional, defaults to 0 when context = instream api: [ 1, 2 ], // optional skip: 0, // optional @@ -147,7 +147,7 @@ var adUnits = [ context: 'outstream', // required mimes: ['video/mp4','video/x-flv'], // required protocols: [ 2, 3 ], // required, set at least 1 value in array - placement: 2, // optional, defaults to 2 when context = outstream + plcmt: 2, // optional, defaults to 2 when context = outstream api: [ 1, 2 ], // optional skip: 0, // optional minduration: 5, // optional diff --git a/dev-docs/bidders/adbookpsp.md b/dev-docs/bidders/adbookpsp.md index edef5f1ed2..3e601f64bf 100644 --- a/dev-docs/bidders/adbookpsp.md +++ b/dev-docs/bidders/adbookpsp.md @@ -11,6 +11,7 @@ coppa_supported: true usp_supported: true pbjs: true pbs: false +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/adliveplus.md b/dev-docs/bidders/adliveplus.md index 242e3931e7..0aed77bd0a 100644 --- a/dev-docs/bidders/adliveplus.md +++ b/dev-docs/bidders/adliveplus.md @@ -4,11 +4,11 @@ title: Adlive Plus description: Adlive Plus adapter biddercode: adliveplus aliasCode: lucead -tcfeu_supported: false -gvl_id: none +tcfeu_supported: true +gvl_id: 1309 usp_supported: false coppa_supported: false -schain_supported: false +schain_supported: true dchain_supported: false media_types: banner safeframes_ok: true @@ -17,37 +17,51 @@ floors_supported: true fpd_supported: true pbjs: true pbs: false -prebid_member: true/false +prebid_member: false ortb_blocking_supported: false privacy_sandbox: paapi sidebarType: 1 --- ### Note -The Adlive Plus adapter requires setup before beginning. Please contact us at [support@adlive.io](mailto:support@adlive.io). +This adapter requires setup before beginning. Please contact us at [support@adlive.io](mailto:support@adlive.io). ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `placementId` | required | Placement id | `'11111'` | `string` | +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------|--------------------|-----------| +| `placementId` | required | Placement ID | `'1'` | `string` | +| `loader` | required | Site specific async loader code | `new Promise(...)` | `Promise` | +| `region` | optional | Endpoint region | `'ap'` | `string` | -### Test Parameters +### Params type definition + +```typescript +type Params = { + placementId: string; + loader: Promise; + region?: 'eu' | 'us' | 'ap'; +}; +``` + +### Test Params ```javascript const adUnits = [ - { - code: 'test-div', - sizes: [[300, 250]], - bids: [ + { + code: 'test-div', + sizes: [[300, 250]], + bids: [ { bidder: 'adliveplus', params: { - placementId: '1', + placementId: '1', // required + loader: new Promise(/* ... */), // required + region: 'ap', // optional 'eu', 'us', 'ap' } } ] } - ]; +]; ``` 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/adzymic.md b/dev-docs/bidders/adzymic.md similarity index 88% rename from dev-docs/adzymic.md rename to dev-docs/bidders/adzymic.md index 585db1c6ee..e05d58752d 100644 --- a/dev-docs/adzymic.md +++ b/dev-docs/bidders/adzymic.md @@ -6,13 +6,16 @@ biddercode: adzymic pbjs: true pbs: false aliasCode: appnexus -gdpr_supported: true +tcfeu_supported: true +usp_supported: false +coppa_supported: false +gpp_supported: false media_types: banner, video, native safeframes_ok: false multiformat_supported: will-bid-on-any gvl_id: 723 schain_supported: true -userId: all +userIds: all sidebarType: 1 --- ### Bid Params diff --git a/dev-docs/bidders/aidem.md b/dev-docs/bidders/aidem.md index ea8ba9b2ed..6aeb6266eb 100644 --- a/dev-docs/bidders/aidem.md +++ b/dev-docs/bidders/aidem.md @@ -70,7 +70,7 @@ This module is GDPR and CCPA compliant, and no 3rd party userIds are allowed. {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |--------|----------|--------------------------------------------------------------------------------------------------|---------|----------| -| `gdpr` | optional | GDPR Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagement.html) | `{}` | `Object` | +| `gdpr` | optional | GDPR Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagementTcf.html) | `{}` | `Object` | | `usp` | optional | USP Object see [Prebid.js doc](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | `{}` | `Object` | #### Example Banner ad unit @@ -212,7 +212,7 @@ For video: gulp serve --modules=aidemBidAdapter,dfpAdServerVideo ## FAQs -#### How do I view AIDEM bid request? +### How do I view AIDEM bid request? Navigate to a page where AIDEM is setup to bid. In the network tab, search for requests to `zero.aidemsrv.com/bid/request`. diff --git a/dev-docs/bidders/algorix.md b/dev-docs/bidders/algorix.md index 705586e6c0..83265c579e 100644 --- a/dev-docs/bidders/algorix.md +++ b/dev-docs/bidders/algorix.md @@ -2,9 +2,9 @@ layout: bidder title: AlgoriX description: Prebid AlgoriX Bidder Adapter +gvl_id: 1176 biddercode: algorix tcfeu_supported: true -gvl_id: usp_supported: true coppa_supported: true schain_supported: true @@ -14,6 +14,7 @@ pbs: true pbs_app_supported: true prebid_member: true sidebarType: 1 +userIds: all --- ### Note diff --git a/dev-docs/bidders/appnexus.md b/dev-docs/bidders/appnexus.md index a8dff8af88..834f91fe41 100644 --- a/dev-docs/bidders/appnexus.md +++ b/dev-docs/bidders/appnexus.md @@ -45,6 +45,9 @@ All AppNexus (Xandr) placements included in a single call to `requestBids` must #### Bid Params +{: .alert.alert-danger :} +Starting with Prebid.js version 9.0, an update was made to the `appnexusBidAdapter.js` file to remove the support for the `transformBidParams` function. Previously this standard adapter function was used in conjunction of Prebid.js > PBS requests to modify any bid params for that bidder to the bid param format used by the PBS endpoint. Part of the changes for 9.0 in general were to remove these functions from the client-side adapter files, in order to reduce the build size of Prebid.js for those publishers who wanted to make the PBS requests. In the case of our adapter, we instead created a new module named `anPspParamsConverter` that would mimic behavior of the `transformBidParams` function. There's no setup instructions needed on the Prebid.js configs, the module only needs to be included in the Prebid.js build file and it will perform the needed steps. If you have any questions on this change, please reach out to your Microsoft representative and they can help. + {: .alert.alert-danger :} Starting with Prebid.js version 7.36.0, an update was made to the `appnexusBidAdapter.js` file to support bid params in a lower-case underscore format (eg `invCode` to `inv_code`) similar to how the params are formatted for the Prebid Server AppNexus bidder. This change was implemented to streamline publisher setups for both projects instead of maintaining separate versions of the same params depending on what setup is used. To avoid breaking changes, the old 'camelCase' format is still currently supported for all AppNexus bid params in the `appnexusBidAdapter.js` file. If you are using an older version of Prebid.js, you will need to continue to use the older 'camelCase' format as appropriate. diff --git a/dev-docs/bidders/beachfront.md b/dev-docs/bidders/beachfront.md index afd897fdfd..9e9f73c946 100644 --- a/dev-docs/bidders/beachfront.md +++ b/dev-docs/bidders/beachfront.md @@ -52,6 +52,7 @@ For further information, please contact . | `playbackmethod` | optional | Playback method supported by the publisher.
`1`: Auto-play sound on
`2`: Auto-play sound off
`3`: Click-to-play
`4`: Mouse-over | `1` | `integer` | | `maxduration` | optional | Maximum video ad duration in seconds. | `30` | `integer` | | `placement` | optional | Placement type for the impression.
`1`: In-Stream
`2`: In-Banner
`3`: In-Article
`4`: In-Feed
`5`: Interstitial/Slider/Floating | `1` | `integer` | +| `plcmt` | optional | Placement type for the impression. See [AdCOM v1 spec](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/develop/AdCOM%20v1.0%20FINAL.md#list_plcmtsubtypesvideo) | `1` | `integer` | | `skip` | optional | Indicates if the player will allow the video to be skipped. | `1` | `integer` | | `skipmin` | optional | Videos of total duration greater than this number of seconds can be skippable. | `15` | `integer` | | `skipafter` | optional | Number of seconds a video must play before skipping is enabled. | `5` | `integer` | diff --git a/dev-docs/bidders/bizzclick.md b/dev-docs/bidders/bizzclick.md deleted file mode 100644 index 15872a4126..0000000000 --- a/dev-docs/bidders/bizzclick.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: bidder -title: BizzClick -description: Prebid BizzClick Bidder Adaptor -biddercode: bizzclick -tcfeu_supported: false -usp_supported: true -coppa_supported: true -schain_supported: true -media_types: banner, video, native -safeframes_ok: true -deals_supported: true -pbjs: true -pbs: true -pbs_app_supported: true -sidebarType: 1 -floors_supported: true -prebid_member: false -fpd_supported: false -gvl_id: none -multiformat_supported: will-bid-on-one -ortb_blocking_supported: true -userIds: all ---- - -### Note - -The Example Bidding adapter requires setup before beginning. Please contact us at .BizzClick will only respond to the first impression and that multiple ad formats of that single impression are not supported. - -### Bid Params for Prebid Server and Prebid Mobile - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `sourceId` | required | Unique hash provided by bizzclick | `'6dllcEHSxYdSb6yLmCqE'` | `string` | -| `accountId` | required | Unique name provided by bizzclick | `'bizzclick-test'` | `string` | -| `host` | optional | Bizzclick 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 - -{: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `sourceId` | required | Unique hash provided by bizzclick | `'6dllcEHSxYdSb6yLmCqE'` | `string` | -| `accountId` | required | Unique name provided by bizzclick | `'bizzclick-test'` | `string` | -| `host` | optional | Bizzclick server region. US East by default | `'us-e-node1'` | `string` | diff --git a/dev-docs/bidders/blasto.md b/dev-docs/bidders/blasto.md new file mode 100644 index 0000000000..cda556c3a6 --- /dev/null +++ b/dev-docs/bidders/blasto.md @@ -0,0 +1,48 @@ +--- +layout: bidder +title: Blasto +description: Prebid Blasto Bidder Adaptor +biddercode: blasto +tcfeu_supported: false +usp_supported: true +coppa_supported: true +schain_supported: true +media_types: banner, video, native +safeframes_ok: true +deals_supported: true +pbjs: true +pbs: true +pbs_app_supported: true +sidebarType: 1 +floors_supported: true +prebid_member: false +fpd_supported: false +gvl_id: none +multiformat_supported: will-bid-on-one +ortb_blocking_supported: true +userIds: all +--- + +### Note + +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 +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` | + +### Bid Params for Prebid.js + +{: .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` | diff --git a/dev-docs/bidders/bluebillywig.md b/dev-docs/bidders/bluebillywig.md index 33c8a43772..53ae1c57c0 100644 --- a/dev-docs/bidders/bluebillywig.md +++ b/dev-docs/bidders/bluebillywig.md @@ -11,6 +11,7 @@ schain_supported: true coppa_supported: true usp_supported: true userIds: britepoolId, criteo, id5Id, identityLink, liveIntentId, netId, parrableId, pubCommonId, unifiedId +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/brightcom.md b/dev-docs/bidders/brightcom.md deleted file mode 100644 index 2953aba6a7..0000000000 --- a/dev-docs/bidders/brightcom.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: bidder -title: Brightcom -description: Prebid Brightcom Bidder Adaptor -top_nav_section: dev_docs -nav_section: reference -pbjs: true -biddercode: brightcom -gvl_id: 883 -tcfeu_supported: true -sidebarType: 1 ---- - -### Note - -The Brightcom bidder adapter requires setup and approval from the Brightcom team. Please reach out to your account manager for more information and to start using it. - -### Bid params - -{: .table .table-bordered .table-striped } - -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `publisherId` | required | The publisher ID from Brightcom | `2141020` | `integer` | -| `bidFloor` | optional | The minimum bid value desired | `1.23` | `float` | diff --git a/dev-docs/bidders/brightcomssp.md b/dev-docs/bidders/brightcomssp.md deleted file mode 100644 index d78e661a67..0000000000 --- a/dev-docs/bidders/brightcomssp.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: bidder -title: Brightcom SSP -description: Prebid Brightcom SSP Bidder Adaptor -top_nav_section: dev_docs -nav_section: reference -pbjs: true -biddercode: bcmssp -filename: brightcomSSPBidAdapter -tcfeu_supported: true -usp_supported: true -coppa_supported: true -schain_supported: true -sidebarType: 1 -gvl_id: 883 -floors_supported: true ---- - -### Note - -The Brightcom SSP bidder adapter requires setup and approval from the Brightcom team. Please reach out to your account manager for more information and to start using it. - -### Bid params - -{: .table .table-bordered .table-striped } - -| Name | Scope | Description | Example | Type | -| ---- | ----- | ----------- | ------- | ---- | -| `publisherId` | required | The publisher ID from Brightcom | `2141020` | `integer` | -| `bidFloor` | optional | The minimum bid value desired | `1.23` | `float` | 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/colombia.md b/dev-docs/bidders/colombia.md new file mode 100644 index 0000000000..7224b8be41 --- /dev/null +++ b/dev-docs/bidders/colombia.md @@ -0,0 +1,30 @@ +--- +layout: bidder +title: Colombia +description: Prebid Colombia Bidder Adaptor +biddercode: colombia +media_types: banner, video, native +prebid_member: true +pbjs: true +pbs: false +pbs_app_supported: false +fpd_supported: true +multiformat_supported: will-bid-on-one +--- + +### Note + +The Colombia bidding adapter requires setup and approval before implementation. Please reach out to for more details. + +### Prebid.js Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------------|----------|----------------------------------------------------------|------------|-----------| +| `adSlot` | Required | adSlot will be generated on colombia SSP Platform. | `'3849382'` | `string` | +| `keywords` | optional | Comma separated string. | `'India, India news, India news today'` | `string` | +| `category` | optional | Page Categorization. | `'Election, Sports, Entertainments'` | `string` | +| `pagetype` | optional | Type of page. | `'Listing, Show, Liveblog, Photostory'` | `string` | +| `incognito` | optional | 1, for incognito mode. | `'1'` | `string` | +| `dsmi` | optional | CCPA Compliance Flag. | `'0','1'` | `string` | +| `optout` | optional | GDPR Compliance Flag. | `'0','1'` | `string` | diff --git a/dev-docs/bidders/cpmstar.md b/dev-docs/bidders/cpmstar.md index 0573d20d60..0c43369a01 100644 --- a/dev-docs/bidders/cpmstar.md +++ b/dev-docs/bidders/cpmstar.md @@ -6,9 +6,11 @@ pbjs: true pbs: true biddercode: cpmstar media_types: banner, video -tcfeu_supported: false +tcfeu_supported: true +gvl_id: 1317 usp_supported: true coppa_supported: true +schain_supported: true sidebarType: 1 --- diff --git a/dev-docs/bidders/dailymotion.md b/dev-docs/bidders/dailymotion.md index 5557b2befb..e418e7db33 100644 --- a/dev-docs/bidders/dailymotion.md +++ b/dev-docs/bidders/dailymotion.md @@ -24,7 +24,7 @@ To use the adapter with any non-test request, you first need to ask an API key f This API key will ensure proper identification of your inventory and allow you to get real bids. -# Configuration options +### Configuration options Before calling this adapter, you need to at least set a video adUnit in an instream context and the API key in the bid parameters: @@ -49,7 +49,29 @@ const adUnits = [ `apiKey` is your publisher API key. For testing purpose, you can use "dailymotion-testing". -# Test Parameters +#### User Sync + +To enable user synchronization, add the following code. Dailymotion highly recommends using iframes and/or pixels for user syncing. This feature enhances DSP user match rates, resulting in higher bid rates and bid prices. Ensure that `pbjs.setConfig()` is called only once. + +```javascript +pbjs.setConfig({ + userSync: { + syncEnabled: true, + filterSettings: { + iframe: { + bidders: '*', // Or add dailymotion to your list included bidders + filter: 'include' + }, + image: { + bidders: '*', // Or add dailymotion to your list of included bidders + filter: 'include' + }, + }, + }, +}); +``` + +### Test Parameters By setting the following bid parameters, you'll get a constant response to any request, to validate your adapter integration: @@ -74,7 +96,7 @@ const adUnits = [ Please note that failing to set these will result in the adapter not bidding at all. -# Sample video AdUnit +### Sample video AdUnit To allow better targeting, you should provide as much context about the video as possible. There are three ways of doing this depending on if you're using Dailymotion player or a third party one. @@ -130,7 +152,12 @@ const adUnits = [ private: false, tags: 'tag_1,tag_2,tag_3', title: 'test video', + url: 'https://test.com/testvideo' topics: 'topic_1, topic_2', + isCreatedForKids: false, + videoViewsInSession: 1, + autoplay: false, + playerVolume: 8 } } }], @@ -139,6 +166,12 @@ const adUnits = [ video: { api: [2, 7], context: 'instream', + mimes: ['video/mp4'], + minduration: 5, + maxduration: 30, + playbackmethod: [3], + plcmt: 1, + protocols: [7, 8, 11, 12, 13, 14] startdelay: 0, w: 1280, h: 720, @@ -160,10 +193,18 @@ Each of the following video metadata fields can be added in bids.params.video. * `private` - True if video is not publicly available * `tags` - Tags for the video, comma separated * `title` - Video title +* `url` - URL of the content * `topics` - Main topics for the video, comma separated * `xid` - Dailymotion video identifier (only applicable if using the Dailymotion player) +* `isCreatedForKids` - [The content is created for children as primary audience](https://faq.dailymotion.com/hc/en-us/articles/360020920159-Content-created-for-kids) + +The following contextual informations can also be added in bids.params.video. + +* `videoViewsInSession` - Number of videos viewed within the current user session +* `autoplay` - Playback was launched without user interaction +* `playerVolume` - Player volume between 0 (muted, 0%) and 10 (100%) -If you already specify [First-Party data](https://docs.prebid.org/features/firstPartyData.html) through the `ortb2` object when calling [`pbjs.requestBids(requestObj)`](https://docs.prebid.org/dev-docs/publisher-api-reference/requestBids.html), we will fallback to those values when possible. See the mapping below. +If you already specify [First-Party data](https://docs.prebid.org/features/firstPartyData.html) through the `ortb2` object when calling [`pbjs.requestBids(requestObj)`](https://docs.prebid.org/dev-docs/publisher-api-reference/requestBids.html), we will collect the following values and fallback to bids.params.video values when applicable. See the mapping below. | From ortb2 | Metadata fields | |---------------------------------------------------------------------------------|-----------------| @@ -174,3 +215,9 @@ If you already specify [First-Party data](https://docs.prebid.org/features/first | `ortb2.site.content.livestream` | `livestream` | | `ortb2.site.content.keywords` | `tags` | | `ortb2.site.content.title` | `title` | +| `ortb2.site.content.url` | `url` | +| `ortb2.app.bundle` | N/A | +| `ortb2.app.storeurl` | N/A | +| `ortb2.device.lmt` | N/A | +| `ortb2.device.ifa` | N/A | +| `ortb2.device.ext.atts` | N/A | diff --git a/dev-docs/bidders/driftpixel.md b/dev-docs/bidders/driftpixel.md new file mode 100644 index 0000000000..2c8cda4d51 --- /dev/null +++ b/dev-docs/bidders/driftpixel.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: driftpixel +description: driftpixel Bidder Adapter +biddercode: driftpixel +media_types: banner, video +coppa_supported: true +tcfeu_supported: false +usp_supported: true +prebid_member: false +pbjs: true +pbs: true +schain_supported: true +floors_supported: true +multiformat_supported: will-bid-on-any +sidebarType: 1 +safeframes_ok: true +--- + +### Prebid.js Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|-----------------------------|---------------|-----------| +| `pid` | required | Placement ID | `test-banner` | `string` | +| `env` | required | Environment name | `driftpixel` | `string` | +| `ext` | optional | Specific integration config | `{}` | `object` | + +### Prebid Server Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|-----------------------------|---------------|-----------| +| `pid` | required | Unique placement ID | `pid1` | `string` | +| `env` | optional | Driftpixel environment | `test` | `string` | diff --git a/dev-docs/bidders/e_volution.md b/dev-docs/bidders/e_volution.md index 5282e7589b..0d061f302c 100644 --- a/dev-docs/bidders/e_volution.md +++ b/dev-docs/bidders/e_volution.md @@ -2,16 +2,24 @@ layout: bidder title: E-volution tech description: Prebid E-volution tech Bidder Adapter -pbjs: true biddercode: e_volution +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 gvl_id: 957 +multiformat_supported: will-bid-on-one +userIds: all +pbjs: true pbs: true pbs_app_supported: true -usp_supported: true -schain_supported: true -userIds: id5Id +safeframes_ok: true sidebarType: 1 --- diff --git a/dev-docs/bidders/ebdr.md b/dev-docs/bidders/ebdr.md index 0fc6be4dd5..d1938b3aff 100644 --- a/dev-docs/bidders/ebdr.md +++ b/dev-docs/bidders/ebdr.md @@ -5,6 +5,7 @@ description: Prebid EngageBDR Bidder Adaptor biddercode: ebdr pbjs: true media_types: video +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/hyperbrainz.md b/dev-docs/bidders/hyperbrainz.md new file mode 100644 index 0000000000..c1cc738088 --- /dev/null +++ b/dev-docs/bidders/hyperbrainz.md @@ -0,0 +1,36 @@ +--- +layout: bidder +title: HyperBrainz +description: HyperBrainz Adaptor +biddercode: hyperbrainz +pbjs: true +pbs: false +media_types: banner, native, video +gvl_id: 14 (adkernel) +tcfeu_supported: true +gpp_sids: tcfeu, usp +usp_supported: true +coppa_supported: true +pbs_app_supported: false +schain_supported: true +userIds: all +fpd_supported: true +prebid_member: false +ortb_blocking_supported: true +multiformat_supported: will-bid-on-one +floors_supported: true +aliasCode: adkernel +sidebarType: 1 +--- + +### Note + +The HyperBrainz bidding adapter requires setup and approval before implementation. Please reach out to for more details. + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|----------|----------|-----------------------|---------------------------|----------| +| `host` | required | RTB host | `'cpm.hb.hyperbrainz.com'` | `string` | +| `zoneId` | required | Zone Id | 30164 | `integer` | diff --git a/dev-docs/bidders/improvedigital.md b/dev-docs/bidders/improvedigital.md index 0cc21342ff..893e98b235 100644 --- a/dev-docs/bidders/improvedigital.md +++ b/dev-docs/bidders/improvedigital.md @@ -39,11 +39,11 @@ sidebarType: 1 #### Sizes -By default, the adapter doesn't send Prebid ad unit sizes to Improve Digital's ad server and the sizes defined for each placement in the Polaris platform will be used. If the ad server should only respond with creative sizes as defined in Prebid ad unit configuration, turn on `usePrebidSizes` adapter parameter like this: +By default, the adapter sends Prebid ad unit sizes to Improve Digital's ad server. If the ad server should only respond with creative sizes as defined for each placement in the Origin platform, turn off `usePrebidSizes` adapter parameter like this: ```javascript pbjs.setConfig({ - improvedigital: { usePrebidSizes: true } + improvedigital: { usePrebidSizes: false } }); ``` diff --git a/dev-docs/bidders/insticator.md b/dev-docs/bidders/insticator.md index ec3b8565f7..0ec593375a 100644 --- a/dev-docs/bidders/insticator.md +++ b/dev-docs/bidders/insticator.md @@ -10,11 +10,13 @@ usp_supported: true coppa_supported: true gdpr_supported: true schain_supported: true +floors_supported: true media_types: banner, video multiformat_supported: will-bid-on-any pbjs: true gvl_id: 910 sidebarType: 1 +userIds: all --- ### Bid Params @@ -23,11 +25,14 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |-----------------------------|----------|-----------------------------------------------------------------------------------------|------------------------------------|----------| | `adUnitId` | Required | The ad unit ID provided by Insticator | `'test'` | `string` | +| `publisherId` | optional | The publisher ID provided by Insticator | `'test'` | `string` | | `yob` | optional | Year of Birth | `'1982'` | `string` | | `gender` | optional | Gender | `'M'` | `string` | | `instl` | optional | 1 = the ad is interstitial or full screen, 0 = not interstitial. | `1` | `number` | | `pos` | optional | ad position as per IAB standards | `1` | `number` | -| `bid_endpoint_request_url` | optional | Url string representing the endpoint Insticator adaptor should make the request bids to. | `https://ex.ingage.com/v1/openrtb` | `string` | +| `bid_endpoint_request_url` | optional | Url string representing the endpoint Insticator adaptor should make the request bids to.| `https://ex.ingage.com/v1/openrtb` | `string` | +| `floor` | optional | Sets a floor for bidder. | `0.50` | `float` | +| `bidfloorcur` | optional | Currency of the floor. (Insticator only supports USD floors) | `USD` | `string` | ### Banner Params @@ -55,7 +60,8 @@ var adUnitsBannerOnly = [ { bidder: 'insticator', params: { - adUnitId: 'example_adunit_id', + adUnitId: 'example_adunit_id', + publisherId: 'example_publisher_id', }, }, ], @@ -167,7 +173,8 @@ var adUnits = [ bids: [{ bidder: 'insticator', params: { - adUnitId: 'example_adunit_id' + adUnitId: 'example_adunit_id', + publisherId: 'example_publisher_id', } }], ... diff --git a/dev-docs/bidders/iqm.md b/dev-docs/bidders/iqm.md index 31b546afcb..d27390b972 100644 --- a/dev-docs/bidders/iqm.md +++ b/dev-docs/bidders/iqm.md @@ -4,6 +4,7 @@ title: iQM description: Prebid iQM Bidder Adaptor pbjs: true biddercode: iqm +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- @@ -23,7 +24,7 @@ Module that connects to iQM demand sources ## Test Parameters -``` +```javascript var adUnits = [{ code: 'div-gpt-ad-1460505748561-0', mediaTypes: { @@ -51,7 +52,7 @@ var adUnits = [{ ## adUnit Video -``` +```javascript var videoAdUnit = { code: 'video1', mediaTypes: { diff --git a/dev-docs/bidders/iqzone.md b/dev-docs/bidders/iqzone.md index 57ff266f39..8a3278dc03 100644 --- a/dev-docs/bidders/iqzone.md +++ b/dev-docs/bidders/iqzone.md @@ -3,23 +3,32 @@ layout: bidder title: IQzone description: Prebid IQzone Bidder Adapter biddercode: iqzone -usp_supported: true +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: true pbs_app_supported: true +safeframes_ok: true sidebarType: 1 --- ### Prebid.js Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `placementId` | optional | Placement Id | `'0'` | `'string'` | -| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | +| Name | Scope | Description | Example | Type | +|---------------|----------|-----------------------|-----------|------------| +| `placementId` | optional | Placement Id | `'0'` | `'string'` | +| `endpointId` | optional | Endpoint Id | `'0'` | `'string'` | ### Note diff --git a/dev-docs/bidders/ix.md b/dev-docs/bidders/ix.md index 0edc681474..9c9190e7ca 100644 --- a/dev-docs/bidders/ix.md +++ b/dev-docs/bidders/ix.md @@ -5,7 +5,7 @@ description: Prebid Index Exchange Bidder Adapter biddercode: ix pbjs: true pbs: false -userIds: idl, netId, fabrickId, zeotapIdPlus, uid2, TDID, id5Id, lotamePanoramaId, publinkId, hadronId, pubcid, utiq, criteoID, euid, imuid, 33acrossId, nonID, pairid, MRKL +userIds: amazonAdvertisingID, fabrickId, zeotapIdPlus, TDID, tpid, id5Id, lotamePanoramaId, publinkId, hadronId, pubcid, trustpid, utiqMtpId, criteoID, euid, imuid, 33acrossId, nonID, pairId, M1ID, RampID, connectId pbs_app_supported: true schain_supported: true coppa_supported: true @@ -318,30 +318,46 @@ pbjs.addAdUnits({ code: slot.code, mediaTypes: { native: { - image: { - required: true, - sizes: [150, 50] - }, - title: { - required: true, - len: 80 - }, - sponsoredBy: { - required: true - }, - clickUrl: { - required: true - }, - privacyLink: { - required: false - }, - body: { - required: true - len: 90 - }, - icon: { - required: true, - sizes: [50, 50] + ortb: { + assets: [{ + id: 1, + required: 1, + img: { + type: 3, + w: 150, + h: 50, + } + }, + { + id: 2, + required: 1, + title: { + len: 80 + } + }, + { + id: 3, + required: 1, + data: { + type: 1 + } + }, + { + id: 4, + required: 1, + data: { + type: 2 + } + }, + { + id: 6, + required: 1, + img: { + type: 1, + w: 50, + h: 50, + } + }] } } }, @@ -582,7 +598,6 @@ var adUnits = [{ mediaTypes: { video: { // Preferred location as of version 4.43 - video obj context: 'instream', playerSize: [300, 250], api: [2], @@ -590,7 +605,8 @@ var adUnits = [{ minduration: 5, maxduration: 30, mimes: ['video/mp4', 'application/javascript'], - placement: 3 + placement: 3, + plcmt: 1 } }, bids: [{ @@ -649,30 +665,46 @@ pbjs.addAdUnits({ code: slot.code, mediaTypes: { native: { - image: { - required: true, - sizes: [150, 50] - }, - title: { - required: true, - len: 80 - }, - sponsoredBy: { - required: true - }, - clickUrl: { - required: true - }, - privacyLink: { - required: false - }, - body: { - required: true - len: 90 - }, - icon: { - required: true, - sizes: [50, 50] + ortb: { + assets: [{ + id: 1, + required: 1, + img: { + type: 3, + w: 150, + h: 50, + } + }, + { + id: 2, + required: 1, + title: { + len: 80 + } + }, + { + id: 3, + required: 1, + data: { + type: 1 + } + }, + { + id: 4, + required: 1, + data: { + type: 2 + } + }, + { + id: 6, + required: 1, + img: { + type: 1, + w: 50, + h: 50, + } + }] } } }, diff --git a/dev-docs/bidders/jdpmedia.md b/dev-docs/bidders/jdpmedia.md new file mode 100644 index 0000000000..5b2367ed9a --- /dev/null +++ b/dev-docs/bidders/jdpmedia.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: JDPMedia +description: JDPMedia Bidder Adapter +biddercode: jdpmedia +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: true +--- + +### 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/lucead.md b/dev-docs/bidders/lucead.md index 5d6aa90cbd..1715e7d260 100644 --- a/dev-docs/bidders/lucead.md +++ b/dev-docs/bidders/lucead.md @@ -3,11 +3,11 @@ layout: bidder title: Lucead description: Prebid Lucead Bidder Adapter biddercode: lucead -tcfeu_supported: false -gvl_id: none +tcfeu_supported: true +gvl_id: 1309 usp_supported: false coppa_supported: false -schain_supported: false +schain_supported: true dchain_supported: false media_types: banner safeframes_ok: true @@ -16,37 +16,51 @@ floors_supported: true fpd_supported: true pbjs: true pbs: false -prebid_member: true/false +prebid_member: false ortb_blocking_supported: false privacy_sandbox: paapi sidebarType: 1 --- ### Note -The Lucead Bidding adapter requires setup before beginning. Please contact us at [prebid@lucead.com](mailto:prebid@lucead.com). +This adapter requires setup before beginning. Please contact us at [prebid@lucead.com](mailto:prebid@lucead.com). ### Bid Params {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|-----------------------|-----------|-----------| -| `placementId` | required | Placement id | `'11111'` | `string` | +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------------------|--------------------|-----------| +| `placementId` | required | Placement ID | `'1'` | `string` | +| `loader` | required | Site specific async loader code | `new Promise(...)` | `Promise` | +| `region` | optional | Endpoint region | `'us'` | `string` | -### Test Parameters +### Params type definition + +```typescript +type Params = { + placementId: string; + loader: Promise; + region?: 'eu' | 'us' | 'ap'; +}; +``` + +### Test Params ```javascript const adUnits = [ - { - code: 'test-div', - sizes: [[300, 250]], - bids: [ + { + code: 'test-div', + sizes: [[300, 250]], + bids: [ { bidder: 'lucead', params: { - placementId: '1', + placementId: '1', // required + loader: new Promise(/* ... */), // required + region: 'us', // optional 'eu', 'us', 'ap' } } ] } - ]; +]; ``` diff --git a/dev-docs/bidders/mediago.md b/dev-docs/bidders/mediago.md index 4b5f4fcd94..3d31348b80 100644 --- a/dev-docs/bidders/mediago.md +++ b/dev-docs/bidders/mediago.md @@ -3,11 +3,14 @@ layout: bidder title: MediaGo description: MediaGo Prebid Bidder Adapter biddercode: mediago -media_types: banner +media_types: banner,native +prebid_member: true +userIds: all (with commercial activation) tcfeu_supported: true coppa_supported: true usp_supported: true pbjs: true +pbs: true floors_supported: true gvl_id: 1020 pbjs_version_notes: not ported to 5.x, added back 7.13 @@ -26,7 +29,8 @@ The MediaGo Bidding adapter requires setup before beginning. Please contact us a {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | |---------------|----------|-----------------------|-----------|-----------| -| `token` | required | publisher token | `'1e100887dd614b7f69fdd1360437'` | `string` | -| `test` | recommend | 0(default): production env mode.
1: dev env mode and no charge.we will bid Higher frequency to make debug easier. | `1/0` | `Number` | -| `bidfloor` | recommend | Sets a floor price for the bid | `0.05` | `float` | +| `token` | required | publisher token, This parameter expects all imps to be the same | `'1e100887dd614b7f69fdd1360437'` | `string` | +| `region` | recommend | Server region for PBS request: US for US Region, EU for EU Region, APAC for APAC Region, default is US. This parameter expects all imps to be the same. This parameter is available for PBS only. | `'US'` | `string` | +| `test` | recommend | 0(default): production env mode.
1: dev env mode and no charge.we will bid Higher frequency to make debug easier. This parameter is available for PBJS only. | `1/0` | `Number` | +| `bidfloor` | recommend | Sets a floor price for the bid. This parameter is available for PBJS only. | `0.05` | `float` | | `placementId` | recommend | The AD placement ID | `12341234` | `string` | diff --git a/dev-docs/bidders/mediakeys.md b/dev-docs/bidders/mediakeys.md index 45efb078da..ca43f30489 100644 --- a/dev-docs/bidders/mediakeys.md +++ b/dev-docs/bidders/mediakeys.md @@ -166,7 +166,7 @@ Mediakeys fully supports the following [Prebid.js Modules](https://docs.prebid.o {: .table .table-bordered .table-striped } | Module | Scope | |-------------------------------------------------------------------------------------------------------|-----------------------------| -| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagement.html) | Required in Europe | +| [Consent Management - GDPR](https://docs.prebid.org/dev-docs/modules/consentManagementTcf.html) | Required in Europe | | [Consent Management - US Privacy](https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html) | Required in US - California | | [Supply Chain Object](https://docs.prebid.org/dev-docs/modules/schain.html) | Required for all traffic | | [Instream Tracking](https://docs.prebid.org/dev-docs/modules/instreamTracking.html) | Required for Instream Video | diff --git a/dev-docs/bidders/medianet.md b/dev-docs/bidders/medianet.md index 81b317b744..8b402d6818 100644 --- a/dev-docs/bidders/medianet.md +++ b/dev-docs/bidders/medianet.md @@ -42,7 +42,7 @@ sidebarType: 1 |h|integer|(Recommended) Specifies the height of the video player, in pixels. Required if playerSize not present in `mediaTypes.video`|480| |startdelay|integer |(Recommended) Specifies the start delay of the video ad|0| |battr|array of integers|Specifies the video creative attributes to block. Refer to section 5.3 of the IAB specification for a list of attributes.| [ 13, 14 ]| -playbackmethod|array of integers|Specifies the allowed playback methods. If not specified, all are assumed to be allowed. Currently supported values are: `1: Autoplay, sound on`; `2: Autoplay, sound off`; `3: Click to play`; `4: Mouse over to play`|[1, 3]| +|playbackmethod|array of integers|Specifies the allowed playback methods. If not specified, all are assumed to be allowed. Currently supported values are: `1: Autoplay, sound on`; `2: Autoplay, sound off`; `3: Click to play`; `4: Mouse over to play`|[1, 3]| |api| array of integers|Specifies the supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. Currently supported values are: `1: VPAID 1.0`; `2: VPAID 2.0`; `3: MRAID-1`; `4: ORMMA`; `5: MRAID-2`|[1, 2]| |protocols|array of integers|Array of supported video protocols. Currently supported values are: `1: VAST 1.0`; `2: VAST 2.0`; `3: VAST 3.0`; `4: VAST 1.0 Wrapper`; `5: VAST 2.0 Wrapper`; `6: VAST 3.0 Wrapper`; `7: VAST 4.0`|[1, 2]| |placement|integer|Placement type for the impression. Possible options: `1: In-Stream`; `2: In-banner`; `3: Outstream/In-article`; `4: In-feed`; `5: Interstitial/Slider/Floating`; `6: Long-Form`;|1| @@ -143,3 +143,25 @@ var adUnits = [{ }] }]; ``` + +# Protected Audience API (FLEDGE) + +To enable PAAPI auctions follow the instructions below: + +1. Add the `fledgeForGpt` and `paapi` modules to your prebid bundle. +2. Add the following configuration for the module + +```javascript +pbjs.que.push(function() { + pbjs.setConfig({ + fledgeForGpt: { + enabled: true, + bidders: ['medianet'], + defaultForSlots: 1 + } + }); +}); +``` + +For a detailed guide to enabling PAAPI auctions follow Prebid's documentation +on [`fledgeForGpt`](https://docs.prebid.org/dev-docs/modules/fledgeForGpt.html) 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/minutemediaplus.md b/dev-docs/bidders/minutemediaplus.md index 68f867d9de..b1d8ef2c0e 100644 --- a/dev-docs/bidders/minutemediaplus.md +++ b/dev-docs/bidders/minutemediaplus.md @@ -21,6 +21,7 @@ ortb_blocking_supported: false multiformat_supported: will-bid-on-one gvl_id: 918 pbjs: true +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/monetixads.md b/dev-docs/bidders/monetixads.md new file mode 100644 index 0000000000..2039fb405e --- /dev/null +++ b/dev-docs/bidders/monetixads.md @@ -0,0 +1,91 @@ +--- +layout: bidder +title: Monetix Ads +description: Prebid Monetix Bidder Adapter. +pbjs: true +pbs: true +biddercode: monetixads +media_types: banner,video,native +gvl_id: 1281 (admatic) +tcfeu_supported: true +usp_supported: true +coppa_supported: true +gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp +schain_supported: true +dchain_supported: false +userIds: criteo, id5Id, sharedId, unifiedId +safeframes_ok: true +floors_supported: true +aliasCode: admatic +multiformat_supported: will-bid-on-any +sidebarType: 1 +--- + +### Description + +Monetix Ads header bidding adapter connects with Monetix Ads demand sources to fetch bids for network ID. Please reach out to your account manager or for more information. + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|-------------|----------|-------------------------------------|----------|----------| +| `networkId` | required | The network ID from Monetix Ads | `12345` | `number` | +| `host` | required | RTB Host | `rtb.network.monetixads.com` | `string` | + +### Test Parameters + +300x250 banner test + +```javascript +var adUnits = [{ + code: 'your-slot_1-div', + mediaTypes: { + banner: { sizes: [[300, 250]] }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +},{ + code: 'your-slot_2-div', + mediaTypes: { + native: { ... }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +},{ + code: 'your-slot_3-div', + mediaTypes: { + video: { ... }, + }, + bids: [{ + bidder: 'monetixads', + params: { + networkId: 12345, + host: 'rtb.network.monetixads.com' + } + }] +}]; +``` + +## UserSync example + +```javascript +pbjs.setConfig({ + userSync: { + iframeEnabled: true, + syncEnabled: true, + syncDelay: 1, + aliasSyncEnabled: true + } +}); +``` diff --git a/dev-docs/bidders/mytarget.md b/dev-docs/bidders/mytarget.md index a10bf209fe..854ab029d5 100644 --- a/dev-docs/bidders/mytarget.md +++ b/dev-docs/bidders/mytarget.md @@ -4,6 +4,7 @@ title: myTarget description: Prebid myTarget Bidder Adapter pbjs: true biddercode: mytarget +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- diff --git a/dev-docs/bidders/openweb.md b/dev-docs/bidders/openweb.md index fd07aeb675..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 @@ -33,8 +33,8 @@ The OpenWeb adapter requires setup and approval. Please reach out to
**WARNING:**
Misuse of this parameter can impact revenue | 2.00 -| `placementId` | optional | String | A unique placement identifier | "12345678" | `testMode` | optional | Boolean | This activates the test mode | false ## Example @@ -54,8 +54,8 @@ var adUnits = [{ bidder: 'openweb', params: { org: '1234567890abcdef12345678', // Required + placementId: '12345678', // Required floorPrice: 0.05, // Optional - placementId: '12345678', // Optional testMode: false // Optional } }] @@ -77,8 +77,8 @@ var adUnits = [{ bidder: 'openweb', params: { org: '1234567890abcdef12345678', // Required + placementId: '12345678', // Required floorPrice: 5.00, // Optional - placementId: '12345678', // Optional testMode: false // Optional } }] diff --git a/dev-docs/bidders/preciso.md b/dev-docs/bidders/preciso.md index 52523c39c1..867d7b1c34 100644 --- a/dev-docs/bidders/preciso.md +++ b/dev-docs/bidders/preciso.md @@ -1,63 +1,95 @@ --- layout: bidder title: Preciso -description: Prebid Preciso Bidder Adapter +description: Prebid Preciso Bid Adapter +gdpr_supported: true gvl_id: 874 -media_types: display, video, native +media_types: display gdpr_supported: true usp_supported: true pbjs: true -pbs: true +pbs: false biddercode: preciso prebid_member: true floors_supported: true safeframes_ok: true schain_supported: true -userIds: id5Id, identityLink, pubProvidedId -pbs_app_supported: true +userIds: sharedId +deals_supported: false coppa_supported: true -multiformat_supported: will-bid-on-any -ortb_blocking_supported: partial +multiformat_supported: will-not-bid +ortb_blocking_supported: true sidebarType: 1 --- +### Modules -### Bid Params +SharedID: We need you to include the [SharedID module](/dev-docs/modules/userid-submodules/sharedid.html) in order to bid effectively on your inventory. + +### Registration + +The preciso Bidding adapter requires setup before beginning. Please contact us at [tech@preciso.net] + +#### OpenRTB Parameters +The following table contains currently supported parameters we parse. {: .table .table-bordered .table-striped } -| Name | Scope | Description | Example | Type | -|---------------|----------|---------------------|---------------|----------| -| `publisherId` | required | Unique publisher ID | `'ABCDEF'` | `string` | -| `region` | required | Assigned region | `'prebid-eu'` | `string` | -| `bidfloor` | optional | Minimal CPM value | `0.01` | `float` | -| `channel` | optional | Inventory channel identifier, limited to 50 characters | `Partner 1 - News` | `string` | +| Name | Scope | Description | Example | Type | +|--------------------|----------|---------------------------------------------------------------|-------------------|----------------| +| `bcat` | optional | List of blocked advertiser categories (IAB) | `['IAB1-1']` | `string array` | +| `badv` | optional | Blocked Advertiser Domains | `['example.com']` | `string array` | +| `wlang` | optional | Allow List of languages for creatives using ISO-639-1-alpha-2 | `['fr', 'en']` | `string array` | -### ORTB Blocking -Preciso supports blocking advertisers in `badv` and categories in `bcat` parameters. -The blocked advertisers/categories list has no length limitation, but response timeout is more likely to occur as the number of entries grow. -Blocked advertisers list (`badv`) is an array of domains as strings. -Blocked categories list (`bcat`) is an array of IAB categories as strings. +Example configuration: -For example: -#### Globally defined ORTB Blocking: ```javascript + pbjs.setConfig({ - ortb2: { - badv: ["domain1.com", "domain2.com"], - bcat: ["IAB23-1", "IAB23-5", "IAB25-3", "IAB25-2"] - } -)}; -``` -#### ORTB Blocking specific only to preciso bidder: -```javascript -pbjs.setBidderConfig({ - bidders: ['preciso'], - config:{ ortb2: { - badv: ["domain1.com", "domain2.com"], - bcat: ["IAB23-1", "IAB23-5", "IAB25-3", "IAB25-2"] + bcat: ['IAB1-1'], + badv: ['example.com'], + wlang: ['fr', 'en'] } - } }); -``` \ No newline at end of file +``` + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|---------------|----------|---------------------|---------------|----------| +| `publisherId` | required | Numeric Publisher ID
(as provided by Preciso) | `'123AB123'` | `string` | +| `region` | optional,recommended | 3 letter country code | `'IND'` | `string` | +| `bidFloor` | optional,recommended | Minimum bid for this impression expressed in CPM (USD) | `0.01` | `float` | +| `pageType` | optional, recommended | Kind of content present in the page | `'homepage'` | `String` | +| `bcat` | optional | List of blocked advertiser categories (IAB) | `['IAB1-1']` | `string array` | +| `badv` | optional | Blocked Advertiser Domains| `'example.com'` | `string array`| + +Notes: + +- Preferred to provide the `bcat` and `badv` within the first party data (above). When both methods are provided, first party data values will be prioritized. + +### Example Ad Unit + +``````javascript + var adUnits = [{ + code: 'your-unit-container-id', + mediaTypes: { + banner: { + sizes: [[300, 250], [300,600]] + } + }, + bids: [{ + bidder: 'preciso', + params: { + publisherId: 'your-publisher-id', + region: 'IND', + pageType: 'news',// Optional + bidFloor: 0.25, // Optional - default is 0.0 + bcat: ['IAB1-1'], // Optional - default is [] + badv: ['example.com'] // Optional - default is [] + } + }] +}]; +`````` diff --git a/dev-docs/bidders/pubmatic.md b/dev-docs/bidders/pubmatic.md index 26af4168e8..6f1ace23e7 100644 --- a/dev-docs/bidders/pubmatic.md +++ b/dev-docs/bidders/pubmatic.md @@ -98,6 +98,7 @@ The PubMatic adapter supports video as of Prebid v1.16.0 | `video.battr` | optional | Blocked creative attributes, See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.3 for values | `[3, 9]` | | `video.linearity` | optional | Indicates if the impression is linear or nonlinear
Values:
`1`: Linear/In-Stream
`2`: Non-Linear/Overlay. | `1` | | `video.placement` | optional | Video placement type. See [OpenRTB 2.5 specification](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf), List 5.9 for Values | `1` | +| `video.plcmt` | optional | Video placement type. See [OpenRTB 2.6 specification - github](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#327---object-video-), For values [plcmt subtypes](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/develop/AdCOM%20v1.0%20FINAL.md#list_plcmtsubtypesvideo) | `1` | | `video.minbitrate` | optional | Minumim bit rate in Kbps. | 50 | | `video.maxbitrate` | optional | Maximum bit rate in Kbps. | 70 | @@ -120,8 +121,9 @@ var videoAdUnits = [ api: [ 1, 2 ], // optional protocols: [ 2, 3 ], // optional battr: [ 13, 14 ], // optional - linearity: 1, // optional + linearity: 1, // optional placement: 2, // optional + plcmt: 1, // optional minbitrate: 10, // optional maxbitrate: 10 // optional } diff --git a/dev-docs/bidders/qt.md b/dev-docs/bidders/qt.md new file mode 100644 index 0000000000..c0838c774f --- /dev/null +++ b/dev-docs/bidders/qt.md @@ -0,0 +1,35 @@ +--- +layout: bidder +title: QT +description: Prebid QT Bidder Adapter +biddercode: qt +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/ras.md b/dev-docs/bidders/ras.md index e8f9ce3837..3c39d03575 100644 --- a/dev-docs/bidders/ras.md +++ b/dev-docs/bidders/ras.md @@ -13,6 +13,7 @@ floors_supported: false fpd_supported: false sidebarType: 1 multiformat_supported: will-bid-on-one +pbjs_version_notes: removed in 9.0 --- diff --git a/dev-docs/bidders/relevatehealth.md b/dev-docs/bidders/relevatehealth.md new file mode 100644 index 0000000000..5b9e80ab16 --- /dev/null +++ b/dev-docs/bidders/relevatehealth.md @@ -0,0 +1,56 @@ +--- +layout: bidder +title: RelevateHealth +description: Prebid RelevateHealth Bidder Adaptor +pbjs: true +biddercode: relevatehealth +media_types: banner +tcfeu_supported: false +usp_supported: true +coppa_supported: true +gpp_sids: usstate_all +schain_supported: false +safeframes_ok: false +ortb_blocking_supported: false +dsa_supported: false +deals_supported: true +floors_supported: true +sidebarType: 1 +--- + +### Bid Params + +| Name | Scope | Description | Example | Type | +|---------------|-----------|-----------------------|----------------|----------| +| `placement_id` | mandatory | Placement Id | `110011` | `number` | +| `user_id` | mandatory | Unique id for HCP | `'1111111'` | `string` | +| `height` | optional | Height of the creative| `600` | `number` | +| `width` | optional | Width of the creative | `160` | `number` | +| `domain` | optional | Domain | `'domain.com'` | `string` | +| `bid_floor` | optional | Bid Floor Price | `0.5` | `decimal`| + +### AdUnit Format for Banner + +```javascript +var adUnits = [ + { + code: 'banner-ad', + mediaTypes: { + banner: { + sizes: [[160, 600]] + } + }, + bids: [{ + bidder: 'relevatehealth', + params: { + placement_id: 110011, + user_id: '', + height: 600, + width: 160, + domain: '', + bid_floor: 0.5 + } + }] + } + ]; +``` diff --git a/dev-docs/bidders/richaudience.md b/dev-docs/bidders/richaudience.md index f452b0d9a6..acb20c0fc5 100644 --- a/dev-docs/bidders/richaudience.md +++ b/dev-docs/bidders/richaudience.md @@ -7,12 +7,14 @@ userIds: criteo, id5Id, identityLink, liveIntentId, pubCommonId, unifiedId media_types: banner, video tcfeu_supported: true gvl_id: 108 +gpp_supported: true safeframes_ok: false prebid_member: true pbjs: true pbs: true schain_supported: true floors_supported: true +pbjs_version_notes: Please use version 9.1; version 9.0 does not support our adapter. sidebarType: 1 --- diff --git a/dev-docs/bidders/ringieraxelspringer.md b/dev-docs/bidders/ringieraxelspringer.md new file mode 100644 index 0000000000..abb1af0f09 --- /dev/null +++ b/dev-docs/bidders/ringieraxelspringer.md @@ -0,0 +1,44 @@ +--- +layout: bidder +title: RingierAxelSpringer +description: Prebid RingierAxelSpringer Bidder Adapter +biddercode: ringieraxelspringer +media_types: banner, native +pbjs: true +pbs: false +prebid_member: false +gvl_id: 1021 +tcfeu_supported: true +safeframes_ok: false +deals_supported: false +floors_supported: false +fpd_supported: false +sidebarType: 1 +multiformat_supported: will-bid-on-one +dsa_supported: true +privacy_sandbox: paapi +ortb_blocking_supported: false +schain_supported: false +dchain_supported: false +gpp_sids: None +coppa_supported: false +usp_supported: false +--- + +### Bid Params + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|------------------|----------|------------------------------------------------------------------------------------------------------|---------------------------------------------|----------| +| `network` | required | Specific identifier provided by RAS | `'4178463'` | `string` | +| `site` | required | Specific identifier name (case-insensitive) that is associated with this ad unit and provided by RAS | `'example_com'` | `string` | +| `area` | required | Ad unit category name; only case-insensitive alphanumeric with underscores and hyphens are allowed | `'sport'` | `string` | +| `slot` | required | Ad unit placement name (case-insensitive) provided by RAS | `'slot'` | `string` | +| `pageContext` | optional | Web page context data | `{}` | `object` | +| `pageContext.dr` | optional | Document referrer URL address | `'https://example.com/'` | `string` | +| `pageContext.du` | optional | Document URL address | `'https://example.com/sport/football/article.html?id=932016a5-02fc-4d5c-b643-fafc2f270f06'` | `string` | +| `pageContext.dv` | optional | Document virtual address as slash-separated path that may consist of any number of parts (case-insensitive alphanumeric with underscores and hyphens); first part should be the same as `site` value and second as `area` value; next parts may reflect website navigation | `'example_com/sport/football'` | `string` | +| `pageContext.keyWords` | optional | List of keywords associated with this ad unit; only case-insensitive alphanumeric with underscores and hyphens are allowed | `['euro', 'lewandowski']` | `string[]` | +| `pageContext.keyValues` | optional | Key-values associated with this ad unit (case-insensitive); following characters are not allowed in the values: `" ' = ! + # * ~ ; ^ ( ) < > ] [ & @` | `{}` | `object` | +| `pageContext.keyValues.ci` | optional | Content unique identifier | `'932016a5-02fc-4d5c-b643-fafc2f270f06'` | `object` | +| `pageContext.keyValues.adunit` | optional | Ad unit name | `'example_com/sport'` | `string` | diff --git a/dev-docs/bidders/setupad.md b/dev-docs/bidders/setupad.md index a6ce0dad27..f48d280776 100644 --- a/dev-docs/bidders/setupad.md +++ b/dev-docs/bidders/setupad.md @@ -27,7 +27,7 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |----------------+-------+-----------------------------------+-----------+---------| | `placement_id` | required | Placement ID, provided by setupad | `'12345'` | String | -| `account_id` | optional | Account ID, provided by setupad | `'12345'` | String | +| `account_id` | required | Account ID, provided by setupad | `'12345'` | String | ### Additional options diff --git a/dev-docs/bidders/sharethrough.md b/dev-docs/bidders/sharethrough.md index f3673a5291..fa18d284fe 100644 --- a/dev-docs/bidders/sharethrough.md +++ b/dev-docs/bidders/sharethrough.md @@ -21,7 +21,7 @@ ortb_blocking_supported: partial sidebarType: 1 --- -### Note +### Before You Begin The Sharethrough bidder adapter requires additional setup and approval from the Sharethrough Integrations team. Please reach out to your account manager for more information to start using it. @@ -34,8 +34,47 @@ The Sharethrough bidder adapter requires additional setup and approval from the | `bcat` | optional | (deprecated) Array of blocked IAB Categories | `['IAB1-2', 'IAB1-3']` | `string[]` | | `badv` | optional | (deprecated) Array of blocked Advertisers by their domains | `['ford.com', 'pepsi.com']` | `string[]` | -Note: Providing `bcat` and `badv` via Bid Params is deprecated, the First Party Data method should be preferred (see below). -When both methods are provided, first party data values will be used and bid param values will be ignored. +**Note**: Providing `bcat` and `badv` via Bid Params is deprecated, the First Party Data method should be preferred (see below). +When both methods are provided (i.e. when `badv` and `bcat` are specified both as bid params and through the first party ortb2 method), first party data values will be used and bid param values will be ignored. + +#### Configuration + +Sample banner setup: + +```js + +``` #### First Party Data @@ -86,3 +125,31 @@ pbjs.setConfig({ } }); ``` + +### Additional Notes + +#### Request and Response Attributes + +- TTL is 360 for display and native, 3600 for video (in milliseconds). +- Safeframes are supported. +- Advertiser domains are available in bid responses at `meta.advertiserDomains` +- Bids are returned in **net** - that is, the bids returned reflect the bid amount with revenue sharing already taken into account. No adjustment is necessary. +- Sharethrough is GDPR and COPPA compliant. + +#### Supported Media Types + +- Banner +- Native +- Video (instream and outstream) + +#### Default Ad Server Key Value + +- `sharethrough` + +### Prebid Module Support + +For publishers using PBJS version 5 and above, current module support includes: + +- Price Floors +- Supply Chain Object +- User ID diff --git a/dev-docs/bidders/smaato.md b/dev-docs/bidders/smaato.md index f298759132..56227993bf 100644 --- a/dev-docs/bidders/smaato.md +++ b/dev-docs/bidders/smaato.md @@ -8,6 +8,7 @@ gvl_id: 82 usp_supported: true coppa_supported: true gpp_supported: true +dsa_supported: true media_types: banner, video, native userIds: all pbjs: true @@ -59,7 +60,7 @@ The Smaato adapter will convert bidfloors to 'USD' currency as needed. | `adbreakId` | required | Your Smaato adbreak id. Required for adpod (long-form video) requests | `'41002234'` | `string` | | `app` | optional | Object containing mobile app parameters. See the [App Object](#smaato-app-object) for details.| `app : { ifa: '56700000-9cf0-22bd-b23e-46b96e40003a'}` | `object` | -##### Note +#### Note In case of AdPods, the Smaato adapter will only read the first `imp[].skadn` entry for each AdPod, such that there should only be one `skadn` occurrence per AdPod. @@ -274,7 +275,7 @@ Following example includes sample `imp` object with publisherId and adSlot which }, "ext":{ "smaato":{ - "publisherId":"100042525", + "publisherId":"1100042525", "adspaceId":"130563103" } } diff --git a/dev-docs/bidders/spotx.md b/dev-docs/bidders/spotx.md index 0c4fa8ce6b..9f9a9b91d9 100644 --- a/dev-docs/bidders/spotx.md +++ b/dev-docs/bidders/spotx.md @@ -13,6 +13,7 @@ safeframes_ok: false pbjs: true gvl_id: 165 floors_supported: true +pbjs_version_notes: removed in 9.0 sidebarType: 1 --- 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/taboola.md b/dev-docs/bidders/taboola.md index 8ae4fe2cd5..ed1ced43f7 100644 --- a/dev-docs/bidders/taboola.md +++ b/dev-docs/bidders/taboola.md @@ -10,6 +10,7 @@ usp_supported: true coppa_supported: true gpp_supported: true schain_supported: false +dchain_supported: true media_types: banner gvl_id: 42 prebid_member: true diff --git a/dev-docs/bidders/teads.md b/dev-docs/bidders/teads.md index 3099d222e9..c3f623978a 100644 --- a/dev-docs/bidders/teads.md +++ b/dev-docs/bidders/teads.md @@ -20,7 +20,7 @@ multiformat_supported: will-not-bid ortb_blocking_supported: true floors_supported: true coppa_supported: true -gpp_sids: false +gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp fpd_supported: false sidebarType: 1 --- diff --git a/dev-docs/bidders/tredio.md b/dev-docs/bidders/tredio.md new file mode 100644 index 0000000000..0b820465a0 --- /dev/null +++ b/dev-docs/bidders/tredio.md @@ -0,0 +1,39 @@ +--- +layout: bidder +title: Tredio +description: Tredio Bidder Adapter +biddercode: tredio +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: true +--- + +### 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/twistDigital.md b/dev-docs/bidders/twistDigital.md index e5e648fce2..672233164c 100644 --- a/dev-docs/bidders/twistDigital.md +++ b/dev-docs/bidders/twistDigital.md @@ -25,6 +25,4 @@ sidebarType: 1 | Name | Scope | Description | Example | Type | |------------|----------|------------------------------------------------------------------------------------------|------------------------------|----------| | `cId` | required | The connection ID from Twist Digital. | `'562524b21b1c1f08117fc7f9'` | `string` | -| `pId` | required | The publisher ID from Twist Digital. | `'59ac17c192832d0011283fe3'` | `string` | | `bidFloor` | optional | The minimum bid value desired. Twist Digital 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/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/bidders/vox.md b/dev-docs/bidders/vox.md index b531bb3079..2d3e9904b3 100644 --- a/dev-docs/bidders/vox.md +++ b/dev-docs/bidders/vox.md @@ -6,6 +6,7 @@ schain_supported: true floors_supported: true userIds: all pbjs: true +pbs: true media_types: banner, video biddercode: vox tcfeu_supported: true @@ -26,6 +27,7 @@ Please reach out to your partners account team before using this plugin to get p | `placementId` | required | The place id. | '5af45ad34d506ee7acad0c26' | `string` | | `placement` | required | Adunit placement, possible values: banner, video, inImage | 'banner' | `string` | | `imageUrl` | required for inImage | URL of the image on which the banner will be displayed | `'https://example.com/images/image.jpg'` | `string` | +| `displaySizes` | optional, only supported by inImage format | An array of strings. Each string should be in `x` format (currently, this parameter is supported only by PrebidServer vox adapter) | `["123x90", "720x100"]` | `string[]` | ### Sample Banner Ad Unit @@ -54,7 +56,7 @@ var adUnits = [{ code: 'video_ad_unit', mediaTypes: { video: { - context: 'outstream', // required, possible values: instream, outstream + context: 'outstream', // required, possible values: instream, outstream playerSize: [[640, 480]] // required } }, diff --git a/dev-docs/bidders/liftoff.md b/dev-docs/bidders/vungle.md similarity index 83% rename from dev-docs/bidders/liftoff.md rename to dev-docs/bidders/vungle.md index c55d6febc9..b66c0d254b 100644 --- a/dev-docs/bidders/liftoff.md +++ b/dev-docs/bidders/vungle.md @@ -1,8 +1,8 @@ --- layout: bidder -title: liftoff -description: Prebid liftoff Bidder Adapter -biddercode: liftoff +title: vungle +description: Prebid vungle Bidder Adapter +biddercode: vungle tcfeu_supported: false usp_supported: true gpp_supported: false @@ -25,7 +25,7 @@ sidebarType: 1 ### Note -The Liftoff Bidding adapter requires setup before beginning. Please contact us at . +The Vungle Bidding adapter requires setup before beginning. Please contact us at . ### Bid Params diff --git a/dev-docs/bidders/welect.md b/dev-docs/bidders/welect.md new file mode 100644 index 0000000000..40879ba494 --- /dev/null +++ b/dev-docs/bidders/welect.md @@ -0,0 +1,55 @@ +--- +layout: bidder +title: Welect +description: Prebid Welect Bidder Adaptor +pbjs: true +biddercode: welect +media_types: no-display, video +userIds: false +tcfeu_supported: true +gvl_id: 282 +gpp_sids: tcfeu +usp_supported: false +coppa_supported: false +schain_supported: false +dchain_supported: false +safeframes_ok: false +fpd_supported: false +floors_supported: false +ortb_blocking_supported: false +multiformat_supported: will-bid-on-one +privacy_sandbox: none +sidebarType: 1 + +--- + +### Note +The Welect bidder adapter requires setup and approval from the Welect team. Please reach out to [dev@welect.de](mailto:dev@welect.de) for more information. + +### Bid params + +{: .table .table-bordered .table-striped } +| Name | Description | Example | Type | +|---|---|---|---| +| `placementId` | an identifier for your placement, provided by Welect | `'exampleID'` | `string` | +| `domain` | The domain of your placement | `'www.example.com'` | `string` | + +### Example Ad Unit Setup + +```javascript +var adUnits = [ + { + bidder: 'welect', + params: { + placementId: 'exampleId', + domain: 'www.welect.de' + }, + sizes: [[640, 360]], + mediaTypes: { + video: { + context: 'instream' + } + }, + }; +]; +``` diff --git a/dev-docs/bidders/yahooAdvertising.md b/dev-docs/bidders/yahooAdvertising.md index 219a7a4347..b5543dd165 100644 --- a/dev-docs/bidders/yahooAdvertising.md +++ b/dev-docs/bidders/yahooAdvertising.md @@ -5,7 +5,7 @@ description: Yahoo Advertising Bid Adapter pbs: true pbjs: true media_types: banner, video -filename: yahoosspBidAdapter +filename: yahooAdsBidAdapter biddercode: yahooAds prebid_member: true tcfeu_supported: true @@ -63,7 +63,7 @@ For new partners/publishers joining Yahoo Advertising and legacy "oneVideo" part ### Prebid.js Adapter Supported Features -For further setup details & examples please see +For further setup details & examples please see * Media Types: Banner & Video * Outstream renderer @@ -76,4 +76,3 @@ For further setup details & examples please see 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/integrate-with-the-prebid-analytics-api.md b/dev-docs/integrate-with-the-prebid-analytics-api.md index ba1a9dfb42..b073000889 100644 --- a/dev-docs/integrate-with-the-prebid-analytics-api.md +++ b/dev-docs/integrate-with-the-prebid-analytics-api.md @@ -86,7 +86,7 @@ Analytics adapter for Example.com. Contact prebid@example.com for information. adapter needs to specify an enableAnalytics() function, but it should also call the base class function to set up the events. -5. Doing analytics may require user permissions under [GDPR](/dev-docs/modules/consentManagement.html), which means your adapter will need to be linked to your [IAB Global Vendor List](https://iabeurope.eu/vendor-list-tcf/) ID. If no GVL ID is found, and Purpose 7 (Measurement) is enforced, your analytics adapter will be blocked unless it is specifically listed under vendorExceptions. Your GVL ID can be added to the `registerAnalyticsAdapter()` call. +5. Doing analytics may require user permissions under [GDPR](/dev-docs/modules/consentManagementTcf.html), which means your adapter will need to be linked to your [IAB Global Vendor List](https://iabeurope.eu/vendor-list-tcf/) ID. If no GVL ID is found, and Purpose 7 (Measurement) is enforced, your analytics adapter will be blocked unless it is specifically listed under vendorExceptions. Your GVL ID can be added to the `registerAnalyticsAdapter()` call. #### Basic prototype analytics adapter @@ -150,6 +150,7 @@ There are two error events analytics modules may wish to listen for: auctionDebu * listen only to the events required * batch up calls to the backend for post-auction logging rather than calling immediately after each event. +* consider using the keepalive option on the ajax request to keep the priority low and the request queued after the pageview dies ### Step 3: Add unit tests diff --git a/dev-docs/modules/51DegreesRtdProvider.md b/dev-docs/modules/51DegreesRtdProvider.md new file mode 100644 index 0000000000..dda5620d34 --- /dev/null +++ b/dev-docs/modules/51DegreesRtdProvider.md @@ -0,0 +1,164 @@ +--- +layout: page_v2 +title: 51Degrees RTD Provider Module +display_name: 51Degrees RTD Module +description: 51Degrees Real Time Data Module +page_type: module +module_type: rtd +module_code : 51DegreesRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +{: .alert.alert-warning :} +This module loads a dynamically generated JavaScript from cloud.51degrees.com (or your self-hosted domain) based on the evidence (HTTP headers and API results) available. The external resource is used to handle constant platform and browser evolution without requiring frequent changes to the Prebid source code. + +# 51Degrees RTD Submodule + +{:.no_toc} + +* TOC +{:toc} + +## Description + +51Degrees module enriches an OpenRTB request with [51Degrees Device Data](https://51degrees.com/documentation/index.html). + +51Degrees module sets the following fields of the device object: `make`, `model`, `os`, `osv`, `h`, `w`, `ppi`, `pxratio` - interested bidder adapters may use these fields as needed. In addition the module sets `device.ext.fiftyonedegrees_deviceId` to a permanent device ID which can be rapidly looked up in on premise data exposing over 250 properties including the device age, chip set, codec support, and price, operating system and app/browser versions, age, and embedded features. + +The module supports on premise and cloud device detection services with free options for both. + +A free resource key for use with 51Degrees cloud service can be obtained from [51Degrees cloud configuration](https://configure.51degrees.com/tWrhNfY6). This is the simplest approach to trial the module. + +An interface compatible self hosted service can be used with .NET, Java, Node, PHP, and Python. See [51Degrees examples](https://51degrees.com/documentation/_examples__device_detection__getting_started__web__on_premise.html). + +Free cloud and on premise solutions can be expanded to support unlimited requests, additional properties, and automatic daily on premise data updates via a [subscription](https://51degrees.com/pricing). + +## Usage + +### Integration + +Compile the 51Degrees RTD Module with other modules and adapters into your Prebid.js build: + +```bash +gulp build --modules="rtdModule,51DegreesRtdProvider,appnexusBidAdapter,..." +``` + +> Note that the 51Degrees RTD module is dependent on the global real-time data module, `rtdModule`. + +### Prerequisites + +#### Resource Key + +In order to use the module please first obtain a Resource Key using the [Configurator tool](https://configure.51degrees.com/tWrhNfY6) - choose the following properties: + +* DeviceId +* DeviceType +* HardwareVendor +* HardwareName +* HardwareModel +* PlatformName +* PlatformVersion +* ScreenPixelsHeight +* ScreenPixelsWidth +* ScreenInchesHeight +* ScreenInchesWidth +* PixelRatio (optional) + +PixelRatio is desirable, but it's a paid property requiring a paid license. Free API service is limited. Please check [51Degrees pricing](https://51degrees.com/pricing) to choose a plan that suits your needs. + +#### User Agent Client Hint (UA-CH) Permissions + +Some UA-CH headers are not available to third parties. To allow 51Degrees cloud service to access these headers for more accurate detection and lower latency, it is highly recommended to set `Permissions-Policy` in one of two ways: + +In the HTML of the publisher's web page where Prebid.js wrapper is integrated: + +```html + +``` + +Or in the Response Headers of the publisher's web server: + +```http +Permissions-Policy: ch-ua-arch=(self "https://cloud.51degrees.com"), ch-ua-full-version=(self "https://cloud.51degrees.com"), ch-ua-full-version-list=(self "https://cloud.51degrees.com"), ch-ua-model=(self "https://cloud.51degrees.com"), ch-ua-platform=(self "https://cloud.51degrees.com"), ch-ua-platform-version=(self "https://cloud.51degrees.com") + +Accept-CH: sec-ch-ua-arch, sec-ch-ua-full-version, sec-ch-ua-full-version-list, sec-ch-ua-model, sec-ch-ua-platform, sec-ch-ua-platform-version +``` + +See the [51Degrees documentation](https://51degrees.com/documentation/_device_detection__features__u_a_c_h__overview.html) for more information concerning UA-CH and permissions. + +##### Why not use GetHighEntropyValues API instead? + +Thanks for asking. + +The script this module injects has a fall back to the GetHighEntropyValues API, but does not rely on it as a first (or only) choice route - please see the illustrative cases below. Albeit it seems easier, GHEV API is not supported by all browsers (so the decision to call it should be conditional) and also even in Chrome this API will likely be a subject to the Privacy Budget in the future. + +In summary we recommend using `Delegate-CH` http-equiv as the preferred method of obtaining the necessary evidence because it is the fastest and future proof method. + +##### Illustrative Cases + +* if the device is iPhone/iPad then there is no point checking for or calling GetHighEntropyValues at the moment because iOS does not support this API. However this might change in the future. Platforms like iOS require additional techniques to identify the model which are not covered via a single API call, and change from version to version of the operating system and browser rendering engine. **When used with iOS 51Degrees resolves the [iPhone/iPad model groups](https://51degrees.com/documentation/4.4/_device_detection__features__apple_device_table.html) using these techniques.** That is one of the benefits the module brings to the Prebid community as most solutions do not resolve iPhone/iPad model groups. More on Apple Device Detection [here](https://51degrees.com/documentation/4.4/_device_detection__features__apple_detection.html). + +* if the browser is Firefox on Android or desktop then there is similarly no point requesting GHEV as the API is not supported. + +* if the browser is Chrome then the `Delegate-CH` if enabled by the publisher would enable the browser to provide the necessary evidence. However if this is not implemented - then the dynamic script would fall back to GHEV which is slower. + +### Configuration + +This module is configured as part of the `realTimeData.dataProviders` + +```javascript +pbjs.setConfig({ + debug: true, // we recommend turning this on for testing as it adds more logging + realTimeData: { + auctionDelay: 1000, // should be set lower in production use + dataProviders: [ + { + name: '51Degrees', + waitForIt: true, // should be true, otherwise the auctionDelay will be ignored + params: { + // Get your resource key from https://configure.51degrees.com/tWrhNfY6 to connect to cloud.51degrees.com + resourceKey: '', + // alternatively, you can use the on-premise version of the 51Degrees service and connect to your chosen end point + // onPremiseJSUrl: 'https://localhost/51Degrees.core.js' + }, + }, + ], + }, +}); +``` + +### Parameters + +> Note that `resourceKey` and `onPremiseJSUrl` are mutually exclusive parameters. Use strictly one of them: either a `resourceKey` for cloud integration and `onPremiseJSUrl` for the on-premise self-hosted integration. + +{: .table .table-bordered .table-striped } +| Name | Type | Description | Default | +|:----------------------|:--------|:-------------------------------------------------------------------------------------------------|:-------------------| +| name | String | Real time data module name | Always '51Degrees' | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (mandatory) | `false` | +| params | Object | | | +| params.resourceKey | String | Your 51Degrees Cloud Resource Key | | +| params.onPremiseJSUrl | String | Direct URL to your self-hosted on-premise JS file (e.g. `https://your.domain/51Degrees.core.js`) | | + +## Example + +> Note: you need to have a valid resource key to run the example.\ +> It should be set in the configuration instead of ``.\ +> It is located in the `integrationExamples/gpt/51DegreesRtdProvider_example.html` file. + +If you want to see an example of how the 51Degrees RTD module works,\ +run the following command: + +`gulp serve --modules=rtdModule,51DegreesRtdProvider,appnexusBidAdapter` + +and then open the following URL in your browser: + +`http://localhost:9999/integrationExamples/gpt/51DegreesRtdProvider_example.html` + +Open the browser console to see the logs. + +## Customer Notices + +When using the 51Degrees cloud service publishers need to reference the 51Degrees [client services privacy policy](https://51degrees.com/terms/client-services-privacy-policy) in their customer notices. diff --git a/dev-docs/modules/adagioRtdProvider.md b/dev-docs/modules/adagioRtdProvider.md new file mode 100644 index 0000000000..4f10a192a9 --- /dev/null +++ b/dev-docs/modules/adagioRtdProvider.md @@ -0,0 +1,67 @@ +--- +layout: page_v2 +title: Adagio Rtd Module +display_name: Adagio Rtd Module +description: The Adagio Rtd module computes and collects data required to leverage Adagio viewability and attention prediction engine. +page_type: module +module_type: rtd +module_code : adagioRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Adagio Real Time Data Module + +## Overview + +This module can be used in combination with [Adagio Bid Adapter](/dev-docs/bidders/adagioBidAdapter.md) (SSP) and/or with Adagio prebid server endpoint. +It computes and collects data required to leverage Adagio viewability and attention prediction engine. + +Please contact [contact@adagio.io](contact@adagio.io) for more information. + +{% include dev-docs/loads-external-javascript.md %} + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` object. + +```javascript +pbjs.setConfig({ + realTimeData: { + dataProviders:[{ + name: 'adagio', + params: { + organizationId: '1000', // Required. Provided by Adagio + site: "my-site" // Required. Provided by Adagio + placementSource: 'ortb' // Optional. Possible values: 'ortb' | 'code' | 'gpid' + } + }] + } +}); +``` + +Syntax details: + +{: .table .table-bordered .table-striped } +| Name | Scope | Description | Example | Type | +|--------------------------|----------|-----------------------------------------------|-------------|----------| +| `name` | required | Real time data module name: Always `'adagio'` | `'adagio'` | `string` | +| `params` | required | | | `Object` | +| `params.organizationId` | required | Account id provided by Adagio. | `'1000'` | `string` | +| `params.site` | required | Account site name provided by Adagio. | `'my-site'` | `string` | +| `params.placementSource` | optional | Programmatically set the `ortb2Imp.ext.data.placement` signal based on location. Possible values: `ortb` (default), `code`, `gpid`. | `'ortb'` | `string` | + +## Installation + +To install the module, follow these instructions: + +* Contact Adagio to get an account + +* Build the prebid.js file + + * Option 1: Use Prebid [Download](/download.html) page to build the prebid package. Ensure that you do check *Adagio* in Bidder Adapters and *Adagio Rtd Module* in Vendor-Specific Modules + + * Option 2: From the command line, run `gulp build --modules=adagioBidAdapter,rtdModule,adagioRtdProvider,...` + +* Enable Adagio Real Time Module using `pbjs.setConfig`. Example is provided in Configuration section. diff --git a/dev-docs/modules/anPspParamsConverter.md b/dev-docs/modules/anPspParamsConverter.md new file mode 100644 index 0000000000..876f29be4e --- /dev/null +++ b/dev-docs/modules/anPspParamsConverter.md @@ -0,0 +1,26 @@ +--- +layout: page_v2 +page_type: module +title: Module - anPspParamsConverter +description: Formats bid params for AppNexus PSP requests made through Prebid.js. +module_code : anPspParamsConverter +display_name : anPspParamsConverter +enable_download : true +sidebarType : 1 +--- + +# anPspParamsConverter Module + +{:.no_toc} + +This module is a temporary measure for publishers running Prebid.js 9.0+ and using the AppNexus PSP endpoint through their Prebid.js setup. Please ensure to include this module in your builds of Prebid.js 9.0+, otherwise requests to PSP may not complete successfully. + +## Module's Purpose + +This module replicates certain functionality that was previously stored in the appnexusBidAdapter.js file within a function named transformBidParams. + +This transformBidParams was a standard function in all adapters, which helped to change/modify the params and their values to a format that matched the bidder's request structure on the server-side endpoint. In Prebid.js 9.0, this standard function was removed in all adapter files, so that the whole client-side file (eg appnexusBidAdapter.js) wouldn't have to be included in a prebid.js build file that was meant for server-side bidders. + +## How to use the module as a publisher + +There is no setConfig setup needed for this module. Simply include this module in your Prebid.js build file if you plan to make requests to the AppNexus PSP endpoint through Prebid.js. diff --git a/dev-docs/modules/azerionedgeRtdProvider.md b/dev-docs/modules/azerionedgeRtdProvider.md index 58778d0666..d58254d1c8 100644 --- a/dev-docs/modules/azerionedgeRtdProvider.md +++ b/dev-docs/modules/azerionedgeRtdProvider.md @@ -20,7 +20,7 @@ Client-side contextual cookieless audiences. Azerion Edge RTD module helps publishers to capture users' interest audiences on their site, and attach these into the bid request. -Please contact [edge@azerion.com](edge@azerion.com) for more information. +Please contact for more information. Maintainer: [azerion.com](https://www.azerion.com/) @@ -63,7 +63,7 @@ pbjs.setConfig( | :--- | :------- | :------------------ | :--------------- | | name | `String` | RTD sub module name | Always "azerionedge" | | waitForIt | `Boolean` | Required to ensure that the auction is delayed for the module to respond. | Optional. Defaults to false but recommended to true. | -| params.key | `String` | Publisher partner specific key | Mandatory. The key is required for the module to work. If you haven't received one, please reach [support@improvedigital.com](support@improvedigital.com) | +| params.key | `String` | Publisher partner specific key | Mandatory. The key is required for the module to work. If you haven't received one, please reach | | params.bidders | `Array` | Bidders with which to share segment information | Optional. Defaults to "improvedigital". | | params.process | `Object` | Configuration for the Azerion Edge script. | Optional. Defaults to `{}`. | @@ -74,7 +74,7 @@ received from the user, this module does not require a TCF vendor configuration. provided to the module when the user gives the relevant permissions on the publisher website. As Prebid.js utilizes TCF vendor consent for the RTD module to load, the module needs to be labeled -within the Vendor Exceptions. If the Prebid GDPR enforcement is enabled, the module should be configured +within the Vendor Exceptions. If the Prebid TCF Controls are enabled, the module should be configured as exception, as shown below: ```js diff --git a/dev-docs/modules/consentManagementGpp.md b/dev-docs/modules/consentManagementGpp.md index 1e8ad5cb19..9a99ac96ce 100644 --- a/dev-docs/modules/consentManagementGpp.md +++ b/dev-docs/modules/consentManagementGpp.md @@ -129,7 +129,7 @@ You can also use the [Prebid.js Download](/download.html) page. {: .alert.alert-info :} -If you are submitting changes to an adapter to support GPP, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gpp_supported: true` variable to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GPP.** +If you are submitting changes to an adapter to support GPP, please also submit a PR to the [docs repo](https://github.com/prebid/prebid.github.io) to add the `gpp_sids` meta data with a comma separated list of section names (`tcfeu`, `tcfca`, `usnat`, `usstate_all`, `usp`) to your respective page in the [bidders directory](https://github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders). **This will ensure that your adapter's name will automatically appear on the list of adapters supporting GPP.** ### Bidder Adapter GPP Integration @@ -172,7 +172,7 @@ Depending on your needs, you could include the consent information in a query of ## Adapters Supporting GPP -Bidders on this list have self-declared their GPP support in their [github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders] md file by adding "gpp_supported: true". +Bidders on this list have self-declared their GPP support in their [github.com/prebid/prebid.github.io/tree/master/dev-docs/bidders] md file by adding "gpp_sids: tcfeu, tcfca, usnat, usstate_all, usp". @@ -200,7 +200,7 @@ var idx_gdpr=0; - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) -- [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagement.html) +- [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagementTcf.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Activity Controls -- GPP control module - usnat](/dev-docs/modules/gppControl_usnat.html) diff --git a/dev-docs/modules/consentManagement.md b/dev-docs/modules/consentManagementTcf.md similarity index 89% rename from dev-docs/modules/consentManagement.md rename to dev-docs/modules/consentManagementTcf.md index 518ce48a02..de965ca030 100644 --- a/dev-docs/modules/consentManagement.md +++ b/dev-docs/modules/consentManagementTcf.md @@ -1,16 +1,16 @@ --- layout: page_v2 page_type: module -title: Consent Management - GDPR -description: If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the GDPR Enforcement module. -module_code : consentManagement -display_name : Consent Management - GDPR +title: Consent Management - TCF +description: If you have users in Europe, this module works with your Consent Management Platform to pass consent info to bidders and help align with EU regulations. See also the TCF Control module. +display_name : Consent Management - TCF +module_code : consentManagementTcf enable_download : true recommended: true sidebarType : 1 --- -# GDPR Consent Management Module +# TCF Consent Management Module {: .no_toc } - TOC @@ -28,12 +28,12 @@ This module works with supported [Consent Management Platforms](https://www.cmsw Prebid functionality created to address regulatory requirements does not replace each party's responsibility to determine its own legal obligations and comply with all applicable laws. **We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach.** -This base EU GDPR consent management module performs these actions: +This base EU TCF consent management module performs these actions: 1. Fetch the user's GDPR & Google additional consent data from the CMP. 2. Incorporate this data into the auction objects for adapters to collect. -The optional [GDPR enforcement module](/dev-docs/modules/gdprEnforcement.html) adds on these actions: +The optional [TCF control module](/dev-docs/modules/tcfControl.html) adds on these actions: 1. Allows the page to define which activities should be enforced at the Prebid.js level. 2. Actively enforces those activities based on user consent data (in the TCF string, not the AC string). @@ -71,16 +71,17 @@ but we recommend migrating to the new config structure as soon as possible. | gdpr.actionTimeout | `integer` | Length of time (in milliseconds) to allow the user to take action to consent if they have not already done so. The actionTimer first waits for the CMP to load, then the actionTimeout begins for the specified duration. Default is `undefined`. | `10000` | | gdpr.defaultGdprScope | `boolean` | Defines what the `gdprApplies` flag should be when the CMP doesn't respond in time or the static data doesn't supply. Defaults to `false`. | `true` | | gdpr.consentData | `Object` | An object representing the GDPR consent data being passed directly; only used when cmpApi is 'static'. Default is `undefined`. | | -| gdpr.consentData.getTCData.tcString | `string` | Base64url-encoded TCF v2.x string with segments. | | -| gdpr.consentData.getTCData.addtlConsent | `string` | Additional consent string if available from the cmp TCData object | | -| gdpr.consentData.getTCData.gdprApplies | `boolean` | Defines whether or not this pageview is in GDPR scope. | | -| gdpr.consentData.getTCData.purpose.consents | `Object` | An object representing the user's consent status for specific purpose IDs. | | -| gdpr.consentData.getTCData.purpose.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific purpose IDs. | | -| gdpr.consentData.getTCData.vendor.consents | `Object` | An object representing the user's consent status for specific vendor IDs. | | -| gdpr.consentData.getTCData.vendor.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific vendors IDs. | | +| gpdr.dsaPlatform | `boolean` | If true, indicates that the publisher is to be considered an "Online Platform" for the purposes of the [Digital Services Act](https://digital-strategy.ec.europa.eu/en/policies/digital-services-act-package) | | +| gdpr.consentData.tcString | `string` | Base64url-encoded TCF v2.x string with segments. | | +| gdpr.consentData.addtlConsent | `string` | Additional consent string if available from the cmp TCData object | | +| gdpr.consentData.gdprApplies | `boolean` | Defines whether or not this pageview is in GDPR scope. | | +| gdpr.consentData.purpose.consents | `Object` | An object representing the user's consent status for specific purpose IDs. | | +| gdpr.consentData.purpose.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific purpose IDs. | | +| gdpr.consentData.vendor.consents | `Object` | An object representing the user's consent status for specific vendor IDs. | | +| gdpr.consentData.vendor.legitimateInterests | `Object` | An object representing the user's legitimate interest status for specific vendors IDs. | | {: .alert.alert-info :} -NOTE: The `purpose` and `vendor` objects are required if you are using the `gdprEnforcement` module. If the data is not included, your bid adapters, analytics adapters, and/or userId systems will likely be excluded from the auction as Prebid will assume the user has not given consent for these entities. +NOTE: The `purpose` and `vendor` objects are required if you are using the `tcfControl` module. If the data is not included, your bid adapters, analytics adapters, and/or userId systems will likely be excluded from the auction as Prebid will assume the user has not given consent for these entities. A related parameter is `deviceAccess`, which is at the global level of Prebid.js configuration because it can be used GDPR, CCPA, or custom privacy implementations: @@ -210,7 +211,7 @@ Here is a sample of how the data is structured in the `bidderRequest` object: **_consentString_** -This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error (or timeout) during the CMP interaction and the publisher turned off GDPR enforcement. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the _consent_required_ code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. +This field contains the user's choices on consent, represented as an encoded string value. In certain scenarios, this field might come to you with an `undefined` value; normally this happens when there was an error (or timeout) during the CMP interaction and the publisher turned off TCF controls. If you don't want to pass `undefined` to your system, you can check for this value and replace it with a valid consent string. See the _consent_required_ code in the example below (under "gdprApplies") for a possible approach to checking and replacing values. **_addtlConsent_** @@ -369,7 +370,7 @@ This should be false if there was some error in the consent data; otherwise set ## Further Reading -- [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) +- [TCF Control Module](/dev-docs/modules/tcfControl.html) - [IAB TCF Implementation Guide](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md) - [IAB Transparancy and Consent Framework Policies](https://iabeurope.eu/iab-europe-transparency-consent-framework-policies/) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) diff --git a/dev-docs/modules/consentManagementUsp.md b/dev-docs/modules/consentManagementUsp.md index 90aed2ad66..ca804d5646 100644 --- a/dev-docs/modules/consentManagementUsp.md +++ b/dev-docs/modules/consentManagementUsp.md @@ -6,7 +6,7 @@ description: If you have users in California, this module works with your Consen module_code : consentManagementUsp display_name : Consent Management - US Privacy enable_download : true -recommended: true +recommended: false sidebarType : 1 --- @@ -22,10 +22,10 @@ sidebarType : 1 This consent management module is designed to support the California Consumer Privacy Act ([CCPA](https://www.iab.com/guidelines/ccpa-framework/)). The IAB has generalized these guidelines to cover future regulations, referring to the feature as "US Privacy." -This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect. +This module works with an IAB-compatible US Privacy API (USP-API) to fetch an encoded string representing the user's notice and opt-out choices and make it available for adapters to consume and process. In Prebid 7+; the module defaults to working with an IAB-compatible US Privacy API; in prior versions, the module had to be configured to be in effect. This module is no longer recommended, as the signal is no longer supported by a contractual framework as of January 31, 2024. {: .alert.alert-info :} -See also the [Prebid Consent Management - GDPR Module](/dev-docs/modules/consentManagement.html) for supporting the EU General Data Protection Regulation (GDPR) +See also the [Prebid Consent Management - TCF Module](/dev-docs/modules/consentManagementTcf.html) for supporting the IABTL Transparency and Consent Framework. Here's a summary of the interaction process: diff --git a/dev-docs/modules/contxtfulRtdProvider.md b/dev-docs/modules/contxtfulRtdProvider.md index 07fc6418a0..b5523da656 100644 --- a/dev-docs/modules/contxtfulRtdProvider.md +++ b/dev-docs/modules/contxtfulRtdProvider.md @@ -24,14 +24,14 @@ The Contxtful RTD module enhances ad units by adding a Receptivity score to the To incorporate this module into your `prebid.js`, compile the module using the following command: ```sh -gulp build --modules=contxtfulRtdProvider, +gulp build --modules=rtdModule,contxtfulRtdProvider, ``` -### Configuration +## Configuration Configure the `contxtfulRtdProvider` by passing the required settings through the `setConfig` function in `prebid.js`. -```js +```javascript import pbjs from 'prebid.js'; pbjs.setConfig({ @@ -42,8 +42,11 @@ pbjs.setConfig({ "name": "contxtful", "waitForIt": true, "params": { - "version": "", - "customer": "" + "version": "Contact contact@contxtful.com for the API version", + "customer": "Contact contact@contxtful.com for the customer ID", + "hostname": "api.receptivity.io", // Optional, default: "api.receptivity.io" + "bidders": ["bidderCode1", "bidderCode", "..."], // list of bidders + "adServerTargeting": true, // Optional, default: true } } ] @@ -51,35 +54,46 @@ pbjs.setConfig({ }); ``` -#### Parameters +## Parameters {: .table .table-bordered .table-striped } -| Name | Type | Scope | Description | -|------------|----------|----------|-------------------------------------------| -| `version` | `string` | Required | Specifies the API version of Contxtful. | -| `customer` | `string` | Required | Your unique customer identifier. | +| Name | Type | Scope | Description | +|---------------------|----------|----------|--------------------------------------------| +| `version` | `String` | Required | Specifies the version of the Contxtful Receptivity API. | +| `customer` | `String` | Required | Your unique customer identifier. | +| `hostname` | `String` | Optional | Target URL for CONTXTFUL external JavaScript file. Default is "api.receptivity.io". Changing default behaviour is not recommended. Please reach out to [contact@contxtful.com](mailto:contact@contxtful.com) if you experience issues. | +| `adServerTargeting` | `Boolean`| Optional | Enables the `getTargetingData` to inject targeting value in ad units. Setting to true enables the feature, false disables the feature. Default is true | +| `bidders` | `Array` | Optional | Setting this array enables Receptivity in the `ortb2` object through `getBidRequestData` for all the listed `bidders`. Default is `[]` (an empty array). RECOMMENDED : Add all the bidders active like this `["bidderCode1", "bidderCode", "..."]` | -## Usage +## Usage: Injection in Ad Servers The `contxtfulRtdProvider` module loads an external JavaScript file and authenticates with Contxtful APIs. The `getTargetingData` function then adds a `ReceptivityState` to each ad slot, which can have one of two values: `Receptive` or `NonReceptive`. ```json { "adUnitCode1": { "ReceptivityState": "Receptive" }, - "adUnitCode2": { "ReceptivityState": "NonReceptive" } + "adUnitCode2": { "ReceptivityState": "Receptive" } } ``` This module also integrates seamlessly with Google Ad Manager, ensuring that the `ReceptivityState` is available as early as possible in the ad serving process. -### Example +## Usage: Injection in ortb2 for bidders + +Setting the `bidders` field in the configuration parameters enables Receptivity in the `ortb2` object through `getBidRequestData` for all the listed bidders. +On a Bid Request Event, all bidders in the configuration will inherit the Receptivity data through `ortb2` +Default is `[]` (an empty array) + +RECOMMENDED : Add all the bidders active like this `["bidderCode1", "bidderCode", "..."]` + +## Example To view an integration example: 1. In your CLI run: ```bash - gulp serve --modules=appnexusBidAdapter,contxtfulRtdProvider + gulp serve --modules=rtdModule,appnexusBidAdapter,rubiconBidAdapter,sharethroughBidAdapter,contxtfulRtdProvider ``` 2. In your browser, navigate to: @@ -90,4 +104,12 @@ To view an integration example: ## Support -To utilize this module, you need to register for an account with [Contxtful](https://contxtful.com). For inquiries, please contact [prebid@contxtful.com](mailto:prebid@contxtful.com). +To utilize this module, you need to register for an account with [Contxtful](https://contxtful.com). For inquiries, please contact [contact@contxtful.com](mailto:contact@contxtful.com). + +## Links + +- [Basic Prebid.js Example](https://docs.prebid.org/dev-docs/examples/basic-example.html) +- [How Bid Adapters Should Read First Party Data](https://docs.prebid.org/features/firstPartyData.html#how-bid-adapters-should-read-first-party-data) +- [getBidRequestData](https://docs.prebid.org/dev-docs/add-rtd-submodule.html#getbidrequestdata) +- [getTargetingData](https://docs.prebid.org/dev-docs/add-rtd-submodule.html#gettargetingdata) +- [Contxtful Documentation](https://documentation.contxtful.com/) diff --git a/dev-docs/modules/dfpAdpod.md b/dev-docs/modules/dfpAdpod.md new file mode 100644 index 0000000000..6904af0f8d --- /dev/null +++ b/dev-docs/modules/dfpAdpod.md @@ -0,0 +1,21 @@ +--- +layout: page_v2 +page_type: module +title: Module - Google Ad Manager Adpod Support +description: Required for serving adpod video through Google Ad Manager. +module_code : dfpAdpod +display_name : Google Ad Manager Adpod Support +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# Google Ad Manager Adpod Support + +{:.no_toc} + +This module exposes the [`pbjs.adServers.dfp.buildAdpodVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.html) method, required to use [adpod](/dev-docs/modules/adpod.md) with Google Ad Manager. + +## Further Reading + +- [Show long form video ads with GAM](/dev-docs/show-long-form-video-with-gam.html) diff --git a/dev-docs/modules/enrichmentFpdModule.md b/dev-docs/modules/enrichmentFpdModule.md deleted file mode 100644 index d80b64570e..0000000000 --- a/dev-docs/modules/enrichmentFpdModule.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -layout: page_v2 -page_type: module -title: Module - First Party Data Enrichment -description: Injects additional data into the auction stream, including: domain, keywords, and page url. -module_code : enrichmentFpdModule -display_name : First Party Data Enrichment -enable_download : true -recommended: true -sidebarType : 1 ---- - -# First Party Data Enrichment Module - -{:.no_toc} - -{: .alert.alert-warning :} -Since version 7.29, this module does nothing; its functionality is instead included by default in all Prebid distributions. - -This module adds a number of First Party Data (FPD) fields from the environment. - -Add it to the Prebid.js build with this command: - -```bash -gulp build --modules=enrichmentFpdModule -``` - -If included in the build, it will automatically perform the enrichments unless controlled with setConfig: - -```javascript -pbjs.setConfig({ - firstPartyData: { - skipEnrichments: true // defaults to false - } -}); -``` - -## How it works - -At the beginning of each auction, this module merges a number of values into the `ortb2` [requestBids parameter](/dev-docs/publisher-api-reference/requestBids.html). Specific details below. - -## Enrichments - -{: .table .table-bordered .table-striped } -| Page Source | ortb2 field | Notes | -|---+---+---| -| page URL | site.page | Uses pbjs getRefererInfo().page | -| referer URL | site.ref | Uses pbjs getRefererInfo().ref | -| host domain | site.domain | Pulled from the getRefererInfo().page the host domain is used with the www component dropped. | -| aggregated domain | site.publisher.domain | The highest level domain in which cookies can be set. | -| viewport width | device.w | Hunts for window.innerWidth, window.document.documentElement.clientWidth, window.document.body.clientWidth | -| viewport height | device.w | Hunts for window.innerHeight, window.document.documentElement.clientHeight, window.document.body.clientHeight | -| UA client hints | device.sua | Collects user agent client hints. See [note](#ua-hints) below. | -| meta keywords | site.keywords | Looks for a meta tag. e.g. | -| currency | cur | Collects the currency defined by the [Currency module](/dev-docs/modules/currency.html). | - - - -### User agent client hints - -The module populates `device.sua` with UA client hints retrieved from `navigator.userAgentData`. By default, it won't ask for any high entropy hint. You can specify the list of hints using the `uaHints` option with [any available high entropy hint](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData#returning_high_entropy_values): - -```javascript -pbjs.setConfig({ - firstPartyData: { - uaHints: [ - 'platform', - // ... - ] - } -}) -``` - -If `uaHints` is set to an empty array or is not set, the module will not attempt to retrieve any high entropy hint and use only the available low-entropy values. - -# Related Reading - -- [Prebid.js First Party Data feature](/features/firstPartyData.html) -- [First Party Data Validation Module](/dev-docs/modules/validationFpdModule) -- [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) diff --git a/dev-docs/modules/fledgeForGpt.md b/dev-docs/modules/fledgeForGpt.md index 5f64dfa5a5..221b11d6d3 100644 --- a/dev-docs/modules/fledgeForGpt.md +++ b/dev-docs/modules/fledgeForGpt.md @@ -3,7 +3,7 @@ layout: page_v2 page_type: module title: Module - fledgeForGpt description: how to use PAAPI with GPT -module_code : fledgeForGpt +module_code : paapiForGpt display_name : Fledge (PAAPI) for GPT enable_download : true sidebarType : 1 @@ -24,7 +24,7 @@ To use PAAPI with GPT: - include this module with your Prebid.js bundle; this also automatically includes the [PAAPI module](/dev-docs/modules/paapi.html) ```bash - gulp build --modules=fledgeForGpt,... + gulp build --modules=paapiForGpt,... ``` - [configure PAAPI](/dev-docs/modules/paapi.html#config) diff --git a/dev-docs/modules/floors.md b/dev-docs/modules/floors.md index ea86698556..634f61d7b1 100644 --- a/dev-docs/modules/floors.md +++ b/dev-docs/modules/floors.md @@ -371,7 +371,7 @@ a subset that will be merged under the 'data' object. | enforcement.floorDeals | boolean | Enforce floors for deal bid requests. | false | | enforcement.bidAdjustment | boolean | If true, the module will use the bidAdjustment function to adjust the floor per bidder. If false (or no bidAdjustment function is provided), floors will not be adjusted. Note: Setting this parameter to false may have unexpected results, such as signaling a gross floor when expecting net or vice versa. | true | | enforcement.enforceRate | integer | Prebid Server only: Defines a percentage for how often bid response enforcement activity should take place given that the floors feature is active. If the floors feature is skipped due to skipRate, this has no affect. For every non-skipped auction, this percent of them should be enforced: i.e. bids discarded. This feature lets publishers ease into enforcement in case bidders aren't adhering to floor rules. | 100 | -| enforcement.noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| enforcement.noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | endpoint | object | Controls behavior for dynamically retrieving floors. | - | | endpoint.url | string | URL of endpoint to retrieve dynamic floor data. | - | | data | object (required) | Floor data used by the module to pass floor data to bidders and floor enforcement. | - | @@ -380,7 +380,7 @@ a subset that will be merged under the 'data' object. | data.skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. If skipRate is supplied in both the root level of the floors object and within the data object, the skipRate configuration within the data object shall prevail.| 0 | | data.floorsSchemaVersion | integer | The module supports two version of the data schema. Version 1 allows for only one model to be applied in a given data set, whereas Version 2 allows you to sample multiple models selected by supplied weights. If no schema version is provided, the module will assume version 1 for the sake of backwards compatiblity.| 1 | | data.modelTimestamp | int | Epoch timestamp associated with modelVersion. Can be used to track model creation of floor file for post auction analysis.| - | -| data.noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| data.noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | data.modelGroups | array of objects | Array of model objects to be used for A/B sampling multiple models. This field is only used when data.floorsSchemaVersion = 2 | - | | data.modelGroups[].currency | string | Currency of floor data. Floor Module will convert currency where necessary. See Currency section for more details. | 'USD' | | data.modelGroups[].skipRate | integer | skipRate is a random function whose input value is any integer 0 through 100 to determine when to skip all floor logic, where 0 is always use floor data and 100 is always skip floor data. The use case is for publishers or floor providers to learn bid behavior when floors are applied or skipped. Analytics adapters will have access to model version (if defined) when skipped is true to signal the module is in floors mode. | 0 | @@ -393,7 +393,7 @@ a subset that will be merged under the 'data' object. | data.modelGroups[].values."rule key" | string | Delimited field of attribute values that define a floor. | - | | data.modelGroups[].values."rule floor value" | float | The floor value for this key. | - | | data.modelGroups[].default | float | Floor used if no matching rules are found. | - | -| data.modelGroups[].noFloorSignalBidders | array of strings | (Prebid.js 8.31+) Bidders which should not receive floor signals. | none | +| data.modelGroups[].noFloorSignalBidders | array of strings | (PBJS 8.31+, PBS-Java 3.4+) This is an array of bidders for which to avoid sending floors. This is useful for bidders where the publishers has established different floor rules in their systems. The value can be `["*"]`. | - | | additionalSchemaFields | object | Object contain the lookup function to map custom schema.fields. Not supported by Prebid Server. | - | | additionalSchemaFields."custom key" | string | custom key name | - | | additionalSchemaFields."key map function" | function | Function used to lookup the value for that particular custom key | - | diff --git a/dev-docs/modules/genericAnalyticsAdapter.md b/dev-docs/modules/genericAnalyticsAdapter.md index 8c21311c66..201410e70b 100644 --- a/dev-docs/modules/genericAnalyticsAdapter.md +++ b/dev-docs/modules/genericAnalyticsAdapter.md @@ -28,9 +28,9 @@ This is an analytics adapter that can interface with any backend, meant for publ -### Note on GDPR enforcement +### Note on TCF controls -If you are using the [GDPR enforcement module](/dev-docs/modules/gdprEnforcement.html) to enforce purpose 7, by default this module will be blocked when GDPR is in scope. +If you are using the [TCF control module](/dev-docs/modules/tcfControl.html) to enforce purpose 7, by default this module will be blocked when GDPR is in scope. To enable it, you may either specify the `gvlid` option (if you are interfacing with a partner) or declare a `softVendorException` if you deem that vendor consent is not required for compliance: ```javascript diff --git a/dev-docs/modules/gppControl_usnat.md b/dev-docs/modules/gppControl_usnat.md index b2414c5926..b250ae618b 100644 --- a/dev-docs/modules/gppControl_usnat.md +++ b/dev-docs/modules/gppControl_usnat.md @@ -21,9 +21,9 @@ sidebarType : 1 ## Overview -This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) Section 7 string, USNat. For more Prebid-related background, see [Prebid MSPA Support](/features/mspa-usnat.html). In sum, the USNat string is intended to unify various state laws into a single privacy string, with participants' behavior governed by the IAB's ([MSPA](https://www.iabprivacy.com/#)). It is intended to complement, not replace, the GPP consent management module, which gathers GPP consent strings and makes them available to vendor integrations. The goal is to gather sensible and conservative [activity controls](/dev-docs/dev-docs/activity-controls.html) for elements of Prebid.js given various expressions of the [USNat consent string](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md). +This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) Section 7 string, USNat. For more Prebid-related background, see [Prebid US Compliance Support](/features/mspa-usnat.html). In sum, the USNat string is intended to unify various state laws into a single privacy string, with participants' behavior governed by the IAB's ([MSPA](https://www.iabprivacy.com/#)). It is intended to complement, not replace, the GPP consent management module, which gathers GPP consent strings and makes them available to vendor integrations. The goal is to gather sensible and conservative [activity controls](/dev-docs/activity-controls.html) for elements of Prebid.js given various expressions of the [USNat consent string](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md). -This module does not support any other GPP section id or local GPP api. For US state section see the [GPP Control - US State module](/dev-docs/modules/gppControl_usstates.html). In order to control activities in a section without a control module, publishers can express their controls directly in the syntax of the [activity control infrastructure](/dev-docs/dev-docs/activity-controls.html). If a publisher wants finer control over section 7 implications on Prebid.js behavior than this module provides (eg not invalidating certain strings), they are able to achieve that using the activity control syntax as an alternative to this module. +This module does not support any other GPP section id or local GPP api. For US state section see the [GPP Control - US State module](/dev-docs/modules/gppControl_usstates.html). In order to control activities in a section without a control module, publishers can express their controls directly in the syntax of the [activity control infrastructure](/dev-docs/activity-controls.html). If a publisher wants finer control over section 7 implications on Prebid.js behavior than this module provides (eg not invalidating certain strings), they are able to achieve that using the activity control syntax as an alternative to this module. {: .alert.alert-warning :} Prebid functionality created to address regulatory requirements does not replace each party's responsibility to determine its own legal obligations and comply with all applicable laws. **We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach. This module is not yet intended to replace other consent modules; it supplements them.** @@ -47,8 +47,8 @@ You can also use the [Prebid.js Download](/download.html) page. - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) - [IAB Global Privacy Platform USNat string Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) -- [Prebid MSPA Support](/features/mspa-usnat.html) -- [Prebid Activity Controls](/dev-docs/dev-docs/activity-controls.html) +- [Prebid US Compliance Support](/features/mspa-usnat.html) +- [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Consent Management - GPP Module](/dev-docs/modules/consentManagementGpp.html) - [Prebid Consent Management - GPP Control - US States module](/dev-docs/modules/gppControl_usstates.html) diff --git a/dev-docs/modules/gppControl_usstates.md b/dev-docs/modules/gppControl_usstates.md index e82ba32b91..502fe1845b 100644 --- a/dev-docs/modules/gppControl_usstates.md +++ b/dev-docs/modules/gppControl_usstates.md @@ -22,7 +22,7 @@ sidebarType : 1 ## Overview This consent management control module is designed to support the [Global Privacy Platform](https://iabtechlab.com/gpp/) US state strings, [GPP sections](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Section%20Information.md) 8 through 12. -It works by translating them into an equivalent US national string as detailed in [Interpreting USNat strings](/features/mspa-usnat.html#interpreting-usnat-strings), and using it to apply the same [activity restricitons](/features/mspa-usnat.html#usnat-activity-restrictions). +It works by translating them into an equivalent US national string as detailed in [Interpreting USNat strings](/features/mspa-usnat.html#interpreting-usnat-strings), and using it to apply the same [activity restrictions](/features/mspa-usnat.html#usnat-activity-restrictions). {: .alert.alert-warning :} Prebid functionality created to address regulatory requirements does not replace each party's responsibility to determine its own legal obligations and comply with all applicable laws. **We recommend consulting with your legal counsel before determining how to utilize these features in support of your overall privacy approach. This module is not intended to replace other consent modules; it supplements them.** @@ -118,7 +118,7 @@ You can also use the [Prebid.js Download](/download.html) page. - [IAB Global Privacy Platform Full Specification Repository](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) - [IAB Global Privacy Platform CMP API Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Core/CMP%20API%20Specification.md) - [IAB Global Privacy Platform USNat string Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) -- [Prebid MSPA Support](/features/mspa-usnat.html) +- [Prebid US Compliance Support](/features/mspa-usnat.html) - [Prebid Activity Controls](/dev-docs/activity-controls.html) - [Prebid Consent Management - US Privacy Module](/dev-docs/modules/consentManagementUsp.html) - [Prebid Consent Management - GPP Module](/dev-docs/modules/consentManagementGpp.html) diff --git a/dev-docs/modules/idWardRtdProvider.md b/dev-docs/modules/idWardRtdProvider.md index 642ae36ddd..9f49220c3d 100644 --- a/dev-docs/modules/idWardRtdProvider.md +++ b/dev-docs/modules/idWardRtdProvider.md @@ -8,6 +8,7 @@ module_type: rtd module_code : idWardRtdProvider enable_download : false vendor_specific: true +pbjs_version_notes: removed in 9.0 sidebarType : 1 --- diff --git a/dev-docs/modules/jwplayerRtdProvider.md b/dev-docs/modules/jwplayerRtdProvider.md index dacdf35035..7b973cdbef 100644 --- a/dev-docs/modules/jwplayerRtdProvider.md +++ b/dev-docs/modules/jwplayerRtdProvider.md @@ -42,7 +42,11 @@ To use this module, you'll need to work with [JW Player](https://www.jwplayer.co name: "jwplayer", waitForIt: true, params: { - mediaIDs: ['abc', 'def', 'ghi', 'jkl'] + mediaIDs: ['abc', 'def', 'ghi', 'jkl'], + overrideContentId: 'always', + overrideContentUrl: 'always', + overrideContentTitle: 'always', + overrideContentDescription: 'always' } }] } @@ -65,7 +69,7 @@ To use this module, you'll need to work with [JW Player](https://www.jwplayer.co | waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false | | params | Object | | | | params.mediaIDs | Array of Strings | Media Ids for prefetching | Optional | - | params.overrideContentId | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.id | Defaults to 'always' | + | params.overrideContentId | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.id | Defaults to 'whenEmpty' | | params.overrideContentUrl | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.url | Defaults to 'whenEmpty' | | params.overrideContentTitle | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.title | Defaults to 'whenEmpty' | | params.overrideContentDescription | String enum: 'always', 'whenEmpty' or 'never' | Determines when the module should update the oRTB site.content.ext.description | Defaults to 'whenEmpty' | @@ -182,6 +186,6 @@ To view an example: * in your browser, navigate to: -`http://localhost:9999/integrationExamples/gpt/jwplayerRtdProvider_example.html` +`http://localhost:9999/integrationExamples/realTimeData/jwplayerRtdProvider_example.html` **Note:** the mediaIds in the example are placeholder values; replace them with your existing IDs. diff --git a/dev-docs/modules/mobianRtdProvider.md b/dev-docs/modules/mobianRtdProvider.md new file mode 100644 index 0000000000..8958fddf85 --- /dev/null +++ b/dev-docs/modules/mobianRtdProvider.md @@ -0,0 +1,19 @@ +--- +layout: page_v2 +title: Mobian Real-Time Data Provider +display_name: Mobian Prebid Brand Safety Evaluation +description: Mobian provides contextual brand safety evaluations of pages given a URL, which publishers can use for targeting as an alternative to keyword-based evaluation. +page_type: module +module_type: rtd +module_code : mobianRtdProvider +enable_download : true +vendor_specific: false +sidebarType : 1 +--- +# Mobian Brand Safety Module + +Mobian uses AI to determine the GARM risk level of articles from our publisher partners. +This methodology is contextual, rather than keyword-based. +Our evaluation of articles is openly available through our API. This prebid header +exposes that API at prebid time so that advertisers can easily target articles with +the desired mobianGarmRisk diff --git a/dev-docs/modules/permutiveRtdProvider.md b/dev-docs/modules/permutiveRtdProvider.md index b09e2f0dba..984ff6ccbf 100644 --- a/dev-docs/modules/permutiveRtdProvider.md +++ b/dev-docs/modules/permutiveRtdProvider.md @@ -73,7 +73,7 @@ as well as enabling settings for specific use cases mentioned above (e.g. acbidd Permutive is not listed as a TCF vendor as all data collection is on behalf of the publisher and based on consent the publisher has received from the user. Rather than through the TCF framework, this consent is provided to Permutive when the user gives the relevant permissions on the publisher website which allow the Permutive SDK to run. -This means that if GDPR enforcement is configured _and_ the user consent isn’t given for Permutive to fire, no cohorts will populate. +This means that if TCF controls are enabled _and_ the user consent isn’t given for Permutive to fire, no cohorts will populate. As Prebid utilizes TCF vendor consent, for the Permutive RTD module to load, Permutive needs to be labeled within the Vendor Exceptions ### Instructions diff --git a/dev-docs/modules/prebidServer.md b/dev-docs/modules/prebidServer.md index 22bb4c6737..60713aa438 100644 --- a/dev-docs/modules/prebidServer.md +++ b/dev-docs/modules/prebidServer.md @@ -56,20 +56,20 @@ The same bidder cannot be set in both configs. For example: ```javascript pbjs.setConfig({ s2sConfig: [ - { - name: "pbs-appnexus", - accountId: '12345', - bidders: ['appnexus','pubmatic'], - defaultVendor: 'appnexus', - timeout: 300, - }, - { - name: "pbs-rubicon", - accountId: '678910', - bidders: ['rubicon'], - defaultVendor: 'rubicon', - timeout: 300, - }, + { + name: "pbs-appnexus", + accountId: '12345', + bidders: ['appnexus','pubmatic'], + defaultVendor: 'appnexus', + timeout: 300, + }, + { + name: "pbs-rubicon", + accountId: '678910', + bidders: ['rubicon'], + defaultVendor: 'rubicon', + timeout: 300, + }, ], }); ``` @@ -85,7 +85,7 @@ There are many configuration options for s2sConfig: | `allowUnknownBidderCodes` | Optional | Boolean | Allow Prebid Server to bid on behalf of bidders that are not explicitly listed in the adUnit. See important [note](#allowUnknownBidderCodes) below. Defaults to `false`. | | `defaultVendor` | Optional | String | Automatically includes all following options in the config with vendor's default values. Individual properties can be overridden by including them in the config along with this setting. See the Additional Notes below for more information. | | `enabled` | Optional | Boolean | Enables this s2sConfig block - defaults to `false` | -| `timeout` | Optional | Integer | Number of milliseconds allowed for the server-side auctions. This should be approximately 200ms-300ms less than your Prebid.js timeout to allow for all bids to be returned in a timely manner. Defaults to 1000ms. | +| `timeout` | Optional | Integer | Number of milliseconds allowed for the server-side auctions. This should be approximately 200ms-300ms less than your Prebid.js timeout to allow for all bids to be returned in a timely manner. Defaults to 75% of [`bidderTimeout`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Bidder-Timeouts) or 750ms, whichever is lesser. | | `adapter` | Required | String | Adapter to use to connect to Prebid Server. Defaults to 'prebidServer' | | `endpoint` | Required | URL or Object | Defines the auction endpoint for the Prebid Server cluster. See table below for object config properties. | | `syncEndpoint` | Required | URL or Object | Defines the cookie_sync endpoint for the Prebid Server cluster. See table below for object config properties. | @@ -96,6 +96,7 @@ There are many configuration options for s2sConfig: | `defaultTtl` | Optional | Integer | Configures the default TTL in the Prebid Server adapter to use when Prebid Server does not return a bid TTL - 60 if not set | | `adapterOptions` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in every impression object at request.imp[].ext.BIDDER. See the example above. | | `extPrebid` | Optional | Object | Arguments will be added to resulting OpenRTB payload to Prebid Server in request.ext.prebid. See the examples below. | +| `customHeader` | Optional | Object | These custom headers will be included in the XHR call to the bidder's endpoint. This will allow you to send data specific to your use case. The format consists of an object where the keys represent the header names and the values correspond to the respective header values. Here is an example how a customHeader object might look like - `{"Header1": "Value1", "Header2": "Value2"}`| If `endpoint` and `syncEndpoint` are objects, these are the supported properties: diff --git a/dev-docs/modules/pubxaiRtdProvider.md b/dev-docs/modules/pubxaiRtdProvider.md index 26a0f84923..f94758a106 100644 --- a/dev-docs/modules/pubxaiRtdProvider.md +++ b/dev-docs/modules/pubxaiRtdProvider.md @@ -48,18 +48,20 @@ pbjs.setConfig({ ..., realTimeData: { auctionDelay: AUCTION_DELAY, - dataProviders: { - name: "pubxai", - waitForIt: true, - params: { - pubxId: ``, - endpoint: ``, // (optional) - floorMin: ``, // (optional) - enforcement: ``, // (optional) - data: `` // (optional) - } - } - } + dataProviders: [ + { + name: "pubxai", + waitForIt: true, + params: { + pubxId: ``, + endpoint: ``, // (optional) + floorMin: ``, // (optional) + enforcement: ``, // (optional) + data: `` // (optional) + }, + }, + ], + }, // rest of the config ..., }); diff --git a/dev-docs/modules/sirdataRtdProvider.md b/dev-docs/modules/sirdataRtdProvider.md index 860e5952e3..724a036dac 100644 --- a/dev-docs/modules/sirdataRtdProvider.md +++ b/dev-docs/modules/sirdataRtdProvider.md @@ -1,8 +1,8 @@ --- layout: page_v2 title: Sirdata Real Time Data Provider -display_name: Sirdata Real-time Segmentation Module -description: Sirdata Real-time Segmentation Module +display_name: Sirdata Real-time SDA Module +description: Sirdata Real-time Seller Defined Audience based Module page_type: module module_type: rtd module_code : sirdataRtdProvider @@ -12,26 +12,28 @@ sidebarType : 1 --- # Sirdata RTD/SDA Module - {:.no_toc} * TOC {:toc} -Sirdata provides a disruptive API that allows publishers and curating SSPs to leverage its cutting-edge contextualization technology and its audience segments based on cookies and consent or without cookies nor consent, even in Europe! +Sirdata provides a disruptive API that allows publishers and SDA compliant SSPs/DSPs to leverage its cutting-edge contextualization technology and its audience segments! -User-based segments and page-level automatic contextual categories will be attached to bid request objects sent to different SSPs in order to optimize targeting. +User-based segments and page-level automatic contextual categories will be attached to bid request objects sent to different bidders in order to optimize targeting. -Automatic or custom integration with Google Ad Manager and major bidders like Xandr/Appnexus, Smartadserver, Index Exchange, Proxistore, Magnite/Rubicon or Triplelift ! +Automatic or custom integration with Google Ad Manager and major bidders like Xandr's, Equativ's, Index Exchange's, Proxistore's, Magnite's or Triplelift's ! User's country and choice management are included in the module, so it's 100% compliant with local and regional laws like GDPR and CCPA/CPRA. ORTB2 compliant and FPD support for Prebid versions < 4.29 -Now supports Seller Defined Audience ! +Fully supports Seller Defined Audience ! Please find the full SDA taxonomy ids list here. Please contact for more information. +{: .alert.alert-warning :} +Disclosure: This module harvests all page content, even for logged in users, and some EIDs, including the SharedId + ## Publisher Usage ### Configure Prebid.js @@ -42,13 +44,13 @@ Compile the Sirdata RTD module into your Prebid build: Add the Sirdata RTD provider to your Prebid config. -`actualUrl` MUST be set with actual location of parent page if prebid.js is loaded in an iframe (eg. postbid). It can be left blank ('') or removed otherwize. +`actualUrl` MUST be set with actual location of parent page if prebid.js is loaded in an iframe (e.g. hosted). It can be left blank ('') or removed otherwise. `partnerId` and `key` should be provided by your partnering SSP or get one and your dedicated taxonomy from Sirdata (). Segments ids (user-centric) and category ids (page-centric) will be provided salted and hashed : you can use them with a dedicated and private matching table. -Should you want to allow a SSP or a partner to curate your media and operate cross-publishers campaigns with our data, please ask Sirdata () to whitelist him it in your account. +Should you want to allow any SSP or a partner to curate your media and operate cross-publishers campaigns with our data, please ask Sirdata () to whitelist him it in your account. -#### Minimal configuration +#### Typical configuration ```javascript pbjs.setConfig({ @@ -86,21 +88,7 @@ pbjs.setConfig({ key: 1, setGptKeyValues: true, contextualMinRelevancyScore: 50, //Min score to filter contextual category globally (0-100 scale) - actualUrl: '', //top location url, for contextual categories - bidders: [{ - bidder: 'appnexus', - adUnitCodes: ['adUnit-1','adUnit-2'], - customFunction: overrideAppnexus, - curationId: '111', - },{ - bidder: 'ix', - sizeLimit: 1200 //specific to Index Exchange, - contextualMinRelevancyScore: 50, //Min score to filter contextual category for curation in the bidder (0-100 scale) - },{ - bidder: 'smartadserver' - },{ - bidder: 'proxistore' - }] + actualUrl: '' //top location url, for contextual categories } } ] @@ -111,26 +99,27 @@ pbjs.setConfig({ ### Parameter Descriptions for the Sirdata Configuration Section -| Name |Type | Description | Notes | -| :------------ | :------------ | :------------ |:------------ | -| name | String | Real time data module name | Mandatory. Always 'SirdataRTDModule' | -| waitForIt | Boolean | Mandatory. Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true | -| params | Object | | Optional | -| params.partnerId | Integer | Partner ID, required to get results and provided by Sirdata. Use 1 for tests and get one running at | Mandatory. Defaults 1. | -| params.key | Integer | Key linked to Partner ID, required to get results and provided by Sirdata. Use 1 for tests and get one running at | Mandatory. Defaults 1. | -| params.setGptKeyValues | Boolean | This parameter Sirdata to set Targeting for GPT/GAM | Optional. Defaults to true. | -| params.contextualMinRelevancyScore | Integer | Min score to keep filter category in the bidders (0-100 scale). Optional. Defaults to 30. | -| params.bidders | Object | Dictionary of bidders you would like to supply Sirdata data for. | Optional. In case no bidder is specified Sirdata will atend to ad data custom and ortb2 to all bidders, adUnits & Globalconfig | +| Name | Type | Description | Notes | +|:-----------------------------------|:----------------|:----------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------| +| name | String | Real time data module name | Mandatory. Always 'SirdataRTDModule' | +| waitForIt | Boolean | Required to ensure that the auction is delayed until prefetch is complete | Optional. Default to false but recommended to true | +| params | Object | Settings | Optional | +| params.partnerId | Integer | Partner ID, required to get results and provided by Sirdata. Use 1 for tests and request your Id at | Mandatory. Default 1 | +| params.key | Integer | Key linked to Partner ID, required to get results and provided by Sirdata. Use 1 for tests and request your key at | Mandatory. Default 1 | +| params.setGptKeyValues | Boolean | Sets Targeting for GPT/GAM | Optional. Default to true | +| params.authorizedEids | Array of String | List of authorised Eids for graph. Set [] to prevent all Eids usage | Optional. Default to : ID5, pubProvidedId and sharedId | +| params.avoidPostContent | Boolean | Block contextual data POST from user's device (a crawler is use instead) | Optional. Default to false, and setting it to true results in your content downloaded by Sirdata crawler | +| params.contextualMinRelevancyScore | Integer | Min relevancy score to filter categories sent to the bidders (0-100 scale). | Optional. Defaults to 30 | +| params.bidders | Array of Object | Bidders you want to supply your own data to (works only with your private data bought to Sirdata) | Optional | Bidders can receive common setting : -| Name |Type | Description | Notes | -| :------------ | :------------ | :------------ |:------------ | -| bidder | String | Bidder name | Mandatory if params.bidders are specified | -| adUnitCodes | Array of String | Use if you want to limit data injection to specified adUnits for the bidder | Optional. Default is false and data shared with the bidder isn't filtered | -| customFunction | Function | Use it to override the way data is shared with a bidder | Optional. Default is false | -| curationId | String | Specify the curation ID of the bidder. Provided by Sirdata, request it at | Optional. Default curation ids are specified for main bidders | -| contextualMinRelevancyScore | Integer | Min score to filter contextual categories for curation in the bidder (0-100 scale). Optional. Defaults to 30 or global params.contextualMinRelevancyScore if exits. | -| sizeLimit | Integer | used only for bidder 'ix' to limit the size of the get parameter in Index Exchange ad call | Optional. Default is 1000 | + +| Name | Type | Description | Notes | +|:---------------|:----------------|:-----------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------| +| bidder | String | Bidder name | Mandatory if params.bidders are specified | +| adUnitCodes | Array of String | Use if you want to limit data injection to specified adUnits for the bidder | Optional. Default is false and data shared with the bidder isn't filtered | +| customFunction | Function | Use it to override the way data is shared with a bidder | Optional. Default is false | +| curationId | String | Specify the curation ID of the bidder. Provided by Sirdata, request it at | Optional. Default curation ids are specified for main bidders | ### Overriding data sharing function @@ -221,7 +210,6 @@ pbjs.setConfig({ curationId: '111' },{ bidder: 'ix', - sizeLimit: 1200, //specific to Index Exchange customFunction: function(adUnit, segmentsArray, dataObject, bid) { bid.params.contextual.push(dataObject.contextual_categories); }, @@ -229,7 +217,7 @@ pbjs.setConfig({ } } ] - } + }, ... }); ``` diff --git a/dev-docs/modules/gdprEnforcement.md b/dev-docs/modules/tcfControl.md similarity index 93% rename from dev-docs/modules/gdprEnforcement.md rename to dev-docs/modules/tcfControl.md index 27906a944b..42977e1e7c 100644 --- a/dev-docs/modules/gdprEnforcement.md +++ b/dev-docs/modules/tcfControl.md @@ -1,10 +1,10 @@ --- layout: page_v2 page_type: module -title: GDPR Enforcement Module +title: TCF Control Module description: If you have users in Europe, you can use this module to enable actions for processing under the GDPR and ePrivacy -module_code : gdprEnforcement -display_name : GDPR Enforcement +module_code : tcfControl +display_name : TCF Control enable_download : true recommended: true sidebarType : 1 @@ -19,17 +19,17 @@ sidebarType : 1 {% include legal-warning.html %} {: .alert.alert-warning :} -This module requires the [EU GDPR consent management module](/dev-docs/modules/consentManagement.html) (the base consent module), which reads consent values from the Consent Management Platform (CMP). The GDPR Enforcement Module -will then take action based on the results. See the [base module page](/dev-docs/modules/consentManagement.html) for general background, usage, and legal disclaimers. +This module requires the [TCF consent management module](/dev-docs/modules/consentManagementTcf.html) (the base consent module), which reads consent values from the Consent Management Platform (CMP). The TCF Control Module +will then take action based on the results. See the [base module page](/dev-docs/modules/consentManagementTcf.html) for general background, usage, and legal disclaimers. ## Overview -The [base consent module](/dev-docs/modules/consentManagement.html) performs the following actions: +The [base consent module](/dev-docs/modules/consentManagementTcf.html) performs the following actions: 1. Fetches the user's GDPR consent data from the CMP. 2. Incorporates this data into the auction objects for adapters to collect. -The GDPR Enforcement Module adds the following: +The TCF Control Module adds the following: 1. Allows the page to define which activities should be enforced at the Prebid.js level. 2. Actively enforces those activities based on user consent data. @@ -58,10 +58,10 @@ A page needs to define configuration rules about how Prebid.js should enforce ea {: .alert.alert-info :} To turn on Prebid.js enforcement you must: -(1) Include the gdprEnforcement module in the Prebid.js build +(1) Include the tcfControl module in the Prebid.js build and (2) setConfig `consentManagement.gdpr.cmpApi` to either 'iab' or 'static' -The following fields related to GDPR enforcement are supported in the [`consentManagement`](/dev-docs/modules/consentManagement.html) object: +The following fields related to GDPR enforcement are supported in the [`consentManagement`](/dev-docs/modules/consentManagementTcf.html) object: {: .table .table-bordered .table-striped } | Param | Type | Description | Example | @@ -228,14 +228,14 @@ This behavior can be changed to the same "basic enforcement" algorithm described Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). Include the base consent management module and this enforcement module as additional options on the **gulp build** command: ```bash -gulp build --modules=consentManagement,gdprEnforcement,bidAdapter1,bidAdapter2 +gulp build --modules=consentManagement,tcfControl,bidAdapter1,bidAdapter2 ``` You can also use the [Prebid.js Download](/download.html) page. ## Further Reading -* [EU GDPR Consent Management Module](/dev-docs/modules/consentManagement.html) +* [EU GDPR Consent Management Module](/dev-docs/modules/consentManagementTcf.html) * [IAB TCF Implementation Guidelines](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/TCF-Implementation-Guidelines.md) * [IAB TCF2 Consent String Format](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md) * [Prebid TCF2 Support](https://docs.google.com/document/d/1fBRaodKifv1pYsWY3ia-9K96VHUjd8kKvxZlOsozm8E/edit#) diff --git a/dev-docs/modules/topLevelPaapi.md b/dev-docs/modules/topLevelPaapi.md new file mode 100644 index 0000000000..735846a760 --- /dev/null +++ b/dev-docs/modules/topLevelPaapi.md @@ -0,0 +1,124 @@ +--- +layout: page_v2 +page_type: module +title: Module - topLevelPaapi +description: Run top level PAAPI auctions +module_code : topLevelPaapi +display_name : Run top level PAAPI auctions +enable_download : true +sidebarType : 1 +--- + +# Top level PAAPI module + +This module allows Prebid.js to support PAAPI by running on-device auctions as the top level seller. + +## Comparison with paapiForGpt + +Both this module and [paapiForGpt](/dev-docs/modules/paapiForGpt.html) allow bid adapters to participate in PAAPI auctions as component sellers. + +With paapiForGpt, bidders' intent to participate in PAAPI is submitted to GPT, which can then decide how to run the on-device auction. +With topLevelPaapi, Prebid.js directly manages the on-device auction, trading ease of use for more control. + +## Publisher Integration + +To use topLevelPaapi: + +- you'll need a [decision logic URL](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#23-scoring-bids) that has been [attested](https://github.com/privacysandbox/attestation) with Google. How to write decision logic and how to attest it are both out of scope for this document. +- include this module with your Prebid.js bundle; this also automatically includes the [PAAPI module](/dev-docs/modules/paapi.html) + + ```bash + gulp build --modules=topLevelPaapi,... + ``` + +- [configure this module](#config) +- render PAAPI bids (see [examples](#examples)) + + +## Module Configuration + +This module exposes the following settings: + +{: .table .table-bordered .table-striped } +|Name |Type |Description |Notes | +| ------------ | ------------ | ------------ |------------ | +|paapi.topLevelSeller | Object | | | +|paapi.topLevelSeller.auctionConfig | Object | Base [AuctionConfig](https://github.com/WICG/turtledove/blob/main/FLEDGE.md#2-sellers-run-on-device-auctions) to use in `runAdAuction` | Only `seller` and `decisionLogicURL` are required | +|paapi.topLevelSeller.autorun | Boolean | If `true` (the default) , automatically start PAAPI auctions as soon as possible | | +|paapi.topLevelSeller.overrideWinner | Boolean | If `true`, replace contextual winners with PAAPI winners as they are rendered. Default is `false`. | see [example](#overrideWinner) | + + +## Examples + +### Basic Example using renderAd + +```javascript +pbjs.setConfig({ + paapi: { + enabled: true, + defaultForSlots: 1, + topLevelSeller: { + auctionConfig: { + seller: 'https://www.publisher.com', + decisionLogicURL: 'https://www.publisher.com/decisionLogic.js', + }, + } + } +}) +``` + +With the above, `navigator.runAdAuction` is invoked once per ad unit, and the result is made available through [`getPAAPIBids`](/dev-docs/publisher-api-reference/getPAAPIBids.html): + +```javascript +pbjs.requestBids({ + bidsBackHandler: function(contextualBids) { + pbjs.getPAAPIBids().then(paapiBids => { + Object.entries(contextualBids).forEach(([adUnitCode, {bids}]) => { + const paapiWinner = paapiBids[adUnitCode]; + const contextualWinner = bids?.[0]; + const targetDoc = document.getElementById(adUnitCode).contentDocument // assumes there's an iframe with id = adUnitCode + // PAAPI bids can be rendered as if they were "normal" Prebid bids + if (paapiWinner) { + pbjs.renderAd(targetDoc, paapiWinner.adId) + } else { + pbjs.renderAd(targetDoc, contextualWinner.adId) + } + }) + }) + } +}) +``` + + +### Automatically render PAAPI winners instead of contextual bids + +When `overrideWinner` is enabled, rendering a "normal" Prebid bid will instead render a PAAPI bid, if the PAAPI auction for the slot yielded a winner. This is an easy way include the result of PAAPI auctions without having to change the rendering logic. For example: + +```javascript +pbjs.setConfig({ + paapi: { + enabled: true, + defaultForSlots: 1, + topLevelSeller: { + auctionConfig: { + seller: 'https://www.publisher.com', + decisionLogicURL: 'https://www.publisher.com/decisionLogic.js', + }, + overrideWinner: true + } + } +}); + +pbjs.requestBids({ + bidsBackHandler: function() { + // if Prebid wins the GAM auction (and renders a Prebid creative), the following will render PAAPI winners over the Prebid winners + pbjs.setTargetingForGPTAsync(); + } +}) +``` + +## Related Reading + +- [PAAPI module](/dev-docs/modules/paapi.html) +- [FLEDGE](https://github.com/WICG/turtledove/blob/main/FLEDGE.md) +- [getPAAPIBids](/dev-docs/publisher-api-reference/getPAAPIBids.html) diff --git a/dev-docs/modules/topicsFpdModule.md b/dev-docs/modules/topicsFpdModule.md index 30eff8b5e0..27346a3c01 100644 --- a/dev-docs/modules/topicsFpdModule.md +++ b/dev-docs/modules/topicsFpdModule.md @@ -55,15 +55,34 @@ pbjs.setConfig({ userSync: { // ..., topics: { - maxTopicCaller: 3, // SSP rotation + maxTopicCaller: 4, bidders: [{ bidder: 'pubmatic', - iframeURL: 'https://ads.pubmatic.com/AdServer/js/topics/topics_frame.html', - expiry: 7 // Configurable expiry days - },{ - bidder: 'appnexus', - iframeURL: 'https://appnexus.com:8080/topics/fpd/topic.html', // dummy URL - expiry: 7 // Configurable expiry days + iframeURL: 'https://ads.pubmatic.com/AdServer/js/topics/topics_frame.html' + }, { + bidder: 'rtbhouse', + iframeURL: 'https://topics.authorizedvault.com/topicsapi.html' + }, { + bidder: 'openx', + iframeURL: 'https://pa.openx.net/topics_frame.html' + }, { + bidder: 'improvedigital', + iframeURL: 'https://hb.360yield.com/privacy-sandbox/topics.html' + }, { + bidder: 'onetag', + iframeURL: 'https://onetag-sys.com/static/topicsapi.html' + }, { + bidder: 'taboola', + iframeURL: 'https://cdn.taboola.com/libtrc/static/topics/taboola-prebid-browsing-topics.html' + }, { + bidder: 'discovery', + iframeURL: 'https://api.popin.cc/topic/prebid-topics-frame.html' + }, { + bidder: 'undertone', + iframeURL: 'https://creative-p.undertone.com/spk-public/topics_frame.html' + }, { + bidder: 'vidazoo', + iframeURL: 'https://static.vidazoo.com/topics_api/topics_frame.html' }] } // ... diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 3025b6e144..ff11f4b0e6 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -39,7 +39,7 @@ Not all bidder adapters support all forms of user ID. See the tables below for a ## User ID, GDPR, Permissions, and Opt-Out -When paired with the [Consent Management](/dev-docs/modules/consentManagement.html) module, privacy rules are enforced: +When paired with the [Consent Management](/dev-docs/modules/consentManagementTcf.html) module, privacy rules are enforced: * The module checks the GDPR consent string * If no consent string is available OR if the user has not consented to Purpose 1 (local storage): @@ -88,7 +88,7 @@ The table below has the options that are common across ID systems. See the secti | name | Required | String | May be any of the following values: {% for page in userid_pages -%}{% if count == 1 %}{{ name_string │ append: ", " -}}{% endif %}{% assign count = 1 %}`"{{ name_string │ append: name_string -}}{{ name_string │ append: page.useridmodule -}}"`{% endfor %} | `"unifiedId"` | | params | Based on User ID sub-module | Object | | | | bidders | Optional | Array of Strings | An array of bidder codes to which this user ID may be sent. | `['bidderA', 'bidderB']` | -| storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be cookie, HTML5 storage or both. This is not needed when `value` is specified or the ID system is managing its own storage | | +| storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be a cookie, HTML5 storage or both.| | | storage.type | Required | String | Must be `"cookie"`, `"html5"` or `"cookie&html5"`. This is where the results of the user ID will be stored. | `"cookie"` | | storage.name | Required | String | The name of the cookie or html5 local storage where the user ID will be stored. | `"_unifiedId"` | | storage.expires | Strongly Recommended | Integer | How long (in days) the user ID information will be stored. If this parameter isn't specified, session cookies are used in cookie-mode, and local storage mode will create new IDs on every page. | `365` | @@ -259,6 +259,7 @@ Bidders that want to support the User ID module in Prebid.js need to update thei | ConnectID | Yahoo | connectId | yahoo.com | {"connectId": "72d04af6..."} | | FreePass ID | FreePass | freepassId | | "1111" | | UtiqMtp ID | Utiq | utiqMtpId | utiq-mtp.com | "1111" | +| Yandex ID | Yandex | yandexId | yandex.com | "11111111111111111" | For example, the adapter code might do something like: @@ -344,7 +345,11 @@ If you're an ID provider that wants to get on this page: * Add your *IdSystem name into the modules/.submodules.json file * Follow all the guidelines in the [contribution page](https://github.com/prebid/Prebid.js/blob/master/CONTRIBUTING.md). * Submit a Pull Request against the [Prebid.js repository](https://github.com/prebid/Prebid.js). -* Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io), modify /dev-docs/modules/userId.md, /download.md, and submit a documentation Pull Request. +* Update the Prebid docs + * Fork the prebid.org [documentation repository](https://github.com/prebid/prebid.github.io) + * Add `/dev-docs/modules/userid-submodules/.md` + * Add a new row to `/dev-docs/modules/userId.md#prebidjs-adapters` + * Submit a documentation Pull Request @@ -411,4 +416,4 @@ This will have no effect until you call the `registerSignalSources` API. This me ## Further Reading * [Prebid.js Usersync](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) -* [GDPR ConsentManagement Module](/dev-docs/modules/consentManagement.html) +* [TCF ConsentManagement Module](/dev-docs/modules/consentManagementTcf.html) diff --git a/dev-docs/modules/userid-submodules/33across.md b/dev-docs/modules/userid-submodules/33across.md index 903bc2a9df..d63c246e10 100644 --- a/dev-docs/modules/userid-submodules/33across.md +++ b/dev-docs/modules/userid-submodules/33across.md @@ -26,10 +26,11 @@ The following configuration parameters are available: | name | Required | String | The name of this sub-module | `"33acrossId"` | | params ||| Details for the sub-module initialization || | params.pid | Required | String | Partner ID (PID) | Please reach out to [PrebidUIM@33across.com](mailto:PrebidUIM@33across.com) and request your PID | -| params.storeFpid | Optional | Boolean | Indicates whether a supplemental first-party ID may be stored to improve addressability | `false` (default) or `true` | +| params.storeFpid | Optional | Boolean | Indicates whether a supplemental first-party ID may be stored to improve addressability | `true` (default) or `false` | +| params.storeTpid | Optional | Boolean | Indicates whether a supplemental third-party ID may be stored to improve addressability | `true` (default) or `false` | | storage ||||| | storage.name | Required | String | The name of the cookie or html5 local storage key | `"33acrossId"` (recommended) | -| storage.type | Required | String | This is where the 33across user ID will be stored | `"html5"` (recommended) or `"cookie"` | +| storage.type | Required | String | This is where the 33across user ID will be stored | `"cookie&html5"` (recommended) or `"html5"` or `"cookie"` | | storage.expires | Strongly Recommended | Number | How long (in days) the user ID information will be stored | `30` (recommended) | | storage.refreshInSeconds | Strongly Recommended | Number | How many seconds until the ID is refreshed | `8 * 3600` (recommended) | @@ -46,7 +47,7 @@ pbjs.setConfig({ }, storage: { name: "33acrossId", - type: "html5", + type: "cookie&html5", expires: 30, refreshInSeconds: 8 * 3600 } diff --git a/dev-docs/modules/userid-submodules/euid.md b/dev-docs/modules/userid-submodules/euid.md index 7e279c9cf1..7551b53fa0 100644 --- a/dev-docs/modules/userid-submodules/euid.md +++ b/dev-docs/modules/userid-submodules/euid.md @@ -103,6 +103,12 @@ pbjs.setConfig({ There is a server-only mode where the value of the advertising token can be provided either directly (see the `value` parameter in the [European Unified ID Configuration](#european-unified-id-configuration) section) or via a cookie. In this mode, no attempt is made to automatically refresh the token. +For a server-side integration, you can create a smaller Prebid.js build by disabling client-side integration functionality. To do this, pass the `--disable UID2_CSTG` flag: + +```bash + gulp build --modules=euidIdSystem --disable UID2_CSTG +``` + ### Cookie-based server-only mode To use the cookie-based server-only mode, set a cookie named `__euid_advertising_token` to the value of the advertising token only, as shown in this fictitious example: diff --git a/dev-docs/modules/userid-submodules/ftrack.md b/dev-docs/modules/userid-submodules/ftrack.md index 89b636c898..2363defd83 100644 --- a/dev-docs/modules/userid-submodules/ftrack.md +++ b/dev-docs/modules/userid-submodules/ftrack.md @@ -5,9 +5,11 @@ description: FTrack ID from Flashtalking By Mediaocean User ID sub-module useridmodule: ftrackIdSystem --- - The FTrack Identity Framework (["FTrack"](https://www.flashtalking.com/identity-framework#FTrack)) User ID Module allows publishers to take advantage of Flashtalking's FTrack ID during the bidding process. +{: .alert.alert-warning :} +Disclosure: This module loads javascript unreviewed by the prebid.js community. + Flashtalking’s cookieless tracking technology uses probabilistic device recognition to derive a privacy-friendly persistent ID for each device. Questions? Comments? Bugs? Praise? Please contact FlashTalking's Prebid Support at [prebid-support@flashtalking.com](mailto:prebid-support@flashtalking.com) diff --git a/dev-docs/modules/userid-submodules/id5.md b/dev-docs/modules/userid-submodules/id5.md index ac2d6455d2..1ab7dc315f 100644 --- a/dev-docs/modules/userid-submodules/id5.md +++ b/dev-docs/modules/userid-submodules/id5.md @@ -29,15 +29,16 @@ The following configuration parameters are available: | name | Required | String | The name of this module: `"id5Id"` | `"id5Id"` | | params | Required | Object | Details for the ID5 ID. | | | params.partner | Required | Number | This is the ID5 Partner Number obtained from registering with ID5. | `173` | -| params.externalModuleUrl | Optional | String | URL to the external ID5 module. Highly recommended for the best integration possible. | `https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js` | +| params.externalModuleUrl | Optional | String | URL to the external ID5 module. Highly recommended for the best integration possible. This is additional javascript unreviewed by the prebid.js community | `https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js` | | params.pd | Optional | String | Partner-supplied data used for linking ID5 IDs across domains. See [our documentation](https://wiki.id5.io/en/identitycloud/retrieve-id5-ids/passing-partner-data-to-id5) for details on generating the string. Omit the parameter or leave as an empty string if no data to supply | `"MT1iNTBjY..."` | | params.abTesting | Optional | Object | Allows publishers to easily run an A/B Test. If enabled and the user is in the Control Group, the ID5 ID will NOT be exposed to bid adapters for that request | Disabled by default | | 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/modules/userid-submodules/liveintent.md b/dev-docs/modules/userid-submodules/liveintent.md index 882209903c..934fc5dca0 100644 --- a/dev-docs/modules/userid-submodules/liveintent.md +++ b/dev-docs/modules/userid-submodules/liveintent.md @@ -82,7 +82,7 @@ pbjs.setConfig({ ### Multiple user IDs -The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. +The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` and `fpid` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. Note: `thetradedesk` will be exposed as `tdid` because of historical reasons. For example, in case `uid2` is configured to be requested in addition to the `nonID`, the `request.userId` object would look like the following: @@ -100,9 +100,54 @@ For example, in case `uid2` is configured to be requested in addition to the `no } ``` -NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` behave the same way. +NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (as `tdid`) and `fpid` behave the same way. -For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`, there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. +For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid` there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. + +### FPID + +The `fpid` is a first party identifier that can be exposed through the liveconnect user ID module. In order to use this functionality tell the module which identifier you want to use as a `fpid` in the config params: + +```javascript +{ + "params": { + "fpid": { + "strategy": "cookie", // "cookie" | "html5" -- Where the identifier should be read from + "name": "foobar" // key in the chosen storage backend + } + } +} +``` + +Additionally, add it to the requested attributes: + +```javascript +{ + //... + "params": { + "fpid": { + "strategy": "cookie", + "name": "foobar" + }, + "requestedAttributesOverrides": {'fpid': true} + } + //... +} +``` + +The user id result will contain both the `fpid` directly in the `lipb` object and separately: + +```javascript +{"lipb":{"fpid":"foobar"},"fpid":{"id":"foobar"}} +``` + +The same applies for the eids: + +```javascript +[{"source":"fpid.liveintent.com","uids":[{"id":"foobar","atype":1}]}] +``` + +NOTE: If COPPA applies, LiveIntent’s user ID module will not return the `fpid`. ### Request uid2 @@ -139,7 +184,7 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.ajaxTimeout |Optional| Number |This configuration parameter defines the maximum duration of a call to the `IdentityResolution` endpoint. By default, 5000 milliseconds.|`5000`| | params.partner | Optional| String |The name of the partner whose data will be returned in the response.|`prebid`| | params.identifiersToResolve |Optional| Array[String] |Used to send additional identifiers in the request for LiveIntent to resolve against the LiveIntent ID and additional attributes.|`['my-id']`| -| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`. | `{'uid2': true}` | +| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid`. | `{'uid2': true}` | | params.emailHash |Optional| String |The hashed email address of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha2.|`1a79a4d60de6718e8e5b326e338ae533`| | params.url | Optional| String |Use this to change the default endpoint URL if you can call the LiveIntent Identity Exchange within your own domain.|`https://idx.my-domain.com`| | params.liCollectConfig |Optional| Object |Container of all collector params.|| @@ -148,6 +193,12 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.liCollectConfig.fpiExpirationDays |Optional| Number |The expiration time of an identifier created and updated by LiveConnect. By default, 730 days.|`729`| | params.liCollectConfig.collectorUrl |Optional| String |The parameter defines where the signal pixels are pointing to. The params and paths will be defined subsequently. If the parameter is not set, LiveConnect will by default emit the signal towards `https://rp.liadm.com`.| `https://rp.liadm.com`| | params.liCollectConfig.appId |Optional| String |LiveIntent's media business entity application ID.|`a-0012`| +| params.fpid.name | Optional | String | The parameter is cookie/localstorage key name | `'__super_duper_cookie'`| +| params.fpid.strategy | Optional | String | The parameter defines where to get the identifier from. Either from the cookie jar, `'cookie'`, or from the local storage, `'html5'`. | `'html5'`| +| storage | Required | Object | This object defines where and for how long the results of the call to get a user ID will be stored. | | +| storage.type | Required | String | This parameter defines where the resolved user ID will be stored (either `'cookie'` or `'html5'` localstorage).| `'cookie'` | +| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'pbjs_li_nonid'` | +| storage.expires | Recommended | Integer | How long (in days) the user ID information will be stored. The recommended value is `1` | `1` | ## LiveIntent ID examples @@ -202,6 +253,10 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at fpiExpirationDays: 730, collectorUrl: "https://rp.liadm.com", appId: "a-0012" + }, + fpid: { + strategy: "cookie" + name: "foobar" } } }] diff --git a/dev-docs/modules/userid-submodules/lockraim.md b/dev-docs/modules/userid-submodules/lockraim.md new file mode 100644 index 0000000000..6a1d8c7373 --- /dev/null +++ b/dev-docs/modules/userid-submodules/lockraim.md @@ -0,0 +1,119 @@ +--- +layout: userid +title: lockr AIM +description: lockr Alternative Identity Manager sub-module +useridmodule: lockrAIMIdSystem +--- + +Alternative Identity Manager (AIM) is a unified container for identity and data management. +AIM includes a self-service platform for publishers to seamlessly integrate and activate alternative IDs like LiveRamp’s Authenticated Traffic Solution (ATS), Unified ID 2.0 (UID2), and ID5. The self-service component allows the publisher to easily enable or disable IDs and to send identity clusters to CDPs or cleanrooms without engaging engineering teams. For more information about AIM and detailed integration docs, please visit [our documentation](https://sso.loc.kr/api/lockr_reference.html#tag/Alternate-Identity-Management-(AIM)). + +### **Account Creation | AIM** + +1. Sign up for an [Identity lockr account.](https://sso.loc.kr/console/signup) +2. Setup your app and activate the AIM library. +3. Compile Prebid with the appropriate configurations, and deploy. + +### **Configuration | AIM** + +Add the lockr’s AIM submodule to your Prebid.js package by running: + +```sh +gulp build –modules=lockrAIMIdSystem,... +``` + +The following configuration parameters are available: +{: .table .table-bordered .table-striped } +| Param | Scope | Type | Description | Example | +|----------------|----------|--------|----------------------------------------|-----------------------| +| name | Required | String | The name of this module: `"lockrAIMId"`| `"lockrAIMId"` | +| params | Required | Object | Details for the configuration. | | +| params.email | Required | String | Email address for identity tokens. | `test@example.com` | +| params.appID | Required | String | Identity lockr appID | `e84afc5f-4adf-4144-949f-1de5bd151fcc` | + +**Google oAuth:** +If you are using Google oAuth (_as an example_), the onSignIn function will subsequently call window.lockr.setAdditionalData function and include a raw email. + +```javascript +function onSignIn(googleUser) { + pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'lockrAIMId', + params: { + email: 'john@example.com', + appID: 'e84afc5f-4adf-4144-949f-1de5bd151fcc' + } + }] + } + }); +} +``` + +**Facebook oAuth:** +If you are using Facebook Login (_as an example_), the statusChangeCallback function will subsequently call window.lockr.setAdditionalData function and include a raw email. + +```javascript +function statusChangeCallback(response) { + console.log('statusChangeCallback'); + console.log(response); + if(response.status === 'connected'){ + pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'lockrAIMId', + params: { + email: 'john@example.com', + appID: 'e84afc5f-4adf-4144-949f-1de5bd151fcc' + } + }] + } + }); + }else{ + document.getElementById('status').innerHTML = 'Please login'; + } +} +``` + +**Note:** The above code can be triggered from anywhere on the domain (i.e. a subscription form). + +**lockr AIM Example** + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'lockrAIMId', + params: { + email: 'test@example.com', + appID: 'e84afc5f-4adf-4144-949f-1de5bd151fcc' + } + }] + } +}); +``` + +_Note_: lockr’s AIM self-service interface empowers publishers with the ability to pass the alternative IDs activated back to the client as local storage or as a first party cookie. Each Identity Provider can be individually set to restrict from client-side delivery and instead be retained as an authentication event within Identity lockr. In this case no data is lost, but instead maintained for automated or manual sharing to any Data Endpoint. + +**Troubleshooting and Error handling:** + +1. Navigate to the domain where Prebid.js Library is integrated. +2. Go to the 'Network' tab of your Developer Tools. Search for “prebid.js” +3. In the application tab, you can confirm any activated Identity Provider (if client-side storage is turned on in AIM’s Identity Provider settings). +4. Debugging: + Enable the debug flag to true in the setConfig call: + +```javascript +pbjs.setConfig({ + debug: true, + userSync: { + userIds: [{ + name: 'lockrAIMId', + params: { + email: 'test@example.com', + appID: 'e84afc5f-4adf-4144-949f-1de5bd151fcc' + } + }] + } +}); +``` diff --git a/dev-docs/modules/userid-submodules/parrable.md b/dev-docs/modules/userid-submodules/parrable.md index f022af4c33..d8aa3be3ea 100644 --- a/dev-docs/modules/userid-submodules/parrable.md +++ b/dev-docs/modules/userid-submodules/parrable.md @@ -2,6 +2,7 @@ layout: userid title: Parrable ID description: Parrable ID User ID sub-module +pbjs_version_notes: removed in 9.0 useridmodule: parrableIdSystem --- diff --git a/dev-docs/modules/userid-submodules/tncIdSystem.md b/dev-docs/modules/userid-submodules/tncIdSystem.md new file mode 100644 index 0000000000..6b82fd0250 --- /dev/null +++ b/dev-docs/modules/userid-submodules/tncIdSystem.md @@ -0,0 +1,36 @@ +# TNCID UserID Module + +## Prebid Configuration + +First, make sure to add the TNCID submodule to your Prebid.js package with: + +```bash +gulp build --modules=tncIdSystem,userId +``` + +## TNCIDIdSystem module Configuration + +Disclosure: This module loads external script unreviewed by the prebid.js community + +You can configure this submodule in your `userSync.userIds[]` configuration: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'tncId', + params: { + url: 'https://js.tncid.app/remote.min.js' //Optional + } + }], + syncDelay: 5000 + } +}); +``` + +## Configuration Params + +| Param Name | Required | Type | Description | +| --- | --- | --- | --- | +| name | Required | String | ID value for the TNCID module: `"tncId"` | +| params.url | Optional | String | Provide TNC fallback script URL, this script is loaded if there is no TNC script on page | diff --git a/dev-docs/modules/userid-submodules/unified2.md b/dev-docs/modules/userid-submodules/unified2.md index f2d2f23549..c61b98bec0 100644 --- a/dev-docs/modules/userid-submodules/unified2.md +++ b/dev-docs/modules/userid-submodules/unified2.md @@ -55,6 +55,12 @@ To use the cookie-based server-only mode, set a cookie named `__uid2_advertising `__uid2_advertising_token=eb33b0cb-8d35-4722-b9c0-1a31d4064888` +For a server-side integration, you can create a smaller Prebid.js build by disabling client-side integration functionality. To do this, pass the `--disable UID2_CSTG` flag: + +```bash + gulp build --modules=uid2IdSystem --disable UID2_CSTG +``` + ## Unified ID 2.0 Configuration The following parameters apply only to the Unified ID 2.0 module integration. diff --git a/dev-docs/modules/userid-submodules/yandex.md b/dev-docs/modules/userid-submodules/yandex.md new file mode 100644 index 0000000000..1b0f8bbbbc --- /dev/null +++ b/dev-docs/modules/userid-submodules/yandex.md @@ -0,0 +1,37 @@ +--- +layout: userid +title: Yandex ID +description: Yandex User ID sub-module +useridmodule: yandexIdSystem +--- + +Yandex ID module is designed to improve the personalization of ads for publishers' users. This documentation provides information about the Yandex User ID module, and instructions to install it. + +## Step 1. Add Yandex ID to Prebid.js package + +Add the module to your Prebid.js package: + +{: .alert.alert-info :} +gulp build --modules=yandexIdSystem + +## Step 2. Enable Yandex ID + +Include the following call to `setConfig` in your Prebid.js code: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [ + { + name: 'yandex', + bidders: ['yandex'], + storage: { + type: 'cookie', + name: '_ym_uid', + expires: 365, + }, + }, + ], + }, +}); +``` diff --git a/dev-docs/pb9-notes.md b/dev-docs/pb9-notes.md new file mode 100644 index 0000000000..39bf23619b --- /dev/null +++ b/dev-docs/pb9-notes.md @@ -0,0 +1,124 @@ +--- +layout: page_v2 +title: Prebid.js 9.0 Release Notes & Publisher API Changes +description: Description of the breaking changes included for Prebid.js 9.0 +sidebarType: 1 +--- + +# Prebid.js 9.0 Bidder Interface and Publisher API Changes + +{:.no_toc} + +This document describes the changes included for Prebid.js version 9.0. + +* TOC +{:toc} + +## Removed Modules + +The following modules have been removed from Prebid.js as part of the 9.0 release. Publishers building with one of them will need to point to its replacement or remove the module from their build. + +{: .table .table-bordered .table-striped } +| Module | Replacement | +|:-----------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Brightcom | OMS Bid Adapter | +| Sovrn Analytics | | +| Empty FPD module file | | +| Adomik | | +| Britepool | | +| SpotX | | +| pirId | | +| Engage BDR | | +| MyTarget | | +| Parrable | | +| Blue BillyWig | | +| Idward RTD | Anonymized RTD | +| Minutemedia Plus | | +| eplanning Analytics | | +| mars media Analytics | | +| sigmoid Analytics | | +| sonobi Analytics | | +| staq Analytics | | +| RichAudience | Update: added to 9.1.0 | +| adbookpsp | | +| yahooSSP | yahooAds | +| GDPR Consent module | TCF Consent module | +| GDPR Enforcement module | TCF Control module | +| Bizzclick | Blasto | +| Utiq | UtiqId | +| Prebid Manager | AsterioBid Prebid Manager | +| Ras | RingierAxelSpringer | +| Fledge for GPT | PAAPI for GPT | +| DFP Video | Split into DFP Video and DFP AdPod | + +## Consent changes + +The USP string was removed from the consent metadata; also USP module is no longer in the recommended build. The GDPR modules were renamed to TCF modules, to reflect their adherence to a technical specification and not imply adherence to the underlying legislation and case law. Support for GPP 1.0 was removed from the GPP module. Of particular importance, "vendorless" modules such as the sharedid module no longer rely on vendor consent in the TCF object, but instead rely on publisher purpose consent. Publishers should check their __tcfapi consent data object to confirm publisher purpose consents are requested by their CMP. + +## Rendering + +This [creative](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html) is now the preferred creative choice for Google Ad Manager users for web. It is created as part of the build process. This [legacy implementation](https://github.com/prebid/Prebid.js/blob/8.52.0/integrationExamples/gpt/creative_rendering.html) was deleted and examples using the Prebid Universal Creative (PUC) in documentation are being ported over to [the new guidance](https://docs.prebid.org/adops/js-dynamic-creative.html). Publishers also using Prebid Mobile SDK creative for apps may wish to remain on the PUC for ease of operations. + +The legacy method of trafficking native creatives has also had a deprecation warning issued. Publishers should prefer the Ortb2 implementation as sendTargetingKeys for native, hb_native_ASSET, will no longer be supported in a coming version. + +## Video ORTB2 Objects + +The Ortb2 core adapter utility no longer infers placement from context. Context = 'instream' now only refers to the technical integration method the publisher is using to interact with the player and is not relevant to the ortb2 bid requests. Adapters should not infer placement nor plcmt is instream from this value. It is however reasonable to infer plcmt = 4 from context = outstream. Adapters are not permitted to only support placement and not plcmt; they are welcome to pass both. Publishers are advised to set plcmt on their video ad units explicitly to avoid downstream inferences causing buyer inventory quality enforcements. + +## PAAPI + +Any module described as Fledge is now PAAPI. PAAPI Configuration is simplified and publishers experimenting with Fledge in 8.x should refer to the module documentation for updates. + +Publishers wishing to support PAAPI should install the PAAPI module and select the submodule appropriate for their top level seller (TLS). Both gpt.js and publisher designated top level decision logic have submodules. Ad servers wishing to add support for top level selling in Prebid.js may choose to issue instructions compatible with the newly released publisher designated TLS or submit their own submodule. + +Bid adapters can now return either complete auction config or an `igb` object according to the Ortb community extension for PAAPI. Publishers wishing to be or to designate a component seller to handle the `igb` objects returned by some bid modules should configure PAAPI with, for example + +`pbjs.setConfig({ + paapi: { + enabled: true, + componentSeller: { + auctionConfig: { + decisionLogicURL: 'publisher.example' + // ... + } + } + } + })` + +PAAPI for GPT now supports custom slot configuration. Also, the autoConfig option has been removed and replaced with configWithTargeting, defaulting to true, which sets GPT targeting and submits auction configs together. It differs in the previous autoconfig in that it no longer relies on gpt being available at the time of requestBids, only at the time of setTargeting. + +Publishers should be aware this behavior may prohibit submission of auction configuration to GPT sooner than the Prebid.js auction has completed, and will likely prefer to use `setPAAPIConfigForGPT`. We're hoping a futute gpt.js release will enable submission of configuration including unresolved promises earlier than the completion of the Prebid auction, by providing an `allConfigsSubmitted` type utility. Prebid support for other top level sellers will include this functionality in the near future. + +## Miscellaneous configuration changes (publishers) + +Pbadslot has had a deprecation warning issued, it is redundant specifying with imp.ext.gpid. Publishers setting pbadslot explicitly will see a warning. In the future, the pre-auction module will not populate it and setting it in configuration will have no effect. + +We stopped supporting top level site, app, and device configuration directly, eg `setConfig({device: X})`. Please prefer the ortb2 object in configuration (or in requestBids), eg `setConfig({ortb2: {device: X}})` + +s2s tmax and userId module default timings were set to more reasonable defaults. + +The Topics module now requires publishers to choose which external topics gathering frames will be injected. Documentation lists many options. + +We now require node.js 20+ to build. Babel was upgraded; the build target was modernized. The test suite raised its browser version targets. + +transformBidParams was removed from the build so publishers would not need an adapter to use a bidder in prebid server. Appnexus adapter added the anPspParamsConverter module as a temporary measure to solve for their adapter. + +Private functions are no longer available to npm consumers. + +Some adapters changed their configuration, including JW Player RTD, Openweb, Yahoo Ads, Improve Digital and 33Across Id module. See [https://github.com/prebid/Prebid.js/issues/11608](https://github.com/prebid/Prebid.js/issues/11608). + +## Miscellaneous deprecation notices (module maintainers) + +Bidders should prefer the eids object in the bidrequest. The redundant userid object in bid requests will be removed in a future version. + +Userid submodules may no longer be able to access set methods in storage manager in the future. The parent userid module is capable of setting the value returned by the submodule according to publisher configuration. + +A variety of performance degrading functions may become unavailable to adapters. Some already have, including .innerText and .outerText. Bidders should generally rely on the request object to interrogate navigator, and if things are missing from the request object, we invite PRs on it as preferred over redundant module implementations. + +Some modules not using our methods, or using excessive payloads, for storage or network transmission were modified. + +Bidders may no longer import the events system. + +getConfig is no longer allowed to gather consent, as it may be stale; use the consent object. + +Bidder companion scripts are now completely removed; only other module types may source js. diff --git a/dev-docs/publisher-api-reference/aliasBidder.md b/dev-docs/publisher-api-reference/aliasBidder.md index fd0a7248ef..24d7e6aef3 100644 --- a/dev-docs/publisher-api-reference/aliasBidder.md +++ b/dev-docs/publisher-api-reference/aliasBidder.md @@ -27,7 +27,7 @@ The options object supports these parameters: {: .table .table-bordered .table-striped } | Option Parameter | Type | Description | |------------|---------|---------------------------------| -| gvlid | integer | IAB Global Vendor List ID for this alias for use with the [GDPR Enforcement module](/dev-docs/modules/gdprEnforcement.html). | +| gvlid | integer | IAB Global Vendor List ID for this alias for use with the [TCF control module](/dev-docs/modules/tcfControl.html). | {: .alert.alert-info :} Creating an alias for a Prebid Server adapter is done differently. See 'extPrebid' diff --git a/dev-docs/publisher-api-reference/getPAAPIBids.md b/dev-docs/publisher-api-reference/getPAAPIBids.md new file mode 100644 index 0000000000..aa6cdb5365 --- /dev/null +++ b/dev-docs/publisher-api-reference/getPAAPIBids.md @@ -0,0 +1,93 @@ +--- +layout: api_prebidjs +title: pbjs.getPAAPIBids(options) +description: getPAAPIBids API +sidebarType: 1 +--- + +Returns a promise of the latest PAAPI bid for each ad unit, optionally filtered by auction or ad unit. + +**Kind**: static method of pbjs API. Only available when the [topLevelPaapi module](/dev-docs/modules/topLevelPaapi.html) is installed. + +**Returns**: `Promise` - Promise to a map from ad unit code to the PAAPI winner for that ad unit, if available. + +**Parameters**: + +{: .table .table-bordered .table-striped } +| Param | Scope | Type | Description | +| --- | --- | --- | --- | +| options | Optional | `Object` | | +| options.adUnitCode | Optional | `String` | Ad unit filter; if provided, only return the PAAPI winner for this ad unit | +| options.auctionId | Optional | `String` | Auction filter; if provided, only return PAAPI winners for this auction | + +**Result**: + +The return value is a map where each value is either `null` (when there is no PAAPI winner), or an object with this format: + +{: .table .table-bordered .table-stripped :} +| Param | Type | Description | +| --- | --- | --- | +| adId | String | Ad ID. can be used with [renderAd](/dev-docs/publisher-api-reference/renderAd.html) | +| auctionId | String | Auction ID tied to this bid | +| adUnitCode | String | Ad unit code tied to this bid | +| source | String | Always `"paapi"` | +| urn | String | Creative URN (only set if `paapi.topLevelSeller.auctionConfig.resolveToConfig` is `false`| +| frameConfig | Object | Creative fenced frame config (only set if `paapi.topLevelSeller.auctionConfig.resolveToConfig` is `true`| +| auctionConfig | Object | The auction config object that was passed to `navigator.runAdAuction` and generated this bid | +| width | Number | Creative width | +| height | Number | Creative height | + +**Example**: + +```js +pbjs.getPAAPIBids({adUnitCode: 'test-slot'}) +``` + +```json +{ + "test-slot": { + "source": "paapi", + "adId": "paapi:/0c00694d-958d-4250-98b3-5fe15cb019ab/:/test-slot", + "width": 300, + "height": 250, + "adUnitCode": "test-slot", + "auctionId": "0c00694d-958d-4250-98b3-5fe15cb019ab", + "urn": "urn:uuid:81005931-5726-4fb4-8bec-9ae74248e1ef", + "auctionConfig": { + "auctionSignals": { + "prebid": { + "bidfloor": 1, + "bidfloorcur": "USD" + } + }, + "requestedSize": { + "width": 300, + "height": 250 + }, + "componentAuctions": [ + { + "requestedSize": { + "width": "300px", + "height": "250px" + }, + "seller": "https://ads.optable.co", + "decisionLogicURL": "https://ads.optable.co/ca/paapi/v1/ssp/decision-logic.js?origin=daa30ba1-5613-4a2c-b7f0-34e2c033202a", + "interestGroupBuyers": [ + "https://ads.optable.co" + ], + "sellerCurrency": "USD", + "perBuyerCurrencies": { + "https://ads.optable.co": "USD" + }, + "perBuyerMultiBidLimits": { + "https://ads.optable.co": 100 + } + } + ], + "resolveToConfig": false, + "seller": "https://publisher.com", + "decisionLogicURL": "https://publisher.com/decisionLogic.js" + } + } +} +``` diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 73ad3d0643..0ee1994b45 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -48,7 +48,7 @@ Core config: Module config: other options to `setConfig()` are available if the relevant module is included in the Prebid.js build. * [Currency module](/dev-docs/modules/currency.html) -* [Consent Management](/dev-docs/modules/consentManagement.html#page-integration) +* [Consent Management](/dev-docs/modules/consentManagementTcf.html#page-integration) * [User ID module](/dev-docs/modules/userId.html#configuration) * [Adpod](/dev-docs/modules/adpod.html) * [IAB Category Translation](/dev-docs/modules/categoryTranslation.html) diff --git a/dev-docs/release-notes.md b/dev-docs/release-notes.md index e85e26c54f..90b21a65c9 100644 --- a/dev-docs/release-notes.md +++ b/dev-docs/release-notes.md @@ -15,6 +15,7 @@ This page has links to release notes for each of the projects associated with Pr ## Prebid.js + [Release notes on GitHub](https://github.com/prebid/Prebid.js/releases) ++ [Prebid.js 9 Release Notes](/dev-docs/pb9-notes.html) + [Prebid.js 8 Release Notes](/dev-docs/pb8-notes.html) + [Prebid.js 7 Release Notes](/dev-docs/pb7-notes.html) + [Prebid.js 6 Blog Post](https://prebid.org/blog/prebid-6-0-release/) diff --git a/dev-docs/show-long-form-video-with-gam.md b/dev-docs/show-long-form-video-with-gam.md index 7f9d4ef178..fd18bc87b7 100644 --- a/dev-docs/show-long-form-video-with-gam.md +++ b/dev-docs/show-long-form-video-with-gam.md @@ -175,7 +175,7 @@ For instructions on setting custom price buckets, view the [Custom Price Granula ### 5. Send request for bids and build video URL -The `dfpAdServerVideo` module provides a method, `buildAdpodVideoUrl`, that combines publisher-provided parameters with Prebid.js targeting key values to build a GAM video ad tag URL that can be used by a video player. +The `dfpAdpod` module provides a method, `buildAdpodVideoUrl`, that combines publisher-provided parameters with Prebid.js targeting key values to build a GAM video ad tag URL that can be used by a video player. In the example below the callback in the `bidsBackHandler` returns the video ad tag needed by the video player. @@ -196,7 +196,7 @@ pbjs.que.push(function(){ pbjs.requestBids({ bidsBackHandler: function(bids) { - pbjs.adServers.dfp. buildAdpodVideoUrl({ + pbjs.adServers.dfp.buildAdpodVideoUrl({ codes: ['sample-code'], params: { iu: '/123456/testing/prebid.org/adunit1', 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/faq/prebid-server-faq.md b/faq/prebid-server-faq.md index 26d7946c36..5f6ad81c19 100644 --- a/faq/prebid-server-faq.md +++ b/faq/prebid-server-faq.md @@ -248,6 +248,10 @@ In the long run, if you'd prefer to change the filenames too, that's ok - but ou 1. Submit a PR that changes the filenames and makes the old name a hard-coded alias. 2. Keep both bidder documentation files. +## May I build a server that calls Prebid Server? + +Sure. The main endpoint you're going to utilize is the [auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html). Basically, it's just OpenRTB 2.6, but with quite a few Prebid-specific extensions. See the [auction request example](/prebid-server/endpoints/openrtb2/auction-request-example.html). + ## Should Prebid bidders be in ads.txt? Publishers should be careful to list all their bidding partners in their ads.txt file. Bidders without an entry in ads.txt may be diff --git a/features/ac-quebec.md b/features/ac-quebec.md index 8adeb46692..f8555e3530 100644 --- a/features/ac-quebec.md +++ b/features/ac-quebec.md @@ -28,8 +28,8 @@ Given this context, Prebid has identified publisher concern that many will not b References: -- [TCF Canada Infographic on Quebec Privacy Law](https://iabcanada.com/content/uploads/2022/04/IAB-Canada_Quebec-Privacy-Law-Inforgraphic.pdf) - [IAB Canada TCF Canada policies](https://iabcanada.com/tcf-canada/for-publishers/) +- [IAB Canada Quebec Privacy Legislation (Law 25) Resource Centre](https://iabcanada.com/iab-standards-and-guidelines/law25-resource-centre/) - [IABTL's GPP Canada section spec](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Canada/GPPExtension%3A%20IAB%20Canada%20TCF.md) ## TCF Canada and GPP Support in Prebid.js @@ -101,9 +101,6 @@ bidders are in such alignment. An alternate solution would utilize the Prebid Server version of the [Activity Control system](/prebid-server/features/pbs-activitycontrols.html). -{: .alert.alert-info :} -Only the Java version of Prebid Server currently supports targeting Activity Controls to geographic regions. - Here's an example account configuration that utilizes the user's geographic region to determine whether to allow or deny the named activities. Publishers will need to confirm the details with their Prebid Server host company. diff --git a/features/firstPartyData.md b/features/firstPartyData.md index 2d8f0abc3d..899956f4fd 100644 --- a/features/firstPartyData.md +++ b/features/firstPartyData.md @@ -52,7 +52,7 @@ If not specified through any of the methods above, Prebid.js attempts to automat {: .table .table-bordered .table-striped } | Field | Value | Notes | |-----------+--------------| -| `site.page` | Site URL, from `pageUrl` falling back to `location.href` | [`pageUrl` config](/dev-docs/publisher-api-reference/setConfig.md#setConfig-Page-URL) | +| `site.page` | Site URL, from `pageUrl` falling back to `location.href` | [`pageUrl` config](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Page-URL) | | `site.ref` | `document.referrer` | | | `site.domain` | Domain portion of `site.page` | | | `site.keywords` | Contents of ``, if such a tag is present on the page | | @@ -65,7 +65,7 @@ If not specified through any of the methods above, Prebid.js attempts to automat | `device.sua` | User agent client hints | [uaHints config](#uaHints) | | `device.ext.webdriver`| `true` if the browser declares to be an automation tool | [Navigator.webdriver](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/webdriver) | | `device.ext.cdep`| Google Chrome cookie deprecation label | [Chrome-facilitated testing](https://developers.google.com/privacy-sandbox/setup/web/chrome-facilitated-testing) | -| `regs.coppa` | COPPA Regulation flag | [COPPA config](/dev-docs/publisher-api-reference/setConfig.md#setConfig-coppa) +| `regs.coppa` | COPPA Regulation flag | [COPPA config](/dev-docs/publisher-api-reference/setConfig.html#setConfig-coppa) | `regs.ext.gpc` | Global Privacy Control setting | [Navigator.globalPrivacyControl](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/globalPrivacyControl) | Publisher-provided first party data always takes precedence for all fields; you can also set `null` to disable them. For example, the following discards the automatically collected `device.keywords`: @@ -188,7 +188,7 @@ pbjs.setConfig({ {: .alert.alert-warning :} Note that supplying first party **user** data may require special -consent in certain regions. By default, Prebid's [gdprEnforcement](/dev-docs/modules/gdprEnforcement.html) module does **not** police the passing +consent in certain regions. By default, Prebid's [tcfControl](/dev-docs/modules/tcfControl.html) module does **not** police the passing of user data, but can optionally do so if the `personalizedAds` rule is enabled. {: .alert.alert-warning :} diff --git a/features/mspa-usnat.md b/features/mspa-usnat.md index f488fd3a06..635783088d 100644 --- a/features/mspa-usnat.md +++ b/features/mspa-usnat.md @@ -1,11 +1,11 @@ --- layout: page_v2 -title: Prebid MSPA Support -description: Prebid MSPA Support +title: Prebid US Compliance Support +description: Prebid US Compliance Support sidebarType: 7 --- -# Prebid Multi-State Privacy Agreement Support +# Prebid US Compliance Support {: .no_toc} - TOC @@ -17,24 +17,27 @@ sidebarType: 7 Starting July 1st 2023, several US states started enforcing new privacy regulations. -The IAB released the "Multi-State Privacy Agreement" (MSPA) as its proposal for how the advertising ecosystem can support these and future US State regulations. References: +As a result, the IAB released the "Multi-State Privacy Agreement" (MSPA), the Global Privacy Protocol (GPP), and several "sections" of the GPP dedicated to these US states. References: - [IAB's MSPA](https://www.iab.com/news/multi-state-privacy-agreement-mspa/) - IAB Guidance on the [MSPA Decision Tree](https://www.iab.com/wp-content/uploads/2022/12/IAB_MSPA_Decision_Tree.pdf) - IAB's [US National technical protocols](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/tree/main/Sections) +Prebid refers to GPP Sections 7-12 as "US Compliance", which is distinct from the original [US Privacy](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/US%20Privacy%20String.md) approach which has been deprecated. + ### Glossary 1. **Global Privacy Platform (GPP)** - A technical IAB framework that defines a container format for communicating multiple privacy protocols. e.g. GPP can contain existing Transparency and Consent Framework (TCF) strings, various US privacy string formats, and other future implementations. 1. **GPP Section ID (SID)** - the GPP container may contain multiple encoded privacy protocol strings. Each protocol gets its own SID in the overall GPP container. e.g. TCF-EU is assigned SID 2. -1. **Multi-State Privacy Agreement (MSPA)** - the IAB's contractual framework for publishers to manage various US state privacy laws. +1. **Multi-State Privacy Agreement (MSPA)** - the IAB's contractual framework for publishers to manage various US state privacy laws. Note that there are high profile companies in the industry that have not signed the MSPA, but are still able to process the IAB's technical protocol to consider user preferences. 1. **MSPA Covered Transaction** - Whether a given ad auction falls legally under the MSPA's privacy requirements. For MSPA-covered 'transactions' (ad auctions), publishers must declare themselves in one of two modes: "Service Provider Mode" or "Opt-Out Mode". 1. **MSPA Service Provider Mode** - "Service Provider Mode is for First Parties who do not Sell or Share Personal Information, and do not Process Personal Information for Targeted Advertising". This means that personal information is never sent to downstream entities. 1. **MSPA Opt-Out Mode** - For First Parties that may engage in targeted advertising activities or disclose personal information for such purposes. This means that user consent is gathered before privacy-sensitive data is sent to downstream entities. 1. **US National Privacy Technical Specification (USNat)** - the IAB's technical framework for encoding MSPA publisher policies and user consents. Stored in the GPP container as SID 7. 1. **US State Privacy Technical Specifications** - the IAB has defined technical frameworks for 5 states based on their interpretation of state privacy laws. These protocols are similar to the US National protocol and are stored in the GPP container as SIDs 8 through 12. +1. **US Compliance** - the term Prebid uses to encompass both US National Privacy Technical Specification and the US State Privacy Technical Specifications. 1. **Global Privacy Control (GPC)** - a browser-level control for end users. Some US states have referred to a global control so that users don't have to state their preferences on each website they visit. The USNat protocol strings also contain the GPC flag. -1. **US Privacy** - this is the IAB's original version of a US privacy protocol, meant to address CCPA only. It's active during a transition period until September 30, 2023. +1. **US Privacy** - this is the IAB's original, now deprecated, version of a US privacy protocol, meant to address older California laws. 1. **Prebid Activity Controls** - Prebid.js and Prebid Server have identified a set of behaviors for activities that may be in scope for privacy concerns such as transmitting user IDs. These activities may be allowed or suppressed with flexible conditions and exceptions as defined by the publisher. - [Prebid.js Activity Controls](/dev-docs/activity-controls.html) were released with PBJS 7.52 - [Prebid Server Activity Controls](/prebid-server/features/pbs-activitycontrols.html) were released with PBS-Java 1.118 @@ -50,29 +53,29 @@ Prebid's assumptions about the MSPA and the US National Privacy specification: 1. For requests that are in-scope for SIDs 7 through 12 that are not "covered" by MSPA, Prebid treats them as being in "Opt-Out Mode". This implies that CMPs have prompted users for consent and encoded the results in the relevant section of the GPP container. 1. Prebid never changes the GPP string. This means that all downstream vendors will see whatever the CMP set. 1. Prebid has implemented a default way to interpret the US National string (SID 7) in the context of each Prebid Activity. -1. US state privacy rules do not mandate the cancellation of contextual advertising, but rather are focused on protecting user privacy. Therefore, Prebid's MSPA module may anonymize different aspects of a header bidding auction, but will never outright cancel an auction. +1. US state privacy rules do not mandate the cancellation of contextual advertising, but rather are focused on protecting user privacy. Therefore, Prebid's US compliance modules may anonymize different aspects of a header bidding auction, but will never outright cancel an auction. 1. There are differences in the US state-level protocols and the US National protocol as defined by the IAB. (e.g. child consent for targeted advertising is somewhat different across SIDs 7 through 12.) 1. Rather than implementing several very similar modules and forcing publishers to include separate modules for each US state, Prebid handles state differences through a normalization process. The differences for each state are mapped onto the US National (SID 7) string, and that string is interpreted for which activities are allowed or suppressed. As with the rest of Prebid’s approach, this is a default intended to ease publishers’ ability to comply with the state laws, but publishers should make their own determinations about state law obligations and consult legal counsel to ensure that they feel comfortable that this approach allows them to meet their legal obligations. 1. Publishers that do not agree with Prebid's default behavior may override the behavior. This includes the interpretation of the USNat string as well as the normalization of state protocols. 1. The Global Privacy Control (GPC) flag is interpreted as a strong user signal that ad requests should be anonymized. 1. There's no need to support a data-deletion activity for MSPA. -1. Prebid doesn't need to explicitly support mapping US National Privacy SID 6 (legacy US Privacy) for anonymization activities. This is covered by a feature on Prebid Server where SID 6 is pulled out into regs.us_privacy and is covered by documentation in Prebid.js. +1. Prebid doesn't need to explicitly support mapping GPP SID 6 (legacy US Privacy) for anonymization activities. This is covered by a feature on Prebid Server where SID 6 is pulled out into regs.us_privacy and is covered by documentation in Prebid.js. -## USNat Support in Prebid Products +## US Compliance Support in Prebid Products ### Prebid.js Here's a summary of the privacy features in Prebid.js that publishers may use to align with the guidance of their legal counsel: {: .table .table-bordered .table-striped } -| Prebid.js Version | USNat-Related Features | Notes | +| Prebid.js Version | US Compliance-Related Features | Notes | | ----------------- | ---------------------- | ----- | | before 7.30 | None | If you operate in the US, you should consider upgrading. | -| 7.30-7.51 | **GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) reads the GPP string from a compliant CMP and passes to compliant bid adapters. Not many bid adapters supported GPP in earlier versions. | -| 7.52-8.1 | GPP module
**Activity Controls** | [Activity Controls](/dev-docs/activity-controls.html) provide the ability for publishers to allow or restrict certain privacy-sensitive activities for particular bidders and modules. See examples in that document for supporting CCPA directly. | -| 8.2-8.x | GPP module
Activity Controls
**USNat module** | The [USNat module](/dev-docs/modules/gppControl_usnat.html) processes SID 7. | -| After 8.x | GPP module
Activity Controls
USNat module
**US State module** | The US State module processes SIDs 8 through 12 after normalizing protocol differences. | -| After 8.10 | **GPP Module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) now understands GPP 1.1 which makes it incompatible with GPP 1.0. Publishers **MUST** upgrade for continued GPP support. | +| 7.30-7.51 | **Consent Mgmt GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) reads the GPP string from a compliant CMP and passes to compliant bid adapters. Not many bid adapters supported GPP in earlier versions. | +| 7.52-8.1 | Consent Mgmt GPP module
**Activity Controls** | [Activity Controls](/dev-docs/activity-controls.html) provide the ability for publishers to allow or restrict certain privacy-sensitive activities for particular bidders and modules. See examples in that document for supporting CCPA directly. | +| 8.2-8.9 | Consent Mgmt GPP module
Activity Controls
**GPP USNat module** | The [GPP USNat module](/dev-docs/modules/gppControl_usnat.html) processes SID 7. | +| 8.10+ | Consent Mgmt GPP module
Activity Controls
USNat module
**GPP US State module** | The [GPP US State module](/dev-docs/modules/gppControl_usstates.html) processes SIDs 8 through 12 after normalizing protocol differences. | +| 8.10+ | **Consent Mgmt GPP module** | The [GPP module](/dev-docs/modules/consentManagementGpp.html) now understands GPP 1.1 which makes it incompatible with GPP 1.0. Publishers **MUST** upgrade for continued GPP support. | ### Prebid Server diff --git a/identity/sharedid.md b/identity/sharedid.md index cd25557eac..78c7acc23c 100644 --- a/identity/sharedid.md +++ b/identity/sharedid.md @@ -6,11 +6,10 @@ sidebarType: 9 --- # Prebid SharedID - {: .no_toc} - TOC - {:toc} +{:toc} {: .alert.alert-warning :} As of Prebid.js 5.0, PubCommon ID is no longer supported -- it's been merged into SharedId. Also, SharedId no longer syncs to sharedid.org like it did in Prebid.js 4.x. @@ -157,7 +156,7 @@ You can find available configuration options for the SharedID module [here](http There are several privacy scenarios in which a user ID is not created or read: 1. The User ID module suppresses all cookie reading and setting activity - when the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) is in place and there's no consent for Purpose 1. + when the [TCF Control Module](/dev-docs/modules/tcfControl.html) is in place and there's no consent for Purpose 1. 2. The User ID module infrastructure supports a first-party opt-out, by setting the `_pbjs_id_optout` cookie or local storage to any value. No other cookies will be set if this one is set. 3. The SharedId module will suppress the ID when the COPPA flag is set. @@ -217,7 +216,7 @@ Below are the available configuration options for the PubCID script. | create | boolean | If true, then an id is created automatically by the script if it's missing. Default is true. If your server has a component that generates the id instead, then this should be set to false | | `true` | | expInterval | decimal | Expiration interval in minutes. Default is 525600, or 1 year | | `525600` | | extend | boolean | If true, the the expiration time is automatically extended whenever the script is executed even if the id exists already. Default is true. If false, then the id expires from the time it was initially created. | For publisher server support only. If true, the publisher's server will create the (pubcid) cookie. Default is true. | `true` | -| pixelUrl | string (optional) | For publisher server support only. Where to call out to for a server cookie. | | `/wp-json/pubcid/v1/extend/` +| pixelUrl | string (optional) | For publisher server support only. Where to call out to for a server cookie. | | `/wp-json/pubcid/v1/extend/` | | type | string | Type of storage. It's possible to specify one of the following: 'html5', 'cookie'. Default is 'html5' priority, aka local storage, and fall back to cookie if local storage is unavailable. | If true, the expiration time of the stored IDs will be refreshed during each page load. Default is false. | `cookie` | #### Example Configurations diff --git a/overview/all-videos.md b/overview/all-videos.md index bf43d4652a..0f1aace48c 100644 --- a/overview/all-videos.md +++ b/overview/all-videos.md @@ -21,3 +21,5 @@ Multimedia overviews covering various aspect of Header Bidding and Prebid. 1. [Prebid.js and The Video Ad Format](/prebid-video/video-overview-video.html) - An introduction to how video works with Prebid.js. 1. [Prebid and Ad Operations](/adops/adops-overview-video.html) - An overview of the process of planning a Prebid integration for ad operations. 1. [Floors in Prebid.js and Prebid Server](/dev-docs/floors-video-overview.html) - An overview of the Prebid.js and Prebid Server price floor features. +1. [Prebid Mobile Impression Flow](/prebid-mobile/prebid-mobile-video-flow.html) - A step-by-step walkthrough of a typical Prebid Mobile auction. +1. [Prebid Mobile Planning Guide](/prebid-mobile/prebid-mobile-video-planning.html) - A video guide to planning your first Prebid Mobile integration. diff --git a/overview/ga-analytics.md b/overview/ga-analytics.md deleted file mode 100644 index 1abd33862f..0000000000 --- a/overview/ga-analytics.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -layout: page_v2 -title: Prebid Analytics with GA -description: Prebid.js Analytics with GA for Header Bidding -pid: 10 -top_nav_section: overview -nav_section: analytics -sidebarType: 1 ---- - - - -# Prebid Analytics with GA - -{:.no_toc} - -> Are my header bidding demand partners generating more revenue for me? If not, is it because of latency or is it due to low bid CPM? How about discrepancies? - -- TOC -{:toc} - -## Prebid Analytics helps you better manage your header bidding partners - -It includes: - -- Bidder bid/win price analysis by geo, domain, with price range distribution. -- Bid latency by bidder, geo, and domain. -- Seamless integration with your Google Analytics account and scheduled reports delivered to your mailbox. - -
- -## Example reports by Prebid Analytics - -The day starts from making sure the bidders are not generating less revenue: - -![Blocking Ad Calls 1]({{ site.baseurl }}/assets/images/overview/analytics/revenue-by-date.png) - -Something is not right here - total revenue from yesterday dropped quite a bit. This could be caused by certain bidders were down or experienced technical issues. Let's take a look at the bidder timeout rate: - -![Blocking Ad Calls 1]({{ site.baseurl }}/assets/images/overview/analytics/timeout-by-date.png) - -Bidder timeout seems okay. The problem might then be caused by bidders' lower bid rate: - -![Blocking Ad Calls 1]({{ site.baseurl }}/assets/images/overview/analytics/bidrate-by-date.png) - -Here we go. Bidder 1 and 4 bid much less than usual. You may want to drill down even further - Prebid.js Analytics also provides: - -- More metrics such as: bid load time, avg bid CPM, bid rate, avg win CPM, win rate. -- Ability to filter the above metrics further by geo, domain, and OS - -> **Explore an example dashboard here** - -
- -## Histogram analysis of latency and CPM distribution - -To understand exactly how much time per bidder spent, the Analytics Platform allows you to make the below query: - -- For country X, what are bidders' bid load time, for mobile traffic on Android only? - -
- -![Blocking Ad Calls 1]({{ site.baseurl }}/assets/images/overview/analytics/loadtime-histogram.png) - -You might derive: - -- Bidder 1 is really fast, because 1/3 of its bids are in red, which is in the 200 - 300ms response time range. -- Bidder 5 is really slow, as 1/3 of its bids are in 800 - 1000ms. - -
- -Similar query for bidders' bid CPM: - -
- -![Blocking Ad Calls 1]({{ site.baseurl }}/assets/images/overview/analytics/cpm-histogram.png) - -> **Try out the product and explore the demo dashboard here!** This will be the base of your dashboard! - -
- -## How does it work? - -Prebid.js has a seamless integration with Google Analytics and Google Spreadsheet, as well as [several other Analytics providers](/overview/analytics.html). - -1. Prebid.js has a module for Google Analytics. -2. All data are sent as Events to Google Analytics. You can build reports and dashboards there just as you do today with web traffic data. -3. We've also built dashboards and data visualization in Spreadsheet (where all the above diagrams come from). You can copy our demo dashboard and link it to your Google Analytics account in a few minutes! -4. The Spreadsheet dashboard can be scheduled to run every morning (or in other intervals). You can get 7 day revenue lookback, latency/CPM distribution analysis and more every morning! - -### Building the Prebid.js Package with GA - -You can build the Google Analytics module into your Prebid package in two ways: - -1. The "Easy Button" - use the handy web-based [Prebid.js Download](/download.html) tool, and check the Google Analytics adapter box along with the other modules and adapters desired. -2. From the command line - -```bash -gulp build --modules=googleAnalyticsAdapter, OTHER_MODULES, OTHER_ADAPTERS, ... -``` - -### Enabling the GA Adapter in Your Page - -1. First, make sure GA is on your page as directed by Google. Get the 'tracking code' from the GA interface. It will look something like: - - ```htmk - - - - ``` - -2. Enable the Prebid.js GA module: - - ```javascript - pbjs.que.push(function() { - pbjs.enableAnalytics({ - provider: 'ga', - options: { - sampling: 0.1, - cpmDistribution: myBucketFunction - } - }); - }); - - // takes a CPM value and returns a string price bucket - var myBucketFunction = function(cpm) { - return cpm <= 1 ? '<= 1$' : '> 1$'; - } - ``` - -Here are the options available. None of them are required. - -{: .table .table-bordered .table-striped } -| Option | Type | Example | Notes | -|---+---+---+---| -|global | string | ga | Name of the global analytics object. Default is `ga` | -|trackerName | string | "mytracker" | Use another tracker for prebid events. Default is the default tracker. | -|sampling | float | 0.1 | Choose a value from `0` to `1`, where `0` means 0% and `1` means 100% tracked. | -|enableDistribution | boolean | true | Enables additional events that track load time and cpm distribution by creating buckets for load time and cpm. Default is false. | -|cpmDistribution | function | see example | A function that customizes the buckets for cpm distribution. | -|sendFloors | boolean | true | if set, will include floor data in the eventCategory field and include ad unit code in eventAction field. Defaults to false. | - -## Further Reading - -- [Analytics for Prebid](/overview/analytics.html) (Overview and list of analytics providers) -- [Integrate with the Prebid Analytics API](/dev-docs/integrate-with-the-prebid-analytics-api.html) (For developers) diff --git a/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md b/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md index c667c79871..59bb7df5b8 100644 --- a/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md +++ b/prebid-mobile/modules/rendering/ios-sdk-integration-gam.md @@ -6,7 +6,6 @@ sidebarType: 2 --- # GAM with Prebid Rendering - {:.no_toc} The integration of Prebid Rendering API with Google Ad Manager (GAM) assumes that the publisher has an account on GAM and has already integrated the Google Mobile Ads SDK (GMA SDK) into the app project. @@ -35,7 +34,7 @@ If you do not have GMA SDK in the app yet, refer to the [Google Integration Docu Prebid SDK provides rendering integration into GAM setup thru [app events](https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner#app_events) mechanism. To integrate Prebid Event Handlers into your app, add the following line to your Podfile: ```pod -pod 'PrebidMobileAdMobAdapters' +pod 'PrebidMobileGAMEventHandlers' ``` ## Event Handlers Initialization @@ -200,7 +199,6 @@ Call the method `loadAd()` which will make a bid request to Prebid Server. Wait for the Prebid Server to return an ad and show it to the user in any suitable time. - ```swift // MARK: InterstitialRenderingAdUnitDelegate @@ -217,7 +215,7 @@ GAM setup: 1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. 2. Create a new GAM ad unit. -3. Setup the new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. +3. Setup the new [GAM Order](prebid-mobile/modules/rendering/ios-sdk-integration-gam.html) for rendering approach. Integration: @@ -312,7 +310,7 @@ GAM setup: 1. Leave the original order and ad units as is. They are not relevant for the rendering approach but they will serve ads for released applications. 2. Create a new GAM ad unit. -3. Setup the new [GAM Order](rendering-gam-line-item-setup.html) for rendering approach. +3. Setup the new [GAM Order](prebid-mobile/modules/rendering/ios-sdk-integration-gam.html) for rendering approach. Integration: diff --git a/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.md b/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.md index 0c345afff6..4484b2f197 100755 --- a/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.md +++ b/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.md @@ -12,7 +12,7 @@ sidebarType: 2 Prebid Mobile is an open-source library that provides an end-to-end header bidding solution for mobile app publishers. -* TOC +- TOC {:toc} ## Overview @@ -86,9 +86,9 @@ private fun createGAMListener(adView: AdManagerAdView): AdListener { Initialize the `BannerAdUnit` with properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `width` - the width of the ad unit which will be used in the bid request. -* `height` - the height of the ad unit which will be used in the bid request. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `width` - the width of the ad unit which will be used in the bid request. +- `height` - the height of the ad unit which will be used in the bid request. #### Step 2: Configure banner parameters {:.no_toc} @@ -100,10 +100,10 @@ Starting from PrebidMobile `2.1.0` the `BannerBaseAdUnit.Parameters` class is de The `api` property is dedicated to adding values for API Frameworks to a bid response according to the [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec. The supported values for GMA SDK integration are: -* `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal -* `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal -* `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal -* `7` or `Signals.Api.OMID_1` : signals OMSDK support +- `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal +- `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal +- `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal +- `7` or `Signals.Api.OMID_1` : signals OMSDK support #### Step 3: Create an AdManagerAdView {:.no_toc} @@ -203,9 +203,9 @@ private fun createListener(gamView: AdManagerAdView): AdListener { Initialize the `BannerAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `adSize` - the size of the ad unit which will be used in the bid request. -* `adUnitFormats` - `AdUnitFormat.VIDEO` for a video ad +- `configId` - an ID of the Stored Impression on the Prebid Server +- `adSize` - the size of the ad unit which will be used in the bid request. +- `adUnitFormats` - `AdUnitFormat.VIDEO` for a video ad #### Step 2: Configure video parameters {:.no_toc} @@ -222,22 +222,22 @@ Starting from PrebidMobile `2.1.0` the `VideoBaseAdUnit.Parameters` class is dep In the context of a VideoInterstitialAdUnit, rewarded video ads are typically labeled as interstitial. As such, Prebid SDK will default to value 5 if no placement value is supplied. -* `2` or `InBanner` : In-Banner placement exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. -* `3` or `InArticle` : In-Article placement loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. -* `4` or `InFeed` : In-Feed placement is found in content, social, or product feeds. -* `5` or `Slider`, `Floating` or `Interstitial` : Open RTB supports one of three values for option 5 as either Slider, Floating or Interstitial. If an enum value is supplied in placement, bidders will receive value 5 for placement type and assume to be interstitial with the instl flag set to 1. +- `2` or `InBanner` : In-Banner placement exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. +- `3` or `InArticle` : In-Article placement loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. +- `4` or `InFeed` : In-Feed placement is found in content, social, or product feeds. +- `5` or `Slider`, `Floating` or `Interstitial` : Open RTB supports one of three values for option 5 as either Slider, Floating or Interstitial. If an enum value is supplied in placement, bidders will receive value 5 for placement type and assume to be interstitial with the instl flag set to 1. #### api {:.no_toc} The `api` property is dedicated to adding values for API Frameworks to a bid response according to the [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec. The supported values for GMA SDK integration are: -* `1` or `Signals.Api.VPAID_1` : VPAID 1.0 -* `2` or `Signals.Api.VPAID_2` : VPAID 2.0 -* `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal -* `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal -* `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal -* `7` or `Signals.Api.OMID_1` : signals OMSDK support +- `1` or `Signals.Api.VPAID_1` : VPAID 1.0 +- `2` or `Signals.Api.VPAID_2` : VPAID 2.0 +- `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal +- `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal +- `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal +- `7` or `Signals.Api.OMID_1` : signals OMSDK support #### maxBitrate {:.no_toc} @@ -269,26 +269,26 @@ Array of strings representing the supported OpenRTB 2.5 content MIME types (e.g. Array of OpenRTB 2.5 playback methods. If none are specified, any method may be used. Only one method is typically used in practice. It is strongly advised to use only the first element of the array. -* `1` or `Signals.PlaybackMethod.AutoPlaySoundOn` : Initiates on Page Load with Sound On -* `2` or `Signals.PlaybackMethod.AutoPlaySoundOff` : Initiates on Page Load with Sound Off by Default -* `3` or `Signals.PlaybackMethod.ClickToPlay` : Initiates on Click with Sound On -* `4` or `Signals.PlaybackMethod.MouseOver` : Initiates on Mouse-Over with Sound On -* `5` or `Signals.PlaybackMethod.EnterSoundOn` : Initiates on Entering Viewport with Sound On -* `6` or `Signals.PlaybackMethod.EnterSoundOff`: Initiates on Entering Viewport with Sound Off by Default +- `1` or `Signals.PlaybackMethod.AutoPlaySoundOn` : Initiates on Page Load with Sound On +- `2` or `Signals.PlaybackMethod.AutoPlaySoundOff` : Initiates on Page Load with Sound Off by Default +- `3` or `Signals.PlaybackMethod.ClickToPlay` : Initiates on Click with Sound On +- `4` or `Signals.PlaybackMethod.MouseOver` : Initiates on Mouse-Over with Sound On +- `5` or `Signals.PlaybackMethod.EnterSoundOn` : Initiates on Entering Viewport with Sound On +- `6` or `Signals.PlaybackMethod.EnterSoundOff`: Initiates on Entering Viewport with Sound Off by Default #### protocols {:.no_toc} Array or enum of OpenRTB 2.5 supported Protocols. Values can be one of: -* `1` or `Signals.Protocols.VAST_1_0` : VAST 1.0 -* `2` or `Signals.Protocols.VAST_2_0` : VAST 2.0 -* `3` or `Signals.Protocols.VAST_3_0` : VAST 3.0 -* `4` or `Signals.Protocols.VAST_1_0_Wrapper` : VAST 1.0 Wrapper -* `5` or `Signals.Protocols.VAST_2_0_Wrapper` : VAST 2.0 Wrapper -* `6` or `Signals.Protocols.VAST_3_0_Wrapper` : VAST 3.0 Wrapper -* `7` or `Signals.Protocols.VAST_4_0` : VAST 4.0 -* `8` or `Signals.Protocols.VAST_4_0_Wrapper` : VAST 4.0 Wrapper +- `1` or `Signals.Protocols.VAST_1_0` : VAST 1.0 +- `2` or `Signals.Protocols.VAST_2_0` : VAST 2.0 +- `3` or `Signals.Protocols.VAST_3_0` : VAST 3.0 +- `4` or `Signals.Protocols.VAST_1_0_Wrapper` : VAST 1.0 Wrapper +- `5` or `Signals.Protocols.VAST_2_0_Wrapper` : VAST 2.0 Wrapper +- `6` or `Signals.Protocols.VAST_3_0_Wrapper` : VAST 3.0 Wrapper +- `7` or `Signals.Protocols.VAST_4_0` : VAST 4.0 +- `8` or `Signals.Protocols.VAST_4_0_Wrapper` : VAST 4.0 Wrapper #### Step 3: Create an AdManagerAdView {:.no_toc} @@ -346,10 +346,10 @@ adUnit?.fetchDemand(request) { Initialize the `BannerAdUnit` with properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `width` - the width of the ad unit which will be used in the bid request. -* `height` - the height of the ad unit which will be used in the bid request. -* `adUnitFormats` - ad unit formats for the current ad unit. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `width` - the width of the ad unit which will be used in the bid request. +- `height` - the height of the ad unit which will be used in the bid request. +- `adUnitFormats` - ad unit formats for the current ad unit. #### Step 2-5 {:.no_toc} @@ -409,9 +409,9 @@ private fun createListner(): AdManagerInterstitialAdLoadCallback { Initialize the Interstitial Ad Unit with properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's screen. Support in SDK version 1.2+ -* `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's screen. Support in SDK version 1.2+ +- `configId` - an ID of Stored Impression on the Prebid Server +- `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's screen. Support in SDK version 1.2+ +- `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's screen. Support in SDK version 1.2+ > **NOTE:** As of version 1.2+, Prebid SDK has extended the functionality of Interstitial ad monetization by using a smart ad size selection process to monetize sizes smaller than full screen ads. App developers can specify a minimum width and minimum height percentage an ad can occupy of a devices screen, with Prebid Server (PBS) deriving a limited set of ad sizes (max 10) as eligible for the auction. > @@ -516,8 +516,8 @@ private fun createAdListener(): AdManagerInterstitialAdLoadCallback { Initialize the `InterstitialAdUnit` with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `adUnitFormats` - AdUnitFormat.VIDEO for a video ad +- `configId` - an ID of Stored Impression on the Prebid Server +- `adUnitFormats` - AdUnitFormat.VIDEO for a video ad #### Step 2: Configure video parameters {:.no_toc} @@ -570,8 +570,8 @@ adUnit?.fetchDemand(request) { Initialize the `InterstitialAdUnit` with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `adUnitFormats` - ad unit formats for the current ad unit. +- `configId` - an ID of Stored Impression on the Prebid Server +- `adUnitFormats` - ad unit formats for the current ad unit. #### Steps 2-3 {:.no_toc} @@ -641,7 +641,7 @@ private fun createListener(): RewardedAdLoadCallback { Initialize the Rewarded Video Ad Unit with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server +- `configId` - an ID of Stored Impression on the Prebid Server ### Step 2: Configure video parameters {:.no_toc} @@ -763,9 +763,9 @@ private fun initializePlayer() { Initialize the VideoAdUnit with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `width` - Width of the video ad unit. -* `height` - Height of the video ad unit +- `configId` - an ID of Stored Impression on the Prebid Server +- `width` - Width of the video ad unit. +- `height` - Height of the video ad unit ### Step 2: Configure the video parameters {:.no_toc} @@ -881,16 +881,16 @@ private fun addNativeAssets(adUnit: NativeAdUnit?) { Initialize the `NativeAdUnit` with properties: -* `configId` - an ID of the Stored Impression on the Prebid Server +- `configId` - an ID of the Stored Impression on the Prebid Server #### Step 2: Add Native Assets and Event Trackers {:.no_toc} In order to make a bid request for the native ads you should provide a description of native assets that should be present in the native bid response. Prebid SDK supports the following set of assets to request. -* `NativeImageAsset` -* `NativeDataAsset` -* `NativeTitleAsset` +- `NativeImageAsset` +- `NativeDataAsset` +- `NativeTitleAsset` #### Step 3: Create an AdManagerAdView {:.no_toc} @@ -1094,16 +1094,16 @@ private class SafeNativeListener : PrebidNativeAdEventListener { Initialize the `NativeAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server +- `configId` - an ID of the Stored Impression on the Prebid Server ##### Step 2: Add Native Assets and Event Trackers {:.no_toc} In order to make a bid request for the native ads you should provide a description of native assets that should be present in the native bid response. Prebid SDK supports the following set of assets to request. -* `NativeImageAsset` -* `NativeDataAsset` -* `NativeTitleAsset` +- `NativeImageAsset` +- `NativeDataAsset` +- `NativeTitleAsset` ##### Step 3: Make a bid request {:.no_toc} @@ -1341,7 +1341,7 @@ private fun inflatePrebidNativeAd(ad: PrebidNativeAd) { Initialize the `PrebidAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server +- `configId` - an ID of the Stored Impression on the Prebid Server ### Step 2: Create a PrebidRequest {:.no_toc} @@ -1355,9 +1355,9 @@ In addition you can set the following properties of the `PrebidRequest`. For each intersted ad format you should creatae a respective configuration parameter: -* [BannerParameters](#step-2-configure-banner-parameters) object. -* [VideoParameters](#step-2-configure-the-video-parameters) object. -* [NativeParameters](#nativeparameters) object +- [BannerParameters](#step-2-configure-banner-parameters) object. +- [VideoParameters](#step-2-configure-the-video-parameters) object. +- [NativeParameters](#nativeparameters) object #### NativeParameters {:.no_toc} @@ -1444,13 +1444,6 @@ PB Ad Slot is an identifier tied to the placement the ad will be delivered in. T `adUnit.ortb2Imp.ext.data.pbadslot = "/1111111/homepage/med-rect-2"` -### AppContext - -#### setAppContent -{:.no_toc} - -Provides targeting information for the `app.content` field of the bid request. Parameter is an `ContentObject` which provides all respective fields. - ### Auto Refresh #### setAutoRefreshPeriodMillis @@ -1460,7 +1453,7 @@ If set on a given Prebid Mobile ad unit, the `fetchDemand` function will be call **Parameters** -* `periodMillis`: Integer defining the refresh time in milliseconds. +- `periodMillis`: Integer defining the refresh time in milliseconds. #### startAutoRefresh {:.no_toc} @@ -1472,168 +1465,21 @@ Starts the auto-refresh behavior for a given Prebid Mobile ad unit. Halts the auto-refresh behavior for a given Prebid Mobile ad unit. If no auto-refresh behavior has been set, `stopAutoRefresh` will be ignored. -### Context Keywords - -#### addContextKeywords -{:.no_toc} - -Ad Unit context keywords object is a free form list of comma separated keywords about the app as defined in app.keyword in OpenRTB 2.5. - -**Parameters** -`keyword` : a keyword of type string. - -```java -void addContextKeyword(String keyword) -``` - -#### addContextKeywords -{:.no_toc} - -**Parameters** -`keyword` : a keyword of type string. - -```java -void addContextKeywords(Set keywords) -``` - -#### removeContextKeywords -{:.no_toc} - -**Parameters** -`keyword`: a keyword of type string. - -```java -void removeContextKeyword(String keyword) -``` - -#### clearContextKeywords -{:.no_toc} - -```java -void clearContextKeywords() -``` - -### First Party Data - -First Party Data (FPD) is free form data supplied by the publisher to provide additional targeting of the user or inventory context. It is used primarily for striking PMP (Private MarketPlace) deals with Advertisers. Data supplied in the data parameters are typically not sent to DSPs whereas information sent in non-data objects (i.e. `setYearOfBirth`, `setGender`, etc.) will be. Access to FPD can be limited to a supplied set of Prebid bidders via an access control list. - -Data is broken up into two different data types: - -* User - * Global in scope only -* Inventory (context) - * Global scope - * Ad Unit grain - - The first party inventory context will apply to the specic ad unit the data object it is applied to. For global user or inventory context level first party data, refer to [first party data section of the Targeting](pbm-targeting-params-android#first-party-data) page. - -#### addContextData -{:.no_toc} - -**Parameters** -`key`: string containing the key for the specific data object -`value`: String containing the value for the supplied key - -```java -void addContextData(String key, String value) -``` - -#### updateContextData -{:.no_toc} - -**Parameters** -`key`: string containing the key for the specific data object -`value`: String containing the value for the supplied key - -```java -void updateContextData(String key, Set value) -``` - -#### removeContextData -{:.no_toc} - -**Parameters** -`key`: string containing the key - -```java -void removeContextData(String key) -``` - -#### clearContextData -{:.no_toc} - -```java -void clearContextData() -``` - ### GPID (requires SDK v2.1.6) +The Global Placement ID (GPID) is a key that uniquely identifies a specific instance of an adunit. Some bidders require this value. An important scenario is "infinite scroll" -- if your app creates instances +of an adunit dynamically as the user scrolls through content, the the GPID must be different for each by appending some kind of sequence or ID. e.g. "/newsfeed#7" + Using the following method, you can set the impression-level [GPID](https://docs.prebid.org/features/pbAdSlot.html#the-gpid) value to the bid request: ``` kotlin adUnit?.gpid = "/36117602/hnp-sfgate.com/Homepage/AP300" ``` -### UserKeyword - -#### setUserKeyword -{:.no_toc} +## Further Reading -Set a single key-value pair. - -**Parameters** - -* `key`: String containing the key. -* `value`: String containing the value. - -#### setUserKeywords -{:.no_toc} - -Define multiple values for a single key. - -**Parameters** - -* `key`: String containing the key. -* `values`: String array containing the list of values for the key. - -#### removeUserKeyword -{:.no_toc} - -Remove a key and all its associated values from a given Prebid Mobile ad unit. - -**Parameters** - -* `key`: String containing the key you want to remove. - -#### removeUserKeywords -{:.no_toc} - -Clear all key-value combinations from the Prebid Mobile ad unit. - -### UserData - -The following methods enable adding `user.data[]` objects into the bid request: - -```kotlin -public void addUserData(DataObject dataObject) - -public ArrayList getUserData() - -public void clearUserData() -``` - -### App Content Data - -In order to set the `app.contnent.data[]` objects use the `getAppContent()` first and then one of the respective methods of the `ContentObject` class: - -```kotlin -public void addData(@NonNull DataObject dataObject) - -public ArrayList getDataList() - -public void setDataList(@NonNull ArrayList dataObjects) - -public void clearDataList() -``` +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Global Parameters - Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/pbm-api/android/code-integration-android.md b/prebid-mobile/pbm-api/android/code-integration-android.md index 0ce5beba6f..7611dfa20d 100644 --- a/prebid-mobile/pbm-api/android/code-integration-android.md +++ b/prebid-mobile/pbm-api/android/code-integration-android.md @@ -8,12 +8,12 @@ nav_section: prebid-mobile-android sidebarType: 2 --- -# Integration for Android +# Prebid SDK Integration for Android {:.no_toc} Get started with Prebid Mobile by creating a [Prebid Server account](/prebid-mobile/prebid-mobile-getting-started.html). Once your account is set up include the Prebid Mobile SDK in your app by either using Maven or by [cloning the repo](https://github.com/prebid/prebid-mobile-android) and using our included script to build the SDK. -* TOC +- TOC {:toc} ## SDK Integration @@ -62,9 +62,9 @@ If you see errors while building the Prebid Mobile SDK or Demo Applications, mak {% endcapture %} {% include /alerts/alert_warning.html content=warning_note %} -## Add SDK +## Add the Prebid SDK -### Set Prebid Server +### Point to a Prebid Server {% capture warning_note %} All integration examples for Android are written in `Kotlin`. @@ -81,10 +81,22 @@ PrebidMobile.setPrebidServerAccountId(YOUR_ACCOUNT_ID) PrebidMobile.setPrebidServerHost(Host.APPNEXUS) ``` -If you have opted to host your own Prebid Server solution you will need to store the url to the server in your app. Make sure that your URL points to the [/openrtb2/auction](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html) endpoint. +If you have opted to host your own Prebid Server solution you will need to store the url to the server in your app. Make sure that your URL points to the [/openrtb2/auction](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html) endpoint. ```kotlin -PrebidMobile.setPrebidServerHost(Host.createCustomHost(PREBID_SERVER_AUCTION_ENDPOINT)) +PrebidMobile.setPrebidServerHost(Host.createCustomHost("https://prebidserver.example.com/openrtb2/auction")) +``` + +#### Account Settings ID + +Each mobile app may have its own "account settings ID". This is used to look up data in Prebid Server like timeout, targeting, and price granularity. + +By default the Account Settings ID is set to be the same as the Account ID. i.e. the setPrebidServerAccountId() function will set both values. +If you want to define a different Account Settings ID as determined in conjunction with +your Prebid Server team, use the [arbitrary OpenRTB](/prebid-mobile/pbm-api/android/pbm-targeting-params-android.html#arbitrary-openrtb) method like this: + +```kotlin +adUnitConfiguration?.ortbConfig = "{\"ext\":{\"prebid\":{\"storedrequest\": {\"id\":\"account-settings-id\"}}}}" ``` ### Initialize SDK @@ -148,8 +160,8 @@ Open your AndroidManifest.xml and add the following permissions and activity dec **Notes:** -* `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` will automatically allow the device to send user location for targeting, which can help increase revenue by increasing the value of impressions to buyers. -* `WRITE_EXTERNAL_STORAGE` is optional and only required for MRAID 2.0 storePicture ads. +- `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` will automatically allow the device to send user location as First Party Data, which can help increase revenue by increasing the value of impressions to buyers. +- `WRITE_EXTERNAL_STORAGE` is optional and only required for MRAID 2.0 storePicture ads. For *banner and interstitial ads only*, include the following custom activities (even though you won't instantiate them directly). This is not necessary for video interstitial ads. @@ -175,19 +187,24 @@ Add this tag to your `` to use Google Play Services: ``` -## Set Targeting Parameters +## Set Global Parameters + +There are several types of parameters app developers should consider providing to Prebid SDK: -Targeting parameters enable you to define the target audience for the bid request. Prebid Mobile supports the following global targeting parameters. These targeting parameters are set only once and apply to all Prebid Mobile ad units. They do not change for a given user session. +- Values that control Prebid SDK behavior (timeout, etc) +- Privacy consent settings (TCF, GPP, COPPA, etc). +- First Party Data to help bidders understand the context and/or u +ser better. -View the full list of [targeting parameters](/prebid-mobile/pbm-api/android/pbm-targeting-params-android.html). +See the [global parameters page](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) for details. ## Supported Android versions Prebid supports the following versions by release: -* Prebid SDK version 1.0 or 1.1 supports Android 16+ -* Prebid SDK version 1.1.1+ supports Android 19+ -* Prebid SDK version 2.0.0+ supporst Android 16+ +- Prebid SDK version 1.0 or 1.1 supports Android 16+ +- Prebid SDK version 1.1.1+ supports Android 19+ +- Prebid SDK version 2.0.0+ supporst Android 16+ ## Setup SDK @@ -304,8 +321,8 @@ You can pass some SDK configuration properties from PBS to the SDK using the `ex For now Prebid SDK supports the following configuration properties: -* `cftbanner` - see the `Prebid.creativeFactoryTimeout` -* `cftprerender` - see the `Prebid.creativeFactoryTimeoutPreRenderContent` +- `cftbanner` - see the `Prebid.creativeFactoryTimeout` +- `cftprerender` - see the `Prebid.creativeFactoryTimeoutPreRenderContent` An example of a stored request: @@ -343,11 +360,11 @@ All values received in the `passthrough` of the bid response will be applied to Follow the corresponding guide to integrate Prebid Mobile: -* [GAM using Original API](android-sdk-integration-gam-original-api.html) -* [No Ad Server](../../modules/rendering/android-sdk-integration-pb.html) -* [GAM using Rendering API](../../modules/rendering/android-sdk-integration-gam.html) -* [AdMob](../../modules/rendering/android-sdk-integration-admob) -* [AppLovin MAX](../../modules/rendering/android-sdk-integration-max.html) +- [GAM using Original API](android-sdk-integration-gam-original-api.html) +- [No Ad Server](../../modules/rendering/android-sdk-integration-pb.html) +- [GAM using Rendering API](../../modules/rendering/android-sdk-integration-gam.html) +- [AdMob](../../modules/rendering/android-sdk-integration-admob) +- [AppLovin MAX](../../modules/rendering/android-sdk-integration-max.html) ### Test configs diff --git a/prebid-mobile/pbm-api/android/pbm-plugin-renderer.md b/prebid-mobile/pbm-api/android/pbm-plugin-renderer.md index 86d7162e6c..626341cd65 100755 --- a/prebid-mobile/pbm-api/android/pbm-plugin-renderer.md +++ b/prebid-mobile/pbm-api/android/pbm-plugin-renderer.md @@ -127,7 +127,7 @@ It is important to notice that the compliant formats you set on `isSupportRender ### Original API -The Plugin Renderer feature does not work with [GAM Original API](/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.md) since the ad rendering does not happen in the Prebid SDK but externally. Despite that if you are using the regular GAM integration it will work fine. +The Plugin Renderer feature does not work with [GAM Original API](/prebid-mobile/pbm-api/android/android-sdk-integration-gam-original-api.html) since the ad rendering does not happen in the Prebid SDK but externally. Despite that if you are using the regular GAM integration it will work fine. ## Ad Event Listeners An optional dedicated generic ad event listener is offered in case of the existing event listeners are insufficient to keep your ad consumer fully aware of your ad lifecycle. diff --git a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md index 13273f10c1..e470e326d3 100755 --- a/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md +++ b/prebid-mobile/pbm-api/android/pbm-targeting-params-android.md @@ -1,387 +1,754 @@ --- layout: page_v2 -title: Global Targeting Parameters - Android -description: Prebid Mobile API global targeting parameters for Android +title: Global Parameters - Android +description: Prebid Mobile API global parameters for Android top_nav_section: prebid-mobile nav_section: prebid-mobile sidebarType: 2 --- -# Global Targeting Parameters +# Prebid SDK Global Parameters - Android {:.no_toc} -Prebid Mobile supports the following global targeting parameters. These targeting parameters are set only once and apply to all Prebid Mobile ad units. They do not change for a given user session. - -* TOC +- TOC {:toc} -## Global GDPR Targeting +## How to Read this Guide -Prebid Mobile supports the [IAB GDPR recommendations](https://www.iab.com/topics/consumer-privacy/gdpr/). For a general overview of Prebid Mobile support for GDPR, see [Prebid Mobile Guide to European Ad Inventory and Providing Notice, Transparency and Choice](/prebid-mobile/prebid-mobile-privacy-regulation.html) +This page documents various global parameters you can set on the Prebid SDK for Android. It describes the properties and methods of the Prebid SDK that allow you to supply important parameters to the header bidding auction. -Prebid SDK doesn't modify values for IAB-defined keys in the `SharedPreferences`. Instead, SDK will keep the provided value in the in-memory property. +Specifically, app developers should consider each of these general sections: -The values provided via targeting API will be included in the bid request according to the `TCF v2` framework. +- Prebid SDK class parameters: these cover behavior of the SDK. Some values are required like a Prebid Server. +- Privacy / Consent Management parameters: we recommend developing a clear plan for user privacy with your legal counsel. +- First Party Data: data about the app or user that helps bidders choose an appropriate ad. -{% capture warning_note %} +{: .alert.alert-info :} +Note that the SDK's Targeting class uses the term "Targeting" loosely. It's mostly about +passing data to bidders that would help improve auction results. But there are also fields and methods +in the Targeting class that convey privacy data, Open Measurement info, and other data used beyond actual +bid targeting. -Since the SDK API has priority over CMP values, using the API blocks the CMP signals. Use a single way to provide the TCF signals. +## Prebid Global Properties and Methods -If you need to use an API way, ensure that all the following properties are set in the app code. +The `Prebid` class is a singleton that enables you to apply certain global settings. -If you need to use a CMP way, ensure that you don't set any of the following API properties. +### Prebid Class Global Properties -{% endcapture %} -{% include /alerts/alert_warning.html content=warning_note %} +All of these properties of the Prebid class can be set on the `shared` object like this: -### Subject To GPDR -{:.no_toc} +```kotlin +Prebid.shared.sendMraidSupportParams=true +``` + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Purpose | Description | Example | +| --- | --- | --- | --- | --- | +| isCoppaEnabled | optional | boolean | ORTB | Set this to true if this app is aimed at children. It sets the ORTB `regs.coppa` flag. Default is false. | `true` | +| useExternalBrowser | optional | boolean | behavior | If true, clicking on the ad will open your default browser instead of showing within the app's webview. Defaults to `false`. | `true` | +| sendMraidSupportParams | optional | boolean | ORTB | If `true`, the SDK sends imp[].banner.api=[3,5], indicating support for MRAID. Defaults to `true`. | `false` | + +### Prebid Class Global Methods + +#### setPrebidServerAccountId() + +Your Prebid Server team will tell you whether this is required or not and if so, the value. See the initialization page for [Android](/prebid-mobile/pbm-api/android/code-integration-android.html). -Enable (true) or disable (false) the ability to provide consent. +#### setPrebidServerHost() + +This is where the Prebid SDK will send the auction information. + +Signature: ```kotlin -TargetingParams.isSubjectToGDPR() -TargetingParams.setSubjectToGDPR(true) +func setPrebidServerHost(host: String) ``` -### GDPR Consent String -{:.no_toc} +Parameters: -```java -val consent = TargetingParams.getGDPRConsentString(); -TargetingParams.setGDPRConsentString(string); +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| host | required | object | Host.APPNEXUS, Host.RUBICON, Host.createCustomHost(PREBID_SERVER_AUCTION_ENDPOINT) | Host.createCustomHost(`https://prebidserver``.example.com``/openrtb2/auction`) | + +Examples: + +```kotlin +PrebidMobile.setPrebidServerHost(Host.APPNEXUS) +PrebidMobile.setPrebidServerHost(Host.RUBICON) +PrebidMobile.setPrebidServerHost(Host.createCustomHost("https://prebidserver.example.com/openrtb2/auction")) ``` -### Purpose Consent -{:.no_toc} +#### setCustomStatusEndpoint() + +Signature: ```kotlin -val consent = TargetingParams.getPurposeConsents() -TargetingParams.setPurposeConsents(string) + public static void setCustomStatusEndpoint(String url) { ``` -## COPPA +Parameters: -Prebid supports passing of the Child Online Privacy Prection (COPPA) signal to Prebid Server (PBS) for all COPPA traffic. When PBS receives the COPPA flag we strip out all personal data from the requeset. For a general overview of COPPA, see the [FTC's guidlines](https://www.ftc.gov/enforcement/rules/rulemaking-regulatory-reform-proceedings/childrens-online-privacy-protection-rule). +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| url | required | string | Use this URL to check the status of Prebid Server. The default status endpoint is the PBS URL appended with '/status'. | `https://prebidserver``.example``.com/custom``/status` | -Example: +#### setTimeoutMillis() + +The Prebid SDK timeout. When this number of milliseconds passes, the Prebid SDK returns control to the ad server SDK to fetch an ad without Prebid bids. See the initialization page for [Android](/prebid-mobile/pbm-api/android/code-integration-android.html). + +#### setShareGeoLocation() + +If this flag is true AND the app collects the user’s geographical location data, Prebid Mobile will send the user’s lat/long geographical location data to the Prebid Server. The default is false. + +#### setIncludeWinnersFlag() + +If `true`, Prebid sdk will add the `includewinners` flag inside the targeting object described in [PBS Documentation](prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . This is needed if you've set up line items in an ad server in "Send Top Bid" mode, as it's what creates the key value pairs like `hb_pb`. + +Signature: -```java -TargetingParams.setSubjectToCOPPA(true); +```kotlin + public static void setIncludeWinnersFlag(boolean includeWinners) ``` -## Parameters +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| includeWinners | required | boolean | If `true`, Prebid sdk will add `includewinners` flag inside the targeting object described in [PBS Documentation](prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . Default is `false`. | `true` | -The tables below list the methods and properties that the Prebid Rendering API uses for customization. -The more data about the user, app, and device that can be provided the more chances to win an impression. +#### setIncludeBidderKeysFlag() -It is advised that you strictly follow the recommendations in the tables below. Any field marked with an ❗is required and recommended. +If `true`, Prebid sdk will add the `includebidderkeys` flag inside the targeting object described in [PBS Documentation](prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . This is needed if you've set up line items in an ad server in "Send All Bids" mode, as it's what creates the key value pairs like `hb_pb_bidderA`. -1. [Targeting Params](#targeting) +Signature: -### Targeting +```kotlin + public static boolean setIncludeBidderKeysFlag(boolean includeBidderKeys) { +``` -You can use `Targeting` to pass ad call request parameters. +Parameters: {: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| includeBidderKeys | required | boolean | If `true`, Prebid sdk will add `includewinners` flag inside the targeting object described in [PBS Documentation](prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . Default is `false`. | `true` | -| **Parameter** | **Method** | Description | Required?| -| -------------------------- | ------------------------- | ------------------------------------------------------------ | -------- | -| User Age | `setUserAge` | Age of the user in years. For example: `35` | ❗ Highly Recommended | -| Buyer Id | `setBuyerId` | Buyer-specific ID for the user as mapped by the exchange for the buyer. | Optional | -| Custom User Data | `setUserCustomData` | Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional | -| User Extensions | `setUserExt` | Placeholder for exchange-specific extensions to OpenRTB. | Optional | -| User Gender | `setGender` | The gender of the user (Male, Female, Other, Unknown). For example: `Gender.FEMALE` | ❗ Highly Recommended | -| Keywords | `addUserKeywords` | Comma separated list of keywords, interests, or intent. | Optional | -| Lat, Lon | `setUserLatLng` | Location of the user’s home base defined by a provided longitude and latitude. It's highly recommended to provide Geo data to improve the request.| Optional | -| Publisher Name | `setPublisherName` | Publisher name (may be aliased at the publisher’s request).| Recommended if available | -| Store Url | `setStoreUrl` | The URL for the mobile application in Google Play. That field is required in the request.
**For example:**`https://play.google.com/store/apps/details?id=com.outfit7.talkingtom`. | ❗ Required | -| User ID | `setUserId` | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended | -|Year of Birth|`setYearOfBirth`| The year of user's birth|| +#### setStoredAuctionResponse() -Example: +For testing and debugging. Get this value from your Prebid Server team. It signals Prebid Server to respond with a static response from the Prebid Server Database. +See [more information on stored auction responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses). -``` java -// Set user parameters to enrich ad request data. -// Please see Targeting for the userKeys and the APIs available. -TargetingParams.addUserKeyword("socialNetworking"); -TargetingParams.setUserAge(18); +Signature: + +```kotlin +public static void setStoredAuctionResponse(@Nullable String storedAuctionResponse) ``` -### ORTBConfig +Parameters: -(requires SDK v2.2.1) +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| storedAuctionResponse | required | string | Key as defined by Prebid Server. Get this value from your Prebid Server team. | "abc123-sar-test-320x50" | -Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the [ORTB guidelines](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#321---object-bidrequest-) as it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server. +#### addStoredBidResponse() -There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed. +Stored Bid Responses are for testing and debugging similar to Stored Auction Responses (see the Global Properties above). They signal Prebid Server to respond with a static pre-defined response, except Stored Bid Responses actually exercise the bidder adapter. For more information on how stored bid responses work, refer to the [Prebid Server endpoint doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses). Your Prebid Server team will help you determine how best to setup test and debug. -``` kotlin -//global invocation -adUnitConfiguration?.ortbConfig = "{"ext":{"prebid":{"debug":1,"trace":"verbose"}}}" +Signature: + +```kotlin +void addStoredBidResponse(String bidder, String responseId) ``` -``` kotlin -//ad unit / impression-level -adUnit?.ortbConfig = "{"ext":{"gpid":"abc123"}}" +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| bidder | required | string | Bidder name as defined by Prebid Server | "bidderA" | +| responseId | required | string | ID used in the Prebid Server Database. Get this value from your Prebid Server team. | "abc123-sbr-test-300x250" | + +#### clearStoredBidResponses() + +This method clears any stored bid responses. It doesn’t take any parameters. + +Signature: + +```kotlin +void clearStoredBidResponses() ``` -### Global User Targeting +Parameters: none. -#### User Keywords -{:.no_toc} +#### setLogLevel -User keywords are a list of keywords, intrests or intent as defined by user.keywords in OpenRTB 2.5. Any keywords passed in the UserKeywords object may be passsed to DSPs. +Controls the level of logging output to the console. + +Signature: ```kotlin -void addUserKeyword(String keyword) -void addUserKeywords(Set keywords) -void removeUserKeyword(String keyword) -void clearUserKeywords() + public static void setLogLevel(LogLevel logLevel) ``` -Example: +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| logLevel | required | enum | The value can be NONE, VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT. The default is `NONE`. | `DEBUG` | + +#### setPbsDebug() + +Adds the debug flag (`test`:1) on the outbound http call to the Prebid Server. The `test` flag signals to the Prebid Server to emit the full resolved request and the full Bid Request and Bid Response to and from each bidder. + +Signature: ```kotlin -TargetingParams.addUserKeyword("globalUserKeywordValue1") -TargetingParams.addUserKeyword("globalUserKeywordValue2") +public static void setPbsDebug(boolean pbsDebug) ``` -## Global Application Targeting +Parameters: -### Inventory (Context) Keywords -{:.no_toc} +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| pbsDebug | required | boolean | Turn on/off debug mode. Defaults to `false`. | `true` | + +#### assignNativeAssetID() + +Whether to automatically assign an assetID for a Native ad. Default is `false`. -Context Keywords are a list of keywords about the app as referenced in OpenRTB 2.5 as app.keywords. Any keyword passed in the context keyword field may be passed to the buyer for targeting. +Signature: ```kotlin -void addContextKeyword(String keyword) -void addContextKeywords(Set keywords) -void removeContextKeyword(String keyword) -void clearContextKeywords() + public static void assignNativeAssetID(boolean assignNativeAssetID) { ``` -Example: +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| assignNativeAssetID | required | boolean | Whether to automatically assign an assetID for a Native ad. Defaults to `false`. | `true` | + +#### setCreativeFactoryTimeout() + +Controls how long a banner creative has to load before it is considered a failure. + +Signature: ```kotlin -TargetingParams.addContextKeyword("globalContextKeywordValue1") -TargetingParams.addContextKeyword("globalContextKeywordValue2") + public static void setCreativeFactoryTimeout(int creativeFactoryTimeout) ``` -### Bundle ID -{:.no_toc} +Parameters: -Use the following code to retrieve the platform-specific bundle/package name: +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| creativeFactoryTimeout | required | integer | Controls how long a banner creative has to load before it is considered a failure. This value is in milliseconds. The default is 6,000 milliseconds. | 10000 | + +#### setCreativeFactoryTimeoutPreRenderContent() + +Controls how much time video and interstitial creatives have to load before it is considered a failure. + +Signature: ```kotlin -bundleName = TargetingParams.getBundleName() + public static void setCreativeFactoryTimeoutPreRenderContent(int creativeFactoryTimeoutPreRenderContent) ``` -Pass in the platform-specific identifier - the bundle/package name - to set the bundle ID: +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| creativeFactoryTimeoutPreRenderContent | required | integer | Controls how much time video and interstitial creatives have to load before it is considered a failure. This value is in milliseconds. The default is 30,000 milliseconds. | 60000 | + +#### setCustomHeaders() + +This method enables you to customize the HTTP call to Prebid Server. + +Signature: ```kotlin -TargetingParams.setBundleName(bundleName) + public static void setCustomHeaders(@Nullable HashMap customHeaders) ``` -### Domain -{:.no_toc} +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| customHeaders | required | hashmap | Hashmap of custom headers | "X-mycustomheader: customvalue" | + +#### setCustomLogger() + +Define a custom PrebidLogger object. + +Signature: + +```kotlin + public static void setCustomLogger(@NonNull PrebidLogger logger) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| logger | required | object | The PrebidLogger interface enables the app developer to define where the Prebid SDK should send log-level details about the header bidding transaction. | | + +--- + +## Consent Management Parameters + +This section describes how app developers can provide info on user consent to the Prebid SDK and how SDK behaves under different kinds of restrictions. + +### GDPR / TCF-EU + +Prebid Mobile supports [IAB TCF](https://iabeurope.eu/transparency-consent-framework/). For a general overview of Prebid Mobile support for GDPR, see the [Prebid Mobile Guide to Privacy Regulation](/prebid-mobile/prebid-mobile-privacy-regulation.html). + +There are two ways to provide information on user consent to the Prebid SDK: + +- Explicitly via Prebid SDK API: publishers can provide TCF data via Prebid SDK’s 'Targeting' class. +- Implicitly set through the Consent Management Platform (CMP): Prebid SDK reads the TCF data stored in the `SharedPreferences`. This is the preferred approach. + +{: .alert.alert-warning :} +The Prebid SDK prioritizes values set explicitly through the API over those stored by the CMP. If the publisher provides TCF data both ways, the values set through the API will be sent to the PBS, and values stored by the CMP will be ignored. + +#### Setting TCF-EU Values with the API + +Prebid SDK provides three properties to set TCF consent values explicitly, though this method is not preferred. Ideally, the Consent Management Platform will set these values – see the next section. + +If you need to set the values directly, here's how to indicate that the user is subject to GDPR: + +```kotlin +TargetingParams.setSubjectToGDPR(true) +``` -Retrieve and set the domain of your app with the following commands: +To provide the consent string: ```kotlin -TargetingParams.setDomain(domain) +TargetingParams.setGDPRConsentString("BOMyQRvOMyQRvABABBAAABAAAAAAEA") +``` + +To set the purpose consent: + +```kotlin +TargetingParams.setPurposeConsents("100000000000000000000000") +``` + +Related functions: isSubjectToGDPR(), getGDPRConsentString(), getPurposeConsent(int index), getPurposeConsents(), getDeviceAccessConsent() + +#### Getting Consent Values from the CMP + +Prebid SDK reads the values for the following keys from the `SharedPreferences` object: + +- **IABTCF_gdprApplies** - indicates whether the user is subject to GDPR +- **IABTCF_TCString** - full encoded TC string +- **IABTCF_PurposeConsents** - indicates the consent status for the purpose. + +For more detailed information, read the [In-App Details section](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#in-app-details) of the TCF. + +{: .alert.alert-warning :} +Publishers shouldn’t explicitly assign values for these keys unless they have a custom-developed Consent Management Platform (CMP). If the publisher wants to provide this data to the Prebid SDK, they should use the explicit APIs described above. + +Here's how Prebid SDK processes CMP values: + +- It reads CMP values during the initialization and on each bid request, so the latest value is always used. +- It doesn’t verify or validate CMP values in any way + +### CCPA / US Privacy + +The California Consumer Protection Act prompted the IAB to implement the "US Privacy" protocol. -val domain = TargetingParams.getDomain() +Prebid SDK reads and sends USP/CCPA signals according to the [US Privacy User Signal Mechanism](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/USP%20API.md) and [OpenRTB extension](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/7f4f1b2931cca03bd4d91373bbf440071823f257/CCPA/OpenRTB%20Extension%20for%20USPrivacy.md). + +Prebid SDK reads the value for the `IABUSPrivacy_String` key from `SharedPreferences` and sends it in the `regs.ext.us_privacy` object of the OpenRTB request. + +### COPPA + +The Children's Online Privacy Protection Act of the United States is a way for content producers to declare that their content is aimed at children, which invokes additional privacy protections. + +Prebid SDK follows the OpenRTB 2.6 spec and provides an API to indicate whether the current content falls under COPPA regulation. Publishers can set the respective flag using the targeting API: + +```kotlin +TargetingParams.setSubjectToCOPPA(true) ``` +Prebid SDK passes this flag in the `regs.coppa` object of the bid requests. + +If you're app developer setting this COPPA flag, we recommend you also: + +- set the `shareGeoLocation` property to false +- avoid passing any sensitive first party data + +### Global Privacy Platform (GPP) + +A Consent Management Platform (CMP) utilizing [IAB's Global Privacy Protocol](https://iabtechlab.com/gpp/) is a comprehensive way for apps to manage user consent across multiple regulatory environments. + +Since version 2.0.6, Prebid SDK reads and sends GPP signals: + +- The GPP string is read from IABGPP_HDR_GppString in `SharedPreferences`. It is sent to Prebid Server on `regs.gpp`. +- The GPP Section ID is likewise read from IABGPP_GppSID. It is sent to Prebid Server on `regs.gpp_sid`. + +--- + ## Open Measurement SDK (OMSDK) API -**NOTE**: these properties are relevant only for the original Prebid integration into GAM monetization. In this case the creative is rendered by GMA SDK and publishers should provide OMID description in the bid re qest. If you use Prebid SDK as a rendering engine you shouldn’t use these properties. Prebid SDK sends them automaticaly according to the current OMID setup. +{: .alert.alert-info :} +Defining OMSDK values is only relevant for the 'Bidding-Only' Prebid integration with GAM. In this case the creative is rendered by GMA SDK and publishers should provide OMID description in the bid request. If you use Prebid SDK as a rendering engine you shouldn’t use these properties -- it sends them automaticaly according to the current OMID setup. -OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. +OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters by way of Prebid Server, indicating that the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. -There three components to signaling support for OMSDK: +There are three components to signaling support for OMSDK: -* Partner Name -* Partner Version -* API code +- Partner Name +- Partner Version +- Banner API code ### Partner Name -{:.no_toc} - -This will be the [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. See below for configuration and examples -Open Measurement partner name. +The [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. ```kotlin TargetingParams.setOmidPartnerName("Google") ``` ### Partner Version -{:.no_toc} -The OMSDK version number the partner integrated with. See below for configuration and examples. +The OMSDK version number for the integration partner. + +```kotlin +TargetingParams.setOmidPartnerVersion("1.0"); +``` + +### Banner API Code -Partner's OMSDK version number implementation +The following code lets bidders know that Open Measurement is being used for this adunit: -```java -TargetingParams.setOmidPartnerVersion(); +```swift +let parameters = BannerParameters() +parameters.api = [Signals.Api.OMID_1] ``` -## First Party Data +--- -First Party Data (FPD) is free form data supplied by the publisher to provide additional targeting of the user or inventory context, used primarily for striking PMP (Private MarketPlace) deals with Advertisers. Data supplied in the data parameters are typically not sent to DSPs whereas information sent in non-data objects (i.e. `setYearOfBirth`, `setGender`, etc.) will be. Access to FPD can be limited to a supplied set of Prebid bidders via an access control list. +## First Party Data -Data is broken up into two different data types: +First Party Data (FPD) is information about the app or user known by the developer that may be of interest to advertisers. -* User - * Global in scope only -* Inventory (context) - * Global scope - * Ad Unit grain +- User FPD includes details about a specific user like "frequent user" or "job title". This data if often subject to regulatory control, so needs to be specified as user-specific data. Note that some attributes like health status are limited in some regions. App developers are strongly advised to speak with their legal counsel before passing User FPD. +- Inventory FPD includes details about the particular part of the app where the ad will displayed like "sports/basketball" or "editor 5-star rating". -### First Party User Data -{:.no_toc} +### User FPD -User specic data is passed in the global scope (i.e. applicable to all ad units). +Prebid SDK provides a number of properties in the [Targeting class](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#targeting-class-properties-and- +methods) for setting user-oriented First Party Data. -```java +```kotlin void addUserData(String key, String value) -void updateUserData(String key, Set value) + +void updateUserData( String key, Set value) + void removeUserData(String key) + void clearUserData() + +Map> getUserDataDictionary() { + +void addUserKeywords(Set keywords) { + +void removeUserKeyword(String keyword) { + +void clearUserKeywords() { + +String getUserKeywords() { + +Set getUserKeywordsSet() { ``` Example: -```java +```kotlin TargetingParams.addUserData("globalUserDataKey1", "globalUserDataValue1") ``` -### First Party Inventory (Context) Data -{:.no_toc} +{: .alert.alert-info :} +Note: The 'UserData' functions end up putting data into the OpenRTB user.ext.data object while the 'UserKeywords' functions +put data into user.keywords. -Inventory specific free form data decribing the context of the inventory. +### Inventory FPD -#### Global Context Data -{:.no_toc} +Prebid SDK provides a number of methods in the [Targeting class](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#targeting-class-properties-and-methods) for setting content-oriented First Party Data. ```kotlin -void addContextData(String key, String value) -void updateContextData(String key, Set value) -void removeContextData(String key) -void clearContextData() +void addExtData(String key, String value) + +void updateExtData(String key, Set value) + +void removeExtData(String key) + +Map> getExtDataDictionary() + +void addExtKeyword(String keyword) + +void addExtKeywords(Set keywords) + +void removeExtKeyword(String keyword) + +void clearExtKeywords() + +Set getExtKeywordsSet() ``` Example: ```kotlin -TargetingParams.addContextData("globalContextDataKey1", "globalContextDataValue1, globalContextDataValue2") +Targeting.addExtData("globalContextDataKey1", "globalContextDataValue1") ``` -#### Ad Unit Context Data -{:.no_toc} - -For ad unit context data, please refer to the [ad unit](pbm-adunit-android.html) section. - -### Access Control List -{:.no_toc} - -The First Party Data Access Control List provides a method to restrict access to first party data to a supplied list of bidders. +### Controlling Bidder Access to FPD -Only bidders supplied in the ACL will have access to the first party data. If no bidder is supplied, Prebid Server will supply first party data to all bid adapers. +Prebid Server will let you control which bidders are allowed access to First Party Data. Prebid SDK collects this an Access Control List with the following methods: -```java +```kotlin void addBidderToAccessControlList(String bidderName) + void removeBidderFromAccessControlList(String bidderName) + void clearAccessControlList() + +Set getAccessControlList() ``` Example: -```java -TargetingParams.addBidderToAccessControlList(TargetingParams.BIDDER_NAME_RUBICON_PROJECT); +```kotlin +Targeting.addBidderToAccessControlList("bidderA") ``` +--- + ## User Identity -Prebid SDK supports two interfaces to pass / maintain User IDs and ID vendor details: +Mobile apps traditionally rely on IDFA-type device IDs for advertising, but there are other User ID systems available to app developers and more will be made available in the future. Prebid SDK supports two ways to maintain Extended User ID (EID) details: -* Real-time in Prebid SDK's API field setExternalUserIds -* Store User Id(s) in local storage +- A global property - in this approach, the app developer sets the IDs while initializing the Prebid SDK. This data persists only for the user session. +- Local storage - the developer can choose to store the IDs persistently in local storage and Prebid SDK will utilize them on each bid request. -Any identity vendor's details in local storage will be sent over to Prebid Server as is, unadulterated. If data is sent in the API and entered into local storage, the API detail will prevail. +Any identity vendor's details in local storage will be sent to Prebid Server unadulterated. If user IDs are set both in the property and entered into local storage, the property data will prevail. + +{: .alert.alert-info :} +Note that the phrase "EID" stands for "Extended IDs" in [OpenRTB 2.6](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md), but for historic reasons, Prebid SDK methods use the word "external" rather than "extended". Please consider the phrase "external ID" a synonym for "extended ID". ### Prebid SDK API Access -{:.no_toc} -Prebid SDK supports passing an array of UserID(s) at auction time in the field setExternalUserIds, that is globably scopped. It is sufficient enough to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session. +Prebid SDK supports passing an array of EIDs at auction time with the function storeExternalUserId, which is globably scoped. It is sufficient to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session. -```java -public static void setExternalUserIds(List externalUserIds) +```kotlin +void storeExternalUserId( externalUserIds) + +List fetchStoredExternalUserIds() + +ExternalUserId fetchStoredExternalUserId(@NonNull String source) + +void removeStoredExternalUserId(@NonNull String source) { -public static List getExternalUserIds() +void clearStoredExternalUserIds() { ``` -Exmaple (JAVA): +Example: -```java -// User Id from External Third Party Sources -ArrayList externalUserIdArray = new ArrayList<>(); -externalUserIdArray.add(new ExternalUserId("adserver.org", "111111111111", null, new HashMap() { +```kotlin + // User Id from External Third Party Sources + ArrayList externalUserIdArray = new ArrayList<>(); + externalUserIdArray.add(new ExternalUserId("adserver.org", "111111111111", null, new HashMap() { { put ("rtiPartner", "TDID"); } - })); -externalUserIdArray.add(new ExternalUserId("netid.de", "999888777", null, null)); -externalUserIdArray.add(new ExternalUserId("criteo.com", "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N", null, null)); -externalUserIdArray.add(new ExternalUserId("liveramp.com", "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg", null, null)); -externalUserIdArray.add(new ExternalUserId("sharedid.org", "111111111111", 1, new HashMap() { - { - put("third", "01ERJWE5FS4RAZKG6SKQ3ZYSKV"); - } + externalUserIdArray.add(new ExternalUserId("netid.de", "999888777", null, null)); + externalUserIdArray.add(new ExternalUserId("criteo.com", "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N", null, null)); + externalUserIdArray.add(new ExternalUserId("liveramp.com", "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg", null, null)); + externalUserIdArray.add(new ExternalUserId("sharedid.org", "111111111111", 1, null)); })); -//Set External User ID -PrebidMobile.setExternalUserIds(externalUserIdArray); + +//Set External User IDs +PrebidMobile.storeExternalUserId(externalUserIdArray); ``` -### Local Storage -{:.no_toc} +--- + +## Targeting Class Methods -Prebid SDK provides a local storage interface to set, retrieve or update an array of user IDs with associated identity vendor details. Prebid SDK will retrieve and pass User IDs and ID vendor details to PBS if values are present in local storage. The main difference between the Prebid API interface and the local storage interface is the persistence of storage of data. Local Storage data will persist across user sessions whereas the Prebid API interface (setExternalUserIds) persists only for the user session. If a vendor's details are passed both in local storage and the Prebid API at the same time, the Prebid API data (setExternalUserIds) will prevail. +There are several other fields app developers may want to set to give bidders additional information about the auction. Prebid recommends that app developers consider setting the following values for best auction performance: -Prebid SDK Provides five functions to handle User ID details: +- setBundleName() +- setPublisherName() +- setStoreUrl() -```java -public static void storeExternalUserId(ExternalUserId externalUserId) -public static ExternalUserId fetchStoredExternalUserId(@NonNull String source) -public static List fetchStoredExternalUserIds() -public static void removeStoredExternalUserId(@NonNull String source) -public static void clearStoredExternalUserIds() +### setBundleName() + +Define the OpenRTB app.bundle field. + +Signature: + +```kotlin +void setBundleName(String bundleName) { ``` -Examples +Parameters: -```java -//Set External User ID -TargetingParams.storeExternalUserId(new ExternalUserId("sharedid.org", "111111111111", 1, new HashMap() { - { - put ("third", "01ERJWE5FS4RAZKG6SKQ3ZYSKV"); - } +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| bundleName | required | string | App bundle name. Sets ORTB `app.bundle`. | "com.example" | -})); +Related function: getBundleName(). -//Get External User ID -ExternalUserId externalUserId = TargetingParams.fetchStoredExternalUserId("sharedid.org"); +### setDomain() -//Get All External User IDs -List externalUserIdList = TargetingParams.fetchStoredExternalUserIds(); +Define the OpenRTB app.domain field. -//Remove External UserID -TargetingParams.removeStoredExternalUserId("adserver.org"); +Signature: -//Remove All External UserID -TargetingParams.clearStoredExternalUserIds(); +```kotlin +void setDomain(String domain) ``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| domain | required | string | Domain. Sets `app.domain`. | "example.com" | + +Related function: getDomain(). + +### setPublisherName() + +Define the OpenRTB app.publisher.name field. + +Signature: + +```kotlin +void setPublisherName(String publisherName) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| publisherName | required | string | Publisher name. Sets `app.publisher.name`. | "publisher 1" | + +Related function: getPublisherName(). + +### setStoreUrl() + +Define the OpenRTB app.storeurl field. + +Signature: + +```kotlin +void setStoreUrl(String storeUrl) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| storeUrl | required | string | App store URL. Sets `app.storeurl` | `https://play.google.com/store/apps/details?id=1234` | + +Related function: getStoreUrl(). + +### setOmidPartnerName() + +Define the OpenRTB source.ext.omidpn field. + +Signature: + +```kotlin +setOmidPartnerName(@Nullable String omidPartnerName) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| omidPartnerName | required | string | Open Measurement Partner name. | "MyIntegrationPartner" | + +Related function: getOmidPartnerName(). + +### setOmidPartnerVersion() + +Define the OpenRTB source.ext.omidpv field. + +Signature: + +```kotlin +setOmidPartnerVersion(@Nullable String omidPartnerVersion) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| omidPartnerVerson | required | string | Open Measurement Partner version | "7.1" | + +Related function: getOmidPartnerVersion(). + +### setUserLatLng() + +Sets the device location for buyer targeting. It's incumbent upon to the app developer to make sure they have permission to read this data. Prebid Server may remove it under some privacy scenarios. + +Signature: + +```kotlin +void setUserLatLng( Float latitude, Float longitude) +``` + +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| latitude | required | double | The device latitude. | 40.71 | +| longitude | required | double | The device longitude. | 74.01 | + +--- + +## Arbitrary OpenRTB + +(requires SDK v2.2.1) + +While there are many specific methods for adding data to the request detailed in +this document, OpenRTB is big and it moves quickly. To cover scenarios not already covered by an existing method, +Prebid SDK Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the [OpenRTB structure](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md) -- it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server. + +There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed. + +```kotlin +//global invocation +adUnitConfiguration?.ortbConfig = "{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}" +``` + +```kotlin +//ad unit / impression-level +adUnit?.ortbConfig = "{\"ext\":{\"gpid\":\"abc123\"}}" +``` + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android integration](/prebid-mobile/pbm-api/android/code-integration-android.html) diff --git a/prebid-mobile/pbm-api/ios/code-integration-ios.md b/prebid-mobile/pbm-api/ios/code-integration-ios.md index 065ed65767..6b417c9ed6 100644 --- a/prebid-mobile/pbm-api/ios/code-integration-ios.md +++ b/prebid-mobile/pbm-api/ios/code-integration-ios.md @@ -8,12 +8,12 @@ nav_section: prebid-mobile-ios sidebarType: 2 --- -# Integration for iOS +# Prebid SDK Integration for iOS {:.no_toc} Get started with Prebid Mobile by creating a [Prebid Server account](/prebid-mobile/prebid-mobile-getting-started.html). Once your account is set up include the Prebid Mobile SDK in your app by either using dependencies managers or by [cloning the repo](https://github.com/prebid/prebid-mobile-ios) and using our included script to build the SDK. -* TOC +- TOC {:toc} ## SDK Integration @@ -60,20 +60,18 @@ If you are not familiar with the Swift Package Manager, please refer to the proj **Variant 1** - * Run CarthageBuild.sh script from Cartfile folder. The path should be: + - Run CarthageBuild.sh script from Cartfile folder. The path should be: `.../Carthage/Checkouts/prebid-mobile-ios/scripts/CarthageBuild.sh` - - * Enter Schema name (PrebidMobile or PrebidMobileCore) - * If you run CarthageBuild.sh and see Permission denied use: + - Enter Schema name (PrebidMobile or PrebidMobileCore) + - If you run CarthageBuild.sh and see Permission denied use: `chmod +x ` **Variant 2** - * Open `PrebidMobile.xcodeproj` at `.../Carthage/Checkouts/prebid-mobile-ios/PrebidMobile.xcodeproj` using Xcode - - * Manage Schemes -> Check Shared checkbox for a necessary schema + - Open `PrebidMobile.xcodeproj` at `.../Carthage/Checkouts/prebid-mobile-ios/PrebidMobile.xcodeproj` using Xcode + - Manage Schemes -> Check Shared checkbox for a necessary schema + - run `carthage build prebid-mobile-ios` - * run `carthage build prebid-mobile-ios` 5. Integrate the binary into your project You can find the schema name in the build PrebidSDK framework inside Info.plist with `PrebidMobileName` key @@ -88,9 +86,9 @@ scripts/buildPrebidMobile.sh This will output the PrebidMobile.framework. -## Add SDK +## Add the Prebid SDK -### Set Prebid Server +### Point to a Prebid Server Once you have a [Prebid Server](/prebid-mobile/prebid-mobile-getting-started.html), you will add 'account' info to the Prebid Mobile. For example, if you're using the AppNexus Prebid Server: @@ -99,14 +97,26 @@ Prebid.shared.prebidServerAccountId = YOUR_ACCOUNT_ID Prebid.shared.prebidServerHost = .Appnexus ``` -If you have opted to host your own Prebid Server solution, you will need to store the URL to the server in your app. Make sure that your URL points to the [/openrtb2/auction](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html) endpoint. +If you have opted to host your own Prebid Server solution, you will need to store the URL to the server in your app. Make sure that your URL points to the [/openrtb2/auction](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html) endpoint. ```swift -try! Prebid.shared.setCustomPrebidServer(url: PREBID_SERVER_AUCTION_ENDPOINT) +try! Prebid.shared.setCustomPrebidServer(url: "https://prebidserver.example.com/openrtb2/auction") ``` This method throws an exception if the provided URL is invalid. +#### Account Settings ID + +Each mobile app may have its own "account settings ID". This is used to look up data in Prebid Server like timeout, targeting, and price granularity. + +By default the Account Settings ID is set to be the same as the Account ID. i.e. the Prebid.shared.prebidServerAccountId property will set both values. +If you want to define a different Account Settings ID as determined in conjunction with +your Prebid Server team, use the [arbitrary OpenRTB](/prebid-mobile/pbm-api/android/pbm-targeting-params-android.html#arbitrary-openrtb) method like this: + +```swift +adUnitConfig.setOrtbConfig = "{\"ext\":{\"prebid\":{\"storedrequest\": {\"id\":\"account-settings-id\"}}}}" +``` + ### Initialize SDK Once you set the account ID and the Prebid Server host, you should initialize the Prebid SDK. There are several options for how to do it. @@ -171,11 +181,15 @@ Prebid.shared.customStatusEndpoint = PREBID_SERVER_STATUS_ENDPOINT If something goes wrong with the request, the status of the initialization callback will be `.serverStatusWarning`. It doesn't affect an SDK flow and just informs you about the health check result. -## Set Targeting Parameters +## Set Global Parameters + +There are several types of parameters app developers should consider providing to Prebid SDK: -Targeting parameters enable you to define the target audience for the bid request. Prebid Mobile supports the following global targeting parameters. These targeting parameters are set only once and apply to all Prebid Mobile ad units. They do not change for a given user session. +- Values that control Prebid SDK behavior (timeout, etc) +- Privacy consent settings (TCF, GPP, COPPA, etc). +- First Party Data to help bidders understand the context and/or user better. -View the full list of [targeting parameters](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html). +See the [global parameters page](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html) for details. ## Setup SDK @@ -217,8 +231,8 @@ public static let severe = LogLevel(stringValue: "[🔥]", rawValue: 5) `addStoredBidResponse`: Function containing two properties: -* `bidder`: Bidder name as defined by Prebid Server bid adapter of type string. -* `responseId`: Configuration ID used in the Prebid Server Database to store static bid responses. +- `bidder`: Bidder name as defined by Prebid Server bid adapter of type string. +- `responseId`: Configuration ID used in the Prebid Server Database to store static bid responses. Stored Bid Responses are similar to Stored Auction Responses in that they signal to Prebid Server to respond with a static pre-defined response, except Stored Bid Responses is done at the bidder level, with bid requests sent out for any bidders not specified in the bidder parameter. For more information on how stored auction responses work, refer to the written [description on github issue 133](https://github.com/prebid/prebid-mobile-android/issues/133). @@ -251,8 +265,8 @@ You can pass some SDK configuration properties from PBS to the SDK using the `ex For now Prebid SDK supports the following configuration properties: -* `cftbanner` - see the `Prebid.creativeFactoryTimeout` -* `cftprerender` - see the `Prebid.creativeFactoryTimeoutPreRenderContent` +- `cftbanner` - see the `Prebid.creativeFactoryTimeout` +- `cftprerender` - see the `Prebid.creativeFactoryTimeoutPreRenderContent` An example of a stored request: @@ -327,11 +341,11 @@ Prebid.shared.addStoredBidResponse(bidder: "rubicon", responseId: "221155") Follow the corresponding guide to integrate Prebid Mobile: -* [GAM using Original API](code-integration-ios.html) -* [No Ad Server](../../modules/rendering/ios-sdk-integration-pb.html) -* [GAM using Rendering API](../../modules/rendering/ios-sdk-integration-gam.html) -* [AdMob](../../modules/rendering/ios-sdk-integration-gam.html) -* [AppLovin MAX](../../modules/rendering/ios-sdk-integration-max.html) +- [GAM using Original API](code-integration-ios.html) +- [No Ad Server](/prebid-mobile/modules/rendering/ios-sdk-integration-pb.html) +- [GAM using Rendering API](/prebid-mobile/modules/rendering/ios-sdk-integration-gam.html) +- [AdMob](/prebid-mobile/modules/rendering/ios-sdk-integration-gam.html) +- [AppLovin MAX](/prebid-mobile/modules/rendering/ios-sdk-integration-max.html) ### Test configs diff --git a/prebid-mobile/pbm-api/ios/ios-sdk-integration-gam-original-api.md b/prebid-mobile/pbm-api/ios/ios-sdk-integration-gam-original-api.md index 0a33e55029..cb22ee381c 100644 --- a/prebid-mobile/pbm-api/ios/ios-sdk-integration-gam-original-api.md +++ b/prebid-mobile/pbm-api/ios/ios-sdk-integration-gam-original-api.md @@ -12,7 +12,7 @@ sidebarType: 2 Prebid Mobile is an open-source library that provides an end-to-end header bidding solution for mobile app publishers. -* TOC +- TOC {:toc} ## Overview @@ -78,8 +78,8 @@ func bannerViewDidReceiveAd(_ bannerView: GADBannerView) { Initialize the `BannerAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `adSize` - the size of the ad unit which will be used in the bid request. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `adSize` - the size of the ad unit which will be used in the bid request. #### Step 2: Configure banner parameters {:.no_toc} @@ -88,10 +88,10 @@ Using the `BannerParameters` you can customize the bid request for the BannerAdU The `api` property is dedicated to adding values for API Frameworks to bid response according to the OpenRTB [2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec. The supported values for GMA SDK integration are: -* `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal -* `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal -* `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal -* `7` or `Signals.Api.OMID_1` : signals OMSDK support +- `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal +- `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal +- `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal +- `7` or `Signals.Api.OMID_1` : signals OMSDK support {: .alert.alert-warning :} Starting from PrebidMobile `2.1.0` the `parameters` property is deprecated. Use `bannerParameters` instead. @@ -164,8 +164,8 @@ Starting from PrebidMobile `2.1.0` the `VideoAdUnit` class is deprecated. Use `B Initialize the `BannerAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `adSize` - the size of the ad unit which will be used in the bid request. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `adSize` - the size of the ad unit which will be used in the bid request. #### Step 2: Set ad format {:.no_toc} @@ -184,22 +184,22 @@ Using the `VideoParameters` you can customize the bid request for video ads. In the context of a VideoInterstitialAdUnit, rewarded video ads are typically labeled as interstitial. As such, Prebid SDK will default to value 5 if no placement value is supplied. -* `2` or `InBanner` : In-Banner placement exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. -* `3` or `InArticle` : In-Article placement loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. -* `4` or `InFeed` : In-Feed placement is found in content, social, or product feeds. -* `5` or `Slider`, `Floating` or `Interstitial` : Open RTB supports one of three values for option 5 as either Slider, Floating or Interstitial. If an enum value is supplied in placement, bidders will receive value 5 for placement type and assume to be interstitial with the instl flag set to 1. +- `2` or `InBanner` : In-Banner placement exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. +- `3` or `InArticle` : In-Article placement loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. +- `4` or `InFeed` : In-Feed placement is found in content, social, or product feeds. +- `5` or `Slider`, `Floating` or `Interstitial` : Open RTB supports one of three values for option 5 as either Slider, Floating or Interstitial. If an enum value is supplied in placement, bidders will receive value 5 for placement type and assume to be interstitial with the instl flag set to 1. #### api {:.no_toc} The `api` property is dedicated to adding values for API Frameworks to bid response according to the [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec. The supported values for GMA SDK integration are: -* `1` or `Signals.Api.VPAID_1` : VPAID 1.0 -* `2` or `Signals.Api.VPAID_2` : VPAID 2.0 -* `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal -* `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal -* `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal -* `7` or `Signals.Api.OMID_1` : signals OMSDK support +- `1` or `Signals.Api.VPAID_1` : VPAID 1.0 +- `2` or `Signals.Api.VPAID_2` : VPAID 2.0 +- `3` or `Signals.Api.MRAID_1` : MRAID-1 support signal +- `5` or `Signals.Api.MRAID_2` : MRAID-2 support signal +- `6` or `Signals.Api.MRAID_3` : MRAID-3 support signal +- `7` or `Signals.Api.OMID_1` : signals OMSDK support #### maxBitrate {:.no_toc} @@ -232,26 +232,26 @@ Required property. Array of OpenRTB 2.5 playback methods. If none are specified, any method may be used. Only one method is typically used in practice. It is strongly advised to use only the first element of the array. -* `1` or `Signals.PlaybackMethod.AutoPlaySoundOn` : Initiates on Page Load with Sound On -* `2` or `Signals.PlaybackMethod.AutoPlaySoundOff` : Initiates on Page Load with Sound Off by Default -* `3` or `Signals.PlaybackMethod.ClickToPlay` : Initiates on Click with Sound On -* `4` or `Signals.PlaybackMethod.MouseOver` : Initiates on Mouse-Over with Sound On -* `5` or `Signals.PlaybackMethod.EnterSoundOn` : Initiates on Entering Viewport with Sound On -* `6` or `Signals.PlaybackMethod.EnterSoundOff`: Initiates on Entering Viewport with Sound Off by Default +- `1` or `Signals.PlaybackMethod.AutoPlaySoundOn` : Initiates on Page Load with Sound On +- `2` or `Signals.PlaybackMethod.AutoPlaySoundOff` : Initiates on Page Load with Sound Off by Default +- `3` or `Signals.PlaybackMethod.ClickToPlay` : Initiates on Click with Sound On +- `4` or `Signals.PlaybackMethod.MouseOver` : Initiates on Mouse-Over with Sound On +- `5` or `Signals.PlaybackMethod.EnterSoundOn` : Initiates on Entering Viewport with Sound On +- `6` or `Signals.PlaybackMethod.EnterSoundOff`: Initiates on Entering Viewport with Sound Off by Default #### protocols {:.no_toc} Array or enum of OpenRTB 2.5 supported Protocols. Values can be one of: -* `1` or `Signals.Protocols.VAST_1_0` : VAST 1.0 -* `2` or `Signals.Protocols.VAST_2_0` : VAST 2.0 -* `3` or `Signals.Protocols.VAST_3_0` : VAST 3.0 -* `4` or `Signals.Protocols.VAST_1_0_Wrapper` : VAST 1.0 Wrapper -* `5` or `Signals.Protocols.VAST_2_0_Wrapper` : VAST 2.0 Wrapper -* `6` or `Signals.Protocols.VAST_3_0_Wrapper` : VAST 3.0 Wrapper -* `7` or `Signals.Protocols.VAST_4_0` : VAST 4.0 -* `8` or `Signals.Protocols.VAST_4_0_Wrapper` : VAST 4.0 Wrapper +- `1` or `Signals.Protocols.VAST_1_0` : VAST 1.0 +- `2` or `Signals.Protocols.VAST_2_0` : VAST 2.0 +- `3` or `Signals.Protocols.VAST_3_0` : VAST 3.0 +- `4` or `Signals.Protocols.VAST_1_0_Wrapper` : VAST 1.0 Wrapper +- `5` or `Signals.Protocols.VAST_2_0_Wrapper` : VAST 2.0 Wrapper +- `6` or `Signals.Protocols.VAST_3_0_Wrapper` : VAST 3.0 Wrapper +- `7` or `Signals.Protocols.VAST_4_0` : VAST 4.0 +- `8` or `Signals.Protocols.VAST_4_0_Wrapper` : VAST 4.0 Wrapper #### Step 4: Create a GAMBannerView {:.no_toc} @@ -333,8 +333,8 @@ func bannerViewDidReceiveAd(_ bannerView: GADBannerView) { Initialize the `BannerAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `adSize` - the size of the ad unit which will be used in the bid request. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `adSize` - the size of the ad unit which will be used in the bid request. #### Step 2: Set ad formats {:.no_toc} @@ -410,9 +410,9 @@ adUnit.fetchDemand(adObject: gamRequest) { [weak self] resultCode in Initialize the InterstitialAdUnit with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ -* `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ +- `configId` - an ID of Stored Impression on the Prebid Server +- `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ +- `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ > **NOTE:** As of version 1.2+, Prebid SDK has extended the functionality of Interstitial ad monetization by using a smart ad size selection process to monetize sizes smaller than full screen ads. App developers can specify a minimum width and minimum height percentage an ad can occupy of a devices real state, with Prebid Server (PBS) deriving a limited set of ad sizes (max 10) as eligible for the auction. > @@ -485,7 +485,7 @@ Starting from PrebidMobile `2.1.0` the `VideoInterstitialAdUnit` class is deprec Initialize the Interstitial Video Ad Unit with properties: -* `configId` - an ID of Stored Impression on the Prebid Server +- `configId` - an ID of Stored Impression on the Prebid Server #### Step 2: Set ad format {:.no_toc} @@ -556,9 +556,9 @@ adUnit.fetchDemand(adObject: gamRequest) { [weak self] resultCode in Initialize the InterstitialAdUnit with the following properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ -* `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ +- `configId` - an ID of Stored Impression on the Prebid Server +- `minWidthPerc`: Optional parameter to specify the minimum width percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ +- `minHeightPrec`: Optional parameter to specify the minimum height percent an ad may occupy of a device's real estate. Support in SDK version 1.2+ > **NOTE:** As of version 1.2+, Prebid SDK has extended the functionality of Interstitial ad monetization by using a smart ad size selection process to monetize sizes smaller than full screen ads. App developers can specify a minimum width and minimum height percentage an ad can occupy of a devices real state, with Prebid Server (PBS) deriving a limited set of ad sizes (max 10) as eligible for the auction. > @@ -634,7 +634,7 @@ adUnit.fetchDemand(adObject: gamRequest) { [weak self] resultCode in Initialize the Rewarded Video Ad Unit with properties: -* `configId` - an ID of Stored Impression on the Prebid Server +- `configId` - an ID of Stored Impression on the Prebid Server ### Step 2: Configure video parameters {:.no_toc} @@ -755,8 +755,8 @@ Starting from PrebidMobile `2.1.0` the `VideoAdUnit` class is deprecated. Use `I Initialize the Instream Video Ad Unit with properties: -* `configId` - an ID of Stored Impression on the Prebid Server -* `size` - Width and height of the video ad unit. +- `configId` - an ID of Stored Impression on the Prebid Server +- `size` - Width and height of the video ad unit. ### Step 2: Configure video parameters {:.no_toc} @@ -849,8 +849,8 @@ nativeUnit.fetchDemand(adObject: gamRequest) { [weak self] resultCode in Initialize the `NativeRequest` with properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `assets` - the array of `NativeAsset` objects which describes your native ad. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `assets` - the array of `NativeAsset` objects which describes your native ad. ##### NativeAssetImage {:.no_toc} @@ -1017,8 +1017,8 @@ func nativeAdNotValid() { Initialize the `NativeRequest` with properties: -* `configId` - an ID of the Stored Impression on the Prebid Server -* `assets` - the array of `NativeAsset` objects which describes your native ad. +- `configId` - an ID of the Stored Impression on the Prebid Server +- `assets` - the array of `NativeAsset` objects which describes your native ad. ##### Step 2: Make a bid request {:.no_toc} @@ -1037,7 +1037,7 @@ Be sure that you make the ad request with the same `GAMRequest` object that you ##### Step 4: Implement GADCustomNativeAdLoaderDelegate protocol {:.no_toc} -In order to capture the native ad response you need to implement [GADCustomNativeAdLoaderDelegate](GADCustomNativeAdLoaderDelegate) protocol. +In order to capture the native ad response you need to implement the GADCustomNativeAdLoaderDelegate protocol. In the method `-adLoader:didReceiveCustomNativeAd:` you should pass the following Prebid functions: @@ -1165,16 +1165,16 @@ func nativeAdLoaded(ad: NativeAd) { Initialize the `PrebidAdUnit` with the following properties: -* `configId` - an ID of the Stored Impression on the Prebid Server +- `configId` - an ID of the Stored Impression on the Prebid Server ### Step 2: Setup the parameters {:.no_toc} -For each intersted ad format you should creatae a respective configuration parameter: +For each interested ad format you should creatae a respective configuration parameter: -* [BannerParameters](#step-2-configure-banner-parameters) object. -* [VideoParameters](#step-3-configure-the-video-parameters) object. -* [NativeParameters](#nativeparameters) object +- [BannerParameters](#step-2-configure-banner-parameters) object. +- [VideoParameters](#step-3-configure-the-video-parameters) object. +- [NativeParameters](#nativeparameters) object #### NativeParameters {:.no_toc} @@ -1299,138 +1299,21 @@ Halts the auto-refresh behavior for a given Prebid Mobile ad unit. If no auto-re Allows to resume the stopped autorefresh for the ad unit with predefined autorefresh value. -### Context Keyword - -#### addContextKeyword -{:.no_toc} - -Ad Unit context keywords object is a free form list of comma separated keywords about the app as defined in app.keyword in OpenRTB 2.5. The `addContextKeyword` function adds a single keyword to the ad unit. - -``` swift -func addContextKeyword(_ newElement: String) -``` - -#### addContextKeywords -{:.no_toc} - -Ad Unit context keywords object is a free form list of comma separated keywords about the app as defined in app.keyword in OpenRTB 2.5. The `addContextKeywords` function adds a multiple keyword to the ad unit. - -``` swift -func addContextKeywords(_ newElements: Set) -``` - -#### removeContextKeyword -{:.no_toc} - -``` swift -func removeContextKeyword(_ element: String) -``` - -### clearContextKeywords -{:.no_toc} - -``` swift -func clearContextKeywords() -``` - -### App Content - -The `ContentObject` allows you to provide more details about content within the app. All properties provided to the `ContentObject` will be sent in the `app.content` field of the bid request. - -``` swift -func setAppContent(_ appContent: ContentObject) - -func getAppContent() -> ContentObject? - -func clearAppContent() -``` - -### App Content Data - -Using the following methods you can add `app.content.data` objects to the bid requests. - -``` swift -func addAppContentData(_ dataObjects: [ContentDataObject]) - -func removeAppContentData(_ dataObject: ContentDataObject) - -func clearAppContentData() -``` - ### GPID (requires SDK v2.1.6) +The Global Placement ID (GPID) is a key that uniquely identifies a specific instance of an adunit. Some bidders require this value. An important scenario is "infinite scroll" -- if your app creates instances +of an adunit dynamically as the user scrolls through content, the the GPID must be different for each by appending some kind of sequence or ID. e.g. "/newsfeed#7" + Using the following method, you can set the impression-level [GPID](https://docs.prebid.org/features/pbAdSlot.html#the-gpid) value to the bid request: ``` swift adUnit.setGPID("/36117602/hnp-sfgate.com/Homepage/AP300") ``` -### User Data - -Using the following methods you can add `user.data` objects to the bid requests. - -``` swift -func getUserData() -> [PBMORTBContentData]? - -func addUserData(_ userDataObjects: [PBMORTBContentData]) - -func removeUserData(_ userDataObject: PBMORTBContentData) - -func clearUserData() -``` - -### Data Object - -The Data object is free form data (also known as First Party Data) supplied by the publisher to provide additional targeting of the user or inventory context, used primarily for striking PMP (Private MarketPlace) deals with Advertisers. Data supplied in the data parameters are typically not sent to DSPs whereas information sent in non-data objects (i.e. `setYearOfBirth`, `setGender`, etc.) will be. Access to FPD can be limited to a supplied set of Prebid bidders via an access control list. - -Data is broken up into two different data types: - -* User - * Global in scope only -* Inventory (context) - * Global scope - * Ad Unit grain - -The first party inventory context below will apply to the specic ad unit the data object is applied to. For global user or inventory context level first party data, refer to [first party data section of the Targeting](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data) page. - -#### addContextData -{:.no_toc} - -``` swift -func addContextData(key: String, value: String) -``` - -**Parameters** -`key`: string containing the key for the specific data object -`value`: String containing the value for the supplied key - -#### updateContextData -{:.no_toc} - -``` swift -func updateContextData(key: String, value: Set) -``` - -**Parameters** -`key`: string containing the key for the specific data object -`value`: String containing the value for the supplied key - -#### removeContextData -{:.no_toc} - -``` swift -func removeContextData(forKey: String) -``` - -**Parameters** -`key`: string containing the key for the specific data object -`value`: String containing the value for the supplied key +## Further Reading -#### clearContextData -{:.no_toc} - -``` swift -func clearContextData() -``` +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK iOS integration](/prebid-mobile/pbm-api/ios/code-integration-ios.html) +- [Prebid SDK Global Parameters - iOS](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html) diff --git a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md index 8319f7f67b..2556415d82 100644 --- a/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-targeting-ios.md @@ -1,140 +1,261 @@ --- layout: page_v2 -title: Global Targeting Parameters - iOS -description: Prebid Mobile API global targeting parameters for iOS +title: Global Parameters - iOS +description: Prebid Mobile API global parameters for iOS top_nav_section: prebid-mobile nav_section: prebid-mobile sidebarType: 2 --- - -# Request parameters +# Prebid SDK Global Parameters - iOS {:.no_toc} -The tables below list the methods and properties that the Prebid Rendering API uses for customization. -The more data about the user, app, and device that can be provided the more chances to win an impression. - -It is advised that you strictly follow the recommendations in the tables below. Any field marked with an ❗is required and recommended. - -* TOC +- TOC {:toc} -## GPDR API +## How to Read this Guide -Prebid Mobile supports the [IAB GDPR recommendations](https://www.iab.com/topics/consumer-privacy/gdpr/). For a general overview of Prebid Mobile support for GDPR, see [Prebid Mobile Guide to European Ad Inventory and Providing Notice, Transparency and Choice](/prebid-mobile/prebid-mobile-privacy-regulation.html) +This page documents various global parameters you can set on the Prebid SDK for iOS. It describes the properties and methods of the Prebid SDK that allow you to supply important parameters to the header bidding auction. -Prebid SDK doesn't modify values for IAB-defined keys in the `UserDefaults`. Instead, SDK will keep the provided value in the in-memory property. +Specifically, app developers should consider each of these general sections: -The values provided via targeting API will be included in the bid request according to the `TCF v2` framework. +- Prebid SDK class parameters: these cover behavior of the SDK. Some values are required like a Prebid Server. +- Privacy / Consent Management parameters: we recommend developing a clear plan for user privacy with your legal counsel. +- First Party Data: data about the app or user that helps bidders choose an appropriate ad. -{% capture warning_note %} +{: .alert.alert-info :} +Note that the SDK's Targeting class uses the term "Targeting" loosely. It's mostly about +passing data to bidders that would help improve auction results. But there are also fields and methods +in the Targeting class that convey privacy data, Open Measurement info, and other data used beyond actual +bid targeting. -Since the SDK API has priority over CMP values, using the API blocks the CMP signals. Use a single way to provide the TCF signals. +## Prebid Class Global Properties and Methods -If you need to use an API way, ensure that all the following properties are set in the app code. +The `Prebid` class is a singleton that enables you to apply certain global settings. -If you need to use a CMP way, ensure that you don't set any of the following API properties. +### Prebid Class Global Properties -{% endcapture %} -{% include /alerts/alert_warning.html content=warning_note %} - -### Subject To GPDR +All of these properties of the Prebid class can be set on the `shared` object like this: ```swift -public var subjectToGDPR:Bool? +Prebid.shared.prebidServerAccountId="12345" +Prebid.shared.customStatusEndpoint="https://pbs.example.com/v2/status" ``` -You can retrieve and set the subjectToGDPR for targeting: +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Purpose | Description | Example | +| --- | --- | --- | --- | --- | --- | +| prebidServerAccountId | either | string | init | Your Prebid Server team will tell you whether this is required or not and if so, the value. | "abc123" | +| prebidServerHost | optional | enum | init | This can take the values "Appnexus", "Rubicon", or "Custom". If "Custom", you need to use the setCustomPrebidServerUrl() method to set a URL. This is where the Prebid SDK will send the auction information. Your Prebid Server team will tell you which value to use. The default is "Custom". | "Custom" | +| customStatusEndpoint | optional | string | init | Use this URL to check the status of Prebid Server. The default status endpoint is the PBS URL appended with '/status'. | `https://prebidserver``.example``.com/custom``/status` | +| shareGeoLocation | optional | boolean | ORTB | If this flag is true AND the app collects the user’s geographical location data, Prebid Mobile will send the user’s lat/long geographical location data to the Prebid Server. The default is false. | `true` | +| locationUpdatesEnabled | optional | boolean | ORTB | If true, the SDK will periodically try to listen for location updates. Default is `false`. | `true` | +| logLevel | optional | enum | SDK control | This property controls the level of logging output to the console. The value can be .error, .info, .debug, .verbose, .warn, .severe, and .info. The default is `.debug`. | `.error` | +| debugLogFileEnabled | optional | boolean | SDK control | If set to true, the output of PrebidMobile's internal logger is written to a text file. Default is `false`. | `true` | +| timeoutMillis | optional | integer | init | (SDK v1.2+) The Prebid SDK timeout. When this number of milliseconds passes, the Prebid SDK returns control to the ad server SDK to fetch an ad without Prebid bids. | 1000 | +| creativeFactoryTimeout | optional | integer | SDK control | Controls how long a banner creative has to load before it is considered a failure. This value is in seconds. The default is 6 seconds. | 10 | +| creativeFactoryTimeoutPreRenderContent | optional | integer | SDK control | Controls how much time video and interstitial creatives have to load before it is considered a failure. This value is in seconds. The default is 30 seconds. | 60 | +| storedAuctionResponse | optional | string | ORTB | For testing and debugging. Get this value from your Prebid Server team. It signals Prebid Server to respond with a static response from the Prebid Server Database. See [more information on stored auction responses](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses). | "abc123-sar-test-320x50" | +| pbsDebug | optional | boolean | ORTB | Adds the debug flag (`test`:1) on the outbound http call to the Prebid Server. The `test` flag signals to the Prebid Server to emit the full resolved request and the full Bid Request and Bid Response to and from each bidder. | true | +| shouldAssignNativeAssetID | optional | boolean | ORTB | Whether to automatically assign an assetID for a Native ad. Default is `false`. | true | +| useCacheForReportingWithRenderingAPI | optional | boolean | ORTB | Indicates whether PBS should cache the bid on the server side. If the value is `true` the Prebid SDK will make the cache request to retrieve the cached asset. Default is `false`. | true | +| useExternalClickthroughBrowser | optional | boolean | SDK control | Controls whether to use PrebidMobile's in-app browser or the Safari App for displaying ad clickthrough content. Default is false. | true | +| impClickbrowserType | optional | enum | ORTB | Indicates the type of browser opened upon clicking the creative in an app. This corresponds to the OpenRTB imp.clickbrowser field. Values are "embedded" and "native". Default is "native". | "native". | +| includeWinners | optional | boolean | ORTB | If `true`, Prebid sdk will add `includewinners` flag inside the targeting object described in [PBS Documentation](prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . Default is `false`. | `true` | +| includeBidderKeys | optional | boolean | ORTB | If `true`, Prebid sdk will add `includebidderkeys` flag inside the targeting object described in [PBS Documentation](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting) . Default is `false`. | `true` | + +### Prebid Class Global Methods + +#### setCustomPrebidServerUrl() + +Defines which Prebid Server to connect to. See the initialization page for [iOS](/prebid-mobile/pbm-api/ios/code-integration-ios.html). + +#### addStoredBidResponse() + +Stored Bid Responses are for testing and debugging similar to Stored Auction Responses (see the Global Properties above). They signal Prebid Server to respond with a static pre-defined response, except Stored Bid Responses actually exercise the bidder adapter. For more information on how stored bid responses work, refer to the [Prebid Server endpoint doc](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#stored-responses). Your Prebid Server team will help you determine how best to setup test and debug. + +Signature: ```swift -guard let subjectToGDPR = Targeting.shared.subjectToGDPR else { - print("There was an error retrieving subjectToGDPR) - return -} +func addStoredBidResponse(bidder: String, responseId: String) ``` +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| bidder | required | string | Bidder name as defined by Prebid Server | "bidderA" | +| responseId | required | string | ID used in the Prebid Server Database. Get this value from your Prebid Server team. | "abc123-sbr-test-300x250" | + +#### clearStoredBidResponses() + +This method clears any stored bid responses. It doesn’t take any parameters. + +Signature: + ```swift -Targeting.shared.subjectToGDPR = false +func clearStoredBidResponses() ``` - -### GDPR Consent String + +Parameters: none. + +#### addCustomHeader() + +This method enables you to customize the HTTP call to Prebid Server. + +Signature: ```swift -public var gdprConsentString? +func addCustomHeader(name: String, value: String) ``` -You can retrieve and set the subjectToGDPR for targeting: +Parameters: + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| name | required | string | Name of the custom header | "X-mycustomheader" | +| value | required | string | Value for the custom header | "customvalue" | + +#### clearCustomHeaders() + +Allows you to clear any custom headers you have previously set. + +Signature: ```swift -guard let gdprConsentString = Targeting.shared.gdprConsentString else { - print("There was an error retrieving gdprConsentString") - return -} +func clearCustomHeaders() ``` +Parameters: none + +--- + +## Consent Management Parameters + +This section describes how app developers can provide info on user consent to the Prebid SDK and how SDK behaves under different kinds of restrictions. + +### iOS App Tracking Transparency + +You should follow Apple's Guidelines on implementing [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency). The Prebid SDK automatically sends ATT signals, so no Prebid-specific work is required. + +### GDPR / TCF-EU + +Prebid Mobile supports [IAB TCF](https://iabeurope.eu/transparency-consent-framework/). For a general overview of Prebid Mobile support for GDPR, see the [Prebid Mobile Guide to Privacy Regulation](/prebid-mobile/prebid-mobile-privacy-regulation.html). + +There are two ways to provide information on user consent to the Prebid SDK: + +- Explicitly via Prebid SDK API: publishers can provide TCF data via Prebid SDK’s 'Targeting' class. +- Implicitly set through the Consent Management Platform (CMP): Prebid SDK reads the TCF data stored in `UserDefaults`. This is the preferred approach. + +{: .alert.alert-warning :} +The Prebid SDK prioritizes values set explicitly through the API over those stored by the CMP. If the publisher provides TCF data both ways, the values set through the API will be sent to the PBS, and values stored by the CMP will be ignored. + +#### Setting TCF-EU Values with the API + +Prebid SDK provides three properties to set TCF consent values explicitly, though this method is not preferred. Ideally, the Consent Management Platform will set these values – see the next section. + +If you need to set the values directly, here's how to indicate that the user is subject to GDPR: + +Swift: + ```swift -Targeting.shared.gdprConsentString = "A String" +Targeting.shared.subjectToGDPR = false +Targeting.shared.setSubjectToGDPR(false) ``` -### Purpose Consent +To provide the consent string: + +Swift: ```swift -public var purposeConsents: String? +Targeting.shared.gdprConsentString = "BOMyQRvOMyQRvABABBAAABAAAAAAEA" ``` -You can retrieve and set the purposeConsents for targeting: +To set the purpose consent: + +Swift: ```swift Targeting.shared.purposeConsents = "100000000000000000000000" ``` -## Targeting properties +Related functions: getSubjectToGDPR(), getDeviceAccessConsent(), getDeviceAccessConsentObjc, getPurposeConsent(), isAllowedAccessDeviceData(). -{: .table .table-bordered .table-striped } +#### Getting Consent Values from the CMP + +Prebid SDK reads the values for the following keys from the `UserDefaults` object: + +- **IABTCF_gdprApplies** - indicates whether the user is subject to GDPR +- **IABTCF_TCString** - full encoded TC string +- **IABTCF_PurposeConsents** - indicates the consent status for the purpose. + +For more detailed information, read the [In-App Details section](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#in-app-details) of the TCF. + +{: .alert.alert-warning :} +Publishers shouldn’t explicitly assign values for these keys unless they have a custom-developed Consent Management Platform (CMP). If the publisher wants to provide this data to the Prebid SDK, they should use the explicit APIs described above. + +Here's how Prebid SDK processes CMP values: + +- It reads CMP values during the initialization and on each bid request, so the latest value is always used. +- It doesn’t verify or validate CMP values in any way + +### CCPA / US Privacy + +The California Consumer Protection Act prompted the IAB to implement the "US Privacy" protocol. + +Prebid SDK reads and sends USP/CCPA signals according to the [US Privacy User Signal Mechanism](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/USP%20API.md) and [OpenRTB extension](https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/7f4f1b2931cca03bd4d91373bbf440071823f257/CCPA/OpenRTB%20Extension%20for%20USPrivacy.md). + +Prebid SDK reads the value for the `IABUSPrivacy_String` key from the `UserDefaults` and sends it in the `regs.ext.us_privacy` object of the OpenRTB request. + +### COPPA + +The Children's Online Privacy Protection Act of the United States is a way for content producers to declare that their content is aimed at children, which invokes additional privacy protections. + +Prebid SDK follows the OpenRTB 2.6 spec and provides an API to indicate whether the current content falls under COPPA regulation. Publishers can set the respective flag using the targeting API: -| **Variable** | **Description** | **Required?** | -| -------------------- | ---------------- | ------------------------------------------------------------ | ------------------------ | -| `storeURL` | Stores URL for the mobile application. For example: `"https://itunes.apple.com/us/app/your-app/id123456789"` | ❗ Required | -|`contentUrl` | This is the deep-link URL for the app screen that is displaying the ad. This can be an iOS universal link. | ❗ Highly Recommended | -|`publisherName`| App's publisher's name. | ❗ Highly Recommended | -| `yearOfBirth` | For example: `1987` | ❗ Highly Recommended | -| `coppa` or `subjectToCOPPA` | Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes | ❗ Highly Recommended | -| `userGender` | User's gender (Male, Female, Other, Unknown). For example: `.female` | ❗ Highly Recommended | -|`userGenderDescription`| String representation of the user's gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown) | | -| `userID` | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended | -| `buyerUID` | Buyer-specific ID for the user as mapped by the exchange for the buyer. | ❗ Highly Recommended | -| `keywords` | Comma separated list of keywords, interests, or intent | Optional | -| `userCustomData`| Optional feature to pass bidder the data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional | -|`userExt`| Placeholder for exchange-specific extensions to OpenRTB. | Optional | -|`domain`|Retrieve and set the domain of your app|Optional| -|`itunesID`|Retrieve and set the domain of your iTunes ID with the below command. This field will be transmitted to buyers as the bundle ID as recommended in OpenRTB 2.5. Failure to supply this value can have a negative monetary impact.|Optional| - -The code sample: +Swift: ```swift -let targeting = Targeting.shared - -targeting.userGender = .male -targeting.yearOfBirth = 1987 -targeting.userID = "X345Y678Z890" +Targeting.shared.subjectToCOPPA = true ``` +Prebid SDK passes this flag in the `regs.coppa` object of the bid requests. + +If you're app developer setting this COPPA flag, we recommend you also: + +- set the `shareGeoLocation` property to false +- avoid passing any sensitive first party data + +### Global Privacy Platform (GPP) + +A Consent Management Platform (CMP) utilizing [IAB's Global Privacy Protocol](https://iabtechlab.com/gpp/) is a comprehensive way for apps to manage user consent across multiple regulatory environments. + +Since version 2.0.6, Prebid SDK reads and sends GPP signals: + +- The GPP string is read from IABGPP_HDR_GppString in `UserDefaults`. It is sent to Prebid Server on `regs.gpp`. +- The GPP Section ID is likewise read from IABGPP_GppSID. It is sent to Prebid Server on `regs.gpp_sid`. + +--- + ## Open Measurement SDK (OMSDK) API -> **NOTE**: these properties are relevant only for the original Prebid integration into GAM monetization. In this case the creative is rendered by GMA SDK and publishers should provide OMID description in the bid re qest. If you use Prebid SDK as a rendering engine you shouldn't use these properties. Prebid SDK sends them automaticaly according to the current OMID setup. +{: .alert.alert-info :} +Defining OMSDK values is only relevant for the 'Bidding-Only' Prebid integration with GAM. In this case the creative is rendered by GMA SDK and publishers should provide OMID description in the bid request. If you use Prebid SDK as a rendering engine you shouldn’t use these properties -- it sends them automaticaly according to the current OMID setup. -OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is eligible for OMSDK support. Original API of prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. +OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters by way of Prebid Server, indicating that the impression is eligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code. -There three components to signaling support for OMSDK: +There are three components to signaling support for OMSDK: -* Partner Name -* Partner Version -* API code +- Partner Name +- Partner Version +- Banner API code ### Partner Name {:.no_toc} -This will be the [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. See below for configuration and examples +The [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. ```swift Targeting.shared.omidPartnerName = "Google" @@ -143,43 +264,39 @@ Targeting.shared.omidPartnerName = "Google" ### Partner Version {:.no_toc} -The OMSDK version number the partner integrated with. See below for configuration and examples. +The OMSDK version number for the integration partner. ```swift Targeting.shared.omidPartnerVersion = "1.0" ``` -## Targeting methods +### Banner API Code -{: .table .table-bordered .table-striped } - -### Inventory (Context) Keywords - -Context Keywords are a list of keywords about the app as referenced in OpenRTB 2.5 as app.keywords. Any keyword passed in the context keyword field may be passed to the buyer for targeting. Prebid provides following functions to manage context keywords: +The following code lets bidders know that Open Measurement is being used for this adunit: ```swift -func addContextKeyword(_ newElement: String) +let parameters = BannerParameters() +parameters.api = [Signals.Api.OMID_1] +``` -func addContextKeywords(_ newElements: Set) +This translates in OpenRTB to `imp[].banner.api=7`. -func removeContextKeyword(_ element: String) +--- -func clearContextKeywords() -``` +## First Party Data -Example: +First Party Data (FPD) is information about the app or user known by the developer that may be of interest to advertisers. -```swift -Targeting.shared.addContextKeyword("globalContextKeywordValue1") -Targeting.shared.addContextKeyword("globalContextKeywordValue2") -Targeting.shared.addContextKeyword("globalContextKeywordValue3") -``` +- User FPD includes details about a specific user like "frequent user" or "job title". This data if often subject to regulatory control, so needs to be specified as user-specific data. Note that some attributes like health status are limited in some regions. App developers are strongly advised to speak with their legal counsel before passing User FPD. +- Inventory or Contextual FPD includes details about the particular part of the app where the ad will displayed like "sports/basketball" or "editor 5-star rating". -### First Party User Data +### User FPD -Prebid provides following functions to manage First Party User Data: +Prebid SDK provides a number of properties in the [Targeting class](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#targeting-class-properties-and-methods) for setting user-oriented First Party Data. ```swift +func setLatitude(latitude: Double, longitude: Double) + func addUserData(key: String, value: String) func updateUserData(key: String, value: Set) @@ -187,133 +304,126 @@ func updateUserData(key: String, value: Set) func removeUserData(forKey: String) func clearUserData() -``` - -Example: - -```swift -Targeting.shared.addUserData(key: "globalUserDataKey1", value: "globalUserDataValue1") -``` -### First Party Inventory (Context) Data +func addUserKeyword(_ newElement: String) -Prebid provides following functions to manage First Party Inventory Data: +func addUserKeywords(_ newElements: Set) -```swift -func addContextData(key: String, value: String) - -func updateContextData(key: String, value: Set) +func removeUserKeyword(_ element: String) -func removeContextData(forKey: String) +func clearUserKeywords() -func clearContextData() +func getUserKeywords() ``` Example: ```swift -Targeting.shared.addContextData(key: "globalContextDataKey1", value: "globalContextDataValue1") +Targeting.shared.addUserData(key: "globalUserDataKey1", value: "globalUserDataValue1") ``` -### Access Control +{: .alert.alert-info :} +Note: The 'UserData' functions end up putting data into the OpenRTB user.ext.data object while the 'UserKeywords' functions +put data into user.keywords. -The First Party Data Access Control List provides a methods to restrict access to first party data to a supplied list of bidders. +Related functions: setYearOfBirth(), getYearOfBirth() and clearYearOfBirth(). -```swift -func addBidderToAccessControlList(_ bidderName: String) +### Inventory FPD -func removeBidderFromAccessControlList(_ bidderName: String) +Prebid SDK provides a number of methods and properties in the [Targeting class](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#targeting-class-properties-and-methods) for setting content-oriented First Party Data. -func clearAccessControlList() -``` +```swift +func addAppExtData(key: String, value: String) -Example: +func updateAppExtData(key: String, value: Set) -```swift -Targeting.shared.addBidderToAccessControlList(Prebid.bidderNameRubiconProject) -``` +func removeAppExtData(for key: String) -### Custom Params +func clearAppExtData() -The methods that add or change the custom parameters. The name will be auto-prepended with `c.` to avoid collisions. +func getAppExtData() -```swift -public func addCustomParam(_ value: String, withName: String?) +func addAppKeyword(_ newElement: String) -public func setCustomParams(_ params: [String : String]?) -``` +func addAppKeywords(_ newElements: Set) -### Parameter +func removeAppKeyword(_ element: String) -Adds a new param by name and sets its value. +func clearAppKeywords() -```swift -public func addParam(_ value: String, withName: String?) +func getAppKeywords() ``` -### Latitude Longitude - -Store location in the user's section +Example: ```swift -public func setLatitude(_ latitude: Double, longitude: Double) +Targeting.shared.addAppExtData((key: "globalContextDataKey1", value: "globalContextDataValue1") ``` -### ORTBConfig +### Controlling Bidder Access to FPD -(requires SDK v2.2.1) +Prebid Server will let you control which bidders are allowed access to First Party Data. Prebid SDK collects this an Access Control List with the following methods: -Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the setOrtbConfig() method that takes a JSON String as input. The JSON string must follow the [ORTB guidelines](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#321---object-bidrequest-) as it will be merged with the current JSON of the bid request. If you choose to input extra data using the setOrtbConfig() method, please extensively test your requests sent to Prebid Server. +```swift +func addBidderToAccessControlList(_ bidderName: String) -There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed. +func removeBidderFromAccessControlList(_ bidderName: String) -```swift -//global invocation -adUnitConfig.setOrtbConfig("{"ext":{"prebid":{"debug":1,"trace":"verbose"}}}") +func clearAccessControlList() ``` +Example: + ```swift -//ad unit / impression-level -adUnit.setOrtbConfig("{"ext":{"gpid":"abc123"}}") +Targeting.shared.addBidderToAccessControlList(Prebid.bidderNameRubiconProject) ``` -## User Identity API +--- + +## User Identity -Prebid SDK supports two interfaces to pass / maintain User IDs and ID vendor details: +Mobile apps traditionally rely on IDFA-type device IDs for advertising, but there are other User ID systems available to app developers and more will be made available in the future. Prebid SDK supports two ways to maintain User ID details: -* Real-time in Prebid SDK's API field externalUserIdArray -* Store User Id(s) in local storage +- A global property - in this approach, the app developer sets the IDs while initializing the Prebid SDK. This data persists only for the user session. +- Local storage - the developer can choose to store the IDs persistently in local storage and Prebid SDK will utilize them on each bid request. -Any identity vendor's details in local storage will be sent over to Prebid Server as is, unadulterated. If data is sent in the API and entered into local storage, the API detail will prevail. +Any identity vendor's details in local storage will be sent to Prebid Server unadulterated. If user IDs are set both in the property and entered into local storage, the property data will prevail. -### Prebid SDK API Access +{: .alert.alert-info :} +Note that the phrase "EID" stands for "Extended IDs" in [OpenRTB 2.6](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md), but for historic reasons, Prebid SDK methods use the word "external" rather than "extended". Please consider the phrase "external ID" a synonym for "extended ID". -Prebid SDK supports passing an array of UserID(s) at auction time in the field externalUserIdArray, that is globably scopped. It is sufficient enough to set the externalUserIdArray object once per user session, as these values would be used in all consecutive ad auctions in the same session. +### Storing IDs in a Property + +Prebid SDK supports passing an array of EIDs at auction time in the Prebid global field `externalUserIdArray`. Setting the `externalUserIdArray` object once per user session is sufficient unless one of the values changes. ```swift public var externalUserIdArray = [ExternalUserId]() ``` -**Exmaples** +**Examples** ```swift // User Id from External Third Party Sources var externalUserIdArray = [ExternalUserId]() externalUserIdArray.append(ExternalUserId(source: "adserver.org", identifier: "111111111111", ext: ["rtiPartner" : "TDID"])) -externalUserIdArray.append(ExternalUserId(source: "netid.de", identifier: "999888777")) -externalUserIdArray.append(ExternalUserId(source: "criteo.com", identifier: "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N")) +externalUserIdArray.append(ExternalUserId(source: "netid.de", identifier: "999888777")) +externalUserIdArray.append(ExternalUserId(source: "criteo.com", identifier: "_fl7bV96WjZsbiUyQnJlQ3g4ckh5a1N")) externalUserIdArray.append(ExternalUserId(source: "liveramp.com", identifier: "AjfowMv4ZHZQJFM8TpiUnYEyA81Vdgg")) -externalUserIdArray.append(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1, ext: ["third" : "01ERJWE5FS4RAZKG6SKQ3ZYSKV"])) +externalUserIdArray.append(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1)) Prebid.shared.externalUserIdArray = externalUserIdArray ``` -### Local Storage +```kotlin +setExternalUserIds(List externalUserIds) +``` + +### Storing IDs in Local Storage -Prebid SDK provides a local storage interface to set, retrieve or update an array of user IDs with associated identity vendor details. Prebid SDK will retrieve and pass User IDs and ID vendor details to PBS if values are present in local storage. The main difference between the Prebid API interface and the local storage interface is the persistence of storage of data. Local Storage data will persist across user sessions whereas the Prebid API interface (externalUserIdArray) persists only for the user session. If a vendor's details are passed both in local storage and the Prebid API at the same time, the Prebid API data (externalUserIdArray) will prevail. +Prebid SDK provides a local storage interface to set, retrieve, or update an array of user IDs with associated identity vendor details. It will then retrieve and pass these User IDs to Prebid Server on each auction, even on the next user session. -Prebid SDK Provides five functions to handle User ID details: +Prebid SDK Provides several functions to handle User ID details within the local storage: ```swift public func storeExternalUserId(_ externalUserId: ExternalUserId) @@ -331,7 +441,7 @@ public func removeStoredExternalUserIds() ```swift //Set External User ID -Targeting.shared.storeExternalUserId(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1, ext: ["third" : "01ERJWE5FS4RAZKG6SKQ3ZYSKV"])) +Targeting.shared.storeExternalUserId(ExternalUserId(source: "sharedid.org", identifier: "111111111111", atype: 1)) //Get External User ID let externalUserIdSharedId = Targeting.shared.fetchStoredExternalUserId("sharedid.org") @@ -345,3 +455,63 @@ Targeting.shared.removeStoredExternalUserId("sharedid.org") //Remove All External UserID Targeting.shared.removeStoredExternalUserIds() ``` + +--- + +## Targeting Class Properties and Methods + +There are several other fields app developers may want to set to give bidders additional information about the auction. + +### Targeting Class Properties + +Note that several of the properties noted here are also mentioned above for other use cases, e.g. `subjectToCOPPA`. All properties of the 'Targeting' class are listed here. + +{: .table .table-bordered .table-striped } +| Parameter | Scope | Type | Platform | Description | Example | +| --- | --- | --- | --- | --- | --- | +| storeURL | recommended | string | both | App store URL for an installed app; for Inventory Quality Guidelines 2.1 compliance. Translates to OpenRTB app.storeurl | `https://apps.apple.com/app/id111111111` | +| contentUrl | recommended | string | both | This is the deep-link URL for the app screen that is displaying the ad. This can be an iOS universal link. | | +| publisherName | recommended | string | both | OpenRTB app.publisher.name | "Example, Co." | +| itunesID | recommended | string | both | Translates to OpenRTB app.bundle | "11111111" | +| coppa | optional | integer | objC | Defines whether this content is meant for children. 0=false, 1=true. Defaults to false. | 1 | +| subjectToCOPPA | optional | boolean | swift | Defines whether this content is meant for children. Defaults to false. | `true` | +| sourceapp | optional | string | both | Translates to OpenRTB app.name | "Example App" | +| domain | optional | string | both | Translates to OpenRTB app.domain | "example.com" | +| omidPartnerName | optional | string | both | The [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. | "Google" | +| omidPartnerVersion | optional | string | both | The OMSDK version number for the integration partner. | "1.0" | +| userGender | optional | enum | both | "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown) | "F" | +| userExt | optional | array of key-value pairs | both | This is a dictionary of key-value pairs that forms the user.ext object. Prebid requires user-first party data in user.ext.data, so this should be a dictionary that contains a 'data' key whose value is another dictionary. | { data: { key1: val1, key2: val2 }}| +| subjectToGDPR | discouraged | boolean | ? | Defines whether this request is in-scope for European privacy regulations. See [above](/prebid-mobile/pbm-api/ios/pbm-targeting-ios#gdpr--tcf-eu) for more information. | `true` | +| gdprConsentString | discouraged | string | both | See the [GDPR settings](/prebid-mobile/pbm-api/ios/pbm-targeting-ios#gdpr--tcf-eu) section above. | | +| purposeConsents | discouraged | string | both | See the [GDPR settings](/prebid-mobile/pbm-api/ios/pbm-targeting-ios#gdpr--tcf-eu) section above. | | + +### Targeting Class Methods + +All of the targeting class methods have been mentioned above in the context of First Party Data section above. + +--- + +## Arbitrary OpenRTB + +(requires SDK v2.2.1) + +While there are many specific methods for adding data to the request detailed in +this document, OpenRTB is big and it moves quickly. To cover scenarios not already covered by an existing method, +Prebid SDK Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the [OpenRTB structure](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md) -- it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server. + +There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed. + +```swift +//global invocation +adUnitConfig.setOrtbConfig("{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}") +``` + +```swift +//ad unit / impression-level +adUnit.setOrtbConfig("{\"ext\":{\"gpid\":\"abc123"}}\") +``` + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK iOS integration](/prebid-mobile/pbm-api/ios/code-integration-ios.html) diff --git a/prebid-mobile/prebid-mobile-getting-started.md b/prebid-mobile/prebid-mobile-getting-started.md index 85f0e453f7..4fd9c353fc 100644 --- a/prebid-mobile/prebid-mobile-getting-started.md +++ b/prebid-mobile/prebid-mobile-getting-started.md @@ -5,22 +5,36 @@ description: Getting Started with Prebid Mobile sidebarType: 2 --- - # Getting Started with Prebid Mobile - {:.no_toc} This page gives an overview of steps you need to take, either as an ad ops user or as a developer, to start using Prebid Mobile. -{% capture alertNote %} +{: .alert.alert-info :} If this is your first time working with header bidding, we recommend that you read [What is Prebid?](/overview/intro.html) before diving into Prebid Mobile. -{% endcapture %} - -{% include alerts/alert_note.html content=alertNote %} - TOC {:toc} +## Video Overviews + +{% include vimeo-iframe.html id="945961210" title="Prebid Mobile Impression Flow" %} + +Further Content: + +- [Transcript of this video](/prebid-mobile/prebid-mobile-video-flow.html) +- [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html) +- [All videos](/overview/all-videos.html) + +{% include vimeo-iframe.html id="948475423" title="Prebid Mobile Planning Guide" %} + +Further Content: + +- [Transcript of this video](/prebid-mobile/prebid-mobile-video-planning.html) +- [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html) +- [Prebid Managed Services](https://prebid.org/product-suite/managed-services/) +- [All videos](/overview/all-videos.html) + ## Set Up Prebid Server Before you begin using Prebid Mobile in your apps, you need to prepare your end-to-end system. The first step is to set up your Prebid Server host. Prebid Mobile works in conjunction with Prebid Server to request and receive bids. Here are the options: @@ -34,40 +48,77 @@ Prebid Server is an open source project. This allows you to host your own implem See the [Prebid Server documentation](/prebid-server/overview/prebid-server-overview.html) for more information on [setting up your own server host](/prebid-server/hosting/pbs-hosting.html). -### A note on Accounts +### Accounts and Account Settings + +Several pages and examples in the mobile documentation refer to entering a "Prebid Server Account ID". + +There are actually two important concepts: -Several pages and examples in the mobile documentation refer to entering your "Prebid Server Account ID". +- The Prebid Server "account id" is given by your Prebid Server provider. If you're an app developer running your own Prebid Server, you may not have an account ID at all. +- Each mobile app may have its own "account settings ID". This is used to look up data in Prebid Server like timeout, targeting, and price granularity. It's possible for the "account id" and the "auction settings id" to be the same thing, but this is not always the case. -In actuality, an `account ID` is just the name of the “top-level” stored request as described on the [Prebid Server Stored Request page](/prebid-server/features/pbs-storedreqs.html). +Work with your Prebid Server team to determine which scenario to implement: -By convention, most Prebid Server host companies define the top level stored request ID as the account ID they assign to the publisher. -This is a convenient convention since publishers generally set the same timeout and price granularity across all apps. -But it may not be the case for your Prebid Server host company, so please check with them. -If you’re hosting your own Prebid Server, this value can be whatever value you wish, not necessarily an account ID. +- keep "account ID" and "account settings ID" the same. +- establish separate "account ID" and "account settings ID" + +See the "integration" pages for each platform for details on how to set up both scenarios. ## Configure Prebid Server -After you've registered with your chosen Prebid Server host, you need to create at least one Prebid Server bidder configuration in a [stored request](/prebid-server/features/pbs-storedreqs.html). Each stored request configuration contains a list of bidders and their parameters. The configuration will be in the form of a JSON structure, similar to this: +### Auction Setting IDs / Top-Level Stored Requests + +Working with your Prebid Server host, you will need to create at least one "account settings" block. Prebid Server calls this a [top-level stored request](/prebid-server/features/pbs-storedreqs.html). Each top-level stored request contains parameters that are global to the entire auction, not just +one adunit. The configuration will be in the form of a JSON structure that will be merged into the OpenRTB. Something like this: + +```json +{ + "cur": [ + "EUR" + ], + "ext": { + "prebid": { + "cache": { + "bids": {} + }, + "targeting": { + "pricegranularity": "dense", + "includewinners": true, + "includebidderkeys": true, + "includeformat": true + } + } + } +} +``` + +Your Prebid Server team should be able to help you decide which parameters are needed and how to get them into Prebid Server. + +### Config IDs / Impression-Level Stored Requests + +Again, working with your Prebid Server host, there are likely to be many adunit configurations. Prebid Mobile calls this thing a "Config ID", while Prebid Server calls it an [impression-level stored request](/prebid-server/features/pbs-storedreqs.html). Each stored request configuration contains a list of bidders and their parameters. The configuration will be in the form of a JSON structure that will be merged into the OpenRTB `imp` element. Something like this: ```json -[ - { - "bidder": "appnexus", +{ + "ext": { + "prebid": { + "bidder": "bidderA", "params": { - "placementId": 13144370 + "placementId": 1111111111 } } -] + } +} ``` -The preceding is an example "impression-level stored request" using AppNexus as the bidder. The parameters you need to set differ for each bidder. See [Bidder Parameters](/prebid-server/developers/add-new-bidder-go.html) for a full list of parameters for available Prebid Server bidders. - -Each block of JSON like this is called a "stored request" and gets an ID called a "stored request ID". This ID is then programmed into an adslot using the iOS or Android SDKs. Doing it this way allows the publisher to change bidders and parameters without +Each block of JSON like this is called a "stored request" and gets an ID called a "stored request ID". This ID is then linked to an adslot using the iOS or Android SDKs, which refer to it as a "Config ID". Doing it this way allows the publisher to change bidders and parameters without having to change the app. -### Testing with stored configurations +In general, the recommendation is to create different imp-level stored request for each adunit in your app so that you can manage the bidders and their inventory parameters separately. -If you want to verify the SDK integration with test placements, you can add some [Stored Responses](https://docs.prebid.org/troubleshooting/pbs-troubleshooting.html#stored-responses) to your Prebid Server: +### Testing with stored responses + +If you want to verify the SDK integration with test placements, you can add some [Stored Responses](/troubleshooting/pbs-troubleshooting.html#stored-responses) to your Prebid Server: 1. Work with your Prebid Server provider to install the [Mobile Test Stored Requests](https://github.com/prebid/prebid-mobile-ios/tree/master/Example/PrebidDemo/stored-configs/stored-impressions) and [Mobile Test Stored Responses](https://github.com/prebid/prebid-mobile-ios/tree/master/Example/PrebidDemo/stored-configs/stored-responses). (Note: stored "impressions" are a special case of stored "requests" - your Prebid Server provider will know what to do.) 1. Confirm that the bid prices in the stored responses reflects what you want to test. If you're using an ad server, you'll need line items set up that reflect the test bid CPMs and your price granularity setup. @@ -83,33 +134,20 @@ If you want to verify the SDK integration with test placements, you can add some Ad ops users configure the primary ad server with Prebid Mobile line items targeted to key/values. - [Set Up Line Items for Google Ad Manager](/adops/step-by-step.html) +- [Price Granularity](/adops/price-granularity.html) Additional details to help you ensure your line items are set up to target bid prices at an appropriate level of granularity. ## Developers - Using the SDK To begin using Prebid Mobile follow the instructions for the respective platforms and integration approach: -- [iOS Code Integration]({{site.github.url}}/prebid-mobile/pbm-api/ios/code-integration-ios.html) -- [Android Code Integration]({{site.github.url}}/prebid-mobile/pbm-api/android/code-integration-android.html) +- [iOS Code Integration](/prebid-mobile/pbm-api/ios/code-integration-ios.html) +- [Android Code Integration](/prebid-mobile/pbm-api/android/code-integration-android.html) ## Additional Information The following resources are available for further information on working with Prebid Mobile: -### Ad Ops - -- [Price Granularity](/adops/price-granularity.html) Additional details to help you ensure your line items are set up to target bid prices at an appropriate level of granularity. - -### Mobile Developers - -#### Targeting Parameters - -Learn about the parameters available in the Prebid SDK - -- [iOS Targeting Parameters](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html) Learn about the parameters available in the iOS Prebid Mobile SDK. -- [Android Targeting Parameters](/prebid-mobile/pbm-api/android/pbm-targeting-params-android.html) Learn about the parameters available in the Android Prebid Mobile SDK. - -#### GDPR - -Prebid Mobile provides APIs for app publishers in support of the [IAB Europe Transparency & Consent Framework](https://www.iab.com/topics/consumer-privacy/gdpr/). +## Futher Reading -For general information on these APIs see [Prebid Mobile Guide to Privacy Regulation]({{site.baseurl}}/prebid-mobile/prebid-mobile-privacy-regulation.html). +- [How Prebid Server works with Prebid SDK](/prebid-server/use-cases/pbs-sdk.html) +- [Prebid Mobile FAQ](https://docs.prebid.org/faq/prebid-mobile-faq.html) diff --git a/prebid-mobile/prebid-mobile-privacy-regulation.md b/prebid-mobile/prebid-mobile-privacy-regulation.md index 025f1b4dc5..878bc6cfe9 100644 --- a/prebid-mobile/prebid-mobile-privacy-regulation.md +++ b/prebid-mobile/prebid-mobile-privacy-regulation.md @@ -72,27 +72,8 @@ To ensure proper monetization and relevant targeting, the SDK should be enabled ### Code Samples -#### iOS - -```swift -Targeting.shared.subjectToGDPR = false; - -Targeting.shared.gdprConsentString = "BOMyQRvOMyQRvABABBAAABAAAAAAEA"; - -Targeting.shared.purposeConsents = "100000000000000000000000"; - -let deviceAccessConsent = Targeting.shared.getDeviceAccessConsent(); -``` - -#### Android - -```swift -TargetingParams.setSubjectToGDPR(context, true); - -TargetingParams.setGDPRConsentString("BOMyQRvOMyQRvABABBAAABAAAAAAEA"); - -TargetingParams.setPurposeConsents("101010001"); -``` +- See [iOS Global Parameters](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html) +- See [Android Global Parameters](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) ## California Consumer Privacy Act (CCPA) @@ -114,7 +95,7 @@ Prebid mobile supports the [IAB US Privacy signal](https://iabtechlab.com/standa - Translate notice and opt-out signals into [IAB US Privacy String format](https://iabtechlab.com/standards/ccpa/) - Store IAB US Privacy signal in `UserDefaults` for iOS or `SharedPreferences` for Android for persistent storage allowing access for vendors per IAB recommendations -The job of the Prebid SDK will: +Prebid SDK will: - Read from `UserDefaults` (iOS) or `SharedPreferences` (Android) for US Privacy signal - Prebid SDK will look for the key `IABUSPrivacy_String`, all other key names or spellings will be ignored @@ -123,3 +104,8 @@ The job of the Prebid SDK will: - Not strip any user data or signaling of the request regardless of Notice and Opt out signal It is worth noting Prebid Server will be a passthrough as well and will not validate format or correctness of US Privacy signal nor strip any user data from the request either, even if the presence of an opt out. + +## Further Reading + +- [Prebid Privacy Resources](/support/privacy-resources.html) +- Global parameters [iOS](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html), [Android](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/prebid-mobile-video-flow.md b/prebid-mobile/prebid-mobile-video-flow.md new file mode 100644 index 0000000000..dc80e705b9 --- /dev/null +++ b/prebid-mobile/prebid-mobile-video-flow.md @@ -0,0 +1,100 @@ +--- +layout: page_v2 +title: Video overview of how Prebid Mobile works +description: Video overview of how Prebid Mobile works +sidebarType: 0 +--- + +# Video overview of how Prebid Mobile works + +A step-by-step walkthrough of a typical Prebid Mobile auction. + +{% include vimeo-iframe.html id="945961210" title="Prebid Mobile Impression Flow" %} + +Further Content: + +- [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html) +- [All videos](/overview/all-videos.html) + +Related Videos: + +- [Introduction to Prebid Mobile](/prebid-mobile/prebid-mobile-video.html) +- [Prebid.js Impression Flow](/prebid/prebidjs-flow-video.html) +- [Prebid Mobile Planning Guide](/prebid-mobile/prebid-mobile-video-planning.html) + +## Transcript + +### Introduction + +This video explains how Prebid Mobile works by walking through a typical Prebid Mobile Auction. + +Prebid Mobile is Prebid’s solution for header bidding in the mobile app environment. + +For a high level introduction to the Prebid Mobile product and the benefits it offers app developers, check out our Introduction to Prebid Mobile video. For context on Prebid conventions and terminology, we also recommend watching the Prebid.js Impression Flow video, which walks through a standard Prebid.js auction for websites. The links to these videos are in the notes below. + +Prebid Mobile allows app developers to access demand from multiple programmatic advertising marketplaces simultaneously. It can serve ads with or without a primary ad server and is compatible with every major mobile app ad serving solution. + +### Prebid Mobile Architecture + +Let’s start by covering the basic structure of the Prebid Mobile solution. + +The Prebid Mobile solution consists of two components that work closely together: the Prebid SDK and Prebid Server. SDK stands for “Software Development Kit”, which is a type of module that can be installed into an app and has specific functionality. The Prebid SDK is responsible for communicating between the app, Prebid Server, and the primary ad server, if one exists. It also helps to render ads from Prebid Mobile demand sources. + +Prebid Server is responsible for running the auction among demand partners. It allows multiple demand partners to bid simultaneously on each ad opportunity, and it’s where inventory and auction controls are set. + +Prebid Server is open source code. To use it, you’ll need to set up your own hosting server or find a partner to manage the hosting server for you. + +For more information on this process, check out our other video on planning a Prebid Mobile integration. + +### Impression Flow + +With the basics in place, let’s now walk through a Prebid Mobile auction step-by-step. +Like in any Prebid Server auction, the process can be broken down into three stages: Pre-Auction, Auction, and Post-Auction. + +#### Pre-Auction + +As always, we start with Pre-Auction + +In the Pre Auction Phase, the Prebid SDK is initialized. When the development team installs the SDK, they include an auction settings ID, which identifies the entire Prebid Mobile instance. They will also tag each ad slot with a config ID, which allows Prebid Server to look up information about the ad unit and run an auction. + +When an app screen loads that contains ad slots, the SDK will prepare a request for ads. It gathers the auction settings ID and config IDs for each of the page’s ad slots, along with other client-side data like app and device identifiers, first party data, and privacy consent data such as a consent string. + +The SDK then calls Prebid Server with an ad request. When Prebid Server receives the request, it uses the auction settings ID and config IDs to look up data. + +Prebid Mobile stores ad unit data like media type parameters and bidder configurations in a database on the server side. Prebid Mobile’s server-side architecture makes it easy for the monetization team to change auction settings without needing to update the app. + +In the Prebid Server documentation, the auction settings ID is sometimes called the “top-level stored request ID”, while config IDs are called “impression-level stored request IDs”. + +As noted a moment ago, PBS uses these IDs to look up data. Specifically, the account ID (or auction settings ID) is used to look up settings like price granularity, the auction timeout, and ad server targeting settings. + +The config IDs are used to gather information about the ad unit, such as the ad format and the list of bidders enabled to bid on the ad unit. + +During this pre-auction stage, Prebid Server also looks up other data like the device location and applies any location-specific privacy controls. It’s also able to perform extra optional tasks like establishing a price floor to govern the auction. + +Prebid Mobile stores ad unit data like media type parameters and bidder configurations in a database on the server side. Prebid Mobile’s server-side architecture makes it easy for the monetization team to change auction settings without needing to update the app. In the Prebid Server documentation, the auction settings ID is sometimes called the “top-level stored request ID”, while config IDs are called “impression-level stored request IDs”. + +When an app screen loads that contains ad slots, the SDK will prepare a request for ads. It gathers the auction settings ID and config IDs for each of the page’s ad slots, along with other client-side data like app and device identifiers, first party data, and privacy consent data such as a consent string. + +#### Auction + +With the Pre-Auction data-gathering complete, Prebid Server begins the Auction stage. +It makes OpenRTB bid requests to bidders, who evaluate the impression opportunities and return bid responses. +#### Post-Auction + +When either all of the bidders have responded or the bid timeout period has elapsed, Prebid Server closes the auction, and the Post-Auction stage begins. + +Prebid Server parses the bid responses, and may perform validations such as enforcing price floors, if they exist. + +It will cache data including the ad creative for valid bids and prepare a response to the SDK. + +Prebid Server then responds to the Prebid SDK with an OpenRTB response that includes bid prices and ad server targeting key-value pairs. + +When the Prebid SDK receives the response from Prebid Server, it works with the ad serving or mediation stack to complete the ad decisioning process. The bids that Prebid Mobile has gathered will compete with other demand, such as ad networks or direct campaigns for the opportunity to serve. The details of how this process works depends on your ad serving and mediation setup. + +Some ad stacks construct a sequential waterfall of eligible demand sources, while others use auctions. In general, we recommend using an ad stack that allows Prebid demand to compete using real time bid prices instead of static estimates. Prebid’s ability to bid dynamically into the ad stack helps publishers and app developers maximize CPMs and fill rates. Prebid Mobile is flexible and works with all of the major mobile app ad serving and mediation solutions. + +Once the ad server or mediation solution has made a decision about whose ad should serve, it’s time to render the ad. The specific details of ad rendering also depend on your app and ad stack. + +Some solutions use the Prebid Universal Creative that is commonly used for web integrations, while others use ad rendering capabilities that are built into Prebid SDK, the ad server SDK, or an SDK from a demand partner or rich media vendor. Prebid Mobile is flexible enough to work with any common rendering solution. + +That’s how ads are served with Prebid Mobile. To learn more about Prebid Mobile, check out the links included in the notes below. diff --git a/prebid-mobile/prebid-mobile-video-planning.md b/prebid-mobile/prebid-mobile-video-planning.md new file mode 100644 index 0000000000..cc22f8c06b --- /dev/null +++ b/prebid-mobile/prebid-mobile-video-planning.md @@ -0,0 +1,105 @@ +--- +layout: page_v2 +title: A video guide to planning your first Prebid Mobile integration +description: A video guide to planning your first Prebid Mobile integration +sidebarType: 0 +--- + +# Planning a Prebid Mobile integration + +A video guide to planning your first Prebid Mobile integration. + +{% include vimeo-iframe.html id="948475423" title="Prebid Mobile Planning Guide" %} + +Further Content: + +- [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html) +- [Prebid Managed Services](https://prebid.org/product-suite/managed-services/) +- [All videos](/overview/all-videos.html) + +Related Videos: + +- [Introduction to Prebid Mobile](/prebid-mobile/prebid-mobile-video.html) +- [Prebid.js Impression Flow](/prebid/prebidjs-flow-video.html) +- [Prebid Mobile Impression Flow](/prebid-mobile/prebid-mobile-video-flow.html) + +## Transcript + +### Introduction + +This video is a guide to planning an integration of Prebid Mobile. It focuses on the decisions that monetization, ad ops, and development teams should make collaboratively before beginning the technical process of implementing Prebid Mobile. + +This video assumes you have a good grasp on what Prebid Mobile does and how it works. For a high-level introduction to the Prebid Mobile solution, we recommend the Introduction to Prebid Mobile. For a more detailed look at how Prebid Mobile monetizes mobile app ad slots, check out the Prebid Mobile Impression Flow video. You can find the links to these videos in the notes below. + +This video will talk about the planning required to set up the two main components of Prebid Mobile: the Prebid SDK and Prebid Server. + +To set up Prebid Mobile, you’ll need to build the Prebid SDK into your application and configure it with IDs that will define auction settings instances and ad slots. You’ll also need to set up Prebid Server to run on a hosting server and configure it to run auctions for requests that Prebid SDK will make from the mobile app. +### Prebid SDK Planning + +Let’s start with the Prebid SDK. The Prebid SDK acts as the interface between the app’s ad slots and Prebid Server. When an app screen loads, Prebid SDK will make a request to Prebid Server that contains data that Prebid Server and bidders will use. + +There are five key types of data transmitted in an ad request from Prebid SDK: an account ID, an auction settings ID, a config ID, first-party data, and consent data. + +Account ID is used to identify your requests to the Prebid Server instance that is responsible for running your auctions. If you work with a managed service provider to maintain your Prebid Server infrastructure, the ID will be used to separate your data from the provider’s other customers’ data. + +The auction settings ID is used by Prebid Server to determine auction-level settings like bid timeout and ad server targeting. + +Config IDs are ad-unit level parameters that control the settings for a specific ad slot, including the ad slot characteristics and bidder selection. + +First party data, also called targeting data, is free-form data that you can use to enrich your ad requests with additional data that is valuable to bidders. + +Consent data relates to privacy regulations that apply to users in many regions of the world. Prebid SDK is able to obtain consent data from your Consent Management Platform and transmit it to Prebid Server. On the Prebid Server side, you’ll be able to configure how the advertising auction reacts to consent data it receives. + +Prebid Mobile has powerful tools for managing privacy and consent. How you use those tools is up to you. It’s important to develop your own strategy concerning privacy and regulatory compliance. + +When you install the Prebid SDK into your app, you’ll assign an account ID, auction settings ID, and config IDs to the app and ad placements, and you’ll set up specific first party data to be passed. It’s important to think carefully about how you want to set this up, because you would need to update the app in order to change this information. Once the SDK is installed and passing IDs and first party data in requests, your day-to-day management of Prebid Mobile doesn’t require app modifications. This is because Prebid Mobile has a server-side architecture that houses the auction and ad unit-level configurations within Prebid Server. + +Next, we’ll examine each of the Auction Settings, and First Party Data in detail. + +### Auction Settings ID + +The auction settings ID links to an object inside Prebid Server called a top-level stored request, which contains configuration parameters that apply to the entire auction. These parameters include the bid timeout, price granularity, and ad server targeting settings. + +Each time Prebid Server receives a request from Prebid SDK, it expects that request to include one auction settings ID. Many app developers use a single auction settings ID for all of their mobile app inventory, while others break up the inventory more granularly. The primary reasons to use separate auction settings are to be able to customize the bid timeout or a user privacy settings for specific apps or app screens. This increased flexibility can be useful, but it comes at the cost of greater complexity in managing configurations. + +### Config ID + +Next let’s discuss the config ID. + +The config ID links to an object inside Prebid Server called an impression-level stored request, which contains ad-unit level data, which includes bidder configurations and can include details about supported ad formats. + +Bidder parameters are one of the most important parts of any Prebid Ad Unit. By including a bidder’s parameters in the ad unit, you’re making that bidder eligible to compete for the ad unit’s impressions. Further, each bidder requires a proprietary set of ad unit identifiers and other data. Bidder params are where this bidder-specific data lives. + +A separate config ID is used for each ad placement on the app screen, so Prebid Server will expect to receive one or more config IDs in ad requests from the Prebid SDK. You'll coordinate with your Prebid Server team to define these IDs. + +When you set up the Prebid SDK, you can use a streamlined setup that uses relatively few config IDs, or a very detailed one that uses many config IDs to differentiate ad placements by position, screen type, app, and other dimensions. Using many unique config IDs gives you more flexibility in reporting and yield optimization, but can be difficult to manage operationally. Using few config IDs is the opposite: reporting and configuration is simple, but the power and the flexibility of your setup is limited. For example, let’s say you want to add a particular bidder to just one highly specific ad placement. To do so, you’d need to give that placement its own config ID. + +For many app developers, it makes sense to create a Prebid Mobile config ID mapping that matches your ad server ad units. This way, you don’t need to keep track of multiple inventory segmentation schemes, and the ad server scheme usually strikes a healthy balance between flexibility and ease of use. + +Before you start implementing your config ID setup, it’s smart to talk to your header bidding partners. Many bidders also require ad slot identifiers in the the bidder parameters section of the impression-level stored request. These identifiers help bidders understand where the impression is coming from, and bidders may have preferences regarding ad slot identification. Similarly, some Prebid Managed Services include algorithmic yield management features that rely on config IDs to optimize parameters like bid timeout, bidder selection, and price floors. + +### First Party Data + +Requests to Prebid Server can also include first party data. First party data is a wide category that can include contextual information about the app or non-personally-identifiable user data like seller-defined audiences. Like with config IDs, a good starting point is to send to Prebid Server the first party data that you already send in requests to your primary ad server. You can then take things a step further by asking your bidder partners and managed service provider for advice on what first party data signals to pass. + +Once you’ve made decisions about how to set inventory identifiers and first party data, you’ll be ready to move forward with integrating the Prebid SDK. Visit docs.prebid.org for integration documentation for the major platforms and ad stacks. + +### Prebid Server Planning + +Now let’s move to the server side. We’ll explain how to plan a Prebid Server integration. + +As we’ve said, Prebid Server receives requests from the Prebid SDK that contains auction settings IDs and config IDs and runs an auction among bidders, then responds to the Prebid SDK with the auction results. + +Prebid Server is code that the Prebid community has developed to run advertising auctions in the cloud. Anybody is welcome to use it, but they must set up their own servers to run the solution. + +Running an instance of Prebid Server is much like operating an OpenRTB marketplace. The servers must be able to process large numbers of ad requests originating from devices around the globe and run auctions that capture as many bids from bidders as possible. The servers must be both powerful and efficient. Estimating traffic volumes and managing server capacity is critically important to make sure that every ad request can be processed without wasting resources. + +Additionally, Prebid Server setup will need tools for managing auction and ad unit configurations, which can change often as you fine tune your header bidding setup. For example, adding a new bidder means changing the ad unit configuration. + +If your organization has experience managing scaled ad serving infrastructure and is able to develop configuration interfaces, then running Prebid Server on servers that you manage directly could be a good choice. + +An alternative option is to hire a company that specializes in this work. The Prebid community includes several companies that have developed Prebid Managed Services that provide products and services that include Prebid Server hosting as well as configuration tools and analytics. For more information about Prebid Managed Services, visit the link in the description below. + +### Outro + +That’s all for this guide on Prebid Mobile planning. For more information on Prebid Mobile, check out the reference documentation and docs.prebid.org. diff --git a/prebid-mobile/prebid-mobile.md b/prebid-mobile/prebid-mobile.md index 42ca24320d..b7553ea47f 100644 --- a/prebid-mobile/prebid-mobile.md +++ b/prebid-mobile/prebid-mobile.md @@ -101,7 +101,7 @@ Supported Ad Servers: GAM. 1. Prebid Server constructs an OpenRTB bid request and passes it to the demand partners. Each demand partner returns a bid response to Prebid Server. The bid response includes the bid price and the creative content. 1. Prebid Server sends the bid responses to Prebid Mobile. 1. Prebid Mobile sets key/value targeting for each ad slot through the primary ad server mobile SDK. -1. The primary ad server SDK sends the ad request enriched with targeting keywords of the wiining bid. +1. The primary ad server SDK sends the ad request enriched with targeting keywords of the wining bid. 1. The primary ad server responds with an ad. If the line item associated with the Prebid Mobile bid wins, the primary ad server returns the Prebid Universal Creative (PUC) to the ad server's SDK. 1. The primary ad server SDK starts the rendering recived ad markup. 1. The PUC fetches creative content of the winning bid from the Previd Cache and renders it. @@ -137,7 +137,7 @@ Supported Ad Servers: AdMob, MAX. 1. The primary ad server responds with a mediation chain. 1. The Primary Ad Server SDK runs the Waterfall. 1. If the mediation item contains the name Prebid Adatper it instantiates the respoctive class. -1. [OPTIONAL] adaters checks the wheather the Line Item's targeting keywors match the bid targeting keywords +1. [OPTIONAL] adaters checks the wheather the Line Item's targeting keywords match the bid targeting keywords. 1. Adapter renders a wiining bid cached in the SDK. Note: passing the targeting keywords to the ad server depends on the server's ability to target line items. If the server doesn't provide such a feature, Prebid SDK doesn't enrich an ad request with targeting info. But activation of a line item with the proper price still works. The implementation details of such selection you can find in the respective integration guide. @@ -146,46 +146,45 @@ Note: passing the targeting keywords to the ad server depends on the server's ab ### Prebid Server -You must have a Prebid Server account in order to use Prebid Mobile. Prebid Server is a server-based host that communicates bid requests and responses between Prebid Mobile and demand partners. +You must have a Prebid Server available in order to use Prebid Mobile. Prebid Server is a server-based host that communicates bid requests and responses between Prebid Mobile and demand partners. -To set up your Prebid Server account for Prebid Mobile, refer to [Getting Started with Prebid Mobile]({{site.github.url}}/prebid-mobile/prebid-mobile-getting-started.html). +To set up your Prebid Server account for Prebid Mobile, refer to [Getting Started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html). ### Android Follow these steps to integrate the Prebid SDK: -1. If integrating into an ad server, create line items specific for rendering (line items for rendering API are unique and do not coincide with the standard Prebid SDK line items): - - [GAM Original API](../adops/step-by-step.html) - - [GAM Rendering API](../adops/mobile-rendering-gam-line-item-setup.html) - - [AdMob](../adops/mobile-rendering-admob-line-item-setup.html) - - [MAX](../adops/mobile-rendering-max-line-item-setup.html) 1. [Integrate Prebid SDK](pbm-api/android/code-integration-android.html) into your project. -1. Add prebid's ad units to your app respectively to the monetization scenario: +1. Define [global integration and targeting properties](/prebid-mobile/pbm-api/android/pbm-targeting-params-android.html). +1. Add Prebid's ad units to your app respectively to the monetization scenario: - [GAM Original API](pbm-api/android/android-sdk-integration-gam-original-api.html) - [Custom in-app bidding](modules/rendering/android-sdk-integration-pb.html) integration without primary ad server. - [GAM Rendering API](modules/rendering/android-sdk-integration-gam.html) as a primary ad server - [AdMob](modules/rendering/android-sdk-integration-admob) as a primary ad server. - [AppLovin MAX](modules/rendering/android-sdk-integration-max.html) as a primary ad server. - -1. Actualize the [integration and targeting](pbm-api/android/pbm-targeting-params-android.html) properties. +1. If integrating into an ad server, create line items specific for rendering (line items for rendering API are unique and do not coincide with the standard Prebid SDK line items): + - [GAM Original API](../adops/step-by-step.html) + - [GAM Rendering API](../adops/mobile-rendering-gam-line-item-setup.html) + - [AdMob](../adops/mobile-rendering-admob-line-item-setup.html) + - [MAX](../adops/mobile-rendering-max-line-item-setup.html) ### iOS Follow these steps to integrate the rendering API: -1. If integrating into an ad server, create line items specific for rendering (line items are uniqe for the Rendering Module and do not cooicide with the standard Prebid SDK line items): - - [GAM Original API](../adops/step-by-step.html) - - [GAM](../adops/mobile-rendering-gam-line-item-setup.html) - - [AdMob](../adops/mobile-rendering-admob-line-item-setup.html) - - [MAX](../adops/mobile-rendering-max-line-item-setup.html) 1. [Integrate Prebid SDK](pbm-api/ios/code-integration-ios.html). +1. Define [global integration and targeting properties](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html). 1. Add prebid's ad units to your app respectively to the monetization scenario: - [GAM Original API](pbm-api/ios/code-integration-ios.html) - [Custom in-app bidding](modules/rendering/ios-sdk-integration-pb.html) integration without a primary ad server. - [GAM Rendering API](modules/rendering/ios-sdk-integration-gam.html) as a primary ad server. - [AdMob](modules/rendering/ios-sdk-integration-gam.html) as a primary ad server. - [AppLovin MAX](modules/rendering/ios-sdk-integration-max.html) as a primary ad server. -1. Actualize the [integration and targeting](pbm-api/ios/pbm-targeting-params-ios.html) properties. +1. If integrating into an ad server, create line items specific for rendering (line items are uniqe for the Rendering Module and do not cooicide with the standard Prebid SDK line items): + - [GAM Original API](../adops/step-by-step.html) + - [GAM](../adops/mobile-rendering-gam-line-item-setup.html) + - [AdMob](../adops/mobile-rendering-admob-line-item-setup.html) + - [MAX](../adops/mobile-rendering-max-line-item-setup.html) ## Additional References @@ -198,3 +197,8 @@ Currently Prebid Mobile SDK doesn't offer direct analytics capabilities. While w - Generate analytics from the ad server, as key metrics are available there if the line items are broken out by bidder. - Integrate an analytics package directly into the app. You may have one already that can accomodate header bidding metrics. +- Utilize a server-side [analytics module for Prebid Server](/prebid-server/developers/pbs-build-an-analytics-adapter.html). + +## Further Reading + +- [Getting started with Prebid Mobile](/prebid-mobile/prebid-mobile-getting-started.html) diff --git a/prebid-server/developers/add-a-module-go.md b/prebid-server/developers/add-a-module-go.md index 293b478d42..88bd17d86e 100644 --- a/prebid-server/developers/add-a-module-go.md +++ b/prebid-server/developers/add-a-module-go.md @@ -6,7 +6,7 @@ title: Prebid Server | Developers | Adding a Go Module --- # Prebid Server - Adding a Go Module -{: .no_toc} +{:.no_toc} - TOC {:toc } @@ -18,7 +18,7 @@ This document details how to make a module for PBS-Go. You will want to be familiar with the following background information: - the [module overview](/prebid-server/developers/add-a-module.html) -- the [PBS-Go Modularity Tech Spec](https://docs.google.com/document/d/1CmamniQpwcI3p0_rHe2F17zV4sEhzpOdrqU7zuZVZ_I/edit?usp=sharing) +- the [PBS-Go Modularity Tech Spec](https://docs.google.com/document/d/1cr1CJfkJqXVtNrlHulmg_R-9TJCDYjsb/edit#heading=h.gjdgxs) ### Contributing @@ -286,7 +286,7 @@ Unit tests are required. Each implemented hook must be at least 90% covered by u ### How to build and install a module -Read about the module building in the [building section](https://docs.google.com/document/d/1CmamniQpwcI3p0_rHe2F17zV4sEhzpOdrqU7zuZVZ_I/edit#heading=h.o8dv0neoq4xm) of the technical specification. +Read about the module building in the [building section](https://docs.google.com/document/d/1cr1CJfkJqXVtNrlHulmg_R-9TJCDYjsb/edit#heading=h.gjdgxs) of the technical specification. ## Analytics Adapters and Modules diff --git a/prebid-server/developers/add-a-module-java.md b/prebid-server/developers/add-a-module-java.md index c9f474e84c..90aaa31aa7 100644 --- a/prebid-server/developers/add-a-module-java.md +++ b/prebid-server/developers/add-a-module-java.md @@ -205,6 +205,43 @@ To support modules that need to obtain information about the local CPU environme cpuLoadAverageStats.getCpuLoadAverage(); // returns a float ``` +#### Interaction with Activity Infrastructure + +For modules that need to check whether certain activity is allowed, follow the next example: + +```java +public class MyHook implements Hook { + + private final UserFpdActivityMask userFpdActivityMask; // inject this bean using Spring if needed + + // ... + + @Override + public Future> call(PAYLOAD payload, CONTEXT invocationContext) { + // ... + + final AuctionContext auctionContext = invocationContext.auctionContext(); + final ActivityInfrastructure activityInfrastructure = auctionContext.getActivityInfrastructure(); + + final ActivityInvocationPayload activityInvocationPayload = BidRequestActivityInvocationPayload.of( + ActivityInvocationPayloadImpl.of( + ComponentType.GENERAL_MODULE, // or ComponentType.RTD_MODULE + "MODULE NAME"), + auctionContext.getBidRequest()); + + final boolean isTransmitUfpdAllowed = activityInfrastructure.isAllowed( + Activity.TRANSMIT_UFPD, // You can check for any activity that interest you + activityInvocationPayload); + + // Then you can use activity masks for Device and User if needed + final User maskedUser = userFpdActivityMask.maskUser(user, !isTransmitUfpdAllowed, false); + final Device maskedDevice = userFpdActivityMask.maskDevice(device, !isTransmitUfpdAllowed, false); + + // ... + } +} +``` + ### Configuration It's possible to define default module configuration which can be read by the module at PBS startup. Please see the [Configuration](https://docs.google.com/document/d/1VP_pi7L5Iy3ikHMbtC2_rD5RZTVSc3OkTWKvtRS5x5Y/edit#heading=h.mh3urph3k1mk) section of the technical specification. diff --git a/prebid-server/developers/add-a-module.md b/prebid-server/developers/add-a-module.md index c6263e096b..010e7cbc2d 100644 --- a/prebid-server/developers/add-a-module.md +++ b/prebid-server/developers/add-a-module.md @@ -2,7 +2,6 @@ layout: page_v2 sidebarType: 5 title: Prebid Server | Developers | Adding a Module - --- # Prebid Server - Adding a Module @@ -11,7 +10,7 @@ title: Prebid Server | Developers | Adding a Module This document guides you through the process of developing a module for host companies to plug into their instance of Prebid Server. We encourage you to look at existing modules for working examples. You can also ask us questions by [submitting a GitHub issue](https://github.com/prebid/prebid-server/issues/new). -* TOC +- TOC {:toc } ## Overview @@ -142,6 +141,7 @@ to the PBS host company. Examples: If your module either utilizes or supplies user-level data like User First Party Data or precise geographic information, it must adhere to the framework supplied by the [Activity Controls](/prebid-server/features/pbs-activitycontrols.html). For instance: + - if your module is going to supply user-level data (e.g. "job title") to bid adapters, it must check permissions for the `enrichUfpd` activity. - if your module is going to forward the entire ORTB request to an endpoint, it must check the `transmitUfpd` and `transmitPreciseGeo` activity permissions. @@ -173,7 +173,7 @@ The details of the implementation depend on the platform. Other rules for open source PBS pull request: - Unit test coverage must exceed 90%. -- A maintainer email address must be provided and be a group, not an individual. e.g. "support@example.com rather than jsmith@example.com +- A maintainer email address must be provided and be a group, not an individual. e.g. rather than ### 10. Write the Module Documentation @@ -184,7 +184,7 @@ create a file in /prebid-server/pbs-modules. You can start by copying one of the - Prerequisites: any necessary account activation, other required modules, etc. - Configuration: both init and runtime - Analytics Tag support -- Privacy Support: disclose whether the module has user privacy implications and support for TCF-EU, TCF-CA, CCPA, MSPA, etc. +- Privacy Support: disclose whether the module has user privacy implications and support for TCF-EU, TCF-CA, CCPA, etc. ### 11. Submit the Pull Requests diff --git a/prebid-server/developers/add-new-bidder-go.md b/prebid-server/developers/add-new-bidder-go.md index e2bcf0c114..a7b395f972 100644 --- a/prebid-server/developers/add-new-bidder-go.md +++ b/prebid-server/developers/add-new-bidder-go.md @@ -29,6 +29,8 @@ Bid adapters are responsible for translating a 'Prebid-flavored' OpenRTB Bid Req OpenRTB Bid Requests contain one or more impression objects, each representing a single ad placement. An impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the impression into multiple calls and merge the responses. +See the [example auction request](/prebid-server/endpoints/openrtb2/auction-request-example.html) to get an idea for what your adapter will receive. + ## Plan Your Bid Adapter The job of your bid adapter is to adapt. You'll need to think about currency, floors, mediatypes, and other details as noted below. diff --git a/prebid-server/developers/add-new-bidder-java.md b/prebid-server/developers/add-new-bidder-java.md index a0c4da4e79..0c9d06e2a5 100644 --- a/prebid-server/developers/add-new-bidder-java.md +++ b/prebid-server/developers/add-new-bidder-java.md @@ -29,6 +29,8 @@ Bid adapters are responsible for translating a 'Prebid-flavored' OpenRTB Bid Req OpenRTB Bid Requests contain one or more impression objects, each representing a single ad placement. An impression may define multiple sizes and/or multiple ad formats. If your bidding server limits requests to a single ad placement, size, or format, then your adapter will need to split the impression into multiple calls and merge the responses. +See the [example auction request](/prebid-server/endpoints/openrtb2/auction-request-example.html) to get an idea for what your adapter will receive. + ## Plan Your Bid Adapter ### Choose A Name diff --git a/prebid-server/developers/module-atags.md b/prebid-server/developers/module-atags.md index f855805fc3..d30754dfc3 100644 --- a/prebid-server/developers/module-atags.md +++ b/prebid-server/developers/module-atags.md @@ -8,29 +8,30 @@ sidebar_entry: /prebid-server/developers/add-a-module.html # Prebid Server - Module Analytics Tags Conventions {: .no_toc} -* TOC +- TOC {:toc } ## Overview -Analytics Tags (aka ‘ATags’) are a log mechanism provided by PBS-core to allow modules +Analytics Tags (aka ‘aTags’) are a log mechanism provided by PBS-core to allow modules to inform analytics adapters about what happened in the request. Use of the Analytics Tag structure is completely optional. It's meant to be used when there are application or reporting reasons for sharing module results. See the [Prebid Server module overview](/prebid-server/developers/add-a-module.html) for background information. This document defines a convention aimed at allowing module developers to create -consistent ATags that can be easily read by analytics adapters. +consistent aTags that can be easily read by analytics adapters. -![Prebid Server ATags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"} +![Prebid Server aTags](/assets/images/prebid-server/module-atags.png){:class="pb-xlg-img"} -1. Modules may return a data structure containing ATags to PBS-Core. -2. PBS-Core adds any ATags to the 'invocation context' data structure. +1. Modules may return a data structure containing aTags to PBS-Core. +2. PBS-Core adds any aTags to the 'invocation context' data structure. 3. Analytics modules have access to the invocation context. ## Analytics Tag Conventions -The general idea is that ATags are a list of module-specific "activities" that have these attributes: +The general idea is that aTags are a list of module-specific "activities" that have these attributes: + - activity name: should be unique within the context of this module. e.g. 'enrich-request' - an overall status - an array of specific results within the activity @@ -41,7 +42,7 @@ The general idea is that ATags are a list of module-specific "activities" that h Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/ortb2-blocking.html): -``` +```json [{ // scenario: response from bidderA blocked on badv for imp=1 activities: [{ @@ -71,7 +72,7 @@ Here's an example from the [ORTB2 Blocking module](/prebid-server/pbs-modules/or The following table contains the field conventions. {: .table .table-bordered .table-striped } -| ATag Attr | Required? | Description | Type | +| aTag Attr | Required? | Description | Type | |---+---+---+---| | activities | yes | One or more activities carried out by the module. | array of objects | | activities .name | yes | Name of the activity. Must be documented and unique within the module. | string | @@ -86,10 +87,9 @@ The following table contains the field conventions. | activities. results. appliedto. request | no | The service examined the entire openrtb request object. This is in case the module updated something not adunit-specific. | boolean | | activities. results. appliedto. response | no | The service examined the entire openrtb response object. This is in case the module updated something not adunit-specific. | boolean | - ## Designing Analytics Tags -ATags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be +aTags are for reporting. Start by considering what the module's doing that consumers might want to display. Each processing stage the module operates in may be reported as a separate activity, or perhaps everything the module does is lumped as one activity. @@ -106,7 +106,7 @@ to report on what percentage of responses from each bidder were being thrown away due to blocking rules. This could have been done by defining a separate 'activity' for each of the 4 types of enforcement, but it was decided to just have one kind of activity ('enforce-blocking') and get the specific details as part of the 'value'. There was no requirement to report on the -outbound part of what the module does, so no ATags are created for that part +outbound part of what the module does, so no aTags are created for that part of the functionality. Once you know what reports are desired, figure out which activity 'results' @@ -123,6 +123,7 @@ Be sure to detail the results in your module documentation so that analytics ada aware of what they can look for. Let them know: + - which activities your module supports - what kind of results to expect - whether the results objects have module-specific `values` @@ -142,7 +143,8 @@ In short, to get analytics tags, you'll need to parse this data structure: Here's an example of the data structured as JSON, though the details of the actual object will differ in PBS-Java and PBS-Go. -``` + +```json "stages": [ { "stage": "raw-auction-request", @@ -227,6 +229,117 @@ of the actual object will differ in PBS-Java and PBS-Go. See the implementation guide for your platform for specific syntax. +## Sending aTags to the client-side + +{: .alert.alert-info :} +PBS-Java only + +The use cases for server-side and client-side analytics are different: + +- Server-side analytics are the only game in town when it comes to App, AMP, DOOH, etc. +- However, when Prebid.js is in use and bidders are split between client-side and server-side, it would be far better if auctions were only logged once. + +This feature allows all relevant data passed to the client from Prebid Server so that client-side analytics can be the one to log the results. +To allow the sharing of these details, there are two conditions: + +1. Server-side account configuration must allow sharing of these details by setting `analytics.allow-client-details: true` +1. The ORTB request must contain `ext.prebid.analytics.options.enableclientdetails: true` + +If both are true, then any and all PBS analytics tags will be copied to the response field ext.prebid.analytics.tags. + +### Client aTag example + +The "pb-ortb-blocking" module at the "processed auction" stage adds the following Analytics Tags (from the ORTB2 blocking module) + +```json +[{ + "activities": [{ + "name": "enforce-blocking", + "status": "success", + "results": [{ + "status": "success-block", + "values": { + "attributes": ["badv"], + "adomain": ["bad.com"] + }, + "appliedto": { + "bidder": "bidderA", + "impids": ["1"] + } + },{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["2","3","4"] + } + }] + }] + +Also, the "vendorA-brand-safety" module at the "all processed bid responses" stage adds these aTags: + +```json +[{ + "activities": [{ + "name": "brand-safety", + "status": "success", + "results": [{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["1,","2","3","4"] + } + }] + }] +``` + +The resulting response with the request ext.prebid.analytics.options.enableclientdetails: true and config analytics.options.enableclientdetails:true would be: + +```json5 +// this is actually a nested object - but aggregated for readablility +"ext.prebid.analytics.tags": [{ + "stage": "processed-auction-request", + "module": "pb-ortb-blocking", + "analyticstags": [{ + "activities": [{ + "name": "enforce-blocking", + "status": "success", + "results": [{ + "status": "success-block", + "values": { + "attributes": ["badv"], + "adomain": ["bad.com"] + }, + "appliedto": { + "bidder": "bidderA", + "impids": ["1"] + } + },{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["2","3","4"] + } + }] + }] +},{ + "stage": "all-processed-bid-responses", + "module": "vendorA-brand-safety", + "analyticstags": [{ + "activities": [{ + "name": "brand-safety", + "status": "success", + "results": [{ + "status": "success-allow", + "appliedto": { + "bidder": "bidderA", + "impids": ["1,","2","3","4"] + } + }] +}] +``` + +It's up to the client-side analytics adapters to be able to parse the module-specific contents of the aTags. + ## Further Reading - [PBS Module Overview](/prebid-server/developers/add-a-module.html) 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 +