diff --git a/dev-docs/modules/adChoices.md b/dev-docs/modules/adChoices.md new file mode 100644 index 0000000000..3fc314941c --- /dev/null +++ b/dev-docs/modules/adChoices.md @@ -0,0 +1,105 @@ +--- +layout: page_v2 +page_type: module +title: AdChoices Signal Module +description: Reads the DAA AdChoices Signal and conveys it in the OpenRTB bid stream as regs.ext.adchoices. +module_code: adChoices +display_name: AdChoices Signal Module +enable_download: true +recommended: false +min_js_version: 11.20.0 +sidebarType: 1 +--- + +# AdChoices Signal Module +{:.no_toc} + +* TOC +{:toc} + +## Overview + +This module reads the [DAA (Digital Advertising Alliance) AdChoices Signal](https://github.com/Digital-Advertising-Alliance/DAA-Choice-Tools/blob/main/AdChoices%20Signal/AdChoices%20Signal%20Specification.md) +and conveys it in the OpenRTB bid stream as the community extension +`regs.ext.adchoices`, as described in Appendix 5 of the specification. + +The AdChoices Signal is a base64url-encoded string that expresses a user's +interest-based advertising preferences. In the browser it can be read from the +DAA's [Protect My Choices (PMC)](https://github.com/Digital-Advertising-Alliance/DAA-Choice-Tools/blob/main/Protect%20My%20Choices/PMC2%20Overview.md) +extension, which exposes the signal via a `window.postMessage` protocol. When a +user does not have the extension installed, no signal is read and nothing is +added to the bid stream. + +Publishers who obtain the signal by other means (for example, reading the +`X-AdChoices` request header on their server) can supply it directly through the +module's `signal` configuration option instead of, or in addition to, the +extension read. + +When the signal is available it is added to every outgoing bid request: + +```json +{ + "regs": { + "ext": { + "adchoices": "" + } + } +} +``` + +## How it reads the signal + +When included, the module automatically begins listening for the signal from +the Protect My Choices extension using the documented message protocol: + +1. The extension posts an `ExtensionLoaded` message when it is ready. +2. The module requests the preferences by posting `{ type: "GetAdPreferences" }`. +3. The extension responds with an `AdPreferences` message whose `data` field + contains the AdChoices Signal string. + +The module also proactively sends a `GetAdPreferences` request on startup in +case the `ExtensionLoaded` message fired before the listener was attached. + +> Note: page JavaScript cannot read the `X-AdChoices` (Chrome) / `Cookie2` +> (Safari) headers that the extension injects into outbound requests — those are +> intended for server-side consumption. In the browser, the postMessage protocol +> (or the `signal` config option) is the supported way to obtain the value. + +## Configuration + +The module works with no configuration. To supply a static signal or to opt into +delaying auctions while the signal is read, use the `adChoices` config namespace: + +```javascript +pbjs.setConfig({ + adChoices: { + // Optional: a statically supplied AdChoices Signal. Takes precedence over a + // value read from the browser extension. + signal: 'AAEAA... (base64url signal)', + + // Optional: milliseconds to delay the first auction while waiting for the + // signal from the extension. Default 0 (non-blocking). + timeout: 0 + } +}); +``` + +{: .table .table-bordered .table-striped } +| Param | Scope | Type | Description | +|---|---|---|---| +| `signal` | optional | string | A statically supplied AdChoices Signal. When set, it is used as-is and takes precedence over any value read from the Protect My Choices extension. | +| `timeout` | optional | integer | Milliseconds to delay auctions while waiting for the signal from the extension. Defaults to `0` (non-blocking) so that users without the extension are not delayed. Set a positive value to delay the first auction until the signal is read or the timeout elapses. | + +## Build + +Add the module to your Prebid.js build: + +```bash +gulp build --modules=adChoices +``` + +## Related reading + +- [AdChoices Signal Specification](https://github.com/Digital-Advertising-Alliance/DAA-Choice-Tools/blob/main/AdChoices%20Signal/AdChoices%20Signal%20Specification.md) +- [Protect My Choices Overview](https://github.com/Digital-Advertising-Alliance/DAA-Choice-Tools/blob/main/Protect%20My%20Choices/PMC2%20Overview.md) +- [Protect My Choices Vendor Implementation](https://github.com/Digital-Advertising-Alliance/DAA-Choice-Tools/blob/main/Protect%20My%20Choices/PMC2%20Vendor%20Implementation.md)