` element:** `textContent` of the first `

` element. +3. **`[role="main"]` element:** `textContent` of the first element with `role="main"`. + +Content shorter than 50 characters is skipped. Content longer than 50,000 characters is truncated. + +## Data Injected + +The following object is placed at `ortb2Fragments.global.site.ext.data.c2pa`: + +```json +{ + "manifest_url": "https://api.encypher.com/api/v1/public/prebid/manifest/abc123", + "verified": true, + "signer_tier": "connected", + "signed_at": "2026-04-01T10:00:00Z", + "content_hash": "a1b2c3d4e5f6", + "source": "auto", + "extraction_method": "json-ld" +} +``` + +{: .table .table-bordered .table-striped } + +| Field | Type | Description | +| - | - | - | +| `manifest_url` | String | URL to retrieve the C2PA manifest | +| `verified` | Boolean | `true` if provenance was successfully verified or signed | +| `signer_tier` | String | Signing identity tier (see table below) | +| `signed_at` | String | ISO 8601 timestamp of signing | +| `content_hash` | String | SHA-256 hash of article text | +| `source` | String | How provenance was obtained: `cms`, `cache`, or `auto` | +| `extraction_method` | String | DOM extraction method: `json-ld`, `article-element`, or `role-main` | + +## Signer Tiers + +The `signer_tier` field tells DSPs how the content was authenticated: + +{: .table .table-bordered .table-striped } + +| Tier | Meaning | +| - | - | +| `byok` | Publisher signed with their own key (strongest identity) | +| `connected` | Publisher authenticated with Encypher and signed at publish time | +| `encypher_free` | Content was auto-signed by Encypher at first pageview (no publisher authentication) | +| `local` | Manifest fetched from a local or self-hosted endpoint | + +DSPs can use this field for differential bidding. Content signed by authenticated publishers carries stronger brand-safety guarantees than content attested by a third party at pageview time. + +## Free Tier + +The free tier provides 1,000 unique content signatures per publisher domain per month. Re-requests for the same content (deduped by content hash) do not count against quota. Verification of already-signed content does not count against quota. When the quota is exceeded, the module continues without injecting provenance data (fail-open). + +## Privacy + +The module uses Prebid's `getStorageManager` for localStorage access, which enforces GDPR/TCF consent. If consent is denied, caching is disabled and Path C (auto-sign) is skipped entirely, so no page content leaves the browser. When consent is granted but caching is unavailable, the module falls back to API calls on each page load. Article text sent to the Encypher API for signing is not stored on Encypher's servers. Only content hashes and metadata are persisted. A 2-second timeout ensures the module never blocks the auction. + +## Further Reading + +- [C2PA Specification](https://c2pa.org/specifications/) +- [Encypher Documentation](https://encypher.com/docs) diff --git a/dev-docs/modules/genericAnalyticsAdapter.md b/dev-docs/modules/genericAnalyticsAdapter.md index 201410e70b..e3fe405552 100644 --- a/dev-docs/modules/genericAnalyticsAdapter.md +++ b/dev-docs/modules/genericAnalyticsAdapter.md @@ -15,16 +15,16 @@ This is an analytics adapter that can interface with any backend, meant for publ ### Analytics Options {: .table .table-bordered .table-striped } -| Name | Scope | Type | Description | -|--------------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `handler` | required unless `url` is provided | Function | Custom handler function - [example](#custom-handler) | -| `url` | required unless `handler` is provided | String | Data collection URL | -| `method` | optional | String | HTTP method used to call `url`. Defaults to `'POST'` | -| `batchSize` | optional | Number | Number of events to collect into a single call to `handler` or `url`. Defaults to `1` | -| `batchDelay` | optional | Number | Time (in milliseconds) to wait before calling `handler` or `url` with an incomplete batch (when fewer than `batchSize` events have been collected). Defaults to `100` | -| `events` | optional | Object | Map from event name to a custom format function. When provided, only events in this map will be collected, using the data returned by their corresponding function - [example](#event-formatters) | -| `gvlid` | optional | Number | Global vendor list ID to use for the purpose of GDPR purpose 7 enforcement - see [note](#gdpr) | -| `sampling` | optional | Number | Sampling rate, expressed as a number between 0 and 1. Data is collected only on this ratio of browser sessions. Defaults to `1` | +| Name | Scope | Type | Description | +| :--- | :--- | :--- | :--- | +| `handler` | required unless `url` is provided | Function | Custom handler function - [example](#custom-handler) | +| `url` | required unless `handler` is provided | String | Data collection URL | +| `method` | optional | String | HTTP method used to call `url`. Defaults to `'POST'` | +| `batchSize` | optional | Number | Number of events to collect into a single call to `handler` or `url`. Defaults to `1` | +| `batchDelay` | optional | Number | Time (in milliseconds) to wait before calling `handler` or `url` with an incomplete batch (when fewer than `batchSize` events have been collected). Defaults to `100` | +| `events` | optional | Object | Map from event name to a custom format function. When provided, only events in this map will be collected, using the data returned by their corresponding function - [example](#event-formatters) | +| `gvlid` | optional | Number | Global vendor list ID to use for the purpose of GDPR purpose 7 enforcement - see [note](#gdpr) | +| `sampling` | optional | Number | Sampling rate, expressed as a number between 0 and 1. Data is collected only on this ratio of browser sessions. Defaults to `1` | @@ -125,7 +125,7 @@ Example request payload: { "eventType": "bidRequested", "args": { - "bidderCode": "appnexus", + "bidderCode": "bidderA", "auctionId": "db4edde6-ee66-4779-b7ed-c7295d3e3c49", "bidderRequestId": "3cf3eaf48bd5f48", "uniquePbsTid": "1565fd02-d4fd-4369-bf8e-0dee2a00aca5", @@ -189,12 +189,12 @@ Example request payload: [ { "auctionId": "e41e3fcb-6209-4995-b0be-2aed21a8bdf6", - "bidder": "appnexus", + "bidder": "bidderA", "type": "REQUEST" }, { "auctionId": "e41e3fcb-6209-4995-b0be-2aed21a8bdf6", - "bidder": "appnexus", + "bidder": "bidderA", "type": "RESPONSE" } /* ... */ diff --git a/dev-docs/modules/geoedgeRtdProvider.md b/dev-docs/modules/geoedgeRtdProvider.md index 944cf0f5bc..6f734d926c 100644 --- a/dev-docs/modules/geoedgeRtdProvider.md +++ b/dev-docs/modules/geoedgeRtdProvider.md @@ -74,7 +74,7 @@ To view an integration example: 1. in your cli run: ```bash - gulp serve --modules=appnexusBidAdapter,geoedgeRtdProvider + gulp serve --modules=msftBidAdapter,geoedgeRtdProvider ``` 2. in your browser, navigate to: diff --git a/dev-docs/modules/gppControl_usnat.md b/dev-docs/modules/gppControl_usnat.md index df2853e3c4..bb84aabfe9 100644 --- a/dev-docs/modules/gppControl_usnat.md +++ b/dev-docs/modules/gppControl_usnat.md @@ -32,6 +32,28 @@ Prebid functionality created to address regulatory requirements does not replace This module activates if the `gpp` object in the consent management configuration section exists and the consentManagementGpp module exists. See that [module's documentation](/dev-docs/modules/consentManagementGpp.html) for parameter definitions. This module does **not** work with static GPP section 7 strings provided in the first-party data `regs.gpp` object, but **does** work if the `gpp.cmpApi` is set to `static` and `gpp.consentData` is appropriately populated via setConfig. +Optional configuration options are: + +{: .table .table-bordered .table-striped } +| Param | Type | Description | Example | +| --- | --- | --- | --- | +| gpp.mspa | `Object` | | | +| gpp.mspa.restrictActivities | `Array` | A list of [activities](/dev-docs/activity-controls.html#activities) to be restricted in addition to the [default restrictions](/features/mspa-usnat.html#usnat-activity-restrictions). If specified, and if not already restricted, they will be treated similarly to `syncUser`. | `['accessDevice']` | + +### Example: disable device access on user opt-out + +```javascript +pbjs.setConfig({ + consentManagement: { + gpp: { + mspa: { + restrictActivities: ['accessDevice', 'accessRequestCredentials'] + } + } + } +}) +``` + ## Build the Package Follow the basic build instructions in the GitHub Prebid.js repo's main [README](https://github.com/prebid/Prebid.js/blob/master/README.md). To include the consent management module and the GPP Control - USNat module, an additional option must be added to the **gulp build** command: diff --git a/dev-docs/modules/gppControl_usstates.md b/dev-docs/modules/gppControl_usstates.md index d15c603fd7..d4fec53cd1 100644 --- a/dev-docs/modules/gppControl_usstates.md +++ b/dev-docs/modules/gppControl_usstates.md @@ -36,6 +36,7 @@ Optional configuration options are: | Param | Type | Description | Example | | --- | --- | --- | --- | | gpp.mspa | `Object` | | | +| gpp.mspa.restrictActivities | `Array` | A list of [activities](/dev-docs/activity-controls.html#activities) to be restricted in addition to the [default restrictions](/features/mspa-usnat.html#usnat-activity-restrictions). If specified, and if not already restricted, they will be treated similarly to `syncUser`. | `['accessDevice']` | | gpp.mspa.sids | `Array` | GPP SIDs that should be covered by activity restrictions. Defaults to all US state SIDs (`[8, 9, 10, 11, 12]`). This is the only value needed for normal operation. Other options are for special cases and future-proofing. | `[8, 9]` | | gpp.mspa.sections | `Object` | Map from section ID to per-section configuration options | `{8: {name: 'usca'}}` | | gpp.mspa.sections.name | `String` | GPP API name to use for the section. Defaults to the names given listed under [section information -> section IDs](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Section%20Information.md#section-ids). This option would only be used if your CMP has named their sections in a non-standard way. | `uscav3` | @@ -43,6 +44,20 @@ Optional configuration options are: ### Examples +#### Disable device access on user opt-out + +```javascript +pbjs.setConfig({ + consentManagement: { + gpp: { + mspa: { + restrictActivities: ['accessDevice', 'accessRequestCredentials'] + } + } + } +}) +``` + #### Enable activity controls for certain sections only ```javascript @@ -117,7 +132,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%20Multi-State%20Privacy%20Agreement%20(MSPA)%20US%20National%20Technical%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%20Multi-State%20Privacy%20Agreement%20(MSPA)%20US%20National%20Technical%20Specification.md) - [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) diff --git a/dev-docs/modules/growthCodeRtdProvider.md b/dev-docs/modules/growthCodeRtdProvider.md index b31397709c..9ff17aae13 100644 --- a/dev-docs/modules/growthCodeRtdProvider.md +++ b/dev-docs/modules/growthCodeRtdProvider.md @@ -28,7 +28,7 @@ your advertising strategies. Compile the GrowthCode RTD module into your Prebid build: -`gulp build --modules=userId,rtdModule,growthCodeRtdProvider,appnexusBidAdapter` +`gulp build --modules=userId,rtdModule,growthCodeRtdProvider,msftBidAdapter` Please visit [growthcode.io](https://growthcode.io) for more information. diff --git a/dev-docs/modules/hadronRtdProvider.md b/dev-docs/modules/hadronRtdProvider.md index 6f3149fbea..d9c2e1918c 100644 --- a/dev-docs/modules/hadronRtdProvider.md +++ b/dev-docs/modules/hadronRtdProvider.md @@ -40,7 +40,7 @@ please visit https://audigent.com or contact Compile the Hadron RTD module into your Prebid build: -`gulp build --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,appnexusBidAdapter` +`gulp build --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,msftBidAdapter` Add the Hadron RTD provider to your Prebid config. In this example we will configure publisher 1234 to retrieve segments from Audigent. See the @@ -134,7 +134,7 @@ on how to best configure your own Hadron RTD & Open RTB data handlers. To view an example of available segments returned by Audigent's backends: -`gulp serve --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,appnexusBidAdapter` +`gulp serve --modules=userId,unifiedIdSystem,rtdModule,hadronRtdProvider,msftBidAdapter` and then point your browser at: diff --git a/dev-docs/modules/humansecurityRtdProvider.md b/dev-docs/modules/humansecurityRtdProvider.md index 93b1b35ea9..ee0708478b 100644 --- a/dev-docs/modules/humansecurityRtdProvider.md +++ b/dev-docs/modules/humansecurityRtdProvider.md @@ -19,6 +19,14 @@ sidebarType : 1 ## Overview +```text +Module Name: HUMAN Security Rtd provider +Module Type: Rtd Provider +Maintainer: alexey@humansecurity.com +``` + +### What is it? + The HUMAN Security RTD submodule offers publishers a mechanism to integrate pre-bid signal collection for the purpose of providing real-time protection against all sorts of invalid traffic, such as bot-generated ad interactions or sophisticated ad fraud schemes. @@ -34,12 +42,10 @@ sent within bid requests, and used for bot detection on the backend. * No incremental signals collected beyond existing HUMAN post-bid solution * Offsets negative impact from loss of granularity in IP and User Agent at bid time * Does not expose collected IVT signal to any party who doesn’t otherwise already have access to the same signal collected post-bid -* Does not introduce meaningful latency, as demonstrated in the Latency section +* Does not introduce meaningful latency * Comes at no additional cost to collect IVT signal and make it available at bid time * Leveraged to differentiate the invalid bid requests at device level, and cannot be used to identify a user or a device, thus preserving privacy. -{% include dev-docs/loads-external-javascript.md %} - ## Build First, make sure to add the HUMAN Security submodule to your Prebid.js package with: @@ -69,8 +75,8 @@ pbjs.setConfig({ }); ``` -It can be optionally parameterized, for example, to include client ID obtained from HUMAN, -should any advanced reporting be needed, or to have verbose output for troubleshooting: +Other parameters can also be provided. For example, a client ID obtained from HUMAN can +optionally be provided, or verbose output can be enabled for troubleshooting purposes: ```javascript pbjs.setConfig({ @@ -88,11 +94,11 @@ pbjs.setConfig({ ### Supported parameters -{: .table .table-bordered .table-striped } -| Name |Type | Description | Required | -| :--------------- | :------------ | :------------------------------------------------------------------ |:---------| -| `clientId` | String | Should you need advanced reporting, contact [prebid@humansecurity.com](prebid@humansecurity.com) to receive client ID. | No | -| `verbose` | Boolean | Only set to `true` if troubleshooting issues. | No | +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| `clientId` | String | Should you need advanced reporting, contact [prebid@humansecurity.com](prebid@humansecurity.com) to receive client ID. | No | +| `verbose` | Boolean | Only set to `true` if troubleshooting issues. | No | +| `perBidderOptOut` | string[] | Pass any bidder alias to opt-out from per-bidder signal generation. | No | ### Logging, latency and troubleshooting @@ -103,9 +109,6 @@ of type `ERROR`. With `verbose` parameter set to `true`, it may additionally: * Call `logWarning`, resulting in `auctionDebug` events of type `WARNING`, * Call `logInfo` with latency information. - * To observe these messages in console, Prebid.js must be run in - [debug mode](/dev-docs/publisher-api-reference/setConfig.html#debugging) - - either by adding `?pbjs_debug=true` to your page's URL, or by configuring with `pbjs.setConfig({ debug: true });` Example output of the latency information: @@ -153,6 +156,7 @@ There are a few points that are worth being mentioned separately, to avoid confu the ever-evolving nature of the threat landscape without the publishers having to rebuild their Prebid.js frequently. * The signal collection script is also obfuscated, as a defense-in-depth measure in order to complicate tampering by bad actors, as are all similar scripts in the industry, which is something that cannot be accommodated by Prebid.js itself. +* The collected signals are encrypted before they are passed to bid adapters and can only be interpreted by HUMAN backend systems. ### Why is this approach an innovation? @@ -213,10 +217,14 @@ ensuring the value of the inventory. ### FAQ +#### Is partnership with HUMAN required to use the submodule? + +No. Using this submodule does not require any prior communication with HUMAN or being a client of HUMAN. +It is free and usage of the submodule doesn’t automatically make a Publisher HUMAN client. + #### Is latency an issue? The HUMAN Security RTD submodule is designed to minimize any latency in the auction within normal SLAs. - #### Do publishers get any insight into how the measurement is judged? Having the The HUMAN Security RTD submodule be part of the prebid process will allow the publisher to have insight @@ -225,12 +233,9 @@ inventory to the buyer. #### How are privacy concerns addressed? -The HUMAN Security RTD submodule seeks to reduce the impacts from signal deprecation that are inevitable without -compromising privacy by avoiding re-identification. Each bid request is enriched with just enough signal -to identify if the traffic is invalid or not. - -By having the The HUMAN Security RTD submodule operate at the Prebid level, data can be controlled -and not as freely passed through the bidstream where it may be accessible to various unknown parties. +The HUMAN Security RTD submodule seeks to reduce the impacts of signal deprecation without compromising privacy. +Each bid request is enriched with just enough signal to identify if the traffic is invalid or not, and these +signals are encrypted before being included in bid requests to prevent misuse. Note: anti-fraud use cases typically have carve outs in laws and regulations to permit data collection essential for effective fraud mitigation, but this does not constitute legal advice and you should diff --git a/dev-docs/modules/insuradsRtdProvider.md b/dev-docs/modules/insuradsRtdProvider.md new file mode 100644 index 0000000000..0135d4d0e5 --- /dev/null +++ b/dev-docs/modules/insuradsRtdProvider.md @@ -0,0 +1,62 @@ +--- +layout: page_v2 +title: InsurAds RTD Module +display_name: InsurAds RTD Module +description: InsurAds Real Time Data Module +page_type: module +module_type: rtd +module_code : insuradsRtdProvider +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +# InsurAds RTD Module +{:.no_toc} + +* TOC +{:toc} + +## Description + +The [InsurAds](https://insurads.com) real-time data module enables publishers to leverage contextual targeting and audience segmentation capabilities. This module fetches real-time key-value targeting data from the InsurAds services and automatically enriches InsurAds bid requests enhancing your advertising strategies without requiring additional code changes. + +## Integration + +1. Compile the InsurAds RTD Module along with the InsurAds bid adapter and other modules into your Prebid build: + + ```bash + gulp build --modules="rtdModule,insuradsRtdProvider,insuradsBidAdapter,..." + ``` + +2. Use `setConfig` to instruct Prebid.js to initialize the InsurAds RTD module, as specified below. + +## Configuration + +This module is configured as part of the `realTimeData.dataProviders` + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 2000, + dataProviders: [{ + name: 'insuradsRtd', + waitForIt: true, + params: { + publicId: 'YOUR_PUBLIC_ID' + } + }] + } +}); +``` + +## Parameters + +{: .table .table-bordered .table-striped } + +| Name | Type | Description | Default | +| :---------------- | :------ | :---------------------------------------------------------------- |:-------------------- | +| name | String | Real time data module name | Always 'insuradsRtd' | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | +| params | Object | | | +| params.publicId | String | Your InsurAds public ID (required) | | diff --git a/dev-docs/modules/konduit.md b/dev-docs/modules/konduit.md index 811753be93..5f208a517c 100644 --- a/dev-docs/modules/konduit.md +++ b/dev-docs/modules/konduit.md @@ -73,7 +73,7 @@ Konduit platform supports the ‘Send all bids’ scenario, but the GAM configur - If Send all bids is enabled, update the GAM line item creative URL as shown here: `https://p.konduit.me/api/vastProxy?konduit_hb=1&konduit_hb_awarded=1&konduit_cache_key=%%PATTERN:k_cache_key_BIDDERCODE%%&konduit_id=%%PATTERN:k_id%%` -`k_cache_key_BIDDERCODE` is a bidder-specific macro. Replace ‘BIDDERCODE’ with an actual bidder code, such as `k_cache_key_appnexus`. +`k_cache_key_BIDDERCODE` is a bidder-specific macro. Replace ‘BIDDERCODE’ with an actual bidder code, such as `k_cache_key_msft`. Note that the creative URL contains a few custom macros that allow Konduit platform to combine different data for predictive insights functionality. @@ -110,7 +110,7 @@ pbjs.que.push(function() { adUnitCode: videoAdUnit[0].code, timeout: 1500, callback: function (error, bids) { - var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + var videoUrl = pbjs.adServers.gam.buildVideoUrl({ ... }); diff --git a/dev-docs/modules/neuwoRtdProvider.md b/dev-docs/modules/neuwoRtdProvider.md index 1148c09e20..1760b18e7e 100644 --- a/dev-docs/modules/neuwoRtdProvider.md +++ b/dev-docs/modules/neuwoRtdProvider.md @@ -18,55 +18,47 @@ The Neuwo RTD provider fetches real-time contextual data from the Neuwo API. Whe This data is then added to the bid request by populating the OpenRTB 2.x objects `ortb2.site.content.data` (for IAB Content Taxonomy) and `ortb2.user.data` (for IAB Audience Taxonomy). This enrichment allows bidders to leverage Neuwo's contextual analysis for more precise targeting and decision-making. +Additionally, when enabled, the module populates OpenRTB 2.5 category fields (`ortb2.site.cat`, `ortb2.site.sectioncat`, `ortb2.site.pagecat`, `ortb2.site.content.cat`) with IAB Content Taxonomy 1.0 segments. + Here is an example scheme of the data injected into the `ortb2` object by our module: ```javascript ortb2: { site: { + // OpenRTB 2.5 category fields (IAB Content Taxonomy 1.0) + cat: ["IAB12", "IAB12-3", "IAB12-5"], + sectioncat: ["IAB12", "IAB12-3", "IAB12-5"], + pagecat: ["IAB12", "IAB12-3", "IAB12-5"], content: { + // OpenRTB 2.5 category field (IAB Content Taxonomy 1.0) + cat: ["IAB12", "IAB12-3", "IAB12-5"], // IAB Content Taxonomy data is injected here data: [{ name: "www.neuwo.ai", - segment: [{ - id: "274", - name: "Home & Garden", - }, - { - id: "42", - name: "Books and Literature", - }, - { - id: "210", - name: "Food & Drink", - }, + segment: [ + { id: "274" }, + { id: "42" }, + { id: "210" }, ], ext: { - segtax: 7, + segtax: 6, }, - }, ], + }], }, }, user: { // IAB Audience Taxonomy data is injected here data: [{ name: "www.neuwo.ai", - segment: [{ - id: "49", - name: "Demographic | Gender | Female |", - }, - { - id: "161", - name: "Demographic | Marital Status | Married |", - }, - { - id: "6", - name: "Demographic | Age Range | 30-34 |", - }, + segment: [ + { id: "49" }, + { id: "161" }, + { id: "6" }, ], ext: { segtax: 4, }, - }, ], + }], }, } ``` @@ -81,43 +73,82 @@ This module is configured as part of the `realTimeData.dataProviders` object. ```javascript pbjs.setConfig({ - realTimeData: { - auctionDelay: 500, // Value can be adjusted based on the needs - dataProviders: [ - { - name: "NeuwoRTDModule", - waitForIt: true, - params: { - neuwoApiUrl: "", - neuwoApiToken: "", - iabContentTaxonomyVersion: "3.0", - enableCache: true, // Default: true. Caches API responses to avoid redundant requests - }, - }, - ], - }, + realTimeData: { + auctionDelay: 500, // Value can be adjusted based on the needs. Recommended to start with value `500` + dataProviders: [ + { + name: "NeuwoRTDModule", + waitForIt: true, // Recommended to be set to `true` + params: { + neuwoApiUrl: "", + neuwoApiToken: "", + iabContentTaxonomyVersion: "2.2", + enableCache: true, // Default: true. Caches API responses to avoid redundant requests + enableOrtb25Fields: true, // Default: true. + }, + }, + ], + }, }); ``` **Parameters** -| Name | Type | Required | Default | Description | -| :---------------------------------- | :------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | String | Yes | | The name of the module, which is `NeuwoRTDModule`. | -| `params` | Object | Yes | | Container for module-specific parameters. | -| `params.neuwoApiUrl` | String | Yes | | The endpoint URL for the Neuwo Edge API. | -| `params.neuwoApiToken` | String | Yes | | Your unique API token provided by Neuwo. | -| `params.iabContentTaxonomyVersion` | String | No | `'3.0'` | Specifies the version of the IAB Content Taxonomy to be used. Supported values: `'2.2'`, `'3.0'`. | -| `params.enableCache` | Boolean | No | `true` | If `true`, caches API responses to avoid redundant requests for the same page during the session. Set to `false` to disable caching and make a fresh API call on every bid request. | -| `params.stripAllQueryParams` | Boolean | No | `false` | If `true`, strips all query parameters from the URL before analysis. Takes precedence over other stripping options. | -| `params.stripQueryParamsForDomains` | String[] | No | `[]` | List of domains for which to strip **all** query parameters. When a domain matches, all query params are removed for that domain and all its subdomains (e.g., `'example.com'` strips params for both `'example.com'` and `'sub.example.com'`). This option takes precedence over `stripQueryParams` for matching domains. | -| `params.stripQueryParams` | String[] | No | `[]` | List of specific query parameter names to strip from the URL (e.g., `['utm_source', 'fbclid']`). Other parameters are preserved. Only applies when the domain does not match `stripQueryParamsForDomains`. | -| `params.stripFragments` | Boolean | No | `false` | If `true`, strips URL fragments (hash, e.g., `#section`) from the URL before analysis. | +| Name | Type | Required | Default | Description | +| :---------------------------------- | :------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | String | Yes | | The name of the module, which is `NeuwoRTDModule`. | +| `params` | Object | Yes | | Container for module-specific parameters. | +| `params.neuwoApiUrl` | String | Yes | | The endpoint URL for the Neuwo Edge API. | +| `params.neuwoApiToken` | String | Yes | | Your unique API token provided by Neuwo. | +| `params.iabContentTaxonomyVersion` | String | No | `'2.2'` | Specifies the version of the IAB Content Taxonomy to be used. Supported values: `'1.0'`, `'2.2'`, `'3.0'`. | +| `params.enableCache` | Boolean | No | `true` | If `true`, caches API responses to avoid redundant requests for the same page during the session. Set to `false` to disable caching and make a fresh API call on every bid request. | +| `params.enableOrtb25Fields` | Boolean | No | `true` | If `true`, populates OpenRTB 2.5 category fields (`ortb2.site.cat`, `ortb2.site.sectioncat`, `ortb2.site.pagecat`, `ortb2.site.content.cat`) with IAB Content Taxonomy 1.0 segments. See [OpenRTB 2.5 Category Fields](#openrtb-25-category-fields) section below for details. | +| `params.stripAllQueryParams` | Boolean | No | `false` | If `true`, strips all query parameters from the URL before analysis. Takes precedence over other stripping options. | +| `params.stripQueryParamsForDomains` | String[] | No | `[]` | List of domains for which to strip **all** query parameters. When a domain matches, all query params are removed for that domain and all its subdomains (e.g., `'example.com'` strips params for both `'example.com'` and `'sub.example.com'`). This option takes precedence over `stripQueryParams` for matching domains. | +| `params.stripQueryParams` | String[] | No | `[]` | List of specific query parameter names to strip from the URL (e.g., `['utm_source', 'fbclid']`). Other parameters are preserved. Only applies when the domain does not match `stripQueryParamsForDomains`. | +| `params.stripFragments` | Boolean | No | `false` | If `true`, strips URL fragments (hash, e.g., `#section`) from the URL before analysis. | +| `params.iabTaxonomyFilters` | Object | No | | Per-tier filtering configuration for IAB taxonomies. Allows filtering by relevance threshold and limiting the count of categories per tier. Filters configured for `ContentTier1` and `ContentTier2` are automatically applied to IAB Content Taxonomy 1.0 when `enableOrtb25Fields` is `true`. See [IAB Taxonomy Filtering](#iab-taxonomy-filtering) section for details. | ### API Response Caching By default, the module caches API responses during the page session to optimise performance and reduce redundant API calls. This behaviour can be disabled by setting `enableCache: false` if needed for dynamic content scenarios. +### OpenRTB 2.5 Category Fields + +The module supports populating OpenRTB 2.5 category fields with IAB Content Taxonomy 1.0 segments. This feature is enabled by default and provides additional contextual signals to bidders through standard OpenRTB fields. + +**Category Fields Populated:** + +- `ortb2.site.cat` - Array of IAB Content Taxonomy 1.0 category IDs +- `ortb2.site.sectioncat` - Array of IAB Content Taxonomy 1.0 category IDs +- `ortb2.site.pagecat` - Array of IAB Content Taxonomy 1.0 category IDs +- `ortb2.site.content.cat` - Array of IAB Content Taxonomy 1.0 category IDs + +**Result Example:** + +With `enableOrtb25Fields: true`, the module injects: + +```javascript +ortb2: { + site: { + // OpenRTB 2.5 category fields + cat: ["IAB12", "IAB12-3", "IAB12-5"], + sectioncat: ["IAB12", "IAB12-3", "IAB12-5"], + pagecat: ["IAB12", "IAB12-3", "IAB12-5"], + content: { + // OpenRTB 2.5 category field + cat: ["IAB12", "IAB12-3", "IAB12-5"], + // Standard content data + data: [{ + name: "www.neuwo.ai", + segment: [{ id: "274" }, { id: "42" }], + ext: { segtax: 6 } + }] + } + } +} +``` + ### URL Cleaning Options The module provides optional URL cleaning capabilities to strip query parameters and/or fragments from the analysed URL before sending it to the Neuwo API. This can be useful for privacy, caching, or analytics purposes. @@ -126,35 +157,162 @@ The module provides optional URL cleaning capabilities to strip query parameters ```javascript pbjs.setConfig({ - realTimeData: { - auctionDelay: 500, // Value can be adjusted based on the needs - dataProviders: [ - { - name: "NeuwoRTDModule", - waitForIt: true, - params: { - neuwoApiUrl: "", - neuwoApiToken: "", - iabContentTaxonomyVersion: "3.0", - - // Option 1: Strip all query parameters from the URL - stripAllQueryParams: true, - - // Option 2: Strip all query parameters only for specific domains - // stripQueryParamsForDomains: ['example.com', 'another-domain.com'], - - // Option 3: Strip specific query parameters by name - // stripQueryParams: ['utm_source', 'utm_campaign', 'fbclid'], - - // Optional: Strip URL fragments (hash) - stripFragments: true, - }, - }, - ], - }, + realTimeData: { + auctionDelay: 500, // Value can be adjusted based on the needs. Recommended to start with value `500` + dataProviders: [ + { + name: "NeuwoRTDModule", + waitForIt: true, // Recommended to be set to `true` + params: { + neuwoApiUrl: "", + neuwoApiToken: "", + iabContentTaxonomyVersion: "2.2", + + // Option 1: Strip all query parameters from the URL + stripAllQueryParams: true, + + // Option 2: Strip all query parameters only for specific domains + // stripQueryParamsForDomains: ['example.com', 'another-domain.com'], + + // Option 3: Strip specific query parameters by name + // stripQueryParams: ['utm_source', 'utm_campaign', 'fbclid'], + + // Optional: Strip URL fragments (hash) + stripFragments: true, + }, + }, + ], + }, +}); +``` + +### IAB Taxonomy Filtering + +The module provides optional per-tier filtering for IAB taxonomies to control the quantity and quality of categories injected into bid requests. This allows you to limit categories based on their relevance score and restrict the maximum number of categories per tier. Filtering is performed server-side, which means only the filtered categories are returned in the response. This reduces bandwidth and improves performance. + +**Filter Configuration:** + +Each tier can have two optional parameters: + +- `threshold` (Number): Minimum relevance score (0.0 to 1.0). Categories below this threshold are excluded. +- `limit` (Number): Maximum number of categories to include for this tier (after filtering and sorting by relevance). + +**Available Tiers:** + +| Tier Name | Description | IAB Taxonomy | +| :-------------- | :------------------ | :----------------------------------- | +| `ContentTier1` | IAB Content Tier 1 | Based on configured taxonomy version | +| `ContentTier2` | IAB Content Tier 2 | Based on configured taxonomy version | +| `ContentTier3` | IAB Content Tier 3 | Based on configured taxonomy version | +| `AudienceTier3` | IAB Audience Tier 3 | IAB Audience Taxonomy 1.1 (segtax 4) | +| `AudienceTier4` | IAB Audience Tier 4 | IAB Audience Taxonomy 1.1 (segtax 4) | +| `AudienceTier5` | IAB Audience Tier 5 | IAB Audience Taxonomy 1.1 (segtax 4) | + +**Example with IAB taxonomy filtering:** + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 500, // Value can be adjusted based on the needs. Recommended to start with value `500` + dataProviders: [ + { + name: "NeuwoRTDModule", + waitForIt: true, // Recommended to be set to `true` + params: { + neuwoApiUrl: "", + neuwoApiToken: "", + iabContentTaxonomyVersion: "2.2", + + // Filter IAB taxonomies by tier + iabTaxonomyFilters: { + // Content Tier 1: Keep only the top category with at least 10% relevance + ContentTier1: { limit: 1, threshold: 0.1 }, + + // Content Tier 2: Keep top 2 categories with at least 10% relevance + ContentTier2: { limit: 2, threshold: 0.1 }, + + // Content Tier 3: Keep top 3 categories with at least 15% relevance + ContentTier3: { limit: 3, threshold: 0.15 }, + + // Audience Tier 3: Keep top 3 categories with at least 20% relevance + AudienceTier3: { limit: 3, threshold: 0.2 }, + + // Audience Tier 4: Keep top 5 categories with at least 20% relevance + AudienceTier4: { limit: 5, threshold: 0.2 }, + + // Audience Tier 5: Keep top 7 categories with at least 30% relevance + AudienceTier5: { limit: 7, threshold: 0.3 }, + }, + }, + }, + ], + }, }); ``` +**OpenRTB 2.5 Category Fields Filtering** + +When `iabTaxonomyFilters` are configured, the same filters applied to `ContentTier1` and `ContentTier2` are automatically applied to IAB Content Taxonomy 1.0 data used for these fields. Note that IAB Content Taxonomy 1.0 only has tiers 1 and 2, so `ContentTier3` filters are ignored for these fields. + +## Accessing Neuwo Data Outside Prebid.js + +The Neuwo RTD module enriches bid requests with contextual data that can be accessed in application code for analytics, targeting, integration with Google Ad Manager as [Publisher Provided Signals (PPS)](https://support.google.com/admanager/answer/15287325) or other purposes. The enriched data is available through Prebid.js events. + +### Example of Using the `bidRequested` Event + +Listen to the `bidRequested` event to access the enriched ORTB2 data. This event fires early in the auction lifecycle and provides direct access to the Neuwo data: + +```javascript +pbjs.que.push(function () { + pbjs.onEvent("bidRequested", function (bidRequest) { + // The ortb2 data is available directly on the bidRequest + const ortb2 = bidRequest.ortb2; + + // Extract Neuwo-specific data (from www.neuwo.ai provider) + const neuwoSiteData = ortb2?.site?.content?.data?.find( + (d) => d.name === "www.neuwo.ai" + ); + const neuwoUserData = ortb2?.user?.data?.find( + (d) => d.name === "www.neuwo.ai" + ); + + // Extract OpenRTB 2.5 category fields (if enableOrtb25Fields is true) + const categoryFields = { + siteCat: ortb2?.site?.cat, + siteSectioncat: ortb2?.site?.sectioncat, + sitePagecat: ortb2?.site?.pagecat, + contentCat: ortb2?.site?.content?.cat, + }; + + // Use the data in the application + console.log("Neuwo Site Content:", neuwoSiteData); + console.log("Neuwo User Data:", neuwoUserData); + console.log("OpenRTB 2.5 Category Fields:", categoryFields); + + // Example: Store in a global variable for later use + window.neuwoData = { + siteContent: neuwoSiteData, + user: neuwoUserData, + categoryFields: categoryFields, + }; + }); +}); +``` + +### Other Prebid.js Events + +The Neuwo data is also available in other Prebid.js events: + +| Order | Event | Fires Once Per | Data Location | +| :---- | :----------------- | :------------- | :----------------------------------- | +| 1 | `auctionInit` | Auction | `auctionData.bidderRequests[].ortb2` | +| 2 | `bidRequested` | Bidder | `bidRequest.ortb2` | +| 3 | `beforeBidderHttp` | Bidder | `bidRequests[].ortb2` | +| 4 | `bidResponse` | Bidder | `bidResponse.ortb2` | +| 5 | `auctionEnd` | Auction | `auctionData.bidderRequests[].ortb2` | + +For more information on Prebid.js events, see the [Prebid.js Event API documentation](https://docs.prebid.org/dev-docs/publisher-api-reference/getEvents.html). + ## Installation ### Step 1: Install Prebid.js @@ -170,3 +328,5 @@ Include `neuwoRtdProvider` in build: `gulp build --modules=rtdModule,neuwoRtdPro ### Step 2: Set configuration Enable Neuwo Real-Time Data Module using `pbjs.setConfig` in a related Javascript context. Command example is provided in [Configuration](#configuration) section. + +> Version **2.2.6** diff --git a/dev-docs/modules/oftmediaRtdProvider.md b/dev-docs/modules/oftmediaRtdProvider.md index ababdb4866..716cfd97dc 100644 --- a/dev-docs/modules/oftmediaRtdProvider.md +++ b/dev-docs/modules/oftmediaRtdProvider.md @@ -56,7 +56,7 @@ pbjs.setConfig({ params: { publisherId: "0653b3fc-a645-4bcc-bfee-b8982974dd53", // Required: Get this ID from 152media keywords: ["red", "blue", "white"], // Optional: Contextual keywords - bidderCode: "appnexus", // Required: Targeted bidder + bidderCode: "msft", // Required: Targeted bidder enrichRequest: true // Optional: Adds additional targeting fields } } diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 79c42fb4ba..56f56118f7 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -31,7 +31,7 @@ Optable RTD submodule enriches the OpenRTB request by populating `user.ext.eids` Compile the Optable RTD Module with other modules and adapters into your Prebid.js build: ```bash -gulp build --modules="rtdModule,optableRtdProvider,appnexusBidAdapter,..." +gulp build --modules="rtdModule,optableRtdProvider,msftBidAdapter,..." ``` > Note that Optable RTD module is dependent on the global real-time data module, `rtdModule`. @@ -140,7 +140,7 @@ A `handleRtd` function implementation has access to its surrounding context incl If you want to see an example of how the optable RTD module works, run the following command: ```bash -gulp serve --modules=optableRtdProvider,consentManagementGpp,consentManagementTcf,appnexusBidAdapter +gulp serve --modules=optableRtdProvider,consentManagementGpp,consentManagementTcf,msftBidAdapter ``` and then open the following URL in your browser: diff --git a/dev-docs/modules/optimeraRtdProvider.md b/dev-docs/modules/optimeraRtdProvider.md index 8f816eab25..6baa0f88b0 100644 --- a/dev-docs/modules/optimeraRtdProvider.md +++ b/dev-docs/modules/optimeraRtdProvider.md @@ -80,7 +80,7 @@ To view an integration example: 1. in your cli run: ```bash - gulp serve --modules=appnexusBidAdapter,optimeraRtdProvider` + gulp serve --modules=msftBidAdapter,optimeraRtdProvider` ``` 2. in your browser, navigate to: diff --git a/dev-docs/modules/oxxionRtdProvide.md b/dev-docs/modules/oxxionRtdProvide.md index 646160121c..78980c80c1 100644 --- a/dev-docs/modules/oxxionRtdProvide.md +++ b/dev-docs/modules/oxxionRtdProvide.md @@ -31,7 +31,7 @@ Make sure to have the following modules listed while building prebid : `rtdModul For example : ```bash -gulp build --modules=schain,priceFloors,currency,consentManagement,appnexusBidAdapter,rubiconBidAdapter,rtdModule,oxxionRtdProvider +gulp build --modules=schain,priceFloors,currency,consentManagement,msftBidAdapter,rubiconBidAdapter,rtdModule,oxxionRtdProvider ``` Then add the oxxion Rtd module to your prebid configuration : diff --git a/dev-docs/modules/permutiveRtdProvider.md b/dev-docs/modules/permutiveRtdProvider.md index 10c3836212..dde1e6009c 100644 --- a/dev-docs/modules/permutiveRtdProvider.md +++ b/dev-docs/modules/permutiveRtdProvider.md @@ -44,7 +44,7 @@ pbjs.setConfig({ name: 'permutive', waitForIt: true, // should be true if there's an `auctionDelay` params: { - acBidders: ['appnexus'] + acBidders: ['msft'] } }] }, @@ -61,13 +61,18 @@ as well as enabling settings for specific use cases mentioned above (e.g. acbidd {: .table .table-bordered .table-striped } -| Name | Type | Description | Default | -| ---------------------- | -------------------- | --------------------------------------------------------------------------------------------- | ------------------ | -| name | String | This should always be `permutive` | - | -| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | -| params | Object | | - | -| params.acBidders | String[] | An array of bidder codes to share cohorts with in certain versions of Prebid, see below | `[]` | -| params.maxSegs | Integer | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500` | +| Name | Type | Description | Default | +| ---------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| name | String | This should always be `permutive` | - | +| waitForIt | Boolean | Should be `true` if there's an `auctionDelay` defined (optional) | `false` | +| params | Object | | - | +| params.acBidders | String[] | An array of bidder codes to share cohorts with in certain versions of Prebid, see below | `[]` | +| params.maxSegs | Integer | Maximum number of cohorts to be included in either the `permutive` or `p_standard` key-value. | `500` | +| params.bidders | Object | Per-bidder configuration for custom cohort sources. Keys are bidder codes; listing a bidder here also causes the module to write ortb2 data for that bidder, even if it is not in `acBidders` or on Permutive's SSP list. | `{}` | +| params.bidders | Object | Per-bidder configuration for custom cohort sources. Keys are bidder codes. | `{}` | +| params.bidders.\.customCohorts | Object | Custom cohorts source configuration for a specific bidder. | - | +| params.bidders.\.customCohorts.source | String | Storage type to read custom cohorts from. Currently only `'ls'` (localStorage) is supported. | - | +| params.bidders.\.customCohorts.key | String | The localStorage key to read custom cohorts from. | - | ### Context @@ -132,11 +137,25 @@ Currently, bidders with known support for custom cohort targeting are: * Xandr * Magnite +* Microsoft (msft) When enabling the respective Activation for a cohort in Permutive, this module will automatically attach that cohort ID to the bid request. There is no need to enable individual bidders in the module configuration, it will automatically reflect which SSP integrations you have enabled in your Permutive dashboard. Permutive cohorts will be sent in the permutive key-value. +**Note:** Publishers migrating from the `appnexus` bidder to `msft` need to configure the `params.bidders` object so the module knows where to read custom cohorts from. The Permutive SDK writes `msft` custom cohorts to the same localStorage key used by `appnexus` (`_papns`), so publishers should add the following to their Permutive RTD config: + +```javascript +params: { + acBidders: ['msft'], + bidders: { + msft: { + customCohorts: { source: 'ls', key: '_papns' } + } + } +} +``` + ### _Enabling Advertiser Cohorts_ If you are connecting to an Advertiser seat within Permutive to share Advertiser Cohorts, populate the acbidders config in the Permutive RTD with an array of bidder codes with whom you wish to share Advertiser Cohorts with. diff --git a/dev-docs/modules/prebidServer.md b/dev-docs/modules/prebidServer.md index 50bfac23b0..fd93d90854 100644 --- a/dev-docs/modules/prebidServer.md +++ b/dev-docs/modules/prebidServer.md @@ -37,14 +37,13 @@ Video notes: ## Configuration -Here's an example config enabling the AppNexus Prebid Server: +Here's an example config enabling the appnexuspsp Prebid Server: ```javascript pbjs.setConfig({ s2sConfig: { accountId : '12345', - bidders : ['appnexus','pubmatic', 'rubicon'], - defaultVendor: 'appnexus', + bidders : ['msft','pubmatic', 'rubicon'], timeout: 300 } }); @@ -55,22 +54,21 @@ 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, - }, - ], + s2sConfig: { + accountId: YOUR_SELLER_MEMBER_ID, + bidders: ['msft'], + enabled: true, + allowUnknownBidderCodes: true, + timeout: 1000, + endpoint: { + p1Consent: 'https://ib.adnxs.com/openrtb2/prebid', + noP1Consent: 'https://ib.adnxs-simple.com/openrtb2/prebid' + }, + syncEndpoint: { + p1Consent: 'https://prebid.adnxs.com/pbs/v1/cookie_sync', + noP1Consent: 'https://prebid.adnxs-simple.com/pbs/v1/cookie_sync' + } + } }); ``` @@ -83,7 +81,6 @@ There are many configuration options for s2sConfig: | `name` | Optional | String | A handle for this configuration, used to reference a specific server (when multiple are present) from [ad unit configuration](/dev-docs/adunit-reference.html#stored-imp) | | `bidders` | Optional | Array of Strings | Which bidders auctions should take place on the server side | | `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 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' | @@ -111,8 +108,6 @@ If `endpoint` and `syncEndpoint` are objects, these are the supported properties **Notes on s2sConfig properties** -- Currently supported vendors are: appnexus, openx, and rubicon -- When using `defaultVendor` option, `accountId` still needs to be defined. - If `bidders` is omitted, only adUnits that also omit bidders will be sent to Prebid Server. See the [stored impressions](#stored-imp) example below. - If the `s2sConfig` timeout is not specified, Prebid Server will utilize a configured default for `tmax`. - When using the `endpoint` or `syncEndpoint` object configs, you should define both properties. If either property is not defined, Prebid Server requests for that type of user will not be made. If you do not need to distinguish endpoints for consent reasons, you can simply define the same URL value in both fields or use the String version of the field (which is configured to use defined URL for all users). @@ -147,7 +142,7 @@ the bad parameter. ### Defining endpoints -s2sConfig example with the endpoint attributes defined instead of using the 'defaultVendor' approach: +s2sConfig example with the endpoint attributes defined: ```javascript pbjs.setConfig({ @@ -191,7 +186,8 @@ pbjs.setConfig({ s2sConfig: [{ accountId: '1', bidders: ['tripleliftVideo'], - defaultVendor: 'appnexus', + endpoint: 'https://mypbs.example.com/path', + syncEndpoint: 'https://mypbs.example.com/path', timeout: 500, extPrebid: { aliases: { @@ -261,7 +257,6 @@ pbjs.setConfig({ s2sConfig: [{ accountId: '1001', bidders: ['rubicon', 'pubmatic'], - defaultVendor: 'rubicon', timeout: 250, extPrebid: { cache: { diff --git a/dev-docs/modules/pubCommonId.md b/dev-docs/modules/pubCommonId.md index 50322e12c0..775adce72f 100644 --- a/dev-docs/modules/pubCommonId.md +++ b/dev-docs/modules/pubCommonId.md @@ -71,7 +71,7 @@ Adapters should look for `bid.crumbs.pubcid` in buildRequests() method. ```javascript [ { - "bidder":"appnexus", + "bidder":"msft", "params":{ "placement":"12345" }, diff --git a/dev-docs/modules/raveltechRtdProvider.md b/dev-docs/modules/raveltechRtdProvider.md index 596720699f..e492616d63 100644 --- a/dev-docs/modules/raveltechRtdProvider.md +++ b/dev-docs/modules/raveltechRtdProvider.md @@ -48,7 +48,7 @@ Please contact to activate your adapter after installatio ### Build ```bash -gulp build --modules="rtdModule,raveltechRtdProvider,appnexusBidAdapter,..." +gulp build --modules="rtdModule,raveltechRtdProvider,msftBidAdapter,..." ``` > Note that the global RTD module, `rtdModule`, is a prerequisite of the raveltech RTD module. @@ -68,7 +68,7 @@ pbjs.setConfig({ dataProviders: [{ name: 'raveltech', params: { - bidders: ['appnexus', 'rubicon'], + bidders: ['msft', 'rubicon'], preserveOriginalBid: true } }] diff --git a/dev-docs/modules/raynRtdProvider.md b/dev-docs/modules/raynRtdProvider.md index 81cbcd02bf..ed6decfca0 100644 --- a/dev-docs/modules/raynRtdProvider.md +++ b/dev-docs/modules/raynRtdProvider.md @@ -43,7 +43,7 @@ pbjs.setConfig( name: "rayn", waitForIt: true, params: { - bidders: ["appnexus", "pubmatic"], + bidders: ["msft", "pubmatic"], integration: { iabAudienceCategories: { v1_1: { @@ -103,7 +103,7 @@ Please note that raynRtdProvider should be integrated into the website along wit To view an example of the on page setup: ```bash -gulp serve-fast --modules=rtdModule,raynRtdProvider,appnexusBidAdapter +gulp serve-fast --modules=rtdModule,raynRtdProvider,msftBidAdapter ``` Then in your browser access: [http://localhost:9999/integrationExamples/gpt/raynRtdProvider_example.html](http://localhost:9999/integrationExamples/gpt/raynRtdProvider_example.html) diff --git a/dev-docs/modules/relevadRtdProvider.md b/dev-docs/modules/relevadRtdProvider.md index 9d33922dec..1eb54e9e7a 100644 --- a/dev-docs/modules/relevadRtdProvider.md +++ b/dev-docs/modules/relevadRtdProvider.md @@ -46,7 +46,7 @@ pbjs.setConfig({ // The list of bidders to target with Relevad categories and segments. If absent or empty, target all bidders. bidders: [ - { bidder: "appnexus", // Bidder name + { bidder: "msft", // Bidder name adUnitCodes: ['adUnit-1','adUnit-2'], // List of adUnit codes to target. If absent or empty, target all ad units. minscore: 70, // Minimum relevancy score for this bidder (0-100). If absent, defaults to the global minscore. }, @@ -81,7 +81,7 @@ pbjs.setConfig({ | Name | Type | Description | Notes | | :---------- | :--------------- | :----------------------------------------------------------- | :------------------------------------------------------- | -| bidder | String | Bidder name | Mandatory. Example: “appnexus” | +| bidder | String | Bidder name | Mandatory. Example: "msft" | | adUnitCodes | Array of Strings | List of specific AdUnit codes you with to target | Optional. If empty or absent, all ad units are targeted. | | minscore | Integer | Bidder-specific minimum categorization relevancy score (0, 100) | Optional, defaults to global minscore above. | diff --git a/dev-docs/modules/s2sTesting.md b/dev-docs/modules/s2sTesting.md index e227acf841..51599ce02a 100644 --- a/dev-docs/modules/s2sTesting.md +++ b/dev-docs/modules/s2sTesting.md @@ -116,7 +116,7 @@ keep in mind the various data sources you may have access to: monitor revenue impact before going entirely to server-side header bidding. I don't want to modify AdUnits because that's time consuming in the CMS.* -Example S2S Config defining that 10% of Rubicon requests and 100% of AppNexus requests go through the server: +Example S2S Config defining that 10% of Rubicon requests and 100% of Microsoft requests go through the server: ```javascript pbjs.setConfig({ diff --git a/dev-docs/modules/scope3RtdProvider.md b/dev-docs/modules/scope3RtdProvider.md index bac3d92a13..251b547b21 100644 --- a/dev-docs/modules/scope3RtdProvider.md +++ b/dev-docs/modules/scope3RtdProvider.md @@ -62,7 +62,7 @@ pbjs.setConfig({ orgId: "your-org-id", endpoint: "", timeout: 1500, - bidders: ["appnexus", "rubicon", "pubmatic"], + bidders: ["msft", "rubicon", "pubmatic"], includeKey: "axei", excludeKey: "axex", macroKey: "axem", @@ -105,7 +105,7 @@ The Scope3 AEE returns signals in this format: "exclude": ["competitor_exposed"], "macro": "eyJjb250ZXh0IjogImhpZ2hfdmFsdWUifQ==", "bidders": { - "appnexus": { + "msft": { "segments": ["seg1", "seg2"], "deals": ["DEAL123"] }, diff --git a/dev-docs/modules/sirdataRtdProvider.md b/dev-docs/modules/sirdataRtdProvider.md index 724a036dac..0e10ca0f00 100644 --- a/dev-docs/modules/sirdataRtdProvider.md +++ b/dev-docs/modules/sirdataRtdProvider.md @@ -125,7 +125,7 @@ Bidders can receive common setting : As indicated above, it is possible to provide your own bid augmentation functions. This is useful if you know a bid adapter's API supports segment fields which aren't specifically being added to request objects in the Prebid bid adapter. -Please see the following example, which provides a function to modify bids for a bid adapter called ix and overrides the appnexus. +Please see the following example, which provides a function to modify bids for a bid adapter called ix and overrides the msft. data Object format for usage in this kind of function : ```json @@ -182,7 +182,7 @@ data Object format for usage in this kind of function : ``` ```javascript -function overrideAppnexus (adUnit, segmentsArray, dataObject, bid) { +function overrideMsft (adUnit, segmentsArray, dataObject, bid) { for (var i = 0; i < segmentsArray.length; i++) { if (segmentsArray[i]) { bid.params.user.segments.push(segmentsArray[i]); @@ -205,8 +205,8 @@ pbjs.setConfig({ contextualMinRelevancyScore: 50, //Min score to keep contextual category in the bidders (0-100 scale) actualUrl: actual_url, //top location url, for contextual categories bidders: [{ - bidder: 'appnexus', - customFunction: overrideAppnexus, + bidder: 'msft', + customFunction: overrideMsft, curationId: '111' },{ bidder: 'ix', @@ -227,7 +227,7 @@ pbjs.setConfig({ To view an example of available segments returned by Sirdata's backends: ```bash -gulp serve --modules=rtdModule,sirdataRtdProvider,appnexusBidAdapter +gulp serve --modules=rtdModule,sirdataRtdProvider,msftBidAdapter ``` and then point your browser at: diff --git a/dev-docs/modules/stackupRtdProvider.md b/dev-docs/modules/stackupRtdProvider.md new file mode 100644 index 0000000000..36c1408097 --- /dev/null +++ b/dev-docs/modules/stackupRtdProvider.md @@ -0,0 +1,194 @@ +--- +layout: page_v2 +title: Stack Up RTD Provider +display_name: Stack Up RTD Provider +description: Enriches Prebid.js bid requests with IAB contextual and audience segments derived from page content — no cookies or user identifiers required. +page_type: module +module_type: rtd +module_code: stackupRtdProvider +enable_download: true +vendor_specific: true +prebid_member: false +sidebarType: 1 +--- + +# Stack Up RTD Provider + +{:.no_toc} + +- TOC + {:toc} + +## Overview + +The Stack Up RTD module enriches Prebid.js bid requests with contextual and audience segments derived from the content of the current page. Before the auction fires, the module calls the Stack Up enrichment API (or reads from a `sessionStorage` cache on revisit) and merges the response into the global `ortb2` fragments: + +- **`site.content.data`** — Stack Up Content Taxonomy 1.0 segments (segtax 502): topics, brand-safety signals, and emotion signals attached to the article. +- **`user.data`** — Stack Up Audience Taxonomy 1.0 segments (segtax 501) inferred from contextual signals. + +Every bidder that participates in the auction receives these segments in its `ortb2` object. No cookies, fingerprints, or user identifiers are transmitted to the Stack Up API — only a URL path and publisher domain. + +Become a member of Stack Up in order to receive your `pubId`. Contact [support@stackup-ai.com](mailto:support@stackup-ai.com) for more details. + +## Build + +Include the Stack Up RTD module and the core RTD module when building Prebid.js: + +```bash +gulp build --modules=rtdModule,stackupRtdProvider +``` + +Add any bid adapters you use to the same build command: + +```bash +gulp build --modules=rtdModule,stackupRtdProvider,appnexusBidAdapter +``` + +> `rtdModule` is required to use the Stack Up RTD module. + +## Configuration + +Configure the module inside `realTimeData.dataProviders` via `pbjs.setConfig`. + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 1000, + dataProviders: [ + { + name: "stackupRtd", + waitForIt: true, + params: { + pubId: "YOUR-PUB-ID", // required — issued by Stack Up + timeout: 300, // optional — enrichment budget in ms + articleIdMode: "path", // optional — 'path' (default) or 'explicit' + articleId: "", // required when articleIdMode is 'explicit' + apiUrl: "https://api.stackup-ai.com/v1/enrich-ortb-rtd", // optional + cache: { + enabled: true, // optional — disable all cache read/write when false + ttlSeconds: 3600, // optional + storage: "session", // optional — 'session' (default) or 'memory' + }, + debug: false, // optional + }, + }, + ], + }, +}); +``` + +### Parameters + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | Default | +| :--- | :---: | :---: | :--- | :---: | +| `name` | required | String | Must be `'stackupRtd'` | — | +| `waitForIt` | recommended | Boolean | Set `true` when an `auctionDelay` is defined | `false` | +| `params` | required | Object | Module configuration object | — | +| `params.pubId` | required | String | Publisher ID issued by Stack Up | — | +| `params.timeout` | optional | Integer | Max ms to wait for the enrichment API before releasing the auction | `300` | +| `params.articleIdMode` | optional | String | How the article ID is determined. `'path'` derives it from the page URL; `'explicit'` uses `params.articleId` directly | `'path'` | +| `params.articleId` | optional\* | String | Article identifier — required when `articleIdMode` is `'explicit'`. Max 512 characters | — | +| `params.apiUrl` | optional | String | Override the Stack Up enrichment endpoint | `'https://api.stackup-ai.com/v1/enrich-ortb-rtd'` | +| `params.cache.enabled` | optional | Boolean | Enable/disable cache usage entirely | `true` | +| `params.cache.ttlSeconds` | optional | Integer | How long a cached result is considered fresh (sessionStorage TTL) | `3600` | +| `params.cache.storage` | optional | String | Cache backend: `'session'` for browser sessionStorage or `'memory'` for in-process cache | `'session'` | +| `params.debug` | optional | Boolean | Enable verbose `[stackupRtd]` console logging | `false` | +| `params.debugDomain` | optional | String | Override the domain sent to the API when `debug: true` | page domain | + +## Article ID Resolution + +### `articleIdMode: 'path'` (default) + +The module normalises the current page URL path using Prebid's built-in referer detection (works inside iframes and AMP frames). The normalisation strips trailing slashes, AMP path variants (`/amp/`, `/_amp/`, `/amp` suffix), and double slashes. The resulting path is sent to the API and is also used as the `sessionStorage` cache key so cache hits are consistent across AMP and canonical URLs for the same article. + +### `articleIdMode: 'explicit'` + +Pass a stable, opaque article identifier directly in `params.articleId`. Use this when you have a CMS-issued slug or numeric ID that is more stable than the URL. + +## Caching + +When `params.cache.enabled` is `true` (default), the module checks cache before making a network call. + +With `params.cache.storage: 'session'` (default), the result is written to `sessionStorage` under the key: + +```text +stackup:enrich:v1:path_ +``` + +With `params.cache.storage: 'memory'`, entries are kept in runtime memory only and are cleared on full page reload. + +On subsequent page views within the same session the cache is read instead of calling the API, keeping enrichment latency at ~0 ms. Cache entries expire after `params.cache.ttlSeconds` (default 1 hour). Setting `params.cache.enabled: false` disables both reads and writes. + +## Consent + +The module respects user consent before making any network requests: + +- **COPPA**: if `coppa: true` is set, the module is inert. +- **GDPR**: when GDPR applies, the module requires consent (or legitimate interest) for **Purpose 1** (Store/access information on a device) and **Purpose 4** (Select personalised content). If either purpose is missing, or if `vendorData` is absent (e.g. CMP timeout), the module does nothing. +- **USP / CCPA / GPP**: not enforced — the Stack Up API receives only a URL path and domain, no user identifiers, so US sale-of-data frameworks do not apply. + +## ortb2 Output Shape + +After a successful enrichment the following fields are merged into the global `ortb2` object (non-destructively — existing publisher values are preserved): + +```json +{ + "site": { + "content": { + "id": "", + "title": "

", + "data": [ + { + "name": "data.stackup-ai.com", + "ext": { "segtax": 502 }, + "segment": [ + { + "id": "IAB-123", + "name": "Technology", + "ext": { "confidence": 0.95 } + } + ] + } + ], + "ext": { + "brand_safety": {}, + "emotion": {} + } + } + }, + "user": { + "data": [ + { + "name": "data.stackup-ai.com", + "ext": { "segtax": 501 }, + "segment": [ + { + "id": "AUD-456", + "name": "Tech Enthusiasts", + "ext": { "confidence": 0.87 } + } + ] + } + ] + } +} +``` + +`site.content.ext.brand_safety` and `site.content.ext.emotion` are optional fields populated when the API returns them. Existing publisher values in `ext` are preserved — the module only fills fields that are absent. + +## Integration Example + +Build Prebid.js with the module: + +```bash +gulp build --modules=rtdModule,stackupRtdProvider,appnexusBidAdapter +``` + +Start a static file server at the [Prebid.js repo root](https://github.com/prebid/Prebid.js) on port 9999, then open: + +```text +http://localhost:9999/integrationExamples/gpt/stackupRtdProvider_example.html +``` + +The page runs a real GAM/GPT auction. With `debug: true` in `pbjs.setConfig` the Prebid.js debug console shows the enriched `ortb2` fragments (`site.content.data` and `user.data`) merged into each bid request. diff --git a/dev-docs/modules/storageControl.md b/dev-docs/modules/storageControl.md index 9c467841f0..e43dc2cbd3 100644 --- a/dev-docs/modules/storageControl.md +++ b/dev-docs/modules/storageControl.md @@ -4,7 +4,7 @@ page_type: module title: Module - Storage Control description: Check or enforce disclosure of device storage use module_code : storageControl -display_name : storageControl +display_name : Storage Control enable_download : true recommended: true sidebarType : 1 diff --git a/dev-docs/modules/symitriDapRtdProvider.md b/dev-docs/modules/symitriDapRtdProvider.md index 66211f6908..ab93999dae 100644 --- a/dev-docs/modules/symitriDapRtdProvider.md +++ b/dev-docs/modules/symitriDapRtdProvider.md @@ -107,7 +107,7 @@ pbjs.setConfig({ To view an example of available segments returned by dap: ```bash -gulp serve --modules=rtdModule,symitriDapRtdProvider,appnexusBidAdapter,sovrnBidAdapter +gulp serve --modules=rtdModule,symitriDapRtdProvider,msftBidAdapter,sovrnBidAdapter ``` and then point your browser at: diff --git a/dev-docs/modules/tcfControl.md b/dev-docs/modules/tcfControl.md index df8e64a7cd..e3b9fb4102 100644 --- a/dev-docs/modules/tcfControl.md +++ b/dev-docs/modules/tcfControl.md @@ -48,9 +48,9 @@ The following table details the Prebid.js activities that fall under the [Transp | Read and write data to device | Purpose 1 - Store and/or access information on a device | May prevent one or more adapters or modules from being able to read or write cookies or localstorage in the user's browser. | 3.14+ | | Perform header bidding auction | Purpose 2 - Basic ads | May prevent one or more bid adapters from participating in the auction. | 4.0+ | | Transmit user first party data to partners | Purpose 4 - Personalized ads | May prevent one or more modules from receiving user first party data | 8.16+ | -| Transmit Extended User IDs to partners | Depends on configuration (see [note](#note-transmitEids))| May prevent one or more modules from receiving user IDs and EIDs. | 8.16+ | +| Transmit Extended User IDs to partners | Depends on configuration (see [note](#note-transmitEids)) | May prevent one or more modules from receiving user IDs and EIDs. | 8.16+ | | Invoke analytics adapters | Purpose 7 - Measurement | May prevent one or more analytics adapters from participating in the auction. | 4.x+ | -| Transmit precise geolocation data to partners | Specal Feature 1 - Use precise geolocation data | May cause geolocation data to be truncated for one or more modules | 8.16+ | +| Transmit precise geolocation data to partners | Specal Feature 1 - Use precise geolocation data | May cause geolocation data to be truncated for one or more modules | 8.16+ | ## Page Integration @@ -78,8 +78,9 @@ The following fields related to anonymizing aspects of the auction are supported | gdpr.rules[].vendorExceptions | `Array of Strings` | Defines a list of biddercodes or module names that are exempt from determining legal basis for this Purpose. **Note:** Prebid.org recommends working with a privacy lawyer before making enforcement exceptions for any vendor. | ["bidderA", "userID-module-B"] | | gdpr.rules[].softVendorExceptions | `Array of Strings` | Defines a list of biddercodes or module names that are exempt from the checking vendor signals for this purpose. Unlike with `vendorExceptions`, Purpose consent is still checked. **Note:** Prebid.org recommends working with a privacy lawyer before making enforcement exceptions for any vendor. | ["bidderA", "userID-module-B"] | | gdpr.rules[].eidsRequireP4Consent | `Boolean` | Only relevant on the personalizedAds `purpose`. If true, user IDs and EIDs will not be shared without evidence of consent for TCF Purpose 4. If false, evidence of consent for any of Purposes 2-10 is sufficient for sharing user IDs and EIDs. Defaults to false. See [note](#note-transmitEids) | true | +| gdpr.defaultLegalBasis | `Object` | Defines the fallback legal-basis declarations that tcfControl should use when a module's GVL declaration is not checked or is not known. See [Default Legal Basis](#default-legal-basis) below. | `{purposes: [1, 2, 4, 7], flexiblePurposes: [2], legIntPurposes: [], specialFeatures: [1]}` | | strictStorageEnforcement | `Boolean` | If false (the default), allows some use of storage regardless of purpose 1 consent - see [note](#strictStorageEnforcement) below | true | -| gdpr.rules[].deferS2Sbidders | `Boolean` | If true, allows s2s bidders to bypass vendor consent check and delegate it to server. Applies only to `basicAds` rule. Defaults to true | true | +| gdpr.rules[].deferS2Sbidders | `Boolean` | If true, allows s2s bidders to bypass vendor consent check and delegate it to server. Applies only to `basicAds` rule. Defaults to false | false | Notes: @@ -96,6 +97,10 @@ pbjs.setConfig({ }); ``` +* If you set `gvlMapping` for a module whose legal-basis declarations are not + already known to Prebid.js (i.e. it maps to a GVL ID not used by any other module), also set [`gvlLegalBasisMapping`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-gvlLegalBasisMapping) for that GVL ID or + review the `defaultLegalBasis` fallback described below. + ### Examples The following examples cover a range of use cases and show how Prebid.js supports @@ -187,36 +192,121 @@ configuration of different business rules. }] ``` -## Basic Legal Basis +## Legal basis + + + +### Full enforcement (since Prebid.js 11.15) + +Since version 11.15, Prebid.js uses the legal basis declared by each vendor in the GVL at the time of release, which can be further configured with [`gvlLegalBasisMapping`](/dev-docs/publisher-api-reference/setConfig.html#setConfig-gvlLegalBasisMapping) and [`consentManagement.gdpr.defaultLegalBasis`](#default-legal-basis). +This consists of the following fields from GVL vendor entries: + +* `purposes` lists purposes where the vendor declares consent as the legal basis. +* `legIntPurposes` lists purposes where the vendor declares legitimate interest + (LI) as the legal basis. +* `flexiblePurposes` lists purposes where the vendor can use either consent or + LI. Each flexible purpose must also be declared in either `purposes` or + `legIntPurposes`. +* `specialFeatures` lists special features the module may utilize when performing some declared purposes processing. + +See also: [vendor list 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). + +Before allowing an activity tied to a TCF-protected Purpose for a given vendor, one of these scenarios must be true: -Prebid.js does not have access to the Global Vendor List (GVL), so it implements +* Configuration rules check both purpose and vendor signals (`enforcePurpose: true, enforceVendor: true`) and: + * we have the user's consent for both purpose and vendor and the vendor declares either consent or LI as a legal basis for the purpose, or + * we confirmed that the user's LI transparency was established for both purpose and vendor and the vendor declares LI as a legal basis for the purpose, or + * we have the user's consent for the purpose, the vendor is excepted through `softVendorExceptions`, and `defaultLegalBasis` declares either consent or LI as a legal basis for the purpose, or + * we confirmed that the user's LI transparency was established for the purpose, the vendor is excepted through `softVendorExceptions`, and `defaultLegalBasis` declares LI as a legal basis for the purpose, or + * the vendor is excepted through `vendorExceptions`; +* Configuration rules check only purpose signals (`enforcePurpose: true, enforceVendor: false`) and: + * we have the user's consent for the purpose and `defaultLegalBasis` declares either consent or LI as a legal basis for the purpose or + * we confirmed that the user's LI transparency was established for the purpose and `defaultLegalBasis` declares LI as a legal basis for the purpose, or + * the vendor is excepted through `vendorExceptions`; +* Configuration rules check only vendor signals (`enforcePurpose: false, enforceVendor: true`) and: + * we have the user's consent for the vendor and the vendor declares either consent or LI as a legal basis for the purpose, or + * we confirmed that the user's LI transparency was established for the vendor and the vendor declares LI as a legal basis for the purpose, or + * the vendor is excepted through either `softVendorExceptions` or `vendorExceptions`; +* Configuration rules check neither purpose consent nor vendor signal (`enforcePurpose: false, enforceVendor: false`). + +### Basic enforcement (Prebid.js versions prior to 11.15) + +Prior to version 11.15, Prebid.js did not have access to the Global Vendor List (GVL), so it implements a "basic" form of TCF 'legal basis' validation using the supplied consent string. A goal of 'basic legal basis' is to confirm that there's enough evidence of consent to pass data on to vendors who do have access to the GVL and can fully parse and take any necessary action. Evidence of consent for a particular purpose or vendor means that: -* Prebid.js has the the user's vendor purpose or vendor consent, or -* (for Purpose 2 only) we've confirmed the user's Legitimate Intereset (LI) Transparency is established for this purpose or vendor. +* Prebid.js has the user's purpose or vendor consent, or +* (for Purpose 2 only) we've confirmed the user's Legitimate Interest (LI) Transparency is established for this purpose or vendor. Before allowing an activity tied to a TCF-protected Purpose for a given vendor, one of these scenarios must be true: -* Configuration rules check both consent and vendor signals and: +* Configuration rules check both purpose and vendor signals (`enforcePurpose: true, enforceVendor: true`) and: * we have evidence of consent for both, or * we have evidence of consent for the purpose, and the vendor is excepted through `softVendorException`, or * the vendor is excepted through `vendorExceptions`; -* Configuration rules check only purpose consent and either: +* Configuration rules check only purpose signals (`enforcePurpose: true, enforceVendor: false`) and: * we have evidence of consent for the purpose, or * the vendor is excepted through `vendorExceptions`; -* Configuration rules check only vendor signals and either: +* Configuration rules check only vendor signals (`enforcePurpose: false, enforceVendor: true`) and: * we have evidence of consent for the vendor, or * the vendor is excepted through either `softVendorExceptions` or `vendorExceptions`; -* Configuration rules check neither purpose consent nor vendor signal. +* Configuration rules check neither purpose consent nor vendor signal (`enforcePurpose: false, enforceVendor: false`). See the [IAB TCF 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) for details. Before allowing an activity tied to a TCF-protected Purpose for a publisher module, such as Generic Analytics, SharedId, Pub-provided-id, configuration rules check for the relevant publisher purpose consent instead of vendor consent. IAB Europe officials have written to Prebid that "When one is seeking a signal indicating whether the Publisher has had their consent (or legitimate interest) legal basis established to the data subject by the CMP, one should examine the Publisher Purposes Transparency and Consent string segment signals, if present. The core string PurposesConsent bit sequence is intended solely to represent disclosures made by the CMP in the context of Vendors." +### Default Legal Basis + +`consentManagement.gdpr.defaultLegalBasis` defines the fallback legal basis +declaration that tcfControl uses when vendor declarations are not available or +are intentionally not checked. It applies when: + +* `enforceVendor` is `false` for the applicable rule; +* the vendor is listed in `softVendorExceptions` for the applicable rule; or +* tcfControl cannot find the module's declarations, such as when a module's GVL + ID is supplied through `gvlMapping` without a matching `gvlLegalBasisMapping` + entry. + +The default value is: + +```javascript +{ + purposes: [1, 2, 4, 7], + flexiblePurposes: [2], + legIntPurposes: [], + specialFeatures: [1] +} +``` + +This default preserves the legacy behavior of treating Purposes 1, 2, 4, and 7 +as consent-based, treating Purpose 2 as flexible, and requiring opt-in for +Special Feature 1. To use LI as the fallback legal basis for Purpose 7, for +example, move Purpose 7 from `purposes` to `legIntPurposes`: + +```javascript +pbjs.setConfig({ + consentManagement: { + gdpr: { + cmpApi: 'iab', + defaultLegalBasis: { + purposes: [1, 2, 4], + legIntPurposes: [7], + flexiblePurposes: [2], + specialFeatures: [1] + } + } + } +}); +``` + +If a purpose is listed in `flexiblePurposes`, it must also be listed in either +`purposes` or `legIntPurposes`. Do not list the same purpose in both `purposes` +and `legIntPurposes`. + ### Note on Extended User IDs diff --git a/dev-docs/modules/userid-submodules/abtshield.md b/dev-docs/modules/userid-submodules/abtshield.md new file mode 100644 index 0000000000..bd6d9581fe --- /dev/null +++ b/dev-docs/modules/userid-submodules/abtshield.md @@ -0,0 +1,78 @@ +--- +layout: userid +title: ABTShield ID +description: ABTShield ID User ID sub-module +useridmodule: abtshieldIdSystem +bidRequestUserId: abtshieldId +eidsource: abtshield.com +example: '"abc-123-def-456"' +--- + +ABTShield provides cookie-less user identification and audience segmentation for publishers. The module fetches a unique user UUID and optional audience segments from the ABTShield MCR endpoint and surfaces them to bid adapters via the standard Prebid.js `user.eids` interface. + +For more information and to obtain a service ID, visit [abtshield.com](https://abtshield.com). + +## ABTShield ID Prerequisites + +Before using this module you need a **service ID (`sid`)** - register at [abtshield.com](https://abtshield.com) to obtain a unique identifier for your integration. You must also whitelist every domain from which the module will be loaded in the ABTShield dashboard. + +## ABTShield ID Configuration + +Add the module to your Prebid.js build: + +```bash +gulp build --modules=userId,abtshieldIdSystem +``` + +Then configure the module in your `userSync` configuration: + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'abtshieldId', + params: { + sid: 'pb.your-service-id' // required + }, + storage: { + type: 'html5', + name: 'abtshield_id', + expires: 1 + } + }] + } +}); +``` + +{: .table .table-bordered .table-striped } +| Param | Scope | Type | Description | +| --- | --- | --- | --- | +| `params.sid` | Required | String | Service ID obtained from abtshield.com. | +| `params.endpoint` | Optional | String | Override the MCR endpoint. For test environments only. Must use HTTPS. | +| `storage` | Recommended | Object | Standard Prebid User ID storage block (`html5` or `cookie`). | + +## ABTShield ID Example + +This will add a `userId.abtshieldId` property to bid requests: + +```javascript +{ + abtshieldId: { + uuid: 'abc-123-def-456', + segments: ['seg-1', 'seg-2'] // omitted when no segments are returned + } +} +``` + +The `user.eids` entry will look like: + +```javascript +{ + source: 'abtshield.com', + uids: [{ + id: 'abc-123-def-456', + atype: 1, + ext: { segments: ['seg-1', 'seg-2'] } // omitted when no segments are returned + }] +} +``` diff --git a/dev-docs/modules/userid-submodules/adplus.md b/dev-docs/modules/userid-submodules/adplus.md index fefbb4611c..1fadf949f1 100644 --- a/dev-docs/modules/userid-submodules/adplus.md +++ b/dev-docs/modules/userid-submodules/adplus.md @@ -21,8 +21,6 @@ gulp build --modules=adplusIdSystem,userId | Param under userSync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | name | Required | String | The name of this module: `"adplusId"` | `"adplusId"` | -| storage.expires | Optional | Number | How long (in days) the user ID information will be stored | `7` (recommended) | -| storage.refreshInSeconds | Optional | Number | How many seconds until the ID is refreshed | `24 * 3600` (recommended) | ## AdPlus ID Example @@ -32,10 +30,7 @@ pbjs.setConfig({ userIds: [{ name: "adplusId", storage: { - name: "adplusId", - type: "cookie&html5", - expires: 7, - refreshInSeconds: 24 * 3600 + name: "adplusId" } }] } diff --git a/dev-docs/modules/userid-submodules/euid.md b/dev-docs/modules/userid-submodules/euid.md index aeedada2c7..0ea2e77eea 100644 --- a/dev-docs/modules/userid-submodules/euid.md +++ b/dev-docs/modules/userid-submodules/euid.md @@ -185,8 +185,14 @@ The following parameters apply only to the European Unified ID module integratio | value | Optional, Server only | Object | An object containing the value for the advertising token. | See the example above. | | params.euidToken | Optional, Client refresh | Object | The initial EUID token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. | | params.euidCookie | Optional, Client refresh | String | The name of a cookie which holds the initial EUID token, set by the server. The cookie should contain JSON in the same format as the euidToken param. **If euidToken is supplied, this param is ignored.** | See the sample token above. | -| params.euidApiBase | Optional, Client refresh | String | Overrides the default EUID API endpoint. | `"https://prod.euid.eu"` _(default)_| +| params.euidApiBase | Optional, Client refresh | String | Overrides the default EUID API endpoint. | `"https://prod.euid.eu"` _(default)_ | | params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | +| params.serverPublicKey | Optional | String | Server public key for client-side token generation | | +| params.subscriptionId | Optional | String | Subscription id for client-side token generation, provided by the EUID team. | | +| params.email | Optional | String | User email for client-side token generation. Only one of the DII parameters will be used. | | +| params.phone | Optional | String | User phone number for client-side token generation. Only one of the DII parameters will be used. | | +| params.emailHash | Optional | String | Hashed user email for client-side token generation. Only one of the DII parameters will be used. | | +| params.phoneHash | Optional | String | Hashed phone number for client-side token generation. Only one of the DII parameters will be used. | | ## European Unified ID Examples diff --git a/dev-docs/modules/userid-submodules/pubprovided.md b/dev-docs/modules/userid-submodules/pubprovided.md index e533bd8c15..77a8fa07c9 100644 --- a/dev-docs/modules/userid-submodules/pubprovided.md +++ b/dev-docs/modules/userid-submodules/pubprovided.md @@ -116,10 +116,11 @@ gulp build --modules=pubProvidedIdSystem {: .table .table-bordered .table-striped } -| Params under usersync.userIds[]| Scope | Type | Description | Example | +| Params under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | ID value for the ID module | `"PubProvided"` | +| name | Required | String | ID value for the ID module | `"PubProvided"` | | params | Optional | Object | Details for syncing. | | -| params.eidsFunction | Optional | function | any function that exists in the page | getIdsFn() | +| params.eids | Optional | Object[] | Array of extended identifiers as defined in the OpenRTB specification. | | +| params.eidsFunction | Optional | function | any function that exists in the page and returns an array of extended identifiers. The results are concatenated with `eids` | getIdsFn() | | uids.atype | optional | int | ADCOM - Type of user agent the match is from | `"1"` | | uids.ext.stype | Optional | String | Description of how the id was generated and by whom eg. ('ppuid','DMP','other') | `DMP` | diff --git a/dev-docs/modules/userid-submodules/rediads.md b/dev-docs/modules/userid-submodules/rediads.md new file mode 100644 index 0000000000..d2d0775a15 --- /dev/null +++ b/dev-docs/modules/userid-submodules/rediads.md @@ -0,0 +1,125 @@ +--- +layout: userid +title: Rediads ID +description: Rediads User ID sub-module +useridmodule: rediadsIdSystem +bidRequestUserId: rediadsId +eidsource: rediads.com +example: '"ruid_7b9c1d3f-1e2b-4e7b-9e5a-acde12345678"' +--- + +## Overview + +The Rediads User ID submodule generates a first-party browser identifier for publisher-side identity and makes it available to Prebid bidders through both `bidRequest.userId.rediadsId` and `bidRequest.userIdAsEids`. + +This submodule is implemented as a Prebid User ID module and uses Prebid-managed storage. + +## Registration + +For setup information, contact [support@rediads.com](mailto:support@rediads.com). + +## Installation + +Build Prebid.js with the User ID core module, the Rediads ID submodule, and optionally the Rediads bidder: + +```bash +gulp build --modules=rediadsBidAdapter,userId,rediadsIdSystem +``` + +If you only need the user ID module, you can omit `rediadsBidAdapter`: + +```bash +gulp build --modules=userId,rediadsIdSystem +``` + +## Configuration + +```javascript +pbjs.setConfig({ + userSync: { + userIds: [{ + name: 'rediadsId', + params: { + source: 'rediads.com' + }, + storage: { + type: 'html5', + name: 'rediads_id', + expires: 30, + refreshInSeconds: 3600 + } + }] + } +}); +``` + +## Parameters + +{: .table .table-bordered .table-striped } + +| Param under `userSync.userIds[]` | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| `name` | Required | String | Module identifier. Must be `"rediadsId"`. | `"rediadsId"` | +| `params` | Optional | Object | Rediads-specific configuration. | | +| `params.source` | Optional | String | EID source to emit. Defaults to `"rediads.com"`. | `"rediads.com"` | +| `storage` | Recommended | Object | Prebid-managed storage configuration. | | +| `storage.type` | Recommended | String | Storage type. Use `"html5"`, `"cookie"`, or `"cookie&html5"` as needed. | `"html5"` | +| `storage.name` | Recommended | String | Storage key name. | `"rediads_id"` | +| `storage.expires` | Optional | Number | Lifetime of the stored ID in days. Defaults to `30`. | `30` | +| `storage.refreshInSeconds` | Optional | Number | Refresh interval in seconds. Defaults to `3600`. | `3600` | + +## Privacy Handling + +The Rediads ID submodule follows the standard Prebid User ID privacy flow. + +- If COPPA applies, the module does not create or return an ID. +- If GDPR applies without a valid consent string and Purpose 1 consent, the module does not create or return an ID. +- If US Privacy or GPP opt-out signals restrict sharing, the module may still retain its local ID state but does not emit EIDs for bidder sharing. + +The module uses Prebid's vendorless TCF marker so purpose-level enforcement applies without requiring a separate vendor registration in the module config. + +## Bid Request Output + +When available, the Rediads ID is exposed on the bid request as: + +```javascript +bidRequest.userId.rediadsId +``` + +Example: + +```json +{ + "uid": "ruid_7b9c1d3f-1e2b-4e7b-9e5a-acde12345678", + "source": "rediads.com", + "atype": 1, + "ext": { + "canShare": true + } +} +``` + +## EID Output + +When sharing is permitted, the module contributes the following EID: + +```json +{ + "source": "rediads.com", + "uids": [{ + "id": "ruid_7b9c1d3f-1e2b-4e7b-9e5a-acde12345678", + "atype": 1 + }] +} +``` + +## Testing + +After building Prebid.js with `userId` and `rediadsIdSystem`, you can verify the module with: + +```javascript +pbjs.getUserIds() +pbjs.getUserIdsAsEids() +``` + +You should see `rediadsId` in `getUserIds()` and a `rediads.com` entry in `getUserIdsAsEids()` when privacy settings allow sharing. diff --git a/dev-docs/modules/userid-submodules/unified2.md b/dev-docs/modules/userid-submodules/unified2.md index 0c2fc02cc3..a7b5eb7313 100644 --- a/dev-docs/modules/userid-submodules/unified2.md +++ b/dev-docs/modules/userid-submodules/unified2.md @@ -96,10 +96,17 @@ The following parameters apply only to the Unified ID 2.0 module integration. | --- | --- | --- | --- | --- | | name | Required | String | ID value for the Unified ID 2.0 module - `"uid2"` | `"uid2"` | | params.uid2Token | Optional | Object | The initial UID2 token. This should be the `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. | -| params.uid2ServerCookie | Optional | String | The name of a cookie that holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the alternative uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. | +| params.uid2Cookie | Optional | String | The name of a cookie that holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the alternative uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. | +| params.uid2ServerCookie | Optional | String | Alias for `uid2Cookie`. | | | params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `https://prod.uidapi.com` _(default)_ | -| value | Optional | Object | Used only if the page has a separate mechanism for storing the UID 2.0 ID. The value is an object containing the values to be sent to the adapters. In this scenario, no URL is called and nothing is added to local storage, and the tokens are **not** automatically refreshed. | `{"uid2": { "id": "eb33b0cb-8d35-4722-b9c0-1a31d4064888"}}` | | params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ | +| params.serverPublicKey | Optional | String | Server public key for client-side token generation | | +| params.subscriptionId | Optional | String | Subscription id for client-side token generation, provided by the EUID team. | | +| params.email | Optional | String | User email for client-side token generation. Only one of the DII parameters will be used. | | +| params.phone | Optional | String | User phone number for client-side token generation. Only one of the DII parameters will be used. | | +| params.emailHash | Optional | String | Hashed user email for client-side token generation. Only one of the DII parameters will be used. | | +| params.phoneHash | Optional | String | Hashed phone number for client-side token generation. Only one of the DII parameters will be used. | | +| value | Optional | Object | Used only if the page has a separate mechanism for storing the UID 2.0 ID. The value is an object containing the values to be sent to the adapters. In this scenario, no URL is called and nothing is added to local storage, and the tokens are **not** automatically refreshed. | `{"uid2": { "id": "eb33b0cb-8d35-4722-b9c0-1a31d4064888"}}` | ## Unified ID 2.0 Examples diff --git a/dev-docs/modules/userid-submodules/utiq.md b/dev-docs/modules/userid-submodules/utiq.md index 87ca81589f..26e1f40884 100644 --- a/dev-docs/modules/userid-submodules/utiq.md +++ b/dev-docs/modules/userid-submodules/utiq.md @@ -62,4 +62,4 @@ pbjs.setConfig({ ## Utiq ID onboarding -If you wish to find out more about Utiq, please contact +If you wish to find out more about Utiq, please contact diff --git a/dev-docs/modules/userid-submodules/utiqMtp.md b/dev-docs/modules/userid-submodules/utiqMtp.md index 6f061622a4..6a6041e42b 100644 --- a/dev-docs/modules/userid-submodules/utiqMtp.md +++ b/dev-docs/modules/userid-submodules/utiqMtp.md @@ -45,7 +45,7 @@ pbjs.setConfig({ }) ``` -You may like to consider limiting the SSPs that receive the martechpass by **adding the bidders array**, to make sure they are not forwarding this first party ID to DSPs. We are working with SSPs to blacklist the above source from being sent to DSPs, please reach out to to verify which are these SSPs. +You may like to consider limiting the SSPs that receive the martechpass by **adding the bidders array**, to make sure they are not forwarding this first party ID to DSPs. We are working with SSPs to blacklist the above source from being sent to DSPs, please contact to verify which are these SSPs. ## TCF Activity Integration @@ -74,4 +74,4 @@ pbjs.setConfig({ ## Utiq ID onboarding -If you wish to find out more about Utiq, please contact +If you wish to find out more about Utiq, please contact diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index f558c47da3..1d21923776 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -219,16 +219,16 @@ This property support the following types | Type | Description | Example | Notes | | :------------ | :------------ | :------------ |:------------ | | Boolean|If true, send data to all bidders, or not in case of false| `true` | default value | -| String|Will send data to only one bidder | `'appnexus'` | | -| Array of Strings|Will send data to only some bidders | `['appnexus','pubmatic']` | | -| Object |Will send data to only some bidders and some ad units | `{appnexus: true, pubmatic:['adUnitCode1']}` | | -| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(bid, adUnitCode){return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode';}` | | +| String|Will send data to only one bidder | `'msft'` | | +| Array of Strings|Will send data to only some bidders | `['msft','pubmatic']` | | +| Object |Will send data to only some bidders and some ad units | `{msft: true, pubmatic:['adUnitCode1']}` | | +| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(bid, adUnitCode){return bid.bidder == 'msft' && adUnitCode == 'adUnitCode';}` | | A better look on the `Object` type ```javascript sendToBidders: { - appnexus: true, // send profile to appnexus on all ad units + msft: true, // send profile to msft on all ad units pubmatic: ['adUnitCode1'],// send profile to pubmatic on this ad units } ``` @@ -254,8 +254,8 @@ It is possible customize the targeting based on the parameters: ```javascript sendToBidders: function(bid, adUnitCode, data, metadata){ - if (bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'){ - data['foo']=['bar']; // add this section only for appnexus + adUnitCode1 + if (bid.bidder == 'msft' && adUnitCode == 'adUnitCode1'){ + data['foo']=['bar']; // add this section only for msft + adUnitCode1 delete data['other']; // remove this section } return true; @@ -282,7 +282,7 @@ sendToBidders: function(bid, adUnitCode, data, metadata){ In case of using bid _aliases_, we should match the same string used in the adUnit configuration. ```javascript -pbjs.aliasBidder('appnexus', 'foo'); +pbjs.aliasBidder('msft', 'foo'); pbjs.aliasBidder('criteo', 'bar'); pbjs.aliasBidder('pubmatic', 'baz'); pbjs.setConfig({ @@ -503,7 +503,7 @@ pbjs.que.push(function () { weboCtxConf: { token: "to-be-defined", // mandatory setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits - sendToBidders: ['appnexus',...], // overide, send to only some bidders + sendToBidders: ['msft',...], // overide, send to only some bidders enabled: true, }, weboUserDataConf: { @@ -553,7 +553,7 @@ pbjs.que.push(function () { token: "to-be-defined", // mandatory targetURL: "https://prebid.org", // default is document.URL setPrebidTargeting: true, // override param.setPrebidTargeting or default true - sendToBidders: ['appnexus',...], // overide, send to only some bidders + sendToBidders: ['msft',...], // overide, send to only some bidders defaultProfile: { // optional webo_ctx: ['moon'], webo_ds: ['bar'] @@ -565,7 +565,7 @@ pbjs.que.push(function () { accountId: 12345, // recommended setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits sendToBidders: { // send to only some bidders and adunits - 'appnexus': true, // all adunits for appnexus + 'msft': true, // all adunits for msft 'pubmatic': ['adUnitCode1',...] // some adunits for pubmatic // other bidders will be ignored }, @@ -582,7 +582,7 @@ pbjs.que.push(function () { return adUnitCode == 'adUnitCode1'; }, sendToBidders: function(bid, adUnitCode){ // specify sendToBidders via callback - return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'; + return bid.bidder == 'msft' && adUnitCode == 'adUnitCode1'; } defaultProfile: { // optional lite_occupation: ['gérant', 'bénévole'], @@ -603,7 +603,7 @@ pbjs.que.push(function () { We currently support the following bidder adapters with dedicated code: -* AppNexus SSP +* Microsoft SSP We also set the bidder (and global, if no specific bidders are set on `sendToBidders`) ortb2 `site.ext.data` and `user.ext.data` sections (as arbitrary data). The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from [here](https://docs.prebid.org/dev-docs/bidders). @@ -645,7 +645,7 @@ We also set the bidder (and global, if no specific bidders are set on `sendToBid To view an example of available segments returned by Weborama's backends: -`gulp serve --notest --nolint --modules=rtdModule,weboramaRtdProvider,smartadserverBidAdapter,pubmaticBidAdapter,appnexusBidAdapter,rubiconBidAdapter,criteoBidAdapter` +`gulp serve --notest --nolint --modules=rtdModule,weboramaRtdProvider,smartadserverBidAdapter,pubmaticBidAdapter,msftBidAdapter,rubiconBidAdapter,criteoBidAdapter` and then point your browser at: diff --git a/dev-docs/modules/wurflRtdProvider.md b/dev-docs/modules/wurflRtdProvider.md index 5ccea54724..93f4e86308 100644 --- a/dev-docs/modules/wurflRtdProvider.md +++ b/dev-docs/modules/wurflRtdProvider.md @@ -90,7 +90,7 @@ While the WURFL RTD module enriches the OpenRTB 2.0 payload, SSP adapters must a ### Integration Scenarios | SSP Adapter Status | Required Adapter Changes | Required Server Changes | -|-------------------|--------------------------|-------------------------| +| ------------------ | ------------------------ | ----------------------- | | Already passing ORTB2 device to server | No changes required | Update backend logic to utilize device data | | Not currently passing device data | Update adapter to read `device` and/or `device.ext.wurfl` and pass to endpoint | Update backend logic to utilize device data | | No Bidder Adapter exists | Implement Prebid.js adapter to read and pass `device` and/or `device.ext.wurfl` | Implement endpoint logic to read and utilize data | @@ -100,7 +100,7 @@ While the WURFL RTD module enriches the OpenRTB 2.0 payload, SSP adapters must a To build the WURFL RTD module with Prebid.js: ```bash -gulp build --modules="wurflRtdProvider,appnexusBidAdapter,..." +gulp build --modules="wurflRtdProvider,msftBidAdapter,..." ``` ## Configuration @@ -124,7 +124,7 @@ pbjs.setConfig({ {: .table .table-bordered .table-striped } | Name | Type | Description | Default | -|------|------|-------------|---------| +| ---- | ---- | ----------- | ------- | | `name` | String | Real time data module name | Always 'wurfl' | | `params` | Object | Configuration parameters | | | `params.altHost` | String | Alternate host to connect to WURFL.js | | @@ -137,7 +137,7 @@ pbjs.setConfig({ To test the WURFL RTD module locally: ```bash -gulp serve --modules=wurflRtdProvider,appnexusBidAdapter +gulp serve --modules=wurflRtdProvider,msftBidAdapter ``` Then navigate to: @@ -163,7 +163,7 @@ WURFL RTD adds comprehensive device information to the bid request. The `ortb2.d "language": "it", "make": "Apple", "model": "iPhone 16e", - "devicetype": 1, + "devicetype": 4, "os": "iOS", "osv": "18.3", "hwv": "iPhone 16e", @@ -266,6 +266,6 @@ The WURFL RTD module processes minimal personal data under legitimate interest f * Device detection uses only HTTP headers (User-Agent, Client Hints) * No user tracking or cross-site identification -* IP addresses processed transiently for service delivery only +* IP addresses are retained for up to 36 months for fraud detection and invalid traffic prevention, then permanently redacted. They are not used for user identification or behavioral profiling. For questions or support, visit [ScientiaMobile Support](https://support.scientiamobile.com). diff --git a/dev-docs/pb10-notes.md b/dev-docs/pb10-notes.md index 20fa95ba27..664677a343 100644 --- a/dev-docs/pb10-notes.md +++ b/dev-docs/pb10-notes.md @@ -19,11 +19,12 @@ This document describes the changes included for Prebid.js version 10.0. 1. A large number of obsolete modules have been removed. Many modules have changed name. See below for the list. 2. The legacy method of native targeting keys, `sendTargetingKeys`, has been removed. 3. `pbadslot` has been removed from the preAuction module. Use `ortb2Imp.ext.gpid` instead. -4. The API methods `getBidResponses` and `getNoBidsForAdUnitCode` now return arrays of bids. -5. TypeScript support has landed and Node.js 20+ is required to build. -6. Using Prebid as an NPM dependency no longer requires using Babel or Prebid's Babel settings. -7. `targetingControls.allBidsCustomTargeting` now defaults to `false`, this prevents custom targeting values from being set for non-winning bids. -8. Storage use disclosures can now be enforced and catalogued +4. The API methods `getBidResponsesForAdUnitCode` and `getNoBidsForAdUnitCode` now return arrays of bids. +5. The API methods `getBidResponses` and `getNoBids` now return an object with an array of bids for each ad unit. +6. TypeScript support has landed and Node.js 20+ is required to build. +7. Using Prebid as an NPM dependency no longer requires using Babel or Prebid's Babel settings. +8. `targetingControls.allBidsCustomTargeting` now defaults to `false`, this prevents custom targeting values from being set for non-winning bids. +9. Storage use disclosures can now be enforced and catalogued ## Removed Modules @@ -32,7 +33,7 @@ The following modules have been removed from Prebid.js as part of the 10.0 relea {: .table .table-bordered .table-striped } | Module | Replacement | -|:-----------------------------|:-------------------------| +| :----------------------------- | :------------------------- | | dfpAdServerVideo | gamAdServerVideo | | dfpAdPod | gamAdPod | | telariaBidAdapter | | diff --git a/dev-docs/plugins/bc/about-bc-prebid-plugin.md b/dev-docs/plugins/bc/about-bc-prebid-plugin.md index 98f24954ca..f36746c00a 100644 --- a/dev-docs/plugins/bc/about-bc-prebid-plugin.md +++ b/dev-docs/plugins/bc/about-bc-prebid-plugin.md @@ -29,9 +29,9 @@ The Brightcove Prebid Plugin supports the following features: * Single Ad Playback via VAST XML at one or more ad break positions within a video. (For example, you can specify options for a preroll and a postroll ad in a single call to the plugin.) * Versions up thru VAST 3.0 * Both Video and VPAID creatives - * If the AppNexus Viewability Wrapper is delivered: - * AppNexus viewability measurement - * AppNexus domain detection + * If the Microsoft Viewability Wrapper is delivered: + * Microsoft viewability measurement + * Microsoft domain detection * The plugin supports more than one ad renderer by default. * If Google Ad Manager is detected as the primary ad server (indicated by the presence of dfpParameters) for *any* of the ad breaks specified in the Prebid options, then the Brightcove IMA Plugin will be used to render the ad. diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-api.md b/dev-docs/plugins/bc/bc-prebid-plugin-api.md index d9be241b21..19c99c263f 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-api.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-api.md @@ -123,9 +123,9 @@ If the results of the prebid process is being determined outside of the plugin, } }, "bids": [{ - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 8845778 + "placement_id": 8845778 } }] }, diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-integration-dynamic.md b/dev-docs/plugins/bc/bc-prebid-plugin-integration-dynamic.md index 0a4e4af9dc..72909a5b17 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-integration-dynamic.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-integration-dynamic.md @@ -66,16 +66,16 @@ Once the Brightcove Player has loaded, then publisher needs to call `renderAd()` // define options for ad playback window.bc_plugin_pbjs = {plugin_prebid_options: {}}; // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', sizes : [640, 480], mediaType: 'video', bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567, + placement_id: 12334567, video: { skippable: true, playback_method: ['auto_play_sound_off'] @@ -172,16 +172,16 @@ To do this, the publisher must add code in the body of the document where the Br // define options for prebid var plugin_options = {}; // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', sizes : [640, 480], mediaType: 'video', bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567, + placement_id: 12334567, video: { skippable: true, playback_method: ['auto_play_sound_off'] diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-integration-studio.md b/dev-docs/plugins/bc/bc-prebid-plugin-integration-studio.md index d7f53f6e03..d5fb9c78a1 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-integration-studio.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-integration-studio.md @@ -143,9 +143,9 @@ var adOptions = } }, "bids": [{ - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 8845778 + "placement_id": 8845778 } }] }, @@ -252,7 +252,7 @@ None "bidderAliases": [ { "name": "alias1", - "bidderName": "appnexus" + "bidderName": "msft" } ], "biddersSpec": { @@ -268,9 +268,9 @@ None } }, "bids": [{ - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 8845778, + "placement_id": 8845778, "video": {"skippable": true, "playback_method": ["auto_play_sound_off"] @@ -329,7 +329,7 @@ None } ] }, - "appnexus": { + "msft": { "adserverTargeting": [ { "key": "hb_size", diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-multiad-options.md b/dev-docs/plugins/bc/bc-prebid-plugin-multiad-options.md index 7edbfcf383..2651465f7b 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-multiad-options.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-multiad-options.md @@ -58,9 +58,9 @@ The following is a sample JSON definition of the plugin configuration defining c }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 12527596 + "placement_id": 12527596 } } ] @@ -153,9 +153,9 @@ The following is a sample JSON definition of the plugin configuration defining c }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 12531984 + "placement_id": 12531984 } } ] @@ -259,9 +259,9 @@ The following is a sample JSON definition of the plugin configuration defining c }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 12527596 + "placement_id": 12527596 } } ] @@ -355,9 +355,9 @@ The following is a sample JSON definition of the plugin configuration defining c }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 12531984 + "placement_id": 12531984 } } ] @@ -451,9 +451,9 @@ The following is a sample JSON definition of the plugin configuration defining c }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 12531977 + "placement_id": 12531977 } } ] diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-prebid-options.md b/dev-docs/plugins/bc/bc-prebid-plugin-prebid-options.md index 5380e3a9be..1635d26d5b 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-prebid-options.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-prebid-options.md @@ -129,11 +129,11 @@ None ```javascript "bidderAliases": [ { - "bidderName": "appnexus", + "bidderName": "msft", "name": "alias1" }, { - "bidderName": "appnexus", + "bidderName": "msft", "name": "alias2" } ] @@ -325,7 +325,7 @@ None Parameters used when using Google Ad Manager as the ad server. -See prebid.org documentation for [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.html) +See prebid.org documentation for [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.html) **Acceptable Values:** @@ -610,7 +610,7 @@ No The publisher must pass the prebid parameters to the plugin, via the `biddersSpec` option, if the plugin is expected to invoke the prebid process. The syntax for these parameters is defined in [Bidders' Params]({{site.baseurl}}/dev-docs/bidders.html) on Prebid.org. -Use the parameters for AppNexus bidder to include an AppNexus bidder for video ads. +Use the parameters for Microsoft bidder to include an Microsoft bidder for video ads. If these parameters are not specified, the plugin assumes that the prebid process has occurred outside of the plugin and that the results of the header bidding will be provided to the plugin via the `headerBiddingResult` option. diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-body.md b/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-body.md index 9a5970d373..32b2e94391 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-body.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-body.md @@ -69,16 +69,16 @@ The following is a sample Brightcove Player Prebid Plugin integration that invok // set the prebid options // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', sizes : [640, 480], mediaType: 'video', bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567, + placement_id: 12334567, video: { skippable: true, playback_method: ['auto_play_sound_off'] diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-header.md b/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-header.md index 11062bc016..6f35b5d230 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-header.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-sample-prebid-header.md @@ -47,7 +47,7 @@ The following is a sample Brightcove Player Prebid Plugin integration that invok window.bc_plugin_pbjs = { plugin_prebid_options: {} }; // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', mediaTypes: { @@ -61,9 +61,9 @@ The following is a sample Brightcove Player Prebid Plugin integration that invok } bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567 + placement_id: 12334567 } } ] diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-sample-studio-integration-general-method.md b/dev-docs/plugins/bc/bc-prebid-plugin-sample-studio-integration-general-method.md index 6f6ca02132..ef161b5522 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-sample-studio-integration-general-method.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-sample-studio-integration-general-method.md @@ -65,9 +65,9 @@ This page presents a sample publisher page using the General Integration Method } }, "bids": [{ - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 8845778 + "placement_id": 8845778 } }] }, diff --git a/dev-docs/plugins/bc/bc-prebid-plugin-sample-third-party-ad-server.md b/dev-docs/plugins/bc/bc-prebid-plugin-sample-third-party-ad-server.md index 4efd8fb244..e4b92f7962 100644 --- a/dev-docs/plugins/bc/bc-prebid-plugin-sample-third-party-ad-server.md +++ b/dev-docs/plugins/bc/bc-prebid-plugin-sample-third-party-ad-server.md @@ -42,16 +42,16 @@ The following is a sample Brightcove Prebid Plugin integration that invokes preb window.bc_plugin_pbjs = { plugin_prebid_options: {} }; // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', sizes : [640, 480], mediaType: 'video', bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567, + placement_id: 12334567, video: { skippable: true, playback_method: ['auto_play_sound_off'] @@ -152,16 +152,16 @@ The following is a sample Brightcove Prebid Plugin integration that invokes preb // set the prebid options // specify prebid parameters as the value of biddersSpec - // the set of bidders here shows how to specify the AppNexus video bidder: appnexus + // the set of bidders here shows how to specify the Microsoft video bidder: msft var params = { code : 'my-video-tag', sizes : [640, 480], mediaType: 'video', bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 12334567, + placement_id: 12334567, video: { skippable: true, playback_method: ['auto_play_sound_off'] diff --git a/dev-docs/plugins/cross-player-prebid-component/cross-player-config.md b/dev-docs/plugins/cross-player-prebid-component/cross-player-config.md index 2e6418c867..98c9365d14 100644 --- a/dev-docs/plugins/cross-player-prebid-component/cross-player-config.md +++ b/dev-docs/plugins/cross-player-prebid-component/cross-player-config.md @@ -109,11 +109,11 @@ None ```javascript "bidderAliases": [ { - "bidderName": "appnexus", + "bidderName": "msft", "name": "alias1" }, { - "bidderName": "appnexus", + "bidderName": "msft", "name": "alias2" } ] @@ -209,7 +209,7 @@ None Parameters used when using Google Ad Manager (formerly DFP) as the ad server. -See documentation for [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.html) for more information. +See documentation for [buildVideoUrl](/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.html) for more information. **Acceptable Values:** @@ -324,9 +324,9 @@ Here is a sample Prebid configuration JSON object returned via URL: }, "bids": [ { - "bidder": "appnexus", + "bidder": "msft", "params": { - "placementId": 9999 + "placement_id": 9999 } } ] @@ -372,10 +372,10 @@ Here is a sample Prebid configuration JSON object returned via URL: } ] }, - "appnexus": { + "msft": { "adserverTargeting": [ { - "key": "hb_appnexus_key1", + "key": "hb_msft_key1", "val": [ "valueIsFunction", "function (bidResponse) {", @@ -384,7 +384,7 @@ Here is a sample Prebid configuration JSON object returned via URL: ] }, { - "key": "hb_appnexus_key2", + "key": "hb_msft_key2", "val": [ "valueIsFunction", "function (bidResponse) {", @@ -393,7 +393,7 @@ Here is a sample Prebid configuration JSON object returned via URL: ] }, { - "key": "hb_appnexus_key3", + "key": "hb_msft_key3", "val": "value3" } ] diff --git a/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md b/dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md similarity index 88% rename from dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md rename to dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md index 2622837b3c..cf0d72f57c 100644 --- a/dev-docs/publisher-api-reference/adServers.dfp.buildAdpodVideoUrl.md +++ b/dev-docs/publisher-api-reference/adServers.gam.buildAdpodVideoUrl.md @@ -1,19 +1,19 @@ --- layout: api_prebidjs -title: pbjs.adServers.dfp.buildAdpodVideoUrl(options) [Alpha] -description: adServers.dfp.buildAdpodVideoUrl API +title: pbjs.adServers.gam.buildAdpodVideoUrl(options) [Alpha] +description: adServers.gam.buildAdpodVideoUrl API sidebarType: 1 --- {: .alert.alert-info :} -The GAM implementation of this function requires including the `dfpAdServerVideo` module in your Prebid.js build. +The GAM implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build. This method combines publisher-provided parameters with Prebid.js targeting parameters to build a GAM video ad tag URL that can be used by a video player. -#### Argument Reference +## Argument Reference -##### The `options` object +### The `options` object {: .table .table-bordered .table-striped } | Field | Type | Description | @@ -23,7 +23,7 @@ This method combines publisher-provided parameters with Prebid.js targeting para {% include alerts/alert_important.html content="For long form Prebid.js will add key-value strings for multiple bids. This prevents retrieving the description url from bid." %} -#### Example +## Example ```JavaScript pbjs.que.push(function(){ @@ -42,7 +42,7 @@ pbjs.que.push(function(){ pbjs.requestBids({ bidsBackHandler: function(bids) { - pbjs.adServers.dfp. buildAdpodVideoUrl({ + pbjs.adServers.gam. buildAdpodVideoUrl({ codes: ['sample-code'], params: { iu: '/123456/testing/prebid.org/adunit1', diff --git a/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md b/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md similarity index 92% rename from dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md rename to dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md index 6c8ccae331..b30b8bc35c 100644 --- a/dev-docs/publisher-api-reference/adServers.dfp.buildVideoUrl.md +++ b/dev-docs/publisher-api-reference/adServers.gam.buildVideoUrl.md @@ -1,19 +1,18 @@ --- layout: api_prebidjs -title: pbjs.adServers.dfp.buildVideoUrl(options) -description: adServers.dfp.buildVideoUrl API +title: pbjs.adServers.gam.buildVideoUrl(options) +description: adServers.gam.buildVideoUrl API sidebarType: 1 --- - {: .alert.alert-info :} -The Google Ad Manager implementation of this function requires including the `dfpAdServerVideo` module in your Prebid.js build. +The Google Ad Manager implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build. This method combines publisher-provided parameters with Prebid.js targeting parameters to build a Google Ad Manager video ad tag URL that can be used by a video player. -#### Argument Reference +## Argument Reference -##### The `options` object +### The `options` object {: .table .table-bordered .table-striped } | Field | Type | Description | @@ -26,7 +25,7 @@ This method combines publisher-provided parameters with Prebid.js targeting para {: .alert.alert-warning :} One or both of options.params and options.url is required. In other words, you may pass in one, the other, or both, but not neither. -##### The `options.params` object +### The `options.params` object {: .table .table-bordered .table-striped } | Field | Type | Description | Example | @@ -37,7 +36,7 @@ One or both of options.params and options.url is required. In other words, you m For more information on any of these params, see [the Google Ad Manager video tag documentation](https://support.google.com/admanager/answer/1068325). -#### Examples +## Examples There are several different ways to build up your video URL, as shown in the examples below: @@ -46,7 +45,7 @@ Using `options.params` only: ```javascript pbjs.requestBids({ bidsBackHandler: function(bids) { - var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + var videoUrl = pbjs.adServers.gam.buildVideoUrl({ adUnit: videoAdUnit, params: { iu: '/19968336/prebid_cache_video_adunit', @@ -72,7 +71,7 @@ var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' + '&env=vp&output=xml_vast2&unviewed_position_start=1&hl=en&url=https://www.example.com' + '&cust_params=section%3Dblog%26anotherKey%3DanotherValue'; -var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ +var videoUrl = pbjs.adServers.gam.buildVideoUrl({ adUnit: videoAdUnit, url: adserverTag }); diff --git a/dev-docs/publisher-api-reference/adServers.gam.getVastXml.md b/dev-docs/publisher-api-reference/adServers.gam.getVastXml.md index 9a45bd6d96..3d85c8dde0 100644 --- a/dev-docs/publisher-api-reference/adServers.gam.getVastXml.md +++ b/dev-docs/publisher-api-reference/adServers.gam.getVastXml.md @@ -7,15 +7,15 @@ sidebarType: 1 {: .alert.alert-info :} -The Google Ad Manager implementation of this function requires including the dfpAdServerVideo module in your Prebid.js build. +The Google Ad Manager implementation of this function requires including the `gamAdServerVideo` module in your Prebid.js build. This method extends the behavior of `buildVideoUrl` by not only constructing the Google Ad Manager video ad tag URL, but also fetching and processing the resulting VAST wrapper returned by GAM. If the `cache.useLocal` flag is set to true, the function scans the received GAM VAST wrapper for the bid’s cached asset URL that corresponds to a locally stored blob in Prebid.js. When such a match is found, it replaces the contents of the GAM wrapper with the contents of the locally cached VAST XML blob, effectively inlining the ad markup instead of referencing it remotely. -#### Argument Reference +## Argument Reference -##### The `options` object +### The `options` object {: .table .table-bordered .table-striped } | Field | Type | Description | @@ -28,7 +28,7 @@ If the `cache.useLocal` flag is set to true, the function scans the received GAM {: .alert.alert-warning :} One or both of options.params and options.url is required. In other words, you may pass in one, the other, or both, but not neither. -##### The `options.params` object +### The `options.params` object {: .table .table-bordered .table-striped } | Field | Type | Description | Example | @@ -39,7 +39,7 @@ One or both of options.params and options.url is required. In other words, you m For more information on any of these params, see [the Google Ad Manager video tag documentation](https://support.google.com/admanager/answer/1068325). -#### Example +## Example ```javascript pbjs.requestBids({ diff --git a/dev-docs/publisher-api-reference/addAdUnits.md b/dev-docs/publisher-api-reference/addAdUnits.md index 4af75f0210..3d1b0e339b 100644 --- a/dev-docs/publisher-api-reference/addAdUnits.md +++ b/dev-docs/publisher-api-reference/addAdUnits.md @@ -13,7 +13,7 @@ Takes one ad unit object or an array of ad unit objects and adds them to the Pre -#### Ad Unit Properties +## Ad Unit Properties See the table below for the list of properties on the ad unit. For example ad units, see the [Examples](#addAdUnits-Examples) below. @@ -30,7 +30,7 @@ See the table below for the list of properties on the ad unit. For example ad u -##### Bids +### Bids See the table below for the list of properties in the `bids` array of the ad unit. For example ad units, see the [Examples](#addAdUnits-Examples) below. @@ -47,7 +47,7 @@ Note that `bids` is optional only for [Prebid Server stored impressions](/dev-do -##### Media Types +### Media Types See the table below for the list of properties in the `mediaTypes` object of the ad unit. For example ad units showing the different media types, see the [Examples](#addAdUnits-Examples) below. @@ -58,7 +58,7 @@ See the table below for the list of properties in the `mediaTypes` object of the | `native` | optional | Object | Defines properties of a native ad. For an example native ad unit, see [the native example below](#adUnit-native). | | `video` | optional | Object | Defines properties of a video ad. For examples, see [the video examples below](#adUnit-video). | -#### Video +### Video For the list of properties please visit the [adUnit.video reference]({{site.baseurl}}/dev-docs/adunit-reference.html#adUnit.video). @@ -112,9 +112,9 @@ pbjs.addAdUnits({ }, bids: [ { - bidder: 'appnexus', + bidder: 'bidderA', params: { - placementId: 13232354 + placement_id: 13232354 } } ] @@ -143,9 +143,9 @@ pbjs.addAdUnits({ } }, bids: [{ - bidder: 'appnexus', + bidder: 'bidderA', params: { - placementId: 13232361 + placement_id: 13232361 } }] }); @@ -167,9 +167,9 @@ pbjs.addAdUnits({ }, }, bids: [{ - bidder: 'appnexus', + bidder: 'bidderA', params: { - placementId: 13232361 + placement_id: 13232361 } }] }); @@ -219,9 +219,9 @@ pbjs.addAdUnits({ }, bids: [ { - bidder: 'appnexus', + bidder: 'bidderA', params: { - placementId: 13144370 + placement_id: 13144370 } } ] diff --git a/dev-docs/publisher-api-reference/aliasBidder.md b/dev-docs/publisher-api-reference/aliasBidder.md index 590cfc3584..0618f496c9 100644 --- a/dev-docs/publisher-api-reference/aliasBidder.md +++ b/dev-docs/publisher-api-reference/aliasBidder.md @@ -9,11 +9,11 @@ To define an alias for a bidder adapter, call this method at runtime: ```javascript -pbjs.aliasBidder('appnexus', 'newAlias', optionsObject); +pbjs.aliasBidder('bidderA', 'newAlias', optionsObject); ``` -Defining an alias can help avoid user confusion since it's possible to send parameters to the same adapter but in different contexts (e.g, The publisher uses `"appnexus"` for demand and also uses `"newAlias"` which is an SSP partner that uses the `"appnexus"` adapter to serve their own unique demand). +Defining an alias can help avoid user confusion since it's possible to send parameters to the same adapter but in different contexts (e.g, The publisher uses `"bidderA"` for demand and also uses `"newAlias"` which is an SSP partner that uses the `"bidderA"` adapter to serve their own unique demand). If you define an alias and are using `pbjs.sendAllBids`, you must also set up additional line items in the ad server with keyword targeting that matches the name of the alias. For example: @@ -25,8 +25,8 @@ If you define an alias and are using `pbjs.sendAllBids`, you must also set up ad The options object supports these parameters: {: .table .table-bordered .table-striped } -| Option Parameter | Scope | Type | Description | -|------------|---------|---------|---------------------------------| +| Option Parameter | Scope | Type | Description | +| :--- | :--- | :--- | :--- | | gvlid | optional | integer | IAB Global Vendor List ID for this alias for use with the [TCF control module](/dev-docs/modules/tcfControl.html). | | useBaseGvlid | optional | boolean | Flag determining if the GVL ID of the original adapter should be re-used. (PBJS 9.14+) | diff --git a/dev-docs/publisher-api-reference/bidderSettings.md b/dev-docs/publisher-api-reference/bidderSettings.md index a39d866c98..641d33d637 100644 --- a/dev-docs/publisher-api-reference/bidderSettings.md +++ b/dev-docs/publisher-api-reference/bidderSettings.md @@ -6,7 +6,7 @@ sidebarType: 1 --- -#### 1. Overview +## 1. Overview The bidderSettings object provides a way to define some behaviors for the platform and specific adapters. The basic structure is a 'standard' section with defaults for all adapters, and then one or more adapter-specific sections that override behavior for that bidder: @@ -33,23 +33,24 @@ Some sample scenarios where publishers may wish to alter the default settings: * passing additional information to the ad server * adjusting the bid CPM sent to the ad server -#### 2. Bidder Setting Attributes +## 2. Bidder Setting Attributes {: .table .table-bordered .table-striped } | Attribute | Scope | Version | Default | Description | | --- | --- | --- | --- | --- | | adserverTargeting | standard or adapter-specific | all | see below | Define which key/value pairs are sent to the ad server. | | bidCpmAdjustment | standard or adapter-specific | all | n/a | Custom CPM adjustment function. Could, for example, adjust a bidder's gross-price bid to net price. | +| bidDesirabilityAdjustment | standard or adapter-specific | 11.15.0 | n/a | Custom bid desirability adjustment function. Allows bids to be ranked by a publisher-defined score without changing the adjusted CPM. | | inverseBidAdjustment | standard or adapter-specific | 7.33.0 | n/a | Inverse of `bidCpmAdjustment` | | sendStandardTargeting | adapter-specific | 0.13.0 | true | If adapter-specific targeting is specified, can be used to suppress the standard targeting for that adapter. | | suppressEmptyKeys | standard or adapter-specific | 0.13.0 | false | If custom adserverTargeting functions are specified that may generate empty keys, this can be used to suppress them. | | allowZeroCpmBids | standard or adapter-specific | 6.2.0 | false | Would allow bids with a 0 CPM to be accepted by Prebid.js and could be passed to the ad server. | | storageAllowed | standard or adapter-specific | 6.13.0 | true in 6.x, false after 7.0 | Allow use of cookies and/or local storage. | -| allowAlternateBidderCodes | standard or adapter-specific | 6.23.0 | true in v6.x
false from v7.0| Allow adapters to bid with alternate bidder codes. | +| allowAlternateBidderCodes | standard or adapter-specific | 6.23.0 | true in v6.x
false from v7.0 | Allow adapters to bid with alternate bidder codes. | | allowedAlternateBidderCodes | standard or adapter-specific | 6.23.0 | n/a | Array of bidder codes for which an adapter can bid.
`undefined` or `['*']` will allow adapter to bid with any bidder code. | | adjustAlternateBids | standard or adapter-specific | 7.48.0 | false | Optionally allow alternate bidder codes to use an adapter's bidCpmAdjustment function by default instead of the standard bidCpmAdjustment function if present (note: if a bidCpmAdjustment function exists for the alternate bidder code within bidderSettings, then this will be used instead of falling back to the adapter's bidCpmAdjustment function). | -##### 2.1. adserverTargeting +### 2.1. adserverTargeting As described in the [AdOps documentation]({{site.baseurl}}/adops/before-you-start.html), Prebid has a recommended standard set of ad server targeting that works across bidders. This standard targeting approach is @@ -119,13 +120,13 @@ Note that the existence of `bidderSettings.adserverTargeting.standard` will prev **Keyword targeting for a specific bidder** Let’s say the bidder prefers a separate set of line items. You can overwrite the bidder -settings as the below example for AppNexus shows. +settings as the below example for Microsoft shows. *Note that the line item setup has to match the targeting change* ```javascript pbjs.bidderSettings = { - appnexus: { + msft: { sendStandardTargeting: false, adserverTargeting: [ { @@ -144,7 +145,7 @@ pbjs.bidderSettings = { } ``` -In other words, the above config sends 2 pairs of key/value strings targeting for every AppNexus bid and for every ad unit. The 1st pair would be `apn_pbMg` => the value of `bidResponse.pbMg`. The 2nd pair would be `apn_adId` => the value of `bidResponse.adId`. You can find the bidResponse object documentation [here](/troubleshooting/troubleshooting-guide.html#common-bid-response-parameters). +In other words, the above config sends 2 pairs of key/value strings targeting for every Microsoft bid and for every ad unit. The 1st pair would be `apn_pbMg` => the value of `bidResponse.pbMg`. The 2nd pair would be `apn_adId` => the value of `bidResponse.adId`. See [common bid response parameters](/troubleshooting/troubleshooting-guide.html#common-bid-response-parameters) for bidResponse object documentation. Note that sendStandardTargeting is set to false so that the standard Prebid targeting (hb_bidder, etc.) aren't also sent to the ad server. @@ -152,7 +153,7 @@ Note that sendStandardTargeting is set to false so that the standard Prebid targ Now let's say you would like to define a bidder-specific price bucket function rather than use the ones available by default in prebid.js. Even the [priceGranularity config](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Price-Granularity) option applies to all bidders -- with this approach you can overwrite price buckets. -*Note: this will only impact the price bucket sent to the ad server for targeting. It won't actually impact the cpm value used for ordering the bids.* +*Note: this will only impact the price bucket sent to the ad server for targeting. It won't actually impact the CPM or desirability score used for ordering the bids.* ```javascript pbjs.bidderSettings = { @@ -180,7 +181,7 @@ pbjs.bidderSettings = { } ``` -##### 2.2. bidCpmAdjustment +### 2.2. bidCpmAdjustment Some bidders return gross prices instead of the net prices (what the publisher will actually get paid). For example, a publisher's net price might be 15% below the returned gross price. @@ -189,7 +190,7 @@ header bidding auction. Otherwise, this bidder's gross price will unfairly win o other demand sources who report the real price. Custom adjustment can be provided as a function taking 3 arguments: `bidCpmAdjustment(cpm, bidResponse, bidRequest)`. -Note that either `bidResponse` or `bidRequest` may be missing, although at least one of them is guaranteed to be present. This is because Prebid will sometimes need to run adjustment when no bid has been made yet; see [inverseBidAdjustment](#23-inversebidadjustment) below. +Note that either `bidResponse` or `bidRequest` may be missing, although at least one of them is guaranteed to be present. This is because Prebid will sometimes need to run adjustment when no bid has been made yet; see [inverseBidAdjustment](#24-inversebidadjustment) below. For example: @@ -208,7 +209,34 @@ pbjs.bidderSettings = { In the above example, the AOL bidder will inherit from "standard" adserverTargeting keys, so that you don't have to define the targeting keywords again. -##### 2.3. inverseBidAdjustment +### 2.3. bidDesirabilityAdjustment + +By default, Prebid.js ranks accepted bids using their CPM after `bidCpmAdjustment` has been applied. Publishers who want to rank bids with additional business logic can provide `bidDesirabilityAdjustment`. This function returns a numeric score used to compare bids: higher scores are preferred. + +This is useful when the publisher wants auction ordering to account for signals that should not change the bid's adjusted CPM, price bucket, or ad server reporting value. For example, a publisher could prefer bids from a demand source that has better historical fill, lower discrepancy, or other business-priority signals while keeping the CPM available for targeting and reporting unchanged. + +The function takes 3 arguments: `bidDesirabilityAdjustment(cpm, bidResponse, bidRequest)`. The `cpm` argument is the bid CPM after `bidCpmAdjustment` has been applied. The function should return a number, and the default score is the adjusted CPM. If the function throws an error, Prebid.js logs the error and falls back to the adjusted CPM. + +For example: + +```javascript +pbjs.bidderSettings = { + standard: { ... }, + exampleBidder: { + bidDesirabilityAdjustment: function(adjustedCpm, bid) { + // Prefer this bidder slightly for ordering without changing its CPM. + if (bid.dealId) { + return adjustedCpm + 0.25; + } + return adjustedCpm; + } + } +}; +``` + +In the above example, deal bids from `exampleBidder` receive a higher desirability score than their adjusted CPM. The bid's CPM is not changed by this function. + +### 2.4. inverseBidAdjustment When using [price floors](/dev-docs/modules/floors.html), Prebid attempts to calculate the inverse of `bidCpmAdjustment`, so that the floor values it requests from SSPs take into account how the bid will be adjusted. For example, if the adjustment is `bidCpm * .85` as above, floors are adjusted by `bidFloor * 1 / .85`. @@ -231,7 +259,7 @@ pbjs.bidderSettings = { }; ``` -##### 2.4. sendStandardTargeting +### 2.5. sendStandardTargeting This boolean flag minimizes key/value pairs sent to the ad server when adapter-specific targeting is specified. By default, the platform will send both adapter-specific adServerTargeting as well as the standard adServerTargeting. @@ -241,11 +269,11 @@ suppress the standard targeting for adapters that define their own. See the [example above](#key-targeting-specific-bidder) for example usage. -##### 2.5. suppressEmptyKeys +### 2.6. suppressEmptyKeys If a custom adServerTargeting function can return an empty value, this boolean flag can be used to avoid sending those empty values to the ad server. -##### 2.6. allowZeroCpmBids +### 2.7. allowZeroCpmBids By default, 0 CPM bids are ignored by Prebid.js entirely. However if there's a valid business reason to allow these bids, this setting can be enabled to allow either specific bid adapter(s) or all bid adapters the permission for these bids to be processed by Prebid.js and potentially sent to the respective ad server @@ -253,7 +281,7 @@ either specific bid adapter(s) or all bid adapters the permission for these bids -##### 2.7. storageAllowed +### 2.8. storageAllowed This setting defines if the bid adapter can access browser cookies or local storage. Allowed values are: @@ -271,13 +299,13 @@ Note that: -##### 2.8. allowAlternateBidderCodes +### 2.9. allowAlternateBidderCodes If this flag is set to `true`, bidders that have not been explicitly requested in [`adUnit.bids`](../adunit-reference.html#adunitbids) may take part in the auction.
Default value is `true` in version 6.x
Default value will be `false` from version 7.0 -##### 2.9. allowedAlternateBidderCodes +### 2.10. allowedAlternateBidderCodes This array will work in conjunction with `allowAlternateBidderCodes`. In this array, you can specify the names of the bidder for which an adapter can accept the bid. If the value is not specified for the array or `[‘*’]` is specified, Prebid will accept bids of all the bidders for the given adapter. @@ -294,7 +322,7 @@ pbjs.bidderSettings = { allowedAlternateBidderCodes: ["groupm"], [...] }, - appnexus: { + msft: { allowAlternateBidderCodes: true, allowedAlternateBidderCodes: ["*"], bidCpmAdjustment: function(bidCpm, bid){ return bidCpm * .90; }, @@ -308,9 +336,9 @@ pbjs.bidderSettings = { ``` In the above example, `groupm` bid will have a bid adjustment of 80% since the `bidCpmAdjustment` function says so.
-If `appnexus` bids with another bidder code, say `appnexus2`. This bidder code will adjust the bid cpm to 95% because it will apply the `bidCpmAdjustment` function from `standard` setting, since the `bidCpmAdjustment` is missing for given bidder code I.e `appnexus2` +If `msft` bids with another bidder code, say `msft2`. This bidder code will adjust the bid cpm to 95% because it will apply the `bidCpmAdjustment` function from `standard` setting, since the `bidCpmAdjustment` is missing for given bidder code I.e `msft2` -##### 2.10. adjustAlternateBids +### 2.11. adjustAlternateBids Optionally allow alternate bidder codes originating from a specific bid adapter to fallback to that same adapter's bidCpmAdjustment function. When adjustAlternateBids is set to true, the prioity of which bidCpmAdjustment function to utilize will be as follows based on what is present within the bidderSettings object: @@ -333,7 +361,7 @@ pbjs.bidderSettings = { bidCpmAdjustment: function(bidCpm, bid){ return bidCpm * .85; }, [...] }, - appnexus: { + msft: { allowAlternateBidderCodes: true, allowedAlternateBidderCodes: ["*"], bidCpmAdjustment: function(bidCpm, bid){ return bidCpm * .90; }, diff --git a/dev-docs/publisher-api-reference/getAdserverTargeting.md b/dev-docs/publisher-api-reference/getAdserverTargeting.md index 296c69a785..e100db4b8c 100644 --- a/dev-docs/publisher-api-reference/getAdserverTargeting.md +++ b/dev-docs/publisher-api-reference/getAdserverTargeting.md @@ -11,7 +11,7 @@ Returns all ad server targeting for all ad units. Note that some bidder's respon The targeting keys can be configured in [ad server targeting](/dev-docs/publisher-api-reference/bidderSettings.html). -When [deals are enabled]({{site.baseurl}}/adops/deals.html), the object returned by this method may include a field `hb_deal_BIDDERCODE`, where `BIDDERCODE` is replaced by the name of the bidder, e.g., AppNexus, Rubicon, etc. +When [deals are enabled]({{site.baseurl}}/adops/deals.html), the object returned by this method may include a field `hb_deal_BIDDERCODE`, where `BIDDERCODE` is replaced by the name of the bidder, e.g., Microsoft, Rubicon, etc. **Kind**: static method of `pbjs` @@ -32,10 +32,10 @@ When [deals are enabled]({{site.baseurl}}/adops/deals.html), the object returned "hb_pb": "1.00" }, "/9968336/header-bid-tag-2": { - "hb_bidder": "appnexus", + "hb_bidder": "msft", "hb_adid": "147ac541a", "hb_pb": "2.50", - "hb_deal_appnexus": "ABC_123" + "hb_deal_msft": "ABC_123" } } ``` diff --git a/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCodeStr.md b/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCodeStr.md index bd4fe3627a..0e28261df8 100644 --- a/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCodeStr.md +++ b/dev-docs/publisher-api-reference/getAdserverTargetingForAdUnitCodeStr.md @@ -23,5 +23,5 @@ Returns the query string targeting parameters available at the moment for the sp ```javascript const targetingStrings = pbjs.getAdserverTargetingForAdUnitCodeStr('div-1'); -// ["hb_bidder=appnexus", "hb_adid=233bcbee889d46d", ...] +// ["hb_bidder=msft", "hb_adid=233bcbee889d46d", ...] ``` diff --git a/dev-docs/publisher-api-reference/getBidResponses.md b/dev-docs/publisher-api-reference/getBidResponses.md index 0a01d9f02a..a4fce6c82a 100644 --- a/dev-docs/publisher-api-reference/getBidResponses.md +++ b/dev-docs/publisher-api-reference/getBidResponses.md @@ -10,7 +10,7 @@ This function returns the bid responses at the given moment. **Kind**: static method of `pbjs`. -**Returns**: `object` - map | object that contains the bidResponses. +**Returns**: `object` - map | object that contains for each ad unit the array of bid responses. For backwards compatibility, the arrays expose the array also under the `.bids` property. **Returned Object Params**: @@ -33,11 +33,25 @@ This function returns the bid responses at the given moment. | `creativeId` | String | Bidder-specific creative ID | `"12345678"` | | `mediaType` | String | One of: banner, native, video | `banner` | | `dealId` | String | (Optional) If the bid is [associated with a Deal]({{site.baseurl}}/adops/deals.html), this field contains the deal ID. | "ABC_123" | -| `adserverTargeting` | Object | Contains all the adserver targeting parameters | `{ "hb_bidder": "appnexus", "hb_adid": "7a53a9d3" }` | +| `adserverTargeting` | Object | Contains all the adserver targeting parameters | `{ "hb_bidder": "msft", "hb_adid": "7a53a9d3" }` | | `native` | Object | Contains native key value pairs. | `{ "title": "", "body": "" }` | | `status` | String | Status of the bid. Possible values: targetingSet, rendered | `"targetingSet"` | -| `statusMessage` | String | The bid's status message | "Bid returned empty or error response" or "Bid available" | | `ttl` | Integer | How long (in seconds) this bid is considered valid. See this [FAQ entry]({{site.github.url}}/dev-docs/faq.html#does-prebidjs-cache-bids) for more info. | `300` | +| `meta` | Object | (Optional) Contains additional meta information about the bid. | `{ "advertiserDomains": [ "wherewindsmeetgame.com" ] }` | +| `meta.advertiserDomains` | String[] | (Optional) Array with the advertiser domains | | +| `meta.advertiserId` | String | (Optional) The id of the advertiser | | +| `meta.advertiserName` | String | (Optional) The name of the advertiser | | +| `meta.agencyId` | String | (Optional) The id of the agency | | +| `meta.agencyName` | String | (Optional) The name of the agency | | +| `meta.brandId` | String | (Optional) The id of the brand | | +| `meta.brandName` | String | (Optional) The name of the brand | | +| `meta.dchain` | String | (Optional) | | +| `meta.demandSource` | String | (Optional) | | +| `meta.mediaType` | String | (Optional) | | +| `meta.networkId` | String | (Optional) The id of the network | | +| `meta.networkName` | String | (Optional) The name of the network | | +| `meta.primaryCatId` | String | (Optional) | | +| `meta.secondaryCatIds` | String[] | (Optional) | |

@@ -54,13 +68,11 @@ This function returns the bid responses at the given moment. ```json { - "/9968336/header-bid-tag-0": { - "bids": [ + "/9968336/header-bid-tag-0": [ { - "bidderCode": "appnexus", + "bidderCode": "msft", "width": 300, "height": 250, - "statusMessage": "Bid available", "adId": "7a53a9d3", "creative_id": 29681110, "cpm": 0.5, @@ -69,11 +81,11 @@ This function returns the bid responses at the given moment. "responseTimestamp": 1444844944180, "timeToRespond": 85, "adUnitCode": "/19968336/header-bid-tag-0", - "bidder": "appnexus", + "bidder": "msft", "usesGenericKeys": true, "size": "300x250", "adserverTargeting": { - "hb_bidder": "appnexus", + "hb_bidder": "msft", "hb_adid": "7a53a9d3", "hb_pb": "0.50" } @@ -81,7 +93,6 @@ This function returns the bid responses at the given moment. "bidderCode": "pubmatic", "width": "300", "height": "250", - "statusMessage": "Bid available", "adId": "1139e34e14", "adSlot": "39620189@300x250", "cpm": 1, @@ -105,7 +116,6 @@ This function returns the bid responses at the given moment. "bidderCode": "rubicon", "width": "300", "height": "250", - "statusMessage": "Bid available", "adId": "130d3b0d9b", "cpm": 0.795995, "ad": "", @@ -124,15 +134,12 @@ This function returns the bid responses at the given moment. "hb_pb": "0.50" } } - ] - }, - "/9968336/header-bid-tag1": { - "bids": [ + ], + "/9968336/header-bid-tag1": [ { "bidderCode": "casale", "width": 0, "height": 0, - "statusMessage": "Bid returned empty or error response", "adId": "108c0ba49d", "requestTimestamp": 1444844944130, "responseTimestamp": 1444844944223, @@ -145,7 +152,6 @@ This function returns the bid responses at the given moment. "bidderCode": "openx", "width": "728", "height": "90", - "statusMessage": "Bid available", "adId": "14d7f9208f", "ad_id": "537161420", "cpm": 1.717, @@ -164,7 +170,6 @@ This function returns the bid responses at the given moment. } } ] - } } ``` @@ -188,8 +193,7 @@ This function returns the bid responses at the given moment. ```json { - "div-banner-outstream-native" : { - "bids" : [ + "div-banner-outstream-native" : [ { "pbMg" : "10.00", "pbLg" : "5.00", @@ -199,7 +203,7 @@ This function returns the bid responses at the given moment. "pbCg" : "", "adUnitCode" : "div-banner-outstream-native", "size" : "0x0", - "bidder" : "appnexus", + "bidder" : "msft", "pbAg" : "10.00", "adId" : "473965c9df19d2", "adserverTargeting" : { @@ -209,7 +213,7 @@ This function returns the bid responses at the given moment. "hb_adid" : "473965c9df19d2", "hb_pb" : "10.00", "hb_source" : "client", - "hb_bidder" : "appnexus", + "hb_bidder" : "msft", "hb_native_image" : "https://vcdn.adnxs.com/p/creative-image/9e/26/5f/b2/9e265fb2-50c8-43f0-88ef-a5a48a9d0dcf.jpg", "hb_size" : "0x0", "hb_mediatype" : "native", @@ -240,7 +244,7 @@ This function returns the bid responses at the given moment. }, "timeToRespond" : 143, "mediaType" : "native", - "bidderCode" : "appnexus", + "bidderCode" : "msft", "source" : "client", "auctionId" : "1338a6fb-e514-48fc-8db6-872ddf3babdb", "responseTimestamp" : 1516315716205, @@ -250,12 +254,10 @@ This function returns the bid responses at the given moment. "ttl" : 300, "status" : "targetingSet", "height" : 0, - "statusMessage" : "Bid available", "cpm" : 10, "currency" : "USD" } ] - } } ``` diff --git a/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md b/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md index 7e2c984bdd..9018148b4a 100644 --- a/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md +++ b/dev-docs/publisher-api-reference/getBidResponsesForAdUnitCode.md @@ -9,9 +9,10 @@ Returns bidResponses for the specified adUnitCode. See full documentation at [pb **Kind**: static method of `pbjs` -**Returns**: `Object` - bidResponse object +**Returns**: `Array` - an array of bid responses. For backwards compatibility, the array exposes the array also under the `.bids` property. {: .table .table-bordered .table-striped } + | Param | Scope | Type | Description | | --- | --- | --- | --- | | adUnitCode | Required | `String` | adUnitCode | diff --git a/dev-docs/publisher-api-reference/getEvents.md b/dev-docs/publisher-api-reference/getEvents.md index a374315d74..2af6e4c295 100644 --- a/dev-docs/publisher-api-reference/getEvents.md +++ b/dev-docs/publisher-api-reference/getEvents.md @@ -27,6 +27,7 @@ The available events are: | --- | --- | --- | | auctionInit | The auction has started | Object containing auction details | | auctionEnd | The auction has ended | Object containing auction details | +| auctionTimeout | The auction has timed out | Object containing auction details | | beforeRequestBids | Bids are about to be requested from adapters (added in 3.x) | Array of adunits in the auction | | beforeBidderHttp | bidder network request is about be triggered | Array of Bid request objects | | bidRequested | A bid was requested from a specific bidder | Bid request object | diff --git a/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md b/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md index 03058d70c3..8a03ad9570 100644 --- a/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md +++ b/dev-docs/publisher-api-reference/getHighestUnusedBidResponseForAdUnitCode.md @@ -6,5 +6,6 @@ sidebarType: 1 --- Use this method to retrieve the highest unused bid for the specified adUnit. Unused means not it's not rendered. +Returns `null` when no suitable bid exists. This differs from [`getHighestCpmBids()`](/dev-docs/publisher-api-reference/getHighestCpmBids.html) in that getHighestCpmBids only considers bids for auctions that have completed (and are also unused), this function considers bids for ongoing auctions as well. diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 798ca37aec..b0e1a82790 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -229,13 +229,13 @@ Note that targeting config must be set before either `pbjs.setTargetingForGPTAsy "hb_deal_rubicon": "11111111", "hb_format_rubicon": "banner", "hb_source_rubicon": "client", - "hb_adid_appnexus": "191f4aca0c0be8", - "hb_pb_appnexus": "10.00", - "hb_size_appnexus": "300x250", - "hb_format_appnexus": "banner", - "hb_source_appnexus": "client", + "hb_adid_msft": "191f4aca0c0be8", + "hb_pb_msft": "10.00", + "hb_size_msft": "300x250", + "hb_format_msft": "banner", + "hb_source_msft": "client", // the winning bid is copied to attributes without a suffix - "hb_bidder": "appnexus", + "hb_bidder": "msft", "hb_adid": "191f4aca0c0be8", "hb_pb": "10.00", "hb_size": "300x250", @@ -346,6 +346,43 @@ When set, bids are only kept in memory for the duration of their actual TTL life Put another way, this setting doesn't define each bid's TTL, but rather controls how long it's kept around in memory for analytics purposes. +### Minimum cache TTL for targeted bids + + + +When using `minBidCacheTTL` to limit how long bids stay in memory, bids that have already been sent to the ad server (targeting set) can expire before the ad is rendered. This often happens with GPT lazy load or other delayed render: the ad is requested and targeting is set, but the slot only renders when the user scrolls. If the bid is dropped from cache before render, you may see "cannot find ad" (or similar) errors. + +Use **`minTargetedBidCacheTTL`** to give targeted bids a longer (or unlimited) cache time than other bids: + +```javascript +pbjs.setConfig({ + minBidCacheTTL: 30, // drop non-targeted bids after 30s + minTargetedBidCacheTTL: Infinity // keep targeted bids until page unload (lazy-load / long-delay render) +}); +``` + +* When set, it overrides `minBidCacheTTL` only for bids that have had **targeting set** (e.g. sent to GPT via `setTargetingForGPTAsync` / `setTargetingForGPT`). +* When unset, all bids use `minBidCacheTTL` (current behavior). +* Use a number (seconds) for a longer but finite TTL, or `Infinity` to keep targeted bids for the life of the page. + +#### Publisher choices when using bid cache TTL +{: .no_toc} + +If you use `minBidCacheTTL` (with or without `minTargetedBidCacheTTL`), you are making a tradeoff between memory and ad availability. Be explicit about what should happen when: + +1. A bid expires after targeting but before render + * Rely on `minTargetedBidCacheTTL` so targeted bids stay in cache until render, or + * Accept that the slot may show no ad / blank, or + * Run a new auction when the slot is about to render (e.g. in a lazy-load callback). + +2. Bids are dropped for memory saving + * Decide whether you prefer lower memory (shorter TTL) or fewer "missing ad" cases (longer TTL or `minTargetedBidCacheTTL`). + +#### SSP / revenue note +{: .no_toc} + +Bids have a TTL from the bidder/SSP. If an ad is rendered **after** that TTL, the SSP may treat the bid as expired and may not attribute revenue. Keeping bids in Prebid's cache longer (e.g. with `minTargetedBidCacheTTL`) does not change the SSP's own TTL. Use this setting when the delay is on your side (e.g. lazy load), not to extend the SSP's idea of when the bid is valid. + ### Event history TTL @@ -1153,10 +1190,11 @@ pbjs.setConfig({ ### Client-side Caching of VAST XML -When serving video ads, VAST XML creatives must be cached so the +When serving video ads, VAST XML creatives are commonly cached so the video player can retrieve them when it's ready. Players don't obtain the VAST XML from the JavaScript DOM in Prebid.js, but rather expect to be given a URL where it can -be retrieved. There are three different flows possible with Prebid.js around VAST XML caching: +be retrieved. If your player can render VAST XML directly, you can set `cache.allowVastXmlOnly` +to bypass the cache requirement. There are different flows possible with Prebid.js around VAST XML handling: * Server-side caching: Some video bidders (e.g. Rubicon Project) always cache the VAST XML on their servers as part of the bid. They provide a 'videoCacheKey', which is used in conjunction with the VAST URL in the ad server to retrieve the correct VAST XML when needed. In this case, Prebid.js has nothing else to do. As of Prebid.js 4.28, a publisher may specify the `ignoreBidderCacheKey` flag to re-cache these bids somewhere else using a VAST wrapper. @@ -1173,6 +1211,7 @@ be retrieved. There are three different flows possible with Prebid.js around VAS | cache.timeout | no | number | Timeout (in milliseconds) for network requests to the cache | | cache.vasttrack | no | boolean | Passes additional data to the url, used for additional event tracking data. Defaults to `false`. | | cache.ignoreBidderCacheKey | no | boolean | If the bidder supplied their own cache key, setting this value to true adds a VAST wrapper around that URL, stores it in the cache defined by the `url` parameter, and replaces the original video cache key with the new one. This can dramatically simplify ad server setup because it means all VAST creatives reside behind a single URL. The tradeoff: this approach requires the video player to unwrap one extra level of VAST. Defaults to `false`. | +| cache.allowVastXmlOnly | no | boolean | When `true`, allows rendering VAST XML without requiring use of a cache. Useful for players that can consume VAST XML directly. Defaults to `false`. | | cache.batchSize | no | number | Enables video cache requests to be batched by a specified amount (defaults to 1) instead of making a single request per each video. | | cache.batchTimeout | no | number | Used in conjunction with `batchSize`, `batchTimeout` specifies how long to wait in milliseconds before sending a batch video cache request based on the value for `batchSize` (if present). A batch request will be made whether the `batchSize` amount was reached or the `batchTimeout` timer runs out. `batchTimeout` defaults to 0. | @@ -1200,6 +1239,16 @@ pbjs.setConfig({ }); ``` +If your player can render raw VAST XML and you do not want to require caching, you can set: + +```javascript +pbjs.setConfig({ + cache: { + allowVastXmlOnly: true + } +}); +``` + As of Prebid.js 2.36, you can track client-side cached VAST XML. This functionality is useful for publishers who want to allow their analytics provider to measure video impressions. The prerequisite to using this feature is the availability of a Prebid Server that supports: * the /vtrack endpoint @@ -1347,7 +1396,7 @@ The `auctionOptions` object controls aspects related to auctions. | `secondaryBidders` | Optional | Array of Strings | Specifies bidders that the Prebid auction will no longer wait for before determining the auction has completed. This may be helpful if you find there are a number of low performing and/or high timeout bidders in your page's rotation. | | `suppressStaleRender` | Optional | Boolean | When true, prevents `banner` bids from being rendered more than once. It should only be enabled after auto-refreshing is implemented correctly. Default is false. | | `suppressExpiredRender` | Optional | Boolean | When true, prevent bids from being rendered if TTL is reached. Default is false. | -| `legacyRender` | Optional | Boolean | When true, uses "legacy" rendering logic (see [note](#note-legacyRender)) | +| `legacyRender` | Optional | Boolean | When true, uses "legacy" rendering logic (see [note](#legacyRender)) | | `rejectUnknownMediaTypes` | Optional | Boolean | Since Pbjs 11, When true, reject bids when the adapter response omits `mediaType` for an ad unit that has explicit `mediaTypes` configured. Default is false. | | `rejectInvalidMediaTypes` | Optional | Boolean | Since Pbjs 11, When true, reject bids when response `mediaType` does not match one of the ad unit's configured `mediaTypes`. Default is true. | @@ -1408,14 +1457,21 @@ PBJS performs the following actions when expired rendering is detected. Expired winning bids will continue to be rendered unless `suppressExpiredRender` is set to true. Events including `STALE_RENDER` and `BID_WON` are unaffected by this option. - + -#### More on `legacyRender` -{: .no_toc} +#### More on Legacy Rendering -Since Prebid 10.12, `pbjs.renderAd` wraps creatives in an additional iframe. This can cause problems for some creatives +Since Prebid 10.12, [`renderAd`](/dev-docs/publisher-api-reference/renderAd.html) wraps creatives in an additional iframe. This can cause problems for some creatives that try to reach the top window and do not expect to find the extra iframe. You may set `legacyRender: true` to revert -to pre-10.12 rendering logic. +to pre-10.12 rendering logic: + +```javascript +pbjs.setConfig({ + auctionOptions: { + legacyRender: true + } +}); +``` @@ -1507,8 +1563,8 @@ pbjs.setConfig({ iframeURL: 'https://rubicon.com:8080/topics/fpd/topic.html', // dummy URL expiry: 7 // Configurable expiry days },{ - bidder: 'appnexus', - iframeURL: 'https://appnexus.com:8080/topics/fpd/topic.html', // dummy URL + bidder: 'msft', + iframeURL: 'https://microsoft.com:8080/topics/fpd/topic.html', // dummy URL expiry: 7 // Configurable expiry days }] } @@ -1563,7 +1619,7 @@ Prebid modules sometimes need to know the [IAB Global Vendor List](https://iabeu ```javascript pbjs.setConfig({ gvlMapping: { - appnexus: 4, + msft: 4, someModule: 123 } }); @@ -1571,6 +1627,24 @@ pbjs.setConfig({ Prebid Server uses this mapping when it sends `ext.prebid.aliasgvlids` for bidder aliases, and the [TCF Control Module](/dev-docs/modules/tcfControl.html) references it when enforcing consent. + + +### Map Global Vendor ID to legal basis declarations + +Since version 11.15, Prebid.js includes TCF legal basis declarations, used for [tcfControl full enforcement](/dev-docs/modules/tcfControl.html#full-enforcement). The optional `gvlLegalBasisMapping` configuration option can be used to override them. + +```javascript +pbjs.setConfig({ + gvlLegalBasisMapping: { + 123: { + purposes: [2], + legIntPurposes: [7], + flexiblePurposes: [2] + } + } +}) +``` + ### Set Max Bid diff --git a/dev-docs/publisher-api-reference/setTargetingForAst.md b/dev-docs/publisher-api-reference/setTargetingForAst.md index 5a58ec6ff9..1e07a89d6f 100644 --- a/dev-docs/publisher-api-reference/setTargetingForAst.md +++ b/dev-docs/publisher-api-reference/setTargetingForAst.md @@ -6,7 +6,7 @@ sidebarType: 1 --- -Set query string targeting for AST ([Seller Tag](https://docs.xandr.com/bundle/seller-tag/page/seller-tag.html)) ad unit(s). Note that this function has to be called after all ad units on page are defined. For working example code, see [Using Prebid.js with AppNexus Publisher Ad Server]({{site.github.url}}/dev-docs/examples/use-prebid-with-appnexus-ad-server.html). If the function is invoked without arguments it will set targeting for all adUnits defined. +Set query string targeting for AST ([Seller Tag](https://docs.xandr.com/bundle/seller-tag/page/seller-tag.html)) ad unit(s). Note that this function has to be called after all ad units on page are defined. For working example code, see [Using Prebid.js with Microsoft Publisher Ad Server]({{site.github.url}}/dev-docs/examples/use-prebid-with-microsoft-ad-server.html). If the function is invoked without arguments it will set targeting for all adUnits defined. **Kind**: static method of pbjs API diff --git a/dev-docs/publisher-api-reference/yield.md b/dev-docs/publisher-api-reference/yield.md new file mode 100644 index 0000000000..169a50ef6c --- /dev/null +++ b/dev-docs/publisher-api-reference/yield.md @@ -0,0 +1,16 @@ +--- +layout: api_prebidjs +title: pbjs.yield +description: yield setting +sidebarType: 1 +--- + +Since version 10, [pbjs.processQueue](/dev-docs/publisher-api-reference/processQueue.html) yields the main browser thread after executing each command in the queue, to improve UX (and some related metrics such as [interaction to next paint](https://web.dev/articles/inp)). + +You can disable yielding by setting `pbjs.yield` to `false`: + +```javascript +pbjs.yield = false; + +pbjs.que.push(/* ... */) +``` diff --git a/dev-docs/renderer.md b/dev-docs/renderer.md index 30cd9155bf..f9cbceafd5 100644 --- a/dev-docs/renderer.md +++ b/dev-docs/renderer.md @@ -17,22 +17,23 @@ In simple terms, a renderer offers publishers: - A way to introduce new ad formats without disrupting user experience - Control over maintaining design consistency between ads and site content -## Renderer Object +## Types of renderers -{: .table .table-bordered .table-striped } -| Name | Scope | Type | Description | -|--------------+----------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `url` | Required | String | URL to the renderer script that will be loaded. This script should create a renderer object in the global scope. | -| `render` | Required | Function | Function that tells Prebid.js how to invoke the renderer script to render a bid. The function receives the bid object as a parameter. | -| `backupOnly` | Optional | Boolean | if set to true, buyer or adapter renderer will be preferred | +From Prebid 11.15 onward, publishers and adapters can specify their custom renderers in two ways: top window renderers (the old-fashioned way) and the new Safe Renderer approach. The latter has the significant advantage of executing renderer code inside the ad frame, where the ad markup and other important data are accessible within the frame context, whereas the old approach executed renderers in the top window. We strongly recommend using the new Safe Renderer approach whenever possible. + +If both Safe Renderer and top window renderers are specified, the Safe Renderer takes precedence. You can also disable top window renderers through the top level configuration flag: + +```javascript +pbjs.setConfig({ allowTopWindowRenderers: false }) +``` ## Renderer Implementation Levels -Renderers can be specified at multiple levels: +Renderers can be specified at multiple levels by specifying either `safeRenderer` or `renderer` field on one of the following levels: -1. MediaType Level (adUnit.mediaTypes.video\|banner\|native.renderer): If a renderer is associated with a specific mediaType (video, banner, or native), it will be used to display any demand associated with that mediaType. This is the preferred method for all ad types. -2. AdUnit Level (adUnit.renderer): Applied to all bids for this ad unit that don't override it. This is a legacy approach; using the mediaType-level renderer is preferred. -3. Bidder Level (adUnit.bids[].renderer): Applied only to this bidder, overriding adUnit renderer if both exist. +1. MediaType Level `adUnit.mediaTypes.video|banner|native|audio`: If a renderer is associated with a specific mediaType (video, banner, audio or native), it will be used to display any demand associated with that mediaType. This is the preferred method for all ad types. +2. AdUnit Level `adUnit`: Applied to all bids for this ad unit that don't override it. This is a legacy approach; using the mediaType-level renderer is preferred. +3. Bidder Level `adUnit.bids[]`: Applied only to this bidder, overriding adUnit renderer if both exist. 4. Default: If no renderer is specified at any level, Prebid will use the default renderer for the media type, if one exists. For banner and native ads, Prebid.js has built-in default rendering capabilities. ### Priority Order @@ -44,9 +45,150 @@ When multiple renderers are defined, the following priority is used: 3. Bidder Level renderer 4. Default renderer -## Special Cases +## Safe renderer + +The Safe Renderer works similarly to the default Prebid renderer in that it is injected into the ad frame. The key difference is that it does not render the ad by itself. Instead, it loads an external renderer script using the URL specified in the Safe Renderer configuration. Once the script is loaded, the Safe Renderer executes the `window.pbRenderInFrame({ config, ...renderingData })` function, which must be defined by the external script + +### Config object + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | +| -------------- | ---------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `url` | Required | String | URL to the external renderer script that will be loaded and executed within Safe renderer | +| `config` | Optional | Object | Object that will be passed to external renderer script as a `config` field. For bid adapters use | +| `getConfig` | Optional | Function | Function that will evaluate `config` object accessible in external renderer script. For publisher's use. Accepts `bidResponse` as a parameter | + +```javascript +const adUnits = [ + { + mediaTypes: { + video: { + context: 'outstream', + playerSize: [300, 250], + mimes: ['video/mp4'], + safeRenderer: { + url: 'https://trafto.s3.eu-central-1.amazonaws.com/rendererV2.js', + getConfig: (bidResponse) => { + return { + configField: 'passed-from-adunit-config' + } + } + }, + } + }, + code: adUnitCode, + } + ]; +``` + +### External script example implementation + +Existing top level custom renderers can be easily migrated to work with the new Safe Renderer approach. The external script simply needs to define the `window.pbRenderInFrame` method and execute the rendering logic inside it. The function accepts a payload object containing `config` (either passed by bid adapters or evaluated by the publisher-provided `getConfig(bidResponse)` function), and [...renderingData](/dev-docs/renderer.html#renderingData). + +```javascript +/* global YVAP */ +/** + * Reference implementation for `bid.safeRenderer.url`. + * Prebid injects this script into the creative iframe and then calls `window.pbRenderInFrame(payload)`. + */ +window.pbRenderInFrame = function ({ config, ...renderingData }) { + + function yvapPlayerRender(b) { + var safeAdId = + b.adId != null && String(b.adId).length + ? String(b.adId).replace(/[^a-zA-Z0-9_-]/g, '') + : ''; + var targetNodeId = + 'pb-yvap-' + + (safeAdId || 'slot-' + Date.now() + '-' + Math.random().toString(36).slice(2, 9)); + + var container = document.createElement('div'); + container.id = targetNodeId; + if (b.width != null) { + container.style.width = + typeof b.width === 'number' ? b.width + 'px' : String(b.width); + } + if (b.height != null) { + container.style.height = + typeof b.height === 'number' ? b.height + 'px' : String(b.height); + } + document.body.appendChild(container); + + + function initPlayer() { + // eslint-disable-next-line no-new + new YVAP({ + id: targetNodeId, + player: { + type: 'Outstream', + controls: true, + height: b.height, + width: b.width + }, + ads: { + adTagXml: b.vastXml + } + }); + } + + if (window.YVAP) { + initPlayer(); + return; + } + + var script = document.createElement('script'); + script.src = 'https://s.yimg.com/kp/yvap/1.9.0/yvap.js'; + script.async = true; + script.onload = function () { + initPlayer(); + }; + script.onerror = function () { + // eslint-disable-next-line no-console + console.error('[Yahoo ADS bid adapter]: Outstream renderer script failed to load.'); + }; + var firstScript = document.getElementsByTagName('script')[0]; + if (firstScript && firstScript.parentNode) { + firstScript.parentNode.insertBefore(script, firstScript); + } else { + (document.head || document.documentElement).appendChild(script); + } + } + + yvapPlayerRender(renderingData); +}; +``` + + + +### Rendering data + +{: .table .table-bordered .table-striped } +| Property | Description | +| ---------- | ------------- | +| `ad` | Ad markup | +| `adUrl` | Ad markup url | +| `width` | Width of the creative | +| `height` | Height of the creative | +| `instl` | Interstitial flag (`1` for interstitial, `0` for non-interstitial) | +| `vastXml` | The VAST XML content (if available instead of vastUrl) | +| `vastUrl` | URL to the VAST XML for video ads | +| `mediaType` | Type of media ('video', 'banner', etc.) | +| `safeRenderer` | Prepared Safe Renderer configuration (including `url` and related fields) used to load and run the external renderer script | + +## Top window renderer + +### Config object + +{: .table .table-bordered .table-striped } +| Name | Scope | Type | Description | +|--------------+----------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `url` | Required | String | URL to the renderer script that will be loaded. This script should create a renderer object in the global scope. | +| `render` | Required | Function | Function that tells Prebid.js how to invoke the renderer script to render a bid. The function receives the bid object as a parameter. | +| `backupOnly` | Optional | Boolean | if set to true, buyer or adapter renderer will be preferred | + +### Special Cases -### Banner with Custom Renderer +#### Banner with Custom Renderer Although renderers are commonly associated with video ads, they can also be used with banner ads to create custom rendering experiences: @@ -79,9 +221,9 @@ pbjs.addAdUnits({ }, bids: [ { - bidder: "appnexus", + bidder: "msft", params: { - placementId: 13144370, + placement_id: 13144370, }, }, ], @@ -96,7 +238,7 @@ A banner renderer might be used to: 4. Apply custom styling or containers to maintain site design aesthetics 5. Implement fallback scenarios for different devices or browsers -## Renderer Implementation Example +### Renderer Implementation Example ```javascript // Example of a secure custom banner renderer implementation @@ -182,7 +324,7 @@ window.BannerRenderer = function (config) { }; ``` -## Common Renderer Properties +### Common Top window renderer Properties Here are commonly used properties from the bid object that can be accessed in the renderer: diff --git a/dev-docs/requirements/tcf2/PrebidSupportforEnforcingTCF2.html b/dev-docs/requirements/tcf2/PrebidSupportforEnforcingTCF2.html index bd7edfa7a2..73158843a1 100644 --- a/dev-docs/requirements/tcf2/PrebidSupportforEnforcingTCF2.html +++ b/dev-docs/requirements/tcf2/PrebidSupportforEnforcingTCF2.html @@ -1 +1 @@ -

Prebid Support for Enforcing TCF 2.0

Overview

Definitions

Assumptions

Summary of Prebid TCF 2.0 Enforcement

Basic-vs-Full Enforcement

Basic Enforcement

Full Enforcement (Prebid Server Only)

Prebid.js Functional Requirements

Prebid SDK Functional Requirements

Prebid Server Functional Requirements

Overview

The IAB's Transparency and Consent Framework version 2.0 for enhanced support of GDPR is scheduled to take effect Apr 1 2020. It's a major update from TCF 1.1 which Prebid currently supports, and is not compatible with the previous release.

The key changes are:

More 'purposes' are defined.
More flexibility for the legal bases used by vendors.
Different in-page javascript API

References

Definitions

Assumptions

Important Legal Note: Prebid.org cannot provide legal advice about GDPR or any other governmental regulation. Our aim is to provide a toolkit of functionality that will let publishers configure header bidding as defined by their legal counsel. We will consider feature suggestions, and review any code offered by the community.

Enforcement of Purpose 2 (basic ad selection) looks to be one of the bigger areas of concern because the TCF policy could be interpreted to be a form of ad blocking. You will need to work with your legal counsel to determine how you intend to handle this scenario. Prebid.js and Prebid Server offer publishers the ability to enforce or not-enforce purposes individually. As an example of the kind of flexibility we aim to offer (*), here are some options you could discuss with your lawyers:

Treat Purpose 2 as an ad blocker.
Ignore enforcement of selected Purposes at the Prebid level entirely, assuming that downstream vendors will handle the TCF strings appropriately.
Ignore enforcement Purpose 2, assuming that users who object to ‘Basic Ads’ will also object to ‘Personalized Ads’, causing any User IDs to be removed from ad requests.
Ignore the Purpose-Consent portion of Purpose 2, but allow the user to block specific vendors.

(*) - Note on phasing: Please be aware that Prebid.js and Prebid Server will likely not deliver on the full TCF functionality by April 1st. Our initial goal for both products is to support Purpose 1 (Device Access) enforcement by that date. The ability to enforce the other purposes will be developed as soon as we can.

(**) Did we mention that you cannot rely on this document to learn how to configure your header bidding for GDPR? Seriously, talk to your lawyers.

General

Prebid.org is neither a data controller nor data processor, but we supply software to both types of entities. Therefore, our software should provide a flexible set of controls necessary for both types of entities to run their businesses.
Even if Prebid is configured to enforce activities by parsing consent data, publishers and downstream vendors are still responsible for ensuring their legal bases using the consent data they're provided.
Prebid will ignore the TCF "stack" feature, assuming that the CMP will set the underlying Purposes appropriately.
Data from the CMP will never be modified before passing to downstream entities.
If TCF processing is turned on, and the user is determined to be in GDPR scope, and hasn’t provided a consent string, the system should assume a consent string that has no consent offered.

Prebid.js

Prebid.js will only support parsing the TCF 2.0 consent string.
TCF 2.0 features are available in Prebid.js only in a consent module, not as part of core. This allows publishers to build two versions of their wrappers: one for users in the EEA, one for users outside of the EEA.
It's assumed that publishers run in two modes:

A CMP is loaded on every page so TCF functions and data are fully available.
Consent data is stored in first party storage and passed to Prebid directly. TCF functions are not available from the CMP.

Prebid.js will not load the Global Vendors List (GVL) as this would significantly impact the success of header bidding implementations. However, Prebid.js will require a mapping of GVL vendor IDs to Prebid.js bidder codes.

Further, we assume that not all Prebid adapters will be in the GVL, so we'll need to support reference by GVL ID or bidder code.
Further, we assume that bidder aliases within one adapter may have different GVL IDs.

As a result of not having access to GVL entries, Prebid.js will only support ‘Basic Enforcement’.
TCF2 will be supported in Prebid.js 3.x, with 'no enforcement' being the default option. Prebid.js 4.0 will enforce Purpose 1 by default when the module is included.
PurposeOneTreatment is ignored for Prebid.js. Publishers who don’t want to enforce Purpose 1 (or any other purpose) need to set Prebid’s configuration appropriately.

Prebid Server

Prebid Server will need concurrent support of TCF 1.1 and TCF 2.0.
Prebid Server will need to support “Full Enforcement” checks.
AMP TCF 2.0 will be passed on the same parameter as TCF 1.1.

Prebid SDK

Prebid SDK should parse the consent string in order to read the IDFA. Other than that, SDK just passes consent values to Prebid Server..

Summary of Prebid TCF 2.0 Enforcement

TCF Field	In-scope Activities	System	Enforcement	Publisher/ Host Company Controls
Purpose 1 - Store and/or access information on a device	usersync pixels, user ID modules, and device storage	Prebid.js and Prebid Server and Prebid SDK	May result in preventing one or more uesrsync activities for one or more vendors.	Do not enforce purpose 1 Do not enforce purpose 1 for vendor V Enforce purpose 1 at the vendor level only.
Purpose 2 - Select basic ads	call bid adapters	Prebid.js and Prebid Server	May result in skipping one or more bid adapters. All configured modules will be called as usual unless all bidders are eliminated.	Do not enforce purpose 2 Do not enforce purpose 2 for vendor V Enforce purpose 2 at the vendor level only.
Purpose 4 - Select Personalized Ads	call bid adapters with userIds	Prebid.js and Prebid Server	May result in removing the userIds before calling one or more bid adapters.	Do not enforce purpose 4 Do not enforce purpose 4 for vendor V Enforce purpose 4 at the vendor level only.
Purpose 7 - Measure ad performance	initiate analytics	Prebid.js and Prebid Server	May result in skipping one or more analytics adapters.	Do not enforce purpose 7 Do not enforce purpose 7 for vendor V Enforce purpose 7 at the vendor level only.
Special Feature 1 - Use precise geolocation data	passing lat/long to server-side bid adapters	Prebid Server	May result in rounding lat/long values and IP address before sending to server-side adapters.	Do not enforce Special Feature 1
Special Purpose 2 - Technically deliver ads or content	n/a	Special Purposes do not require consent. If a publisher’s legal team wants to consider SP2, Prebid software should not be called.
PurposeOneConsent	n/a	Prebid does not provide specific support for enforcing this flag. Instead, publishers may use the provided controls for Purpose 1 and other Prebid configuration to control whether the user’s device is accessed.

Basic-vs-Full Enforcement

Prebid offers publishers several controls for whether consent/legal basis confirmation is even performed. The following flowchart shows how the controls

Basic Enforcement

The goal of 'basic enforcement' is to confirm that there's enough evidence of consent to pass data on to vendors who have access to the GVL and can fully parse and enforce.

Before allowing a Purpose for a given Vendor, one of these scenarios must be true: :

User’s purpose consent and user’s vendor consent
The Prebid-specific ‘enforceVendor’ flag is set and user’s vendor consent
purpose LI established and vendor LI established
The Prebid-specific ‘enforceVendor’ flag is set and vendor LI established

In terms of the TCF 2.0 fields, Purpose P is ok for vendor V if either of these is true:

PurposesConsent[P,V]==1 AND VendorConsentBitfield[V]==1
pbEnforceVendor[P]==true AND VendorConsentBitfield[V]==1
PurposesLITransparency[P]==1 AND VendorLegitimateInterestBitfield[V]==1
pbEnforceVendor[P,V]==true AND VendorLegitimateInterestBitfield[V]==1

Before allowing Special Feature 1, SpecialFeatureOptIns[1] must be true.

Full Enforcement (Prebid Server Only)

The big difference between 'basic' and 'full' enforcement is that Prebid Server has the GVL available to examine vendor legal bases.

Before allowing an activity that falls under a specific Purpose for a given Vendor, one of these 6 basic scenarios needs to be true:

Vendor claims consent as their basis, publisher doesn't restrict the purpose, user consents to the purpose (if the enforcePurpose flag is on), and user consents to the vendor (if the enforceVendor flag is on).
Vendor claims (inflexible) legitimate interest as their basis, publisher doesn't restrict the purpose, user was provided notice of the legitimate interest basis for this purpose (if the enforcePurpose flag is on), and user was provided notice for the LI basis for this vendor (if the enforceVendor flag is on)
Vendor claims flexible legal basis with legitimate interest as the default, publisher restriction doesn't require consent, and ((user was provided notice of the legitimate interest basis for this purpose+vendor) OR (user consents to purpose+vendor)) [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with legitimate interest as the default, publisher does require consent, user consents to the purpose, and user consents to the vendor. [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with consent as the default, publisher restriction doesn't require legitimate interest, ((user consents to the purpose+vendor) OR (user was provided notice for the legitimate interest basis for this purpose+vendor)) [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with consent as the default, publisher restriction does require legitimate interest, and user was provided notice for the legitimate interest basis for this purpose+vendor. [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]

Note that there are many more scenarios where the activity would not be allowed.

The technical definition in terms of the TCF 2.0 fields follows. Purpose P is ok for vendor V if any of these is true:

GVL[V].purposes contains P and GVL[V].flexiblePurposes doesn't contain P and publisherRestrictions[P]!=0 and (!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes doesn't contain P and publisherRestrictions[P]!=0 and (!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==2 and (((!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)) OR ((!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)))
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==1 and (!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)
GVL[V].purposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==1 and (((!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)) OR ((!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)))
GVL[V].purposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==2 and (!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)

Before allowing Special Feature 1, SpecialFeatureOptIns[1] must be true.

Prebid.js Functional Requirements

1) An optional module must be available for reading the IAB TCF 2.0 API data. Publishers will include this module in their Prebid.js package when they need to support EEA users.

2) Prebid.js must support scenarios where the TCF string parsing functions are not available. If the codebase for parsing the TCF string is significant, it should be made an optional module separate from the enforcement functions. A key goal of Prebid.js is to include only the code that publishers need for their particular use case. The technical design should consider whether it makes sense to bundle all of these components together, or break them into 2 or 3 separate modules:

Reading the TCF string
Enforcing the TCF string
Parsing the TCF string (?)

3) Prebid.js must support the following publisher controls:

Don't even read the TCF string (accomplished by not configuring the module)
Enforce/Do not enforce purpose P
Enforce/Do not enforce purpose P for vendor V

Here's a set of proposed configurations within the existing consentManagement config object:

Param	Type	Description	Details
gdpr.allowAuctionWithoutConsent	boolean	Available in 3.x only, defines behavior for backwards compatibility.	For 3.x: If true, consider all Purposes as not enforceable. If false, consider only Purpose 2 enforceable.
gdpr.consentData	object	Consent data provided statically.	Used when cmpApi is "static".
gdpr.defaultGdprScope	boolean
gdpr.rules	object	Lets the publisher override the defaults set by the enforceMode
gdpr.rules[].purpose	string	Possible values are "storage", "basicAds", "personalizedAds", and "measurement" corresponding to Purposes 1,2,4, and 7 respectively.	For some reason, people tend to prefer using the string names rather than the numbers.
gdpr.rules[].enforcePurpose	boolean	Whether to enforce this purpose or not. Overrides the setting from enforceMode.	The default in PBJS 3.x will be to enforce no purposes, and in 4.0 to enforce Purpose 1 and no others.
gdpr.rules[].enforceVendor	boolean	Whether to enforce vendor consent/legal basis for this purpose or not..	The default in PBJS 3.x will be to enforce no purposes, and in 4.0 to enforce Purpose 1 and no others.
gdpr.rules[].vendorExceptions	array of strings	Which biddercodes or module names should be treated as the opposite of the enforceVendor flag.	If enforceVendor=false, then vendorExceptions are those that will be treated as true. If enforce=true, then vendorExceptions are those that will be treated as false.

Example configurations:

pbjs.setConfig({

consentManagement: {

gdpr: {

cmpApi: 'iab',

defaultGdprScope: true/false (0/1?)

timeout: 3000,

// allowAuctionWithoutConsent: false, // deprecated

rules: [{

// don’t enforce Purpose 1 except for bidderA.

// this means that TCF approval is only considered

// for this one bidder.

purpose: "storage",

enforcePurpose: false,

enforceVendor: false,

vendorExceptions: ["bidderA"]

},{

// Allow the user to object to vendors for Purpose 2

// but don’t allow them to turn off header bidding

// altogether.

// The exception is bidderB, which the user will

// not be allowed to reject

purpose: "basicAds",

enforcePurpose: false,

enforceVendor: true,

vendorExceptions: ["bidderB"]

},{

// allow the user to have their userId removed from

// header bidding except for bidders A and B

purpose: "personalizedAds",

enforcePurpose: true,

enforceVendor: true

vendorExceptions: ["bidderA","bidderB"]

},{

// analytics adapters are ok

purpose: "measurement",

enforcePurpose: false,

enforcePurpose: false

}]

}

});

You may notice that the examples above provide more flexibility than TCF requires. This allows publishers to establish custom legal bases in consultation with their legal counsel.

4) If the 'gdprApplies' flag is defined and is false, then Prebid.js may assume that GDPR is not in scope and therefore doesn't need to be enforced. All Purposes will be set to enforce=false.

4) There should be a way for bidAdapters to supply a GVL ID for each alias they support.

5) The aliasBidder() function should be extended to support specification of a GVL ID. e.g.

pbjs.aliasBidder('appnexus', 'newAlias', 999);

6) If a bidder code isn't associated with a GVL ID, enforcement should assume that the vendor is not allowed unless the publisher has specifically named their bidder code.

7) Analytics adapters must be associated with a GVL ID and/or a "name" to allow the system to determine which analytics adapter(s) are permitted to operate in the current context.

8) User ID modules and Real Time Data modules should be associated with a GVL ID and/or a "name" to allow the system to determine which modules are permitted to operate in the current context.

9) The system must be able to verify vendor consent in two ways:

User consents to GVL ID 52, and Prebid.js knows that 52 corresponds to the Rubicon bid adapter (and the Rubicon analytics adapter)

10) The internal interface to bid adapters should remain the same: bidrequest.gdprConsent

11) The OpenRTB interface to Prebid Server should remain the same:

regs.ext.gdpr
user.ext.consent

12) The system must support all the activity enforcement noted in the 'Summary of Prebid TCF 2.0 Enforcement' section.

If Purpose 1 is being enforced:

Before invoking usersync pixels for each enforceable vendor, verify consent as described in 'Basic Enforcement'.
Before reading or storing cookies or HTML 5 localstorage for each enforceable vendor, verify consent as described in 'Basic Enforcement'. This will require enhancing the getCookie and setCookie utility functions to determine or accept the biddercode or module name.
Before invoking each enforceable userID sub-module, verify consent as described in 'Basic Enforcement'.

If Purpose 2 is being enforced, verify consent for each vendor as described in 'Basic Enforcement' before calling a bid adapter. If consent is not granted, log a console warning and skip it.
If Purpose 4 is being enforced, verify consent for each vendor that passed the Purpose 2 test. If consent is not granted, log a console warning, remove the bidrequest.userId attribute and call the adapter.
If Purpose 7 is being enforced, verify consent for each analytics module. If consent is not granted, log a console warning and skip it.

13) If consentManagement.gdpr is configured but no consent string is available, the system must assume that the user does not consent to either purpose or vendor. Activities may still take place if the publisher has configured the relevant Purposes as 'not enforced'.

13) Bid adapters must do one of the following for all device access activities (reading or setting cookies or local storage):

Use the PBJS core utility functions, which will handle Purpose 1 enforcement.
Post a public disclosure in the code and on prebid.org explaining the legal basis for not adhering to GDPR.

14) Prebid core must make the following information available to analytics adapters:

Enforcement status of Purposes 1,2,4 and 7.
An array of bidders and modules skipped due to TCF enforcement.

15) It should be possible for a pub to define a mapping between a module code and a GVL ID

pbjs.setConfig({

gvlMapping: {

“id5”: 9999

“bidderX”: 8888

}

Prebid SDK Functional Requirements

1) Prebid SDK must accept the following optional parameters to support TCF 2.0. It’s assumed the app will pass these values directly or indirectly from a mobile CMP.

GDPR in-scope
TCF Consent string
‘deviceAccessConsent’ flag defining whether the SDK is allowed to read the IDFA or equivalent. It’s assumed that the app will parse the consent string to confirm the user has consented to Purpose 1.

2) When a request is defined to be GDPR in-scope, the SDK must confirm that the ‘deviceAccessConsent’ flag is true. Here’s the truth table for when the SDK is allowed to access the device ID:

	deviceAccessConsent=true	deviceAccessConsent=false	deviceAccessConsent undefined
GDPR scope=false	Yes, read IDFA	No, don’t read IDFA	Yes, read IDFA
GDPR scope=true	Yes, read IDFA	No, don’t read IDFA	No, don’t read IDFA
GDPR scope undefined	Yes, read IDFA	No, don’t read IDFA	Yes, read IDFA

3) The SDK must pass the consent data to Prebid Server on the same OpenRTB attributes as defined in TCF 1.1:

GDPR in-scope flag is regs.ext.gdpr
Consent string is user.ext.consent

Prebid Server Functional Requirements

1) Optional configuration must be available for host companies to turn on and off enforcing GDPR with IAB TCF 2.0 API data. There should be global and publisher account level configuration. The default should be to enforce.

2) If enforcement is turned on for this request, Prebid Server must be able to determine whether it's in-scope for GDPR processing. If any of the following conditions are true, the request is in-scope:

the incoming request defines regs.ext.gdpr:true.
regs.ext.gdpr is undefined, geo-lookup is turned on, and the user's IP address is in a configurable set of countries.
regs.ext.gdpr is undefined and the host company's default scope is to enforce.

3) Prebid Server must support the following host company controls:

Enforce/Do not enforce purpose P (globally and per-account)
Enforce/Do not enforce purpose P for vendor V (globally and per-account)
Enforce/Do not enforce special purpose 1
Enforce/Do not enforce special purpose 1 for vendor V
ACCOUNT

4) Prebid Server must give host company config to say what to do with the purposeOneTreatment - both as a default and for each account:

ignore the flag entirely
if purposeOneTreatment=1 and IsServiceSpecific=1 then Purpose 1 is overridden to no-access-allowed
if purposeOneTreatment=1 and IsServiceSpecific=1 then Purpose 1 is overridden to access-allowed

The implementation of this “PurposeOneTreatmentInterpretation flag modifies the flowchart above: it may short-circuit the logic, jumping straight to Yes or No without a normal enforcement check.

5) It must be possible for a Host Company to define its GVL ID to use for confirming user user consent for setting cookies.

Example configuration/DB entries:

gdpr.host-vendor-id: 52
gdpr.enabled: true/false // default true

gdpr.purpose.P.enforcePurpose: no/basic/full // default full

gdpr.purpose.P.enforceVendors: true/false // default true

gdpr.purpose.P.vendorExceptions: list of biddercodes
gdpr.specialfeature.S.enforce: true/false // default true

gdpr.specialfeature.S.vendorExceptions: list of biddercodes

gdpr.purposeOneTreatmentInterpretation: ignore/no-access-allowed/access-allowed

account.A.gdpr.enabled: true/false // default true

account.A.gdpr.purpose.P.enforcePurpose

account.A.gdpr.purpose.P.enforceVendors

account.A.gdpr.purpose.P.vendorExceptions
account.A.gdpr.specialfeature.S.enforce

account.A.gdpr.specialfeature.S.vendorExceptions

account.A.gdpr.purposeOneTreatmentInterpretation

geolocation.VENDOR.server: url // location of geo lookup service

6) There should be a way for bidAdapters to supply a GVL ID for each alias they support.

7) The external definition of aliases should be extended to support specification of a GVL ID. e.g.

"ext": {

"prebid": {

"aliases": { // existing feature

"districtm": "appnexus"

"aliasgvlids": { // new feature

"districtm": 144

}

8) Prebid Server's enforcement should be "Full" mode unless it doesn't have access to the proper GVL version.

9) Prebid Server should be able to read the TCF2.0 GVL that's specified in the consent string. If it does not have immediate access to that version of the GVL, it may downgrade enforcement to "Basic". The assumption is that subsequent requests for that version of the GVL will succeed. The system should log any usage of Basic Enforcement.

10) If a bidder code isn't associated with a GVL ID, enforcement should assume that the vendor is not allowed unless the publisher has specifically named the bidder code as a configured exception.

11) Analytics adapters must be associated with a GVL ID and/or a "name" to allow the system to determine which analytics adapter(s) are permitted to operate in the current context.

12) User ID modules and Real Time Data modules should be associated with a GVL ID and/or a "name" to allow the system to determine which modules are permitted to operate in the current context.

13) The system must be able to verify vendor consent in two ways:

User consents to GVL ID 52, and Prebid Server knows that 52 corresponds to the Rubicon bid adapter (and the Rubicon analytics adapter)
The Host Company consents to the name "bidderB", which would allow that biddercode to bid even if the user's Purpose 1 doesn't have specific consent.

14) The internal interface to bid adapters should remain the same.

15) The OpenRTB interface to Prebid Server should remain the same:

regs.ext.gdpr
user.ext.consent

16) The system must support all the activity enforcement noted in the 'Summary of Prebid TCF 2.0 Enforcement' section.

If Purpose 1 is being enforced:

Before invoking /cookie_sync pixels for each enforceable vendor, verify consent as appropriate for the enforcement method.
Before setting a cookie on /setuid, verify consent for the Host Company's GVL ID as appropriate for the enforcement method
Before passing ID values to each enforceable vendor, verify consent as appropriate for the enforcement method.

If Purpose 2 is being enforced, verify consent for each vendor as appropriate for the enforcement method before calling a bid adapter. If consent is not granted, log a metric and skip it.
If Purpose 4 is being enforced, verify consent for each vendor that passed the Purpose 2 test. If consent is not granted, log a metric, remove the bidrequest.userId attribute and call the adapter.
If Purpose 7 is being enforced, verify consent for each analytics module. If consent is not granted, log a metric and skip it.
If Special Feature 1 is being enforced, verify user opt-in. If the user has opted out, round off the IP address and lat/long details and log a metric.

IP masking: for IPv4, zero out the last byte. For IPv6, zero out the last 2 bytes.
Check the OpenRtb packet for $.device.geo.lat, $.device.geo.lon, $.user.geo.lat, $.user.geo.lon. Round off the values to the last two decimal points if they exist.

17) If GDPR is being enforced but no consent string is available, the system must assume that the user does not consent to either purpose or vendor. Activities may still take place if the Host Company has configured the relevant Purposes as 'not enforced'.

18) Prebid Server core must make the following information available to analytics adapters:

Enforcement status of Purposes 1,2,4,7, and Special Purpose 1
An array of bidders and modules skipped due to TCF enforcement.

Prebid Support for Enforcing TCF 2.0

Overview

Definitions

Assumptions

Summary of Prebid TCF 2.0 Enforcement

Basic-vs-Full Enforcement

Basic Enforcement

Full Enforcement (Prebid Server Only)

Prebid.js Functional Requirements

Prebid SDK Functional Requirements

Prebid Server Functional Requirements

Overview

The key changes are:

More 'purposes' are defined.
More flexibility for the legal bases used by vendors.
Different in-page javascript API

References

Definitions

Assumptions

Treat Purpose 2 as an ad blocker.
Ignore enforcement of selected Purposes at the Prebid level entirely, assuming that downstream vendors will handle the TCF strings appropriately.
Ignore enforcement Purpose 2, assuming that users who object to ‘Basic Ads’ will also object to ‘Personalized Ads’, causing any User IDs to be removed from ad requests.
Ignore the Purpose-Consent portion of Purpose 2, but allow the user to block specific vendors.

(**) Did we mention that you cannot rely on this document to learn how to configure your header bidding for GDPR? Seriously, talk to your lawyers.

General

Prebid.org is neither a data controller nor data processor, but we supply software to both types of entities. Therefore, our software should provide a flexible set of controls necessary for both types of entities to run their businesses.
Even if Prebid is configured to enforce activities by parsing consent data, publishers and downstream vendors are still responsible for ensuring their legal bases using the consent data they're provided.
Prebid will ignore the TCF "stack" feature, assuming that the CMP will set the underlying Purposes appropriately.
Data from the CMP will never be modified before passing to downstream entities.
If TCF processing is turned on, and the user is determined to be in GDPR scope, and hasn’t provided a consent string, the system should assume a consent string that has no consent offered.

Prebid.js

Prebid.js will only support parsing the TCF 2.0 consent string.
TCF 2.0 features are available in Prebid.js only in a consent module, not as part of core. This allows publishers to build two versions of their wrappers: one for users in the EEA, one for users outside of the EEA.
It's assumed that publishers run in two modes:

A CMP is loaded on every page so TCF functions and data are fully available.
Consent data is stored in first party storage and passed to Prebid directly. TCF functions are not available from the CMP.

Prebid.js will not load the Global Vendors List (GVL) as this would significantly impact the success of header bidding implementations. However, Prebid.js will require a mapping of GVL vendor IDs to Prebid.js bidder codes.

Further, we assume that not all Prebid adapters will be in the GVL, so we'll need to support reference by GVL ID or bidder code.
Further, we assume that bidder aliases within one adapter may have different GVL IDs.

As a result of not having access to GVL entries, Prebid.js will only support ‘Basic Enforcement’.
TCF2 will be supported in Prebid.js 3.x, with 'no enforcement' being the default option. Prebid.js 4.0 will enforce Purpose 1 by default when the module is included.
PurposeOneTreatment is ignored for Prebid.js. Publishers who don’t want to enforce Purpose 1 (or any other purpose) need to set Prebid’s configuration appropriately.

Prebid Server

Prebid Server will need concurrent support of TCF 1.1 and TCF 2.0.
Prebid Server will need to support “Full Enforcement” checks.
AMP TCF 2.0 will be passed on the same parameter as TCF 1.1.

Prebid SDK

Prebid SDK should parse the consent string in order to read the IDFA. Other than that, SDK just passes consent values to Prebid Server..

Summary of Prebid TCF 2.0 Enforcement

TCF Field	In-scope Activities	System	Enforcement	Publisher/ Host Company Controls
Purpose 1 - Store and/or access information on a device	usersync pixels, user ID modules, and device storage	Prebid.js and Prebid Server and Prebid SDK	May result in preventing one or more uesrsync activities for one or more vendors.	Do not enforce purpose 1 Do not enforce purpose 1 for vendor V Enforce purpose 1 at the vendor level only.
Purpose 2 - Select basic ads	call bid adapters	Prebid.js and Prebid Server	May result in skipping one or more bid adapters. All configured modules will be called as usual unless all bidders are eliminated.	Do not enforce purpose 2 Do not enforce purpose 2 for vendor V Enforce purpose 2 at the vendor level only.
Purpose 4 - Select Personalized Ads	call bid adapters with userIds	Prebid.js and Prebid Server	May result in removing the userIds before calling one or more bid adapters.	Do not enforce purpose 4 Do not enforce purpose 4 for vendor V Enforce purpose 4 at the vendor level only.
Purpose 7 - Measure ad performance	initiate analytics	Prebid.js and Prebid Server	May result in skipping one or more analytics adapters.	Do not enforce purpose 7 Do not enforce purpose 7 for vendor V Enforce purpose 7 at the vendor level only.
Special Feature 1 - Use precise geolocation data	passing lat/long to server-side bid adapters	Prebid Server	May result in rounding lat/long values and IP address before sending to server-side adapters.	Do not enforce Special Feature 1
Special Purpose 2 - Technically deliver ads or content	n/a	Special Purposes do not require consent. If a publisher’s legal team wants to consider SP2, Prebid software should not be called.
PurposeOneConsent	n/a	Prebid does not provide specific support for enforcing this flag. Instead, publishers may use the provided controls for Purpose 1 and other Prebid configuration to control whether the user’s device is accessed.

Basic-vs-Full Enforcement

Prebid offers publishers several controls for whether consent/legal basis confirmation is even performed. The following flowchart shows how the controls

Basic Enforcement

The goal of 'basic enforcement' is to confirm that there's enough evidence of consent to pass data on to vendors who have access to the GVL and can fully parse and enforce.

Before allowing a Purpose for a given Vendor, one of these scenarios must be true: :

User’s purpose consent and user’s vendor consent
The Prebid-specific ‘enforceVendor’ flag is set and user’s vendor consent
purpose LI established and vendor LI established
The Prebid-specific ‘enforceVendor’ flag is set and vendor LI established

In terms of the TCF 2.0 fields, Purpose P is ok for vendor V if either of these is true:

PurposesConsent[P,V]==1 AND VendorConsentBitfield[V]==1
pbEnforceVendor[P]==true AND VendorConsentBitfield[V]==1
PurposesLITransparency[P]==1 AND VendorLegitimateInterestBitfield[V]==1
pbEnforceVendor[P,V]==true AND VendorLegitimateInterestBitfield[V]==1

Before allowing Special Feature 1, SpecialFeatureOptIns[1] must be true.

Full Enforcement (Prebid Server Only)

The big difference between 'basic' and 'full' enforcement is that Prebid Server has the GVL available to examine vendor legal bases.

Before allowing an activity that falls under a specific Purpose for a given Vendor, one of these 6 basic scenarios needs to be true:

Vendor claims consent as their basis, publisher doesn't restrict the purpose, user consents to the purpose (if the enforcePurpose flag is on), and user consents to the vendor (if the enforceVendor flag is on).
Vendor claims (inflexible) legitimate interest as their basis, publisher doesn't restrict the purpose, user was provided notice of the legitimate interest basis for this purpose (if the enforcePurpose flag is on), and user was provided notice for the LI basis for this vendor (if the enforceVendor flag is on)
Vendor claims flexible legal basis with legitimate interest as the default, publisher restriction doesn't require consent, and ((user was provided notice of the legitimate interest basis for this purpose+vendor) OR (user consents to purpose+vendor)) [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with legitimate interest as the default, publisher does require consent, user consents to the purpose, and user consents to the vendor. [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with consent as the default, publisher restriction doesn't require legitimate interest, ((user consents to the purpose+vendor) OR (user was provided notice for the legitimate interest basis for this purpose+vendor)) [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]
Vendor claims flexible legal basis with consent as the default, publisher restriction does require legitimate interest, and user was provided notice for the legitimate interest basis for this purpose+vendor. [Purpose checked only if the enforcePurpose flag is on, and vendor checked only if the enforceVendor flag is on]

Note that there are many more scenarios where the activity would not be allowed.

The technical definition in terms of the TCF 2.0 fields follows. Purpose P is ok for vendor V if any of these is true:

GVL[V].purposes contains P and GVL[V].flexiblePurposes doesn't contain P and publisherRestrictions[P]!=0 and (!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes doesn't contain P and publisherRestrictions[P]!=0 and (!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==2 and (((!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)) OR ((!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)))
GVL[V].legIntPurposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==1 and (!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)
GVL[V].purposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==1 and (((!enforcePurpose[P] or PurposesConsent[P]==1) AND (!enforceVendor[P,V] or VendorConsentBitfield[V]==1)) OR ((!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)))
GVL[V].purposes contains P and GVL[V].flexiblePurposes contains P and publisherRestrictions[P]==2 and (!enforcePurpose[P] or PurposesLITransparency[P]==1) AND (!enforceVendor[P,V] or VendorLegitimateInterestBitfield[V]==1)

Before allowing Special Feature 1, SpecialFeatureOptIns[1] must be true.

Prebid.js Functional Requirements

1) An optional module must be available for reading the IAB TCF 2.0 API data. Publishers will include this module in their Prebid.js package when they need to support EEA users.

Reading the TCF string
Enforcing the TCF string
Parsing the TCF string (?)

3) Prebid.js must support the following publisher controls:

Don't even read the TCF string (accomplished by not configuring the module)
Enforce/Do not enforce purpose P
Enforce/Do not enforce purpose P for vendor V

Here's a set of proposed configurations within the existing consentManagement config object:

Param	Type	Description	Details
gdpr.allowAuctionWithoutConsent	boolean	Available in 3.x only, defines behavior for backwards compatibility.	For 3.x: If true, consider all Purposes as not enforceable. If false, consider only Purpose 2 enforceable.
gdpr.consentData	object	Consent data provided statically.	Used when cmpApi is "static".
gdpr.defaultGdprScope	boolean
gdpr.rules	object	Lets the publisher override the defaults set by the enforceMode
gdpr.rules[].purpose	string	Possible values are "storage", "basicAds", "personalizedAds", and "measurement" corresponding to Purposes 1,2,4, and 7 respectively.	For some reason, people tend to prefer using the string names rather than the numbers.
gdpr.rules[].enforcePurpose	boolean	Whether to enforce this purpose or not. Overrides the setting from enforceMode.	The default in PBJS 3.x will be to enforce no purposes, and in 4.0 to enforce Purpose 1 and no others.
gdpr.rules[].enforceVendor	boolean	Whether to enforce vendor consent/legal basis for this purpose or not..	The default in PBJS 3.x will be to enforce no purposes, and in 4.0 to enforce Purpose 1 and no others.
gdpr.rules[].vendorExceptions	array of strings	Which biddercodes or module names should be treated as the opposite of the enforceVendor flag.	If enforceVendor=false, then vendorExceptions are those that will be treated as true. If enforce=true, then vendorExceptions are those that will be treated as false.

Example configurations:

pbjs.setConfig({

consentManagement: {

gdpr: {

cmpApi: 'iab',

defaultGdprScope: true/false (0/1?)

timeout: 3000,

// allowAuctionWithoutConsent: false, // deprecated

rules: [{

// don’t enforce Purpose 1 except for bidderA.

// this means that TCF approval is only considered

// for this one bidder.

purpose: "storage",

enforcePurpose: false,

enforceVendor: false,

vendorExceptions: ["bidderA"]

},{

// Allow the user to object to vendors for Purpose 2

// but don’t allow them to turn off header bidding

// altogether.

// The exception is bidderB, which the user will

// not be allowed to reject

purpose: "basicAds",

enforcePurpose: false,

enforceVendor: true,

vendorExceptions: ["bidderB"]

},{

// allow the user to have their userId removed from

// header bidding except for bidders A and B

purpose: "personalizedAds",

enforcePurpose: true,

enforceVendor: true

vendorExceptions: ["bidderA","bidderB"]

},{

// analytics adapters are ok

purpose: "measurement",

enforcePurpose: false,

enforcePurpose: false

}]

}

});

You may notice that the examples above provide more flexibility than TCF requires. This allows publishers to establish custom legal bases in consultation with their legal counsel.

4) If the 'gdprApplies' flag is defined and is false, then Prebid.js may assume that GDPR is not in scope and therefore doesn't need to be enforced. All Purposes will be set to enforce=false.

4) There should be a way for bidAdapters to supply a GVL ID for each alias they support.

5) The aliasBidder() function should be extended to support specification of a GVL ID. e.g.

pbjs.aliasBidder('msft', 'newAlias', 999);

6) If a bidder code isn't associated with a GVL ID, enforcement should assume that the vendor is not allowed unless the publisher has specifically named their bidder code.

7) Analytics adapters must be associated with a GVL ID and/or a "name" to allow the system to determine which analytics adapter(s) are permitted to operate in the current context.

8) User ID modules and Real Time Data modules should be associated with a GVL ID and/or a "name" to allow the system to determine which modules are permitted to operate in the current context.

9) The system must be able to verify vendor consent in two ways:

User consents to GVL ID 52, and Prebid.js knows that 52 corresponds to the Rubicon bid adapter (and the Rubicon analytics adapter)

10) The internal interface to bid adapters should remain the same: bidrequest.gdprConsent

11) The OpenRTB interface to Prebid Server should remain the same:

regs.ext.gdpr
user.ext.consent

12) The system must support all the activity enforcement noted in the 'Summary of Prebid TCF 2.0 Enforcement' section.

If Purpose 1 is being enforced:

Before invoking usersync pixels for each enforceable vendor, verify consent as described in 'Basic Enforcement'.
Before reading or storing cookies or HTML 5 localstorage for each enforceable vendor, verify consent as described in 'Basic Enforcement'. This will require enhancing the getCookie and setCookie utility functions to determine or accept the biddercode or module name.
Before invoking each enforceable userID sub-module, verify consent as described in 'Basic Enforcement'.

If Purpose 2 is being enforced, verify consent for each vendor as described in 'Basic Enforcement' before calling a bid adapter. If consent is not granted, log a console warning and skip it.
If Purpose 4 is being enforced, verify consent for each vendor that passed the Purpose 2 test. If consent is not granted, log a console warning, remove the bidrequest.userId attribute and call the adapter.
If Purpose 7 is being enforced, verify consent for each analytics module. If consent is not granted, log a console warning and skip it.

13) Bid adapters must do one of the following for all device access activities (reading or setting cookies or local storage):

Use the PBJS core utility functions, which will handle Purpose 1 enforcement.
Post a public disclosure in the code and on prebid.org explaining the legal basis for not adhering to GDPR.

14) Prebid core must make the following information available to analytics adapters:

Enforcement status of Purposes 1,2,4 and 7.
An array of bidders and modules skipped due to TCF enforcement.

15) It should be possible for a pub to define a mapping between a module code and a GVL ID

pbjs.setConfig({

gvlMapping: {

“id5”: 9999

“bidderX”: 8888

}

Prebid SDK Functional Requirements

1) Prebid SDK must accept the following optional parameters to support TCF 2.0. It’s assumed the app will pass these values directly or indirectly from a mobile CMP.

GDPR in-scope
TCF Consent string
‘deviceAccessConsent’ flag defining whether the SDK is allowed to read the IDFA or equivalent. It’s assumed that the app will parse the consent string to confirm the user has consented to Purpose 1.

2) When a request is defined to be GDPR in-scope, the SDK must confirm that the ‘deviceAccessConsent’ flag is true. Here’s the truth table for when the SDK is allowed to access the device ID:

	deviceAccessConsent=true	deviceAccessConsent=false	deviceAccessConsent undefined
GDPR scope=false	Yes, read IDFA	No, don’t read IDFA	Yes, read IDFA
GDPR scope=true	Yes, read IDFA	No, don’t read IDFA	No, don’t read IDFA
GDPR scope undefined	Yes, read IDFA	No, don’t read IDFA	Yes, read IDFA

3) The SDK must pass the consent data to Prebid Server on the same OpenRTB attributes as defined in TCF 1.1:

GDPR in-scope flag is regs.ext.gdpr
Consent string is user.ext.consent

Prebid Server Functional Requirements

the incoming request defines regs.ext.gdpr:true.
regs.ext.gdpr is undefined, geo-lookup is turned on, and the user's IP address is in a configurable set of countries.
regs.ext.gdpr is undefined and the host company's default scope is to enforce.

3) Prebid Server must support the following host company controls:

Enforce/Do not enforce purpose P (globally and per-account)
Enforce/Do not enforce purpose P for vendor V (globally and per-account)
Enforce/Do not enforce special purpose 1
Enforce/Do not enforce special purpose 1 for vendor V
ACCOUNT

4) Prebid Server must give host company config to say what to do with the purposeOneTreatment - both as a default and for each account:

ignore the flag entirely
if purposeOneTreatment=1 and IsServiceSpecific=1 then Purpose 1 is overridden to no-access-allowed
if purposeOneTreatment=1 and IsServiceSpecific=1 then Purpose 1 is overridden to access-allowed

The implementation of this “PurposeOneTreatmentInterpretation flag modifies the flowchart above: it may short-circuit the logic, jumping straight to Yes or No without a normal enforcement check.

5) It must be possible for a Host Company to define its GVL ID to use for confirming user user consent for setting cookies.

Example configuration/DB entries:

gdpr.host-vendor-id: 52
gdpr.enabled: true/false // default true

gdpr.purpose.P.enforcePurpose: no/basic/full // default full

gdpr.purpose.P.enforceVendors: true/false // default true

gdpr.purpose.P.vendorExceptions: list of biddercodes
gdpr.specialfeature.S.enforce: true/false // default true

gdpr.specialfeature.S.vendorExceptions: list of biddercodes

gdpr.purposeOneTreatmentInterpretation: ignore/no-access-allowed/access-allowed

account.A.gdpr.enabled: true/false // default true

account.A.gdpr.purpose.P.enforcePurpose

account.A.gdpr.purpose.P.enforceVendors

account.A.gdpr.purpose.P.vendorExceptions
account.A.gdpr.specialfeature.S.enforce

account.A.gdpr.specialfeature.S.vendorExceptions

account.A.gdpr.purposeOneTreatmentInterpretation

geolocation.VENDOR.server: url // location of geo lookup service

6) There should be a way for bidAdapters to supply a GVL ID for each alias they support.

7) The external definition of aliases should be extended to support specification of a GVL ID. e.g.

"ext": {

"prebid": {

"aliases": { // existing feature

"districtm": "msft"

"aliasgvlids": { // new feature

"districtm": 144

}

8) Prebid Server's enforcement should be "Full" mode unless it doesn't have access to the proper GVL version.

10) If a bidder code isn't associated with a GVL ID, enforcement should assume that the vendor is not allowed unless the publisher has specifically named the bidder code as a configured exception.

11) Analytics adapters must be associated with a GVL ID and/or a "name" to allow the system to determine which analytics adapter(s) are permitted to operate in the current context.

12) User ID modules and Real Time Data modules should be associated with a GVL ID and/or a "name" to allow the system to determine which modules are permitted to operate in the current context.

13) The system must be able to verify vendor consent in two ways:

User consents to GVL ID 52, and Prebid Server knows that 52 corresponds to the Rubicon bid adapter (and the Rubicon analytics adapter)
The Host Company consents to the name "bidderB", which would allow that biddercode to bid even if the user's Purpose 1 doesn't have specific consent.

14) The internal interface to bid adapters should remain the same.

15) The OpenRTB interface to Prebid Server should remain the same:

regs.ext.gdpr
user.ext.consent

16) The system must support all the activity enforcement noted in the 'Summary of Prebid TCF 2.0 Enforcement' section.

If Purpose 1 is being enforced:

Before invoking /cookie_sync pixels for each enforceable vendor, verify consent as appropriate for the enforcement method.
Before setting a cookie on /setuid, verify consent for the Host Company's GVL ID as appropriate for the enforcement method
Before passing ID values to each enforceable vendor, verify consent as appropriate for the enforcement method.

If Purpose 2 is being enforced, verify consent for each vendor as appropriate for the enforcement method before calling a bid adapter. If consent is not granted, log a metric and skip it.
If Purpose 4 is being enforced, verify consent for each vendor that passed the Purpose 2 test. If consent is not granted, log a metric, remove the bidrequest.userId attribute and call the adapter.
If Purpose 7 is being enforced, verify consent for each analytics module. If consent is not granted, log a metric and skip it.
If Special Feature 1 is being enforced, verify user opt-in. If the user has opted out, round off the IP address and lat/long details and log a metric.

IP masking: for IPv4, zero out the last byte. For IPv6, zero out the last 2 bytes.
Check the OpenRtb packet for $.device.geo.lat, $.device.geo.lon, $.user.geo.lat, $.user.geo.lon. Round off the values to the last two decimal points if they exist.

18) Prebid Server core must make the following information available to analytics adapters:

Enforcement status of Purposes 1,2,4,7, and Special Purpose 1
An array of bidders and modules skipped due to TCF enforcement.

diff --git a/dev-docs/show-long-form-video-with-gam.md b/dev-docs/show-long-form-video-with-gam.md index 573d25680d..b12f4af3cd 100644 --- a/dev-docs/show-long-form-video-with-gam.md +++ b/dev-docs/show-long-form-video-with-gam.md @@ -22,10 +22,10 @@ The code example below was built with Prebid.js and the following: * The [`dfpAdServerVideo` module](/dev-docs/modules/dfp_video.html), which will provide the video ad support. * The [`categoryTranslation` module](/dev-docs/modules/categoryTranslation.html), to enable competitive separation. -For example, to build with the AppNexus bidder adapter and GAM use the following command: +For example, to build with the Microsoft bidder adapter and GAM use the following command: ```bash -gulp build --modules=appnexusBidAdapter,dfpAdServerVideo +gulp build --modules=msftBidAdapter,dfpAdServerVideo ``` For more information about how to build with modules, see the [Prebid module documentation](/dev-docs/modules/). @@ -63,9 +63,9 @@ var videoAdUnit = [{ }, bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 14542875 + placement_id: 14542875 } } ] diff --git a/dev-docs/show-native-ads.md b/dev-docs/show-native-ads.md index 7e71f1b57b..fbd9b37c0c 100644 --- a/dev-docs/show-native-ads.md +++ b/dev-docs/show-native-ads.md @@ -20,7 +20,7 @@ using the [improved Prebid.js native ad](/prebid/native-implementation.html) sup In this tutorial, we'll set up Prebid.js to show native ads. -We'll use the [AppNexus adapter]({{site.github.url}}/dev-docs/bidders.html#appnexus) since that adapter supports native ads, but the concepts and setup will be largely the same for any bidder adapter that supports the `"native"` media type. +We'll use the [Micosoft adapter]({{site.github.url}}/dev-docs/bidders.html#msft) since that adapter supports native ads, but the concepts and setup will be largely the same for any bidder adapter that supports the `"native"` media type. Similarly, we'll use Google Ad Manager as the ad server, but the concept and implementation should be pretty similar to other ad servers. @@ -69,7 +69,7 @@ This section describes the implementation using code samples, but ignores some o ### 1. Set up your ad slot -In this example we'll store the ad slot info in a variable for reference throughout the page. We use a 1x1 static ad slot size since AppNexus (our demand partner in this example) uses that size for native creatives. +In this example we'll store the ad slot info in a variable for reference throughout the page. We use a 1x1 static ad slot size since Microsoft (our demand partner in this example) uses that size for native creatives. ```javascript const slot = { @@ -145,9 +145,9 @@ pbjs.addAdUnits({ } }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232354 + placement_id: 13232354 } }, ] }) @@ -187,9 +187,9 @@ const adUnits = [{ } } bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232354 + placement_id: 13232354 } }] }]; diff --git a/dev-docs/show-outstream-video-ads.md b/dev-docs/show-outstream-video-ads.md index 5446854e22..c812889a27 100644 --- a/dev-docs/show-outstream-video-ads.md +++ b/dev-docs/show-outstream-video-ads.md @@ -48,9 +48,9 @@ var videoAdUnits = [{ } }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232385, + placement_id: 13232385, } }] }]; diff --git a/dev-docs/show-prebid-ads-on-amp-pages.md b/dev-docs/show-prebid-ads-on-amp-pages.md index 78fdedc434..3c2073fab5 100644 --- a/dev-docs/show-prebid-ads-on-amp-pages.md +++ b/dev-docs/show-prebid-ads-on-amp-pages.md @@ -131,7 +131,7 @@ The `amp-ad` elements in the page body need to be set up as shown below, especia - `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: +e.g. for the Microsoft cluster of Prebid Servers: ```html + +### 5. Using the local cache + +Since version 10.23 it is possible to work around GAM's requirement for a cached VAST URL by using a combination of [client side caching](/dev-docs/publisher-api-reference/setConfig.html#client-side-caching-of-vast-xml) and [`getVastXml`](/dev-docs/publisher-api-reference/adServers.gam.getVastXml.html). This uses the same setup described above, except that the cache is set to local: + +```javascript +pbjs.setConfig({ + cache: { + useLocal: true + } +}); +``` + +And passing a VAST document directly to the player (instead of an ad tag URL). Using VideoJS: + +```javascript + function invokeVideoPlayer() { + videojs("vid1").ready(function() { + this.vastClient({ + adTagXml: function(callback) { + pbjs.adServers.gam.getVastXml({ + adUnit: videoAdUnit, + params: { + iu: '/19968336/prebid_cache_video_adunit' + } + }).then(function(vastXml) { + callback(null, vastXml); + }) + }, + playAdAlways: true, + verbosity: 0, + vpaidFlashLoaderPath: "https://github.com/MailOnline/videojs-vast-vpaid/blob/RELEASE/bin/VPAIDFlash.swf?raw=true", + autoplay: true + }); + this.muted(true); + this.play(); + }); + } +``` + +See [below](#examples) for more examples. + +The way this works is: + +* when Prebid receives a video bid, it stores its VAST document in the browser as a [blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob), and updates its `.videoCacheKey` with the ID of that blob; +* `getVastXml` first makes a request to GAM (using the URL returned by `getVideoUrl`); +* If a Prebid bid wins the GAM auction (and the line items are set up as described in [GAM Step by Step - Video Creatives](/adops/setting-up-prebid-video-in-dfp.md)), the response will contain a VAST URL with a cache key that matches a blob ID; +* `getVastXml` scans the response for such URLs, and replaces them with an inlined copy of the matching VAST XML from blob storage. + +This means that you can migrate an existing setup using a 3rd party cache service to local caching without any changes in GAM (the VAST URLs in GAM creatives are ignored except for the cache key portion). + +{: .alert.alert-warning :} +Video players often add signals to the GAM ad tag URL. They cannot do this when using `getVastXml`, as there is no URL to augment. This can impact the GAM auction; in practice, this means that using client-side caching will likely result in lower AdX demand. + + + ## Working Examples **Note:** Prebid video is designed to work across devices and browsers. This demo has been developed and tested only for Chrome desktop, Firefox desktop, and Chrome Android; additional device/browser support is planned to be added at a later date. diff --git a/docs-examples/web-example.md b/docs-examples/web-example.md index 79c5246494..9e1c64903e 100644 --- a/docs-examples/web-example.md +++ b/docs-examples/web-example.md @@ -56,9 +56,9 @@ var adUnits = [{ } }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13144370 + placement_id: 13144370 } }] }]; diff --git a/examples/video/instream/jwplayer/pb-ve-jwplayer-hosted.html b/examples/video/instream/jwplayer/pb-ve-jwplayer-hosted.html index 67ab3e318d..7ce8a8bbd7 100644 --- a/examples/video/instream/jwplayer/pb-ve-jwplayer-hosted.html +++ b/examples/video/instream/jwplayer/pb-ve-jwplayer-hosted.html @@ -57,8 +57,8 @@

Place this code in the page header.

// define invokeVideoPlayer in advance in case we get the bids back from prebid before the entire page loads
var tempTag = false; - var invokeVideoPlayer = function(url) { - tempTag = url; + var invokeVideoPlayer = function(vastXml) { + tempTag = vastXml; } var videoAdUnit = { @@ -74,9 +74,9 @@

Place this code in the page header.

} }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232361 // Add your own placement id here
+ placement_id: 13232361 // Add your own placement id here
} }] }; @@ -86,24 +86,18 @@

Place this code in the page header.

pbjs.setConfig({ debug: true, cache: { - url: 'https://prebid.example.com/pbc/v1/cache' + useLocal: true } }); pbjs.requestBids({ bidsBackHandler: function(bids) { - var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + pbjs.adServers.gam.getVastXml({ adUnit: videoAdUnit, params: { - iu: '/19968336/prebid_cache_video_adunit', - cust_params: { - section: 'blog', - anotherKey: 'anotherValue' - }, - output: 'vast' - } - }); - invokeVideoPlayer(videoUrl); + iu: '/41758329/localcache', + }, + }).then(vastXml => invokeVideoPlayer(vastXml)); } }); }); @@ -123,7 +117,7 @@

Place this code in the page body.

Place this code in the page body.

"mute": false, "advertising": { client: "vast", + schedule: [ + { + vastxml: vastXml, + offset: 'pre' + } + ] } }); - - jwPlayerInstance.on('beforePlay', function() { - jwPlayerInstance.playAd(url); - }) } if (tempTag) { @@ -155,10 +151,10 @@

Place this code in the page body.

diff --git a/examples/video/instream/jwplayer/pb-ve-jwplayer-platform.html b/examples/video/instream/jwplayer/pb-ve-jwplayer-platform.html index 64f06968ec..772fbd724f 100644 --- a/examples/video/instream/jwplayer/pb-ve-jwplayer-platform.html +++ b/examples/video/instream/jwplayer/pb-ve-jwplayer-platform.html @@ -7,13 +7,6 @@ sidebarType: 4 --- - -

@@ -57,8 +50,8 @@

Place this code in the page header.

} }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232361 //put your placement id here
+ placement_id: 13232361 //put your placement id here
} }] }; @@ -88,26 +81,20 @@

Place this code in the page header.

pbjs.setConfig({ debug: true, cache: { - url: 'https://prebid.example.com/pbc/v1/cache' + useLocal: true } }); - pbjs.requestBids({ - bidsBackHandler: function(bids) { - var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ - adUnit: videoAdUnit, - params: { - iu: '/19968336/prebid_cache_video_adunit', - cust_params: { - section: 'blog', - anotherKey: 'anotherValue' - }, - output: 'vast' - } - }); - invokeVideoPlayer(videoUrl); - } - }); + pbjs.requestBids({ + bidsBackHandler: function(bids) { + pbjs.adServers.gam.getVastXml({ + adUnit: videoAdUnit, + params: { + iu: '/41758329/localcache', + }, + }).then(vastXml => invokeVideoPlayer(vastXml)); + } + }); }); </script> @@ -157,7 +144,7 @@

Place this code in the page body.

diff --git a/examples/video/long-form/long-form-video-with-freewheel.html b/examples/video/long-form/long-form-video-with-freewheel.html index 28f5e06c6b..f88cd24d1d 100644 --- a/examples/video/long-form/long-form-video-with-freewheel.html +++ b/examples/video/long-form/long-form-video-with-freewheel.html @@ -68,9 +68,9 @@ }, bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 14542875 + placement_id: 14542875 } } ] @@ -329,9 +329,9 @@

Prebid Freewheel Integration Demo

}, bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 14542875 + placement_id: 14542875 } } ] diff --git a/examples/video/long-form/pb-ve-lf-freewheel.html b/examples/video/long-form/pb-ve-lf-freewheel.html index bbf15b1a6d..cc2e7ff78c 100644 --- a/examples/video/long-form/pb-ve-lf-freewheel.html +++ b/examples/video/long-form/pb-ve-lf-freewheel.html @@ -85,9 +85,9 @@

}, bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 14542875 + placement_id: 14542875 } } ] diff --git a/examples/video/outstream/basic-ima.html b/examples/video/outstream/basic-ima.html index 6c853181c2..cdbad74405 100644 --- a/examples/video/outstream/basic-ima.html +++ b/examples/video/outstream/basic-ima.html @@ -136,9 +136,9 @@

}, bids: [ { - bidder: "appnexus", + bidder: "msft", params: { - placementId: 13232385, + placement_id: 13232385, }, }, ], diff --git a/examples/video/outstream/pb-ve-outstream-dfp.html b/examples/video/outstream/pb-ve-outstream-dfp.html index 803e067576..5b31ae0d2c 100644 --- a/examples/video/outstream/pb-ve-outstream-dfp.html +++ b/examples/video/outstream/pb-ve-outstream-dfp.html @@ -101,9 +101,9 @@

Place this code in the page header.

}, bids: [ { - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232385 + placement_id: 13232385 } } ] diff --git a/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html b/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html index eb53b2dd88..5154ac5f71 100644 --- a/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html +++ b/examples/video/outstream/pb-ve-outstream-no-server-specify-renderer.html @@ -135,9 +135,9 @@

Place this code in the page header.

} }, bids: [{ - bidder: 'appnexus', + bidder: 'msft', params: { - placementId: 13232385 + placement_id: 13232385 } }] }]; @@ -149,7 +149,7 @@

Place this code in the page header.

intercept: [ { when: { - bidder: 'appnexus', + bidder: 'msft', }, then: { cpm: 10, diff --git a/identity/sharedid.md b/identity/sharedid.md index 80cab18f7d..50d89c68dd 100644 --- a/identity/sharedid.md +++ b/identity/sharedid.md @@ -181,7 +181,7 @@ Publishers that decide to build a first-party opt-out workflow might follow a pr ## Alternative Implementations -For those not using Prebid's header bidding solution, SharedId can deployed via in inline script reference or from a web server. +For those not using Prebid's header bidding solution, SharedId can be deployed via in inline script reference or from a web server. ### SharedId Script diff --git a/npm-postinstall.sh b/npm-postinstall.sh deleted file mode 100755 index 5d422c25b8..0000000000 --- a/npm-postinstall.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/sh - -# Copy all node_modules css and scss files to _sass/node_modules so we can import and build them with Jekyll -cd node_modules || exit -cp --parents -Rf "$(find . -name '*.scss')" ../_sass/node_modules -cp --parents -Rf "$(find . -name '*.css' ! -path "*/dist/*|*/bundle/*")" ../_sass/node_modules - -# Rename all css files to scss, so we can import them in other scss files and they get bundled propery -cd ../_sass/node_modules || exit -find . -name '*.css' -exec sh -c 'mv "$0" "${0%.css}.scss"' {} \; diff --git a/overview/how-to-simplify-line-item-setup.md b/overview/how-to-simplify-line-item-setup.md index a470df22b4..44f1f6ce54 100644 --- a/overview/how-to-simplify-line-item-setup.md +++ b/overview/how-to-simplify-line-item-setup.md @@ -65,7 +65,7 @@ There you go! ### Simplification 2: Remove the bidder dimension -In this section, we'll learn how to remove the bidder dimension for header bidding. Before, a publisher would have to create different set of line items for different bidders. For example, 3 different set of line items for AppNexus, Pubmatic, and Rubicon. With Prebid.js, a publisher only need to create 1 set of line items for all bidders. +In this section, we'll learn how to remove the bidder dimension for header bidding. Before, a publisher would have to create different set of line items for different bidders. For example, 3 different set of line items for Microsoft, Pubmatic, and Rubicon. With Prebid.js, a publisher only need to create 1 set of line items for all bidders. There're a few reasons why previously you'd need different set of line items for bidders. @@ -73,14 +73,14 @@ There're a few reasons why previously you'd need different set of line items for 2. Bidders all have different targeting parameters. 3. You need to run reports to learn fill rates and CPM from different bidders. -Assume we have 1 set of line items for ALL bidders. Consider the below key-value pairs came in: (AppNexus bid $1.60, Rubicon bid $1.20. Ad IDs are used for rendering the right creative): +Assume we have 1 set of line items for ALL bidders. Consider the below key-value pairs came in: (Microsoft bid $1.60, Rubicon bid $1.20. Ad IDs are used for rendering the right creative): -* `appnexus_cpm`: 1.60 -* `appnexus_adId`: 65432 +* `msft_cpm`: 1.60 +* `msft_adId`: 65432 * `rubicon_cpm`: 1.20 * `rubicon_adId`: 23456 -The line item for $1.60 is chosen because it has the highest price. However, the creative attached to this line item will be given both `appnexus_ad_id`: 65432 and `rubicon_ad_id`: 23456. There's not an easy way for the right creative (in this case the AppNexus creative) to render. +The line item for $1.60 is chosen because it has the highest price. However, the creative attached to this line item will be given both `msft_ad_id`: 65432 and `rubicon_ad_id`: 23456. There's not an easy way for the right creative (in this case the Microsoft creative) to render. @@ -90,7 +90,7 @@ Prebid.js only picks the highest price bid and sends its key-value pairs to the * `hb_pb`: 1.60 * `hb_adId`: 65432 -* `hb_bidder`: appnexus +* `hb_bidder`: msft This simplifies the setup and the right creative (with adId 65432) will get displayed. diff --git a/overview/intro-to-header-bidding.md b/overview/intro-to-header-bidding.md index ddebe6e639..d4fcd0ffae 100644 --- a/overview/intro-to-header-bidding.md +++ b/overview/intro-to-header-bidding.md @@ -6,6 +6,9 @@ description: An beginner's guide to header bidding. sidebarType: 0 --- +

# Introduction to Header Bidding diff --git a/overview/prebid-universal-creative.md b/overview/prebid-universal-creative.md index 9a1c5c8e7f..a3eb7ca400 100644 --- a/overview/prebid-universal-creative.md +++ b/overview/prebid-universal-creative.md @@ -45,7 +45,7 @@ Since version 10.11.0, Prebid.js populates the `hb_ver` ad server key-value whic This loads the PUC from the Prebid-maintained location. Your managed service provider may have a different location. -To see specific examples of how to use the PUC within your ad server, see the guides for [GAM](/adops/gam-creative-banner-sbs.html), [Microsoft](/adops/setting-up-prebid-with-the-appnexus-ad-server.html), or [other ad servers](/adops/adops-general-sbs.html). +To see specific examples of how to use the PUC within your ad server, see the guides for [GAM](/adops/gam-creative-banner-sbs.html), [Microsoft](/adops/setting-up-prebid-with-the-microsoft-ad-server.html), or [other ad servers](/adops/adops-general-sbs.html). ## Features of the PUC @@ -114,5 +114,5 @@ If safeframe support is required, some options are: ## Further Reading - [Step by Step Guide to Google Ad Manager Setup](/adops/step-by-step.html) -- [Setting up Prebid with the Xandr Monetize Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) +- [Setting up Prebid with the Xandr Monetize Ad Server](/adops/setting-up-prebid-with-the-microsoft-ad-server.html) - [Prebid.js dynamic creatives](/adops/js-dynamic-creative.html) diff --git a/overview/what-is-prebid-org.md b/overview/what-is-prebid-org.md index cfba8f7a0c..08f0502e32 100644 --- a/overview/what-is-prebid-org.md +++ b/overview/what-is-prebid-org.md @@ -7,7 +7,7 @@ sidebarType: 0 # About Prebid.org -Header bidding has seen incredible adoption across the industry, and Prebid.js has been an integral part of that. AppNexus (now Xandr) created Prebid.js, but considered it too important to be owned by any one company. Thus, Prebid.org was created. +Header bidding has seen incredible adoption across the industry, and Prebid.js has been an integral part of that. AppNexus (now Microsoft) created Prebid.js, but considered it too important to be owned by any one company. Thus, Prebid.org was created. Formed in September of 2017, Prebid.org is an independent organization designed to ensure and promote fair, transparent, and efficient header bidding across the industry. Funded by dues-paying members, it manages the open source projects Prebid.js, Prebid Mobile, Prebid Server, Prebid Video, Prebid Native, and others. diff --git a/package.json b/package.json index fb06b2e31b..3ddf53d002 100644 --- a/package.json +++ b/package.json @@ -10,8 +10,7 @@ "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "npm run development", - "watch": "bundle exec jekyll serve", - "postinstall": "./npm-postinstall.sh" + "watch": "bundle exec jekyll serve" }, "repository": { "type": "git", diff --git a/prebid-mobile/dr-prebid.md b/prebid-mobile/dr-prebid.md index 4683098357..ea280bf0af 100644 --- a/prebid-mobile/dr-prebid.md +++ b/prebid-mobile/dr-prebid.md @@ -98,7 +98,7 @@ These settings will help verify that Prebid Mobile and Prebid Server are connect Select your Prebid Server host: -- *AppNexus* +- *AppNexus (Microsoft)* - *Rubicon* - *Custom* diff --git a/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md b/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md new file mode 100644 index 0000000000..c39732f5c2 --- /dev/null +++ b/prebid-mobile/modules/rendering/android-sdk-integration-nextgen.md @@ -0,0 +1,344 @@ +--- + +layout: page_v2 +title: Prebid Mobile Rendering Google Next-Gen SDK Integration +description: Prebid Mobile Rendering Modules Google Next-Gen SDK integration +sidebarType: 2 + +--- + +# Prebid SDK Android with the Google Next-Gen SDK Prebid-Rendered Integration Method +{:.no_toc} + +- TOC +{:toc} + +{% include mobile/intro-nextgen-prebid-rendered.md platform="android" %} + +## Event Handlers + +First, a little bit of setup is needed. + +### Integrate Event Handlers + +The Prebid SDK supplies a set of classes called the 'Next-Gen Event Handlers' that wrap the Next-Gen Ad Views and manage them in the In-App Bidding flow. These classes are provided in the form of a library that can be added to the app via Gradle: + +Root `build.gradle`: + +```text +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +App module `build.gradle`: + +```text +implementation('org.prebid:prebid-mobile-sdk-next-gen-event-handlers:x.x.x') +``` + +### Initialize the Google Next-Gen Mobile Ads SDK + +Initialize the Next-Gen SDK early in your app lifecycle (e.g., in `Application.onCreate()`): + +```kotlin +val backgroundScope = CoroutineScope(Dispatchers.IO) +backgroundScope.launch { + MobileAds.initialize( + context, + InitializationConfig.Builder("YOUR_APP_ID").build() + ) { + // Initialization complete + } +} +``` + +## AdUnit-Specific Instructions + +This section covers integration details for different ad formats. In each scenario, you'll be asked for a `configId` - this is a key worked out with your Prebid Server provider. It's used at runtime to pull in the bidders and parameters specific to this adunit. Depending on your Prebid Server partner, it may be a UUID or constructed out of parts like an account number and adunit name. + +### Banners + +#### Display Banners + +To integrate the banner ad you need to implement three easy steps: + +```kotlin +// 1. Create a banner custom event handler for the Next-Gen SDK. +val eventHandler = NextGenBannerEventHandler(requireContext(), NEXT_GEN_AD_UNIT_ID, AdSize(WIDTH, HEIGHT)) + +// 2. Create a bannerView instance and provide the Next-Gen event handler +bannerView = BannerView(requireContext(), configId, eventHandler) +// (Optional) set an event listener +bannerView?.setBannerListener(this) + +// Add bannerView to your viewContainer +viewContainer?.addView(bannerView) + +// 3. Execute the loadAd function. +bannerView?.loadAd() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +##### Step 1: Create Event Handler +{:.no_toc} + +Prebid SDK's Next-Gen event handlers are special containers that wrap Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create the event handler you should provide a Next-Gen Ad Unit Id and one or more `AdSize` instances for this ad unit. + +##### Step 2: Create Ad View +{:.no_toc} + +**BannerView** - is the view that will display a particular ad. It should be added to the UI. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - the instance of the Next-Gen banner event handler + +Also, you should add the instance of `BannerView` to the UI. + +And assign the listeners for processing ad events. + +##### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. + +#### Non-Instream Video +{:.no_toc} + +For **Non-Instream Video** you also need to specify the video placement type of the expected ad: + +```kotlin +bannerView.videoPlacementType = PlacementType.IN_BANNER // or any other available type +``` + +#### Migrating banners from a Bidding-Only integration + +Next-Gen SDK 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 new Next-Gen SDK ad unit. +3. Setup new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `AdView` with `BannerView` in the UI. +2. Implement the interface `BannerViewListener`. +3. Remove both `AdView` and `BannerAdRequest`. +4. Remove the original `BannerAdUnit`. +5. Follow the instructions to integrate [Banner API](#banners). + +### Interstitials + +To integrate an interstitial ad follow these steps: + +```kotlin +// 1. Create an interstitial custom event handler for the Next-Gen SDK. +val eventHandler = NextGenInterstitialEventHandler(requireContext(), nextGenAdUnitId) + +// 2. Create an interstitialAdUnit instance and provide the Next-Gen event handler +interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, eventHandler) +// (Optional) for multiformat, specify the ad unit formats +// interstitialAdUnit = InterstitialAdUnit(requireContext(), configId, EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO), eventHandler) + +// (Optional) set an event listener +interstitialAdUnit?.setInterstitialAdUnitListener(this) + +// 3. Execute the loadAd function. +interstitialAdUnit?.loadAd() + +//.... + +// 4. After the ad is loaded you can execute the `show` function to trigger ad display +interstitialAdUnit?.show() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +In order to make a `multiformat bid request`, set the respective values into the `adUnitFormats` parameter: + +```kotlin +interstitialAdUnit = InterstitialAdUnit( + requireContext(), + configId, + EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO), + eventHandler) +``` + +#### Step 1: Create Event Handler +{:.no_toc} + +Next-Gen's event handlers are special containers that wrap the Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a Next-Gen Ad Unit ID. + +#### Step 2: Create Interstitial Ad Unit +{:.no_toc} + +**InterstitialAdUnit** - is an object that will load and display a particular ad. To create it you should provide: + +- **configId** - an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **minSizePercentage** - specifies the minimum width and height percent an ad may occupy of a device’s screen. +- **eventHandler** - the instance of the Next-Gen interstitial event handler + +Also, you can assign the listeners for processing ad events. + +> **NOTE:** minSizePercentage - plays an important role in a bidding process for display ads. If the provided space is too small demand partners won't respond with bids. + +#### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. The ad unit will load an ad and will wait for explicit instructions to display the Interstitial Ad. + +#### Step 4: Show the Ad when it is ready +{:.no_toc} + +The most convenient way to determine if the interstitial ad is ready for displaying is to listen to the listener method: + +```kotlin +override fun onAdLoaded(interstitialAdUnit: InterstitialAdUnit) { + //Ad is ready for display + interstitialAdUnit.show() +} +``` + +#### Migrating interstitials from a Bidding-Only integration + +Next-Gen SDK 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 Next-Gen SDK ad unit. +3. Setup a new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `InterstitialAd` with `InterstitialAdUnit`. +2. Implement the interface for `InterstitialAdUnitListener`. +3. Remove both `InterstitialAd` and `AdRequest`. +4. Follow the instructions to integrate [Interstitial API](#interstitials). + +### Rewarded + +{% include mobile/rewarded-server-side-configuration.md %} + +#### Integration Example + +Displaying the **Rewarded Ad** is the same as displaying an Interstitial Ad, but it adds the ability to handle a reward. To display a Rewarded Ad follow these steps: + +```kotlin +// 1. Create a rewarded custom event handler for the Next-Gen SDK. +val eventHandler = NextGenRewardedEventHandler(requireActivity(), nextGenAdUnitId) + +// 2. Create a rewardedAdUnit instance and provide the Next-Gen event handler +rewardedAdUnit = RewardedAdUnit(requireContext(), configId, eventHandler) + +// You can also set an event listener, this step is optional. +rewardedAdUnit?.setRewardedAdUnitListener(this) + +// 3. Execute the loadAd function. +rewardedAdUnit?.loadAd() + +//... + +// 4. After the ad is loaded you can execute the `show` function to display the ad. +rewardedAdUnit?.show() +``` + +{% capture warning_note %} +Pay attention that the `loadAd()` should be called on the main thread. +{% endcapture %} +{% include /alerts/alert_warning.html content=warning_note %} + +##### Step 1: Create Event Handler +{:.no_toc} + +Next-Gen's event handlers are special containers that wrap the Next-Gen Ad Views and help to manage collaboration between the Next-Gen SDK and Prebid views. + +**Important:** you should create and use a unique event handler for each ad view. + +To create an event handler you should provide a Next-Gen Ad Unit ID. + +##### Step 2: Create Rewarded Ad Unit +{:.no_toc} + +**RewardedAdUnit** - is an object that will load and display the particular ad. To create it you should provide: + +- **configId** - is an ID of a [Stored Impression](/prebid-server/features/pbs-storedreqs.html) on the Prebid server +- **eventHandler** - is the instance of the Next-Gen rewarded event handler + +You can also assign the listener for processing ad events. + +##### Step 3: Load the Ad +{:.no_toc} + +Call the `loadAd()` method to make a bid request. The ad unit will load an ad and will wait for explicit instructions to display the Rewarded Ad. + +##### Step 4: Display the Ad when it is ready +{:.no_toc} + +The most convenient way to determine if the ad is ready for displaying is to listen for the listener method: + +```kotlin +override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) { + //Ad is ready for display + rewardedAdUnit.show() +} +``` + +##### Step 5: Handle a reward +{:.no_toc} + +Handle earning the reward in the appropriate method. Important: a reward can be null. + +```kotlin +override fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit?, reward: Reward?) { + if (reward != null) { + val rewardType = reward.type + val rewardCount = reward.count + val rewardExt = reward.ext + // Process the reward + } +} +``` + +#### Migrating rewarded video from a Bidding-Only integration +{:.no_toc} + +Next-Gen SDK 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 Next-Gen SDK ad unit. +3. Setup a new [GAM Order](/adops/mobile-rendering-gam-line-item-setup.html) for rendering approach. + +Integration: + +1. Replace the `RewardedAd` with `RewardedAdUnit`. +2. Implement the interface for `RewardedAdUnitListener`. +3. Remove the original `RewardedVideoAdUnit`. +4. Follow the instructions to integrate [Rewarded API](#rewarded). + +## Additional Ad Unit Configuration + +{% include mobile/rendering-adunit-config-android.md %} + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android Integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Android Global Parameters](/prebid-mobile/pbm-api/android/pbm-targeting-android.html) diff --git a/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md b/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md new file mode 100644 index 0000000000..bde7a768e4 --- /dev/null +++ b/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.md @@ -0,0 +1,66 @@ +--- +layout: page_v2 +title: Prebid Mobile - Next-Gen SDK Bidding-Only Integration - Android +description: Integration of Prebid SDK Android with Google Next-Gen SDK using the 'Bidding-Only' integration +sidebarType: 2 +--- + +# Prebid SDK Android with the Next-Gen SDK Bidding-Only Integration Method +{:.no_toc} + +- TOC +{:toc} + +{% include mobile/intro-nextgen-bidding-only.md platform='android' %} + +## AdUnit-Specific instructions + +This section describes the integration details for different ad formats. In each scenario, you'll be asked for a `configId` - this is a key established in conjunction with your Prebid Server provider. It's used at runtime to pull in the bidders and parameters specific to this adunit. Depending on your Prebid Server partner, it may be a UUID or constructed out of parts like an account number and adunit name. + +### [Format: HTML Banner](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.html) + +### [Format: Interstitial Banner](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.html) + +### [Format: Non-Instream Video](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-video-outstream.html) + +### [Format: Interstitial Video](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.html) + +### [Format: Rewarded Video Ad](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-rewarded-video.html) + +### [Format: Native In-App](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-app.html) + +### [Format: Native In-Webview](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-native-in-webview.html) + +### [Format: Multiformat (Banner+Video+InApp Native)](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.html) + +### [Format: Multiformat Interstitial (Banner+Video)](/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.html) + +## Additional Ad Unit Configuration + +{% include mobile/adunit-config-android.md %} + +### Impression tracking + +In the Bidding-Only integration scenario, the Prebid SDK is responsible for tracking events for banner ads, like `burl`, `imp`, and `win`. The disadvantage of this approach is that the SDK doesn't have reliable information about the viewability of the WebView. As a result, impression tracking happens at the rendering stage of the ad. Or, if MRAID is supported, once the `viewableChange` event is fired. It leads to big discrepancies since the "1 pixel in view" requirement is not met. + +To activate impression tracking for the banner ad unit - use the `activatePrebidImpressionTracker(adView)` method. The `adView` parameter should be an instance of the Next-Gen SDK `AdView`: + +```kotlin +adUnit.activatePrebidImpressionTracker(adView) +adUnit.fetchDemand(adRequestBuilder) { ... } +``` + +For activation for the interstitial ad unit, you should call `activateInterstitialPrebidImpressionTracker()`: + +```kotlin +adUnit = InterstitialAdUnit(CONFIG_ID, WIDTH, HEIGHT) +adUnit.activateInterstitialPrebidImpressionTracker() +``` + +After the invocation of `activateInterstitialPrebidImpressionTracker()`, the Prebid SDK will start analyzing the View Hierarchy and track the viewability of the ad view. Once the ad view is viewable for the user for at least 1 pixel for 1 second, the SDK will track an impression event for the presented ad. The SDK will stop analyzing the View Hierarchy once the caller object is destroyed. + +## Further Reading + +- [Prebid Mobile Overview](/prebid-mobile/prebid-mobile.html) +- [Prebid SDK Android Integration](/prebid-mobile/pbm-api/android/code-integration-android.html) +- [Prebid SDK Android Global Parameters](/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 911fc9e71b..a6028faf58 100644 --- a/prebid-mobile/pbm-api/android/code-integration-android.md +++ b/prebid-mobile/pbm-api/android/code-integration-android.md @@ -313,7 +313,7 @@ PrebidMobile.setStoredAuctionResponse("response-prebid-banner-320-50") 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). ```kotlin -PrebidMobile.addStoredBidResponse("appnexus", "221144"); +PrebidMobile.addStoredBidResponse("msft", "221144"); PrebidMobile.addStoredBidResponse("rubicon", "221155"); ``` diff --git a/prebid-mobile/pbm-api/ios/code-integration-ios.md b/prebid-mobile/pbm-api/ios/code-integration-ios.md index 0c61ddaf5e..83ffc1a219 100644 --- a/prebid-mobile/pbm-api/ios/code-integration-ios.md +++ b/prebid-mobile/pbm-api/ios/code-integration-ios.md @@ -402,7 +402,7 @@ Prebid.shared.pbsDebug = true Prebid.shared.storedAuctionResponse = "111122223333" //or -Prebid.shared.addStoredBidResponse(bidder: "appnexus", responseId: "221144") +Prebid.shared.addStoredBidResponse(bidder: "msft", responseId: "221144") Prebid.shared.addStoredBidResponse(bidder: "rubicon", responseId: "221155") ``` diff --git a/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md new file mode 100644 index 0000000000..a07b6d3280 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-html-banner.md @@ -0,0 +1,138 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - HTML Banner +description: Android Next-Gen SDK Bidding-Only Integration - HTML Banner +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - HTML Banner + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `BannerAdUnit` to bid over the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `BannerAdUnit` constructor. + +Integration example: + +```kotlin +private fun createAd() { + // 1. Create BannerAdUnit + adUnit = BannerAdUnit(CONFIG_ID, WIDTH, HEIGHT) + adUnit?.setAutoRefreshInterval(refreshTimeSeconds) + + // 2. Configure banner parameters + val parameters = BannerParameters() + parameters.api = listOf(Signals.Api.MRAID_3, Signals.Api.OMID_1) + adUnit?.bannerParameters = parameters + + // 3. Create Next-Gen SDK AdView + val adView = AdView(this) + val adSize = AdSize(WIDTH, HEIGHT) + adWrapperView.addView(adView) + + // 4. Build the Next-Gen SDK ad request + val adRequestBuilder = BannerAdRequest.Builder(AD_UNIT_ID, adSize) + + // 5. Make a bid request to Prebid Server + adUnit?.fetchDemand(adRequestBuilder) { + + // 6. Load Next-Gen Ad + adView.loadAd(adRequestBuilder.build(), createAdLoadCallback(adView)) + } +} +``` + +Prebid SDK can be thought of an OpenRTB request synthesizer. OpenRTB does not have a notion of adaptive banners, but it has a notion of several banner sizes / formats in one request. So an adaptive banner may be represented as a request containing several banner sizes, e.g. a fixed width that equals the size of the screen and several different heights. The examples here deal with a single ad size, but more can be added via BannerParameters.adSizes array. + +It may be necessary to resize the banner view according to the creative size when multiple ad sizes are supported. This logic is not needed for a single-size banner: + +Next-Gen SDK ad load callback: + +```kotlin +private fun createAdLoadCallback(adView: AdView): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: BannerAd) { + super.onAdLoaded(ad) + + // 7. Resize ad view if needed + AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener { + override fun success(width: Int, height: Int) { + adView.resize(AdSize(width, height)) + } + + override fun failure(error: PbFindSizeError) {} + }) + + ad.adEventCallback = object : BannerAdEventCallback { + override fun onAdClicked() { + super.onAdClicked() + } + override fun onAdImpression() { + super.onAdImpression() + } + } + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +Notes: + +1. In case you use a single-size banner (as opposed to multi-size), i.e. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel. +2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it. + +## Step 1: Create a BannerAdUnit +{:.no_toc} + +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. + +## Step 2: Configure banner parameters +{:.no_toc} + +{% include mobile/banner-params.md %} + +## Step 3: Create a Next-Gen SDK AdView +{:.no_toc} + +Follow the [Next-Gen SDK documentation](https://developers.google.com/admob/android/next-gen/banner) to integrate a banner ad unit. + +## Step 4: Build the Ad Request +{:.no_toc} + +Create a `BannerAdRequest.Builder` with the Next-Gen SDK Ad Unit ID and the desired `AdSize`. + +## Step 5: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide a `BannerAdRequest.Builder` object to this method. Prebid SDK will set the targeting keywords of the winning bid into the provided object. Eventually you should use this object to make an ad request to the Next-Gen SDK. + +## Step 6: Load an Ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `BannerAdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `BannerAdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain the targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 7: Adjust the ad view size +{:.no_toc} + +Once an app receives a signal that an ad is loaded, you should use the method `AdViewUtils.findPrebidCreativeSize` to verify whether it's Prebid's ad and resize the ad slot respectively to the creative's properties. + +Notes: + +1. In case you use a single-size banner (as opposed to multi-size), e.g. 300x250 - you don't need to call `AdViewUtils.findPrebidCreativeSize` because you already know the size of the creative. However you still need to call `adView.resize()` because the creative has a 1x1 size by default and without this call it will be rendered as a pixel. +2. Make sure you properly process all possible cases in the `AdViewUtils.findPrebidCreativeSize` callbacks (both success and failure). Sometimes you might not get the size of the creative (or a failure callback) - it simply means that this is not a Prebid creative. It means that you still need to render the creative, but you most likely don't need to resize it. + +## Further Reading + +- [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/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md new file mode 100644 index 0000000000..aec7d2a201 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-banner.md @@ -0,0 +1,88 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner +description: Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Interstitial Banner + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `InterstitialAdUnit` to bid over the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `InterstitialAdUnit` constructor. + +Integration example: + +```kotlin +private fun createAd() { + // 1. Create InterstitialAdUnit + // minWidthPercent=80, minHeightPercent=60 + adUnit = InterstitialAdUnit(CONFIG_ID, 80, 60) + + // 2. Build the Next-Gen SDK ad request + val request = AdRequest.Builder(AD_UNIT_ID) + adUnit?.fetchDemand(request) { + + // 3. Load a Next-Gen interstitial ad + InterstitialAd.load( + request.build(), + createListener() + ) + } +} +``` + +You also need to implement `AdLoadCallback` in order to track the ad readiness: + +```kotlin +private fun createListener(): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: InterstitialAd) { + super.onAdLoaded(ad) + + // 4. Present the interstitial ad + ad.show(this@Activity) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +## Step 1: Create an InterstitialAdUnit +{:.no_toc} + +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+ + +{: .alert.alert-info :} +Here's how min size percentages work. If the adunit size is 1x1, Prebid Server uses the screen width/height and the minWidthPerc/minHeightPerc to generate a list of ad sizes from a [predefined list](https://github.com/prebid/prebid-server/blob/master/config/interstitial.go). It selects the first 10 sizes that fall within the max size and minimum percentage size. All the interstitial parameters will still be passed to the bidders, allowing them to use their own size matching algorithms if they prefer. If you'd prefer to just define the size list, that's ok too - just set the sizes and don't define minWidthPerc/minHeightPerc. + +## Step 2: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 3: Load a Next-Gen interstitial ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 4: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/ad-manager/mobile-ads-sdk/android/interstitial#display_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [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/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md new file mode 100644 index 0000000000..f74a8c8612 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-interstitial-video.md @@ -0,0 +1,116 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Interstitial Video +description: Android Next-Gen SDK Bidding-Only Integration - Interstitial Video +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Interstitial Video + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with Prebid Mobile `2.1.0` you can use `InterstitialAdUnit` to bid for the banner and/or video demand. The default ad format is `BANNER`. To customize the bidding format, specify the ad formats in the `InterstitialAdUnit` constructor. + +Integration Example: + +```kotlin +private fun createAd() { + + // 1. Create InterstitialAdUnit with video format + adUnit = InterstitialAdUnit(CONFIG_ID, EnumSet.of(AdUnitFormat.VIDEO)) + + // 2. Configure video ad unit + adUnit?.videoParameters = configureVideoParameters() + + // 3. Make a bid request to Prebid Server + val requestBuilder = AdRequest.Builder(AD_UNIT_ID) + adUnit?.fetchDemand(requestBuilder) { + + // 4. Load a Next-Gen ad + InterstitialAd.load( + requestBuilder.build(), + createAdListener() + ) + } +} +``` + +Configuration function: + +```kotlin +private fun configureVideoParameters(): VideoParameters { + return VideoParameters(listOf("video/x-flv", "video/mp4")).apply { + placement = Signals.Placement.Interstitial + + api = listOf( + Signals.Api.VPAID_1, + Signals.Api.VPAID_2 + ) + + maxBitrate = 1500 + minBitrate = 300 + maxDuration = 30 + minDuration = 5 + playbackMethod = listOf(Signals.PlaybackMethod.AutoPlaySoundOn) + protocols = listOf( + Signals.Protocols.VAST_2_0 + ) + } +} +``` + +Next-Gen SDK ad listener: + +```kotlin +private fun createAdListener(): AdLoadCallback { + return object : AdLoadCallback() { + override fun onAdLoaded(ad: InterstitialAd) { + super.onAdLoaded(ad) + + // 5. Display an interstitial ad + ad.show(this@Activity) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed to load: $adError") + } + } +} +``` + +## Step 1: Create an Ad Unit +{:.no_toc} + +Initialize the `InterstitialAdUnit` with the following properties: + +- `configId` - an ID of Stored Impression on the Prebid Server +- `adUnitFormats` - `AdUnitFormat.VIDEO` for a video ad + +## Step 2: Configure video parameters +{:.no_toc} + +{% include mobile/video-params.md %} + +## Step 3: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 4: Load a Next-Gen interstitial ad +{:.no_toc} + +Now you should request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise, the ad request won't contain targeting keywords, and Prebid's ad won't ever be displayed. + +## Step 5: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/admob/android/next-gen/interstitial#show_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [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/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md new file mode 100644 index 0000000000..56018e26a0 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat-interstitial.md @@ -0,0 +1,81 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video +description: Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Multiformat Interstitial Banner+Video + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Integration example: + +```kotlin +// 1. Create InterstitialAdUnit +adUnit = InterstitialAdUnit(configId, EnumSet.of(AdUnitFormat.BANNER, AdUnitFormat.VIDEO)) +adUnit?.setMinSizePercentage(80, 60) +adUnit?.adUnitConfig.adSize = new AdSize(1, 1); +adUnit?.videoParameters = VideoParameters(listOf("video/mp4")) + +// 2. Make a bid request to Prebid Server +val requestBuilder = AdRequest.Builder(AD_UNIT_ID) +adUnit?.fetchDemand(requestBuilder) { + + // 3. Load a Next-Gen interstitial ad + InterstitialAd.load( + requestBuilder.build(), + createListener() + ) +} +``` + +## Step 1: Create an Ad Unit +{:.no_toc} + +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. + +{: .alert.alert-info :} +Here's how min size percentages work. If the adunit size is 1x1, Prebid Server takes the screen width/height and the minWidthPerc/minHeightPerc as a size range, generating a list of ad sizes from a [predefined list](https://github.com/prebid/prebid-server/blob/master/config/interstitial.go). It selects the first 10 sizes that fall within the max size and minimum percentage size. All the interstitial parameters will still be passed to the bidders, allowing them to use their own size matching algorithms if they prefer. If you'd prefer to just define the size list, that's ok too - just set the sizes and don't define minWidthPerc/minHeightPerc. + +## Step 2: Set ad formats +{:.no_toc} + +For multiformat ad unit, you must set both banner and video ad formats. + +## Step 3: Configure parameters +{:.no_toc} + +### Banner parameters + +{% include mobile/banner-params.md %} + +### Video parameters + +{% include mobile/video-params.md %} + +## Step 4: Make a bid request +{:.no_toc} + +The `fetchDemand` method makes a bid request to the Prebid Server. You should provide an `AdRequest.Builder` object to this method so Prebid SDK sets the targeting keywords of the winning bid for future ad requests. + +## Step 5: Load a Next-Gen interstitial ad +{:.no_toc} + +You should now request the ad from the Next-Gen SDK. If the `AdRequest` contains targeting keywords, the respective Prebid line item will be returned from GAM, and the Next-Gen SDK will render its creative. + +Be sure that you make the ad request with the same `AdRequest.Builder` object that you passed to the `fetchDemand` method. Otherwise the ad request won't contain targeting keywords and Prebid's ad won't ever be displayed. + +## Step 6: Present the interstitial ad +{:.no_toc} + +Follow the [Next-Gen SDK guide](https://developers.google.com/admob/android/next-gen/interstitial#show_the_ad) to display an interstitial ad right after receiving it or later in natural pauses in the flow of an app. + +## Further Reading + +- [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/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md new file mode 100644 index 0000000000..26793b3003 --- /dev/null +++ b/prebid-mobile/recipes/subrecipes/android/nextgen-bidding-only-multiformat.md @@ -0,0 +1,267 @@ +--- +layout: page_v2 +title: Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative +description: Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative +sidebarType: 2 +--- + +# Android Next-Gen SDK Bidding-Only Integration - Multiformat Banner+Video+InAppNative + +Back to [Bidding-Only Integration](/prebid-mobile/pbm-api/android/android-sdk-integration-nextgen-original-api.html#adunit-specific-instructions) + +Starting with version `2.1.5` Prebid SDK supports the fully multiformat ad unit. It allows to run bid requests with any combination of `banner`, `video`, and `native` formats. + +The following code demonstrates the integration of multiformat ad unit. + +```kotlin +private fun createAd() { + // random() only for test cases, in production use only one config id + val configId = listOf(CONFIG_ID_BANNER, CONFIG_ID_VIDEO, CONFIG_ID_NATIVE).random() + + // Step 1: Create a PrebidAdUnit + prebidAdUnit = PrebidAdUnit(configId) + + // Step 2: Create PrebidRequest + val prebidRequest = PrebidRequest() + + // Step 3: Setup the parameters + prebidRequest.setBannerParameters(createBannerParameters()) + prebidRequest.setVideoParameters(createVideoParameters()) + prebidRequest.setNativeParameters(createNativeParameters()) + + // Step 4: Make a bid request + val requestBuilder = NativeAdRequest.Builder( + AD_UNIT_ID, + listOf(NativeAd.NativeAdType.NATIVE, NativeAd.NativeAdType.CUSTOM_NATIVE, NativeAd.NativeAdType.BANNER) + ).setCustomFormatIds(listOf(CUSTOM_FORMAT_ID)) + .setAdSizes(listOf(AdSize.BANNER, AdSize.MEDIUM_RECTANGLE)) + prebidAdUnit?.fetchDemand(requestBuilder, prebidRequest) { + + // Step 5: Load an Ad + loadAd(requestBuilder.build()) + } +} + +private fun createBannerParameters(): BannerParameters { + val parameters = BannerParameters() + parameters.api = listOf(Signals.Api.MRAID_3, Signals.Api.OMID_1) + + return parameters +} + +private fun createVideoParameters(): VideoParameters { + return VideoParameters(listOf("video/mp4")) +} + +private fun createNativeParameters(): NativeParameters { + val assets = mutableListOf() + + val title = NativeTitleAsset() + title.setLength(90) + title.isRequired = true + assets.add(title) + + val icon = NativeImageAsset(20, 20, 20, 20) + icon.imageType = NativeImageAsset.IMAGE_TYPE.ICON + icon.isRequired = true + assets.add(icon) + + val image = NativeImageAsset(200, 200, 200, 250) + image.imageType = NativeImageAsset.IMAGE_TYPE.MAIN + image.isRequired = true + assets.add(image) + + val data = NativeDataAsset() + data.len = 90 + data.dataType = NativeDataAsset.DATA_TYPE.SPONSORED + data.isRequired = true + assets.add(data) + + val body = NativeDataAsset() + body.isRequired = true + body.dataType = NativeDataAsset.DATA_TYPE.DESC + assets.add(body) + + val cta = NativeDataAsset() + cta.isRequired = true + cta.dataType = NativeDataAsset.DATA_TYPE.CTATEXT + assets.add(cta) + + val nativeParameters = NativeParameters(assets) + nativeParameters.addEventTracker( + NativeEventTracker( + NativeEventTracker.EVENT_TYPE.IMPRESSION, + arrayListOf(NativeEventTracker.EVENT_TRACKING_METHOD.IMAGE) + ) + ) + nativeParameters.setContextType(NativeAdUnit.CONTEXT_TYPE.SOCIAL_CENTRIC) + nativeParameters.setPlacementType(NativeAdUnit.PLACEMENTTYPE.CONTENT_FEED) + nativeParameters.setContextSubType(NativeAdUnit.CONTEXTSUBTYPE.GENERAL_SOCIAL) + + return nativeParameters +} +``` + +Load the ad and process the multiformat response using `NativeAdLoader`: + +```kotlin +private fun loadAd(request: NativeAdRequest) { + val adCallback = object : NativeAdLoaderCallback { + override fun onBannerAdLoaded(bannerAd: BannerAd) { + super.onBannerAdLoaded(bannerAd) + showBannerAd(bannerAd) + } + + override fun onNativeAdLoaded(nativeAd: NativeAd) { + super.onNativeAdLoaded(nativeAd) + showNativeAd(nativeAd, adWrapperView) + } + + override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) { + super.onCustomNativeAdLoaded(customNativeAd) + showPrebidNativeAd(customNativeAd) + } + + override fun onAdFailedToLoad(adError: LoadAdError) { + super.onAdFailedToLoad(adError) + Log.e(TAG, "Ad failed: $adError") + } + } + NativeAdLoader.load(request, adCallback) +} +``` + +The methods managing the Prebid and Next-Gen SDK ads: + +```kotlin +private fun showBannerAd(bannerAd: BannerAd) { + val adView = AdView(this) + adView.registerBannerAd(bannerAd, this) + adWrapperView.addView(adView) + AdViewUtils.findPrebidCreativeSize(adView, object : AdViewUtils.PbFindSizeListener { + override fun success(width: Int, height: Int) { + adView.resize(AdSize(width, height)) + } + + override fun failure(error: PbFindSizeError) {} + }) +} + +private fun showNativeAd(ad: NativeAd, wrapper: ViewGroup) { + val nativeContainer: NativeAdView = + View.inflate(wrapper.context, R.layout.layout_native, null) as NativeAdView + + val icon = nativeContainer.findViewById(R.id.imgIcon) + val iconUrl = ad.icon?.uri?.toString() + if (iconUrl != null) { + ImageUtils.download(iconUrl, icon) + } + + val title = nativeContainer.findViewById(R.id.tvTitle) + title.text = ad.headline + + val image = nativeContainer.findViewById(R.id.imgImage) + val imageUrl = ad.image?.uri?.toString() + if (imageUrl != null) { + ImageUtils.download(imageUrl, image) + } + + val description = nativeContainer.findViewById(R.id.tvDesc) + description.text = ad.body + + val cta = nativeContainer.findViewById

{{ page.title }}

{{ page.title }}

Features

Features

{{ page.title }}

{{ page.title }}

Note:

Note:

Note:

Features

Features

"Send All Bids" Ad Server Keys

"Send All Bids" Ad Server Keys

Notifications

No development required

Partners that work with Prebid

AppNexus

Microsoft

OpenX

PubMatic

Rubicon

Overview

Definitions

Assumptions

Summary of Prebid TCF 2.0 Enforcement

Basic-vs-Full Enforcement

Basic Enforcement

Full Enforcement (Prebid Server Only)

Prebid.js Functional Requirements

Prebid SDK Functional Requirements

Prebid Server Functional Requirements

Overview

Definitions

Assumptions

Summary of Prebid TCF 2.0 Enforcement

Basic-vs-Full Enforcement

Basic Enforcement

Full Enforcement (Prebid Server Only)

Prebid.js Functional Requirements

Prebid SDK Functional Requirements

Prebid Server Functional Requirements

Place this code in the page header.

Place this code in the page header.

Place this code in the page header.

Place this code in the page body.

Place this code in the page body.

Place this code in the page body.

Place this code in the page header.

Place this code in the page header.

Place this code in the page header.

Place this code in the page body.

Prebid Freewheel Integration Demo

{{ page.title }}

{{ page.title }}

Place this code in the page header.

Place this code in the page header.

Place this code in the page header.