AdChoices Signal Module

Overview

This module reads the DAA (Digital Advertising Alliance) AdChoices Signal 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) 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:

{
  "regs": {
    "ext": {
      "adchoices": "<AdChoices Signal string>"
    }
  }
}

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:

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
  }
});
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:

gulp build --modules=adChoices