⚙️Configuration

This section provides a detailed overview of the configuration files used in the Header Bidding wrapper.

How configuration works (read this first)

You don't program the wrapper — you configure it by editing settings files written in JSON. JSON is just a structured way of writing settings: names and values inside braces { }. A change to any of these files triggers an automatic rebuild and redeploy of the wrapper (see Glossary → Build).

There are four files, each with a job:

File

What it controls

config.json

Site-wide settings: identity, timeouts, bidding behaviour, privacy, refresh, ad-server (GAM) options. Most of this page.

adunits.json

Per-placement settings: one entry per ad unit (sizes, devices, bidders, refresh, formats).

deviceDetection.json

The screen-width rules that decide whether a visitor is desktop, tablet, mobile (or a custom tier).

modules.json

Which bidder adapters (demand partners) are included in the build.

A naming note that trips people up: many settings live under a dfp group (e.g. dfp.collapseEmptyDivs). "DFP" is the old name for Google Ad Manager (GAM) — read every dfp setting as "Google Ad Manager." The name was kept for backwards compatibility. Likewise, dfpAccount means your GAM account ID.

Each setting below is documented with its Description, whether it's Required, its Default where one exists, and an example. Unfamiliar with a term (CPM, bidder, S2S, SafeFrame, floor)? See the Glossary.

Before You Begin

Confirm GAM ad unit CODES and full paths
Align device detection names with deviceDetection.json
Decide targeting prefix and understand SafeFrames/S2S implications

Common Pitfalls

Using GAM ad unit NAME instead of CODE
Double quotes inside HTML data- JSON; prefer single quotes on attributes
Device labels mismatch between page and config

config.json

`id`

Description: An identification number used internally within the wrappers, not across different wrapper instances.

Required: Yes - Will throw an error if missing.

Notes: It must be an integer.

{
	"id" : 12345
}

`code`

Description: The identification name of the wrapper. It must be unique.

Required: Yes - Will throw an error if missing.

{
	"code" : "abc"
}

`file`

Description: The name of the file as hosted on the CDN. This is used to build, deploy, and purge. It must be unique.

Required: Yes - will not build without it

Notes: It is best practice for the file name to be lowercase.

{
	"file" : "prefix.code.js"
}

`blockAutoBuild`

Description: If true, it will not allow the wrapper to be automatically built.

Required: No - Optional.

{
	"blockAutoBuild" : true
}

`globalVar`

Description: The variable that Prebid will use. The wrapper uses a custom variable name for Prebid to avoid conflicts with other wrappers on the page.

Required: Yes - Will throw an error if missing.

{
	"globalVar" : "pbjs"
}

`targetingPrefix`

Description: Sets the prefix of targeting key-values used for sending bids to GAM. For example, [prefix]_bidder, [prefix]_hb, [prefix]_adid.

Required: No - Optional.

Important: If you use a custom prefix (not hb), anything related to Prebid Server and Safe Frames will be disabled.

{
	"targetingPrefix" : "chp"
}

`url`

Description: The URL to the site where the wrapper will be implemented.

Required: Yes - Has default value if not set.

Default: "https://example.com"

{
	"url" : "https://example.com"
}

`dfpAccount`

Description: The GAM account ID of the main account.

Required: Yes - Has default value if not set.

Default: "1234"

{
	"dfpAccount" : "123456789"
}

`dfpChildAccount`

Description: The GAM account ID of the child account. If this is set for an MCM network, it will use the GAM tags appropriate for MCM, using both the main and child account. Do not set it if it is not an MCM network.

Required: No - Optional.

{
	"dfpChildAccount" : "4567890123"
}

`adunitMapping`

Description: The method of mapping the div tags implemented in the page with the config built in the wrapper.

Required: Yes - Has default value if not set.

Default: "adunit"

Possible Values:

adunit: Matches based on adunit (data-aa-adunit of the div -> with the property adunit from adunits.json).
targeting: Matches based on a key targeting (data-aa-targeting of the div -> with the property targeting from adunits.json).

{
	"adunitMapping" : "adunit"
}

`adunitMappingKey`

Description: The name of the key-value that will be used for mapping. It only works when adunitMapping is targeting.

Required: No - Optional.

{
	"adunitMappingKey" : "location"
}

`gist`

Description: The URL to the location of tags that the publisher needs to implement on the page.

Required: No - Optional.

{
	"gist" : "https://gist.github.com/abc/123"
}

`analytics.clarity`

Description: To enable Clarity analytics, use the ID provided in the dashboard.

Required: No - Optional.

{
	"analytics" : {
		"clarity" : "4l37sx2uso"
	}
}

`analytics.gtm`

Description: Enables a GTM container.

Required: No - Optional.

Parameters:

containerId: The Google Tag Manager Container ID. Required; without this, the GTM container will not be loaded.
dataLayer: The name of the variable for Data Layer. Default is dataLayer; if not set, it will use the default.

{
	"analytics" : {
		"gtm" : {
			"containerId" : "GTM-ABCDE123",
			"dataLayer" : "customDataLayerVariable"
		}
	}
}

`analytics.prebid`

Description: Enables a Prebid analytics provider. Can take an array for multiple providers or an object for a single one.

Required: No - Optional.

{
	"analytics" : {
		"prebid" : [
                       {
                        "provider": "provider1Analytics",
                            "options": {
                                        "partnerId": 123
                            }
                       },
                       {
                        "provider": "provider2Analytics",
                            "options": {
                                        "partnerId": 123
                            }
                       }
                   ]
	}
}

`wrapper.timeout`

Description: The maximum time in milliseconds that the header bidding auction will wait for bids.

Required: Yes - Has default value if not set.

Default: 2000

{
	"wrapper" : {
		"timeout" : 2000
	}
}

`wrapper.conditionalTimeout`

Description: The maximum time in milliseconds that the header bidding auction will wait for bids for each device type (as defined in deviceDetection.json). It will overwrite the default timeout if the device is detected.

Required: No - Optional.

{
	"wrapper" : {
		"conditionalTimeout" : {
            "desktop": 2000,
            "tablet" : 1500,
            "mobile" : 1000
        }
	}
}

`wrapper.timeoutFallback`

Description: The maximum time in milliseconds that the wrapper will wait until it makes the GAM ad request.

Required: Yes - Has default value if not set.

Default: 5000

{
	"wrapper" : {
		"timeoutFallback" : 5000
	}
}

`wrapper.bidRequestWaitTime`

Description: The time in milliseconds that the processing of ads will be throttled to ensure all processing occurs simultaneously.

Required: Yes - Has default value if not set.

Default: 50

{
	"wrapper" : {
		"bidRequestWaitTime" : 50
	}
}

`wrapper.disableBidders`

Description: An array of bidder names that will be excluded from all auctions (completely disabled).

Required: Yes - Has default value if not set.

Default: [] (empty array)

{
	"wrapper" : {
		"disableBidders" : ["appnexus","pubmatic"]
	}
}

`wrapper.disableBiddersClientSide`

Description: An array of bidder names that will be excluded from all client-side auctions (they will still run in S2S).

Required: Yes - Has default value if not set.

Default: [] (empty array)

{
	"wrapper" : {
		"disableBiddersClientSide" : ["appnexus","pubmatic"]
	}
}

`wrapper.firstPartyData`

Description: When true, enables sending first-party data to the bid stream. Geo, IP, carrier, bot score, A/B bucket, and related fields are enriched into the ortb2 config used for bid requests.

Required: No - Optional.

Default: false

{
	"wrapper" : {
		"firstPartyData" : true
	}
}

`wrapper.geoFilter`

Description: Filters out bidders based on Geo Detection. Geo Detection is asynchronous and might resolve after the auction is initiated, so this functionality is not 100% guaranteed. The value is an object where each key is a bidder name.

Required: No - Optional.

Filter Options (for each bidder):

whitelist: Enables the bidder only for specified countries.
blacklist: Disables the bidder for specified countries.

Each option takes an array of country codes (ISO).

{
	"wrapper" : {
		"geoFilter" : {
			"33across" : {
				"whitelist" : ["US"],
				"blacklist" : []
			}
		}
	}
}

`wrapper.geoFilterUserId`

Description: Filters out User IDs based on Geo Detection. Geo Detection is asynchronous and might resolve after the User ID is initiated, so this functionality is not 100% guaranteed. The value is an object where each key is a User ID name.

Required: No - Optional.

Filter Options (for each User ID):

whitelist: Enables the User ID only for specified countries.
blacklist: Disables the User ID for specified countries.

Each option takes an array of country codes (ISO).

{
	"wrapper" : {
		"geoFilterUserId" : {
			"identityLink" : {
				"whitelist" : ["US","CA","AR","BR","MX","BE","FR","DE","IT"],
				"blacklist" : []
			}
		}
	}
}

`wrapper.patternBlocking`

Description: A feature to block the wrapper from executing based on URL, user agent, or geo country patterns. When a pattern matches, the wrapper will halt execution immediately. Each rule type (href, userAgent, geo) is enabled if its array exists and has at least one pattern.

Required: No - Optional.

Parameters:

href:
- Description: An array of patterns to match against the full page URL (window.location.href), including scheme, host, path, and query string. If this array exists and has length > 0, href pattern blocking is enabled.
- Possible Values:
  - Wildcard strings (e.g., *staging*, *example.com/admin/*, *legal/*). * matches any sequence of characters, ? matches a single character.
  - Regex strings, prefixed with regex: (e.g., regex:^https?://(dev|staging)\.example\.com/ or regex:/legal/).
- Common pitfalls (href):
  - Path-only patterns such as /legal/terms/, /admin/*, or legal/* usually do not match, because the value tested is the full URL (e.g. https://example.com/legal/terms/), not the pathname alone.
  - To block a path segment inside the URL, include * before and/or after the fragment: *legal/*, */legal/terms*, or *example.com/legal/*.
  - Wildcard patterns are converted to a full-string match (the entire href must match). Use regex: when you need substring matching without wrapping the pattern in *.
userAgent:
- Description: An array of patterns to match against the navigator.userAgent. If this array exists and has length > 0, user agent pattern blocking is enabled.
- Possible Values:
  - Wildcard strings (e.g., *bot*).
  - Regex strings, prefixed with regex: (e.g., regex:Puppeteer|Playwright).
geo:
- Description: An array of 2-letter country codes (ISO 3166-1 alpha-2) to block. If this array exists and has length > 0, geo pattern blocking is enabled. The wrapper will halt execution if the detected country matches any code in the array.
- Possible Values:
  - 2-letter country codes (e.g., "US", "CA", "GB", "FR", "DE").
- Notes:
  - Geo detection is asynchronous (happens after the wrapper loads).
  - When country is detected, the geo check is performed before any event handlers run.
  - If the detected country matches a blocked country, an error is thrown and execution stops completely.
  - If the country is not blocked, the wrapper proceeds normally.

Code Examples:

"wrapper": {
  "patternBlocking": {
    "href": [
      "*staging*",
      "*example.com/admin/*",
      "*legal/*",
      "regex:^https?://(dev|staging)\\.example\\.com/",
      "regex:/legal/(terms|privacy)"
    ],
    "userAgent": [
      "*bot*",
      "*Headless*",
      "regex:Puppeteer|Playwright|HeadlessChrome"
    ],
    "geo": [
      "US",
      "CA",
      "GB"
    ]
  }
}

Notes:

The href and userAgent checks are performed immediately at script load before any processing begins (synchronous).
The geo check is performed after the country is detected (asynchronous):
- Geo detection happens in the background after the wrapper loads
- Once the country is detected, the geo check runs in the callback before emitting any events
- If the country matches a blocked country, an error is thrown and execution halts completely
- If the country is not blocked, the wrapper proceeds normally
Each rule type is independently enabled based on the presence and length of its array.
Wildcard matching (for href and userAgent) is case-insensitive. Each wildcard pattern must match the entire href or userAgent string unless you use * so the pattern can span the full value (e.g. *legal/* on https://example.com/legal/terms/).
regex: patterns match as substrings (no automatic ^ / $ anchors). Add anchors in the regex when you need a full-string match.
For regex patterns, you can control flags within the pattern itself.
Country code matching is case-insensitive.
userAgent rules typically target bots and automation; normal browser user agents will not match unless you add patterns that match them (e.g. *google* matches Chrome on all pages).

`wrapper.trafficIntegrity`

Description: Traffic Integrity Score (TIS) — invalid traffic (IVT) scoring. When enabled, the wrapper asks a scoring endpoint how likely the current visit is to be non-human, and gets back a score from 0 to 100, where 100 means almost certainly bot traffic. A visit scoring at or above the threshold you set stops the wrapper from running any further auctions.

Unlike patternBlocking, this check is asynchronous — the wrapper does not wait for the answer before starting. See the Notes below for exactly what blocking can and cannot stop.

There is no endpoint setting. The URL is derived automatically from the analytics host already in use by the build, with /tis appended.

Required: No - Optional. The feature is off unless a block threshold is set, and no scoring request is made until then.

Parameters:

block:
- Description: The score at or above which the wrapper stops. This is the switch for the whole feature: with false there is nothing to act on, so the wrapper does not contact the endpoint at all.
- Possible Values: false, or a number between 0 and 100 (typically 50 or higher).
- Default: false (feature off).

block is the only setting.

Code Examples:

Block traffic scored 70 or above:

{
	"wrapper" : {
		"trafficIntegrity" : {
			"block" : 70
		}
	}
}

Off — the default. No scoring request is made:

{
	"wrapper" : {
		"trafficIntegrity" : {
			"block" : false
		}
	}
}

What gets sent: the site id and code, the page URL and referrer, the wrapper's pageview and session identifiers, and a small set of automation signals for the endpoint to score — whether the browser reports itself as automated, whether it claims to be Chrome without behaving like it, whether it has a language list and plugins, whether the window has a real size, and the user agent. No personal data is collected by the wrapper for this call, and no cookies are sent with it.

What blocking stops: when the score meets the threshold, the wrapper stops doing any further ad work — no processing, no bid requests, no GAM requests, and no refreshes.

Notes:

No block threshold means no request. Nothing is sent to the endpoint until a number is set.
The request is sent once per pageview, as early as possible — immediately after patternBlocking.
Because the check is asynchronous, the answer usually arrives before the first auction, but this is not guaranteed. Anything already in flight when the verdict arrives is allowed to finish; ads that have already rendered are left alone rather than being torn down.
The feature fails open. If the request fails or comes back malformed, nothing is blocked and the wrapper continues normally. A bad or unreachable endpoint can never take a site's ads down.
Be careful with very low thresholds: "block": 0 matches every possible score and will block all traffic.
Blocking is decided per pageview and is not remembered; nothing is written to cookies or local storage.

`wrapper.disableInitialProcessAdsOnPage`

Description: If true, it will disable any automatic processing of ads on page load.

Required: No - Optional.

{
	"wrapper" : {
		"disableInitialProcessAdsOnPage" : true
	}
}

`wrapper.prebidServer.enabled`

Description: Enables Prebid Server for Hybrid bidding (both Client and S2S).

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true
		}
	}
}

`wrapper.prebidServer.accountId`

Description: Prebid Server Account ID, if required by the Prebid Server.

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true,
			"accountId": "123"
		}
	}
}

`wrapper.prebidServer.endpoint`

Description: Updates the Prebid Server Endpoint. This is the URL endpoint for the auction.

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true,
			"accountId": "123",
            "endpoint": "https://prebid.mydomain.com/pbs/v1/openrtb2/auction"
		}
	}
}

`wrapper.prebidServer.syncEndpoint`

Description: Updates the Prebid Server Sync Endpoint. This is the URL endpoint for user synchronization.

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true,
			"accountId": "123",
            "endpoint": "https://prebid.mydomain.com/pbs/v1/openrtb2/auction",
            "syncEndpoint": "https://prebid.mydomain.com/pbs/v1/cookie_sync"
		}
	}
}

`wrapper.prebidServer.maxTimeout`

Description: Updates the Prebid Server Max Timeout. This is the maximum time allowed for the S2S auction to respond.

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true,
			"accountId": "123",
            "endpoint": "https://prebid.mydomain.com/pbs/v1/openrtb2/auction",
            "syncEndpoint": "https://prebid.mydomain.com/pbs/v1/cookie_sync",
            "maxTimeout": 1700
		}
	}
}

`wrapper.prebidServer.bidders`

Description: Updates the Prebid Server Bidders. This is the list of bidders that are allowed to run on S2S.

Required: No - Optional.

{
	"wrapper" : {
		"prebidServer" : {
			"enabled" : true,
			"accountId": "123",
            "endpoint": "https://prebid.mydomain.com/pbs/v1/openrtb2/auction",
            "syncEndpoint": "https://prebid.mydomain.com/pbs/v1/cookie_sync",
            "maxTimeout": 1700,
            "bidders": ["appnexus","sovrn","pubmatic","triplelift","openx"]
		}
	}
}

`bidAdjustments.pubshare`

Description: All header bidding bids will be adjusted with this value.

Required: Yes - Has default value if not set.

Default: 1

{
	"bidAdjustments" : {
		"pubshare" : 0.8
	}
}

`bidAdjustments.s2s`

Description: Header bidding bids received through Server 2 Server will be adjusted to this value.

Required: Yes - Has default value if not set.

Default: 1

{
	"bidAdjustments" : {
		"s2s" : 0.95
	}
}

`bidAdjustments.networks`

Description: Adjusts bids from individual networks. Each bid from the specified network will be multiplied by the adjustment factor.

Required: No - Optional.

{
	"bidAdjustments" : {
		"networks" : {
			"pubmatic" : 0.97,
			"districtm" : 0.9
		}
	}
}

`lazyLoading.preViewLength`

Description: The distance of the ads on the page, in pixels, from the active viewport when ads will be requested.

Required: Yes - Has default value if not set.

Default: 1000

{
	"lazyLoading" : {
		"preViewLength" : 1500
	}
}

`lazyLoading.preViewPorts`

Description: The distance of the ads on the page, in number of viewports, depending on the device, when ads will be requested. If set, this will overwrite lazyLoading.preViewLength.

Required: No - Optional.

{
	"lazyLoading" : {
		"preViewPorts" : 2
	}
}

`lazyLoading.scrollEventDelay`

Description: The time in milliseconds that the scroll event is throttled to mitigate latency.

Required: Yes - Has default value if not set.

Default: 400

{
	"lazyLoading" : {
		"scrollEventDelay" : 400
	}
}

`targeting.refreshIteration`

Description: The name of the key-value used to count refreshes.

Required: No - Optional.

{
	"targeting" : {
		"refreshIteration" : "refresh_count"
	}
}

`targeting.refreshedInventory`

Description: The name of the key-value used to mark if the inventory is refreshed or not.

Required: No - Optional.

{
	"targeting" : {
		"refreshedInventory" : "refreshed"
	}
}

`targeting.refreshedAccelerateSeconds`

Description: If enabled, it will set a key-value representing the seconds that the refresh was accelerated with.

Required: No - Optional.

{
	"targeting" : {
		"refreshedAccelerateSeconds" : true
	}
}

`targeting.speed`

Description: If true, it sends key-values related to speed.

Required: No - Optional.

Key-Values:

wrap_l: The load time of the wrapper (relative to page navigation).
gpt_l: The load time of the googletag library (relative to wrapper load time).
page_r: The load time of the page (relative to wrapper load time).
waai: The time until the auction initiated (relative to wrapper load time), tracked only for the first auction.
waae: The time until the auction ended (relative to auction init).
wabt: The bidders that timeout (relative to what Prebid detects as timeout).
wabtr: The bidders that timeout by not sending a bid until the GAM ad request is made.
cndl: Connection DownLink.
- 0: Unknown.
- 0.1: Under 1MB.
- 1: 1-9.99 MB.
- 10: 10-99.99 MB.
- 100: 100-999.99 MB.
- 1000: >= 1000 MB.
cnrtt: Connection RTT.
- 0: Unknown.
- 10: <= 10ms.
- 100: <= 100ms.
- 900: <= 900ms.
- 1000: >= 1000ms.
cntp: Connection Type. Possible values: na, bluetooth, cellular, ethernet, none, wifi, wimax, other, unknown.
cnet: Connection Effective Type. Possible values: na, slow-2g, 2g, 3g, 4g, 5g.
cnsd: Connection Save Data. Possible values: true, false.

Default: true

`targeting.pageAdDensity`

Description: If true, it sends key-values related to Page Ad Density.

Required: No - Optional.

Key-Values:

padpr (Page Ad Density PreRequest): Represents ad density before requests based on the biggest ad size available.
pad (Page Ad Density): Represents ad density after ads have been rendered.

Default: true

{
	"targeting" : {
		"pageAdDensity" : true
	}
}

`targeting.utmKeyValues`

Description: If true, it sends key-values related to UTM values.

Required: No - Optional.

Key-Values:

utm_source
utm_medium
utm_campaign
utm_content

Default: true

{
	"targeting" : {
		"utmKeyValues" : true
	}
}

`targeting.uids`

Description: If true, it sends key-values related to User Identification Services/Providers.

Required: No - Optional.

Key-Values:

uids: Sends the value of each User ID Service/Provider that identifies a user.
uids_c: Sends the count of all User ID Services that identified a user.
Individual key-value for each User ID Service/Provider: Sets a key with the name of the User ID Service/Provider.

Default: false

{
	"targeting" : {
		"uids" : true
	}
}

`targeting.topicsapi`

Description: If true, it sends key-values with the values from Topics API interests.

Required: No - Optional.

Notes: The topicsFpdModule must be added as it is not included by default anymore.

{
	"targeting" : {
		"topicsapi" : true
	}
}

`targeting.gads`

Description: If true, it sends key-values indicating whether the GAM cookie gads is set.

Required: No - Optional.

{
	"targeting" : {
		"gads" : true
	}
}

`targeting.cookieEnabled`

Description: If true, it sends key-values indicating whether the browser allows third-party cookies.

Required: No - Optional.

{
	"targeting" : {
		"cookieEnabled" : true
	}
}

`targeting.browserLangCode`

Description: If true, it sends key-values related to the user's language as set up in the browser.

Required: No - Optional.

{
	"targeting" : {
		"browserLangCode" : true
	}
}

`targeting.referrer`

Description: If true, it sends key-values related to the referrer domain.

Required: No - Optional.

{
	"targeting" : {
		"referrer" : true
	}
}

`targeting.domain`

Description: If true, it sends key-values related to the domain where the wrapper is loaded.

Required: No - Optional.

{
	"targeting" : {
		"domain" : true
	}
}

`targeting.code`

Description: If true, it sends the key-value wrapCode related to the wrapper code.

Required: No - Optional.

{
	"targeting" : {
		"code" : true
	}
}

`targeting.id`

Description: If true, it sends the key-value wrapId related to the wrapper ID.

Required: No - Optional.

{
	"targeting" : {
		"id" : true
	}
}

`targeting.prerendering`

Description: If true, it sends the key-value prst related to the prerendering state of the page.

Required: No - Optional.

Key-Value Definition:

Key

Possible Values

Description

prst

no

The page is not prerendered.

before

The page is prerendering but not activated yet.

after

The page was prerendered and is now activated.

References:

Default: false

{
	"targeting" : {
		"prerendering" : true
	}
}

`targeting.pageNavigationType`

Description: If true, it sends the key-value pnType related to the page navigation type.

Required: No - Optional.

Key-Value Definition:

Key

Possible Values

Description

pnType

reload

Page was reloaded/refreshed.

push

New navigation entry (normal navigation).

replace

Current entry was replaced.

traverse

Navigation through history (back/forward).

navigate

Normal navigation (clicking a link, typing a URL, etc.).

back_forward

Navigation via browser back/forward buttons.

prerender

Page was prerendered.

reserved

Reserved value.

unknown

When navigation type cannot be determined.

Default: false

{
	"targeting" : {
		"pageNavigationType" : true
	}
}

`targeting.device`

Description: If true, it sends key-values related to the device detected from the browser user agent.

Required: No - Optional.

{
	"targeting" : {
		"device" : true
	}
}

`targeting.browser`

Description: If true, it sends key-values related to the browser detected from the browser user agent.

Required: No - Optional.

{
	"targeting" : {
		"browser" : true
	}
}

`targeting.os`

Description: If true, it sends key-values related to the operating system detected from the browser user agent.

Required: No - Optional.

{
	"targeting" : {
		"os" : true
	}
}

`abtests.uids`

Description: Enables A/B testing for User IDs. When a User Identification Service/Provider identifies a user, it splits the traffic 50/50: half the time it sends the User ID to networks, and half the time it does not. The key-values sent to GAM will be nameOfUserID+test, with values true (User ID sent to network), false (User ID not sent to network), or na (User ID not identified).

Required: No - Optional.

{
	"abtests" : {
		"uids" : ["idl_env","lipb","lotamePanoramaId","id5id","33acrossId","teadsId","fabrickId"]
	}
}

`refresh.gamStrategy`

Description: Chooses how Google Ad Manager (GAM) loads the next ad when a placement refreshes.

Status: Experimental — not tested in production. Prefer the default unless you are deliberately evaluating this option.

Required: No - Optional.

Default: Classic refresh behaviour (same as "refresh"). Omit the setting, or set "refresh", to keep current behaviour.

Valid Values:

"refresh" — Ask GAM to refresh the existing ad slot (the usual approach).
"redefine" — Remove the slot and create it again for each refresh, then load a new ad into that new slot.

In plain terms: With "refresh", the same GAM slot is reused and told to fetch another ad. With "redefine", the wrapper tears that slot down and builds a fresh one, then fills it. Refresh timers, viewability rules, and refresh limits still work the same way. Refresh counts and related key-values (for example whether the inventory is refreshed, and advertiser history) are preserved across the recreate so reporting stays consistent.

Notes:

Out-of-page (interstitial / overlay) placements always stay on classic refresh, even when "redefine" is set.
If the page element for a slot is missing, that slot also stays on classic refresh so it is not lost.
When "redefine" is on, the creative area is emptied briefly while the new slot is created. If you use dfp.failedToFetchFallback, consider a longer wait via dfp.failedToFetchFallbackRedefine so a fallback creative does not appear too early while GAM is still loading.

{
	"refresh" : {
		"gamStrategy" : "refresh"
	}
}

{
	"refresh" : {
		"gamStrategy" : "redefine"
	}
}

`refresh.stopAdvertisers`

Description: An array of GAM advertiser/company IDs that will stop the refresh after an impression from them is displayed.

Required: Yes - Has default value if not set.

Default: [] (empty array)

Notes: Values must be numeric, not strings.

{
	"refresh" : {
		"stopAdvertisers" : []
	}
}

`refresh.pauseOutOfFocus`

Description: When true, it will not refresh until the page is in focus.

Required: No - Optional.

{
	"refresh" : {
		"pauseOutOfFocus" : false
	}
}

`refresh.pauseOutOfView`

Description: Pauses refresh when the adunit is out of view.

Required: No - Optional.

Properties:

threshold: A float from 0 to 1. It will refresh only when the ad is in the active viewport. The value represents the threshold; 0 represents one pixel, 1 represents all pixels of the element.
adunits: An array of strings representing adunits that pauseOutOfView will apply to. It also accepts the wildcard * for all adunits.

{
	"refresh" : {
		"pauseOutOfView" : {
			"threshold" : 1,
			"adunits" : ["*"]
		}
	}
}

{
	"refresh" : {
		"pauseOutOfView" : {
			"threshold" : 0,
			"adunits" : ["/123/AdUnit1","/123/AdUnit2"]
		}
	}
}

`refresh.maxLimit`

Description: The maximum number of refreshes allowed for an adunit. The refresh counter starts at 0 for the initial load and increments with each refresh.

Notes: Applies to timed refresh and to viewable refresh (GAM or wrapper viewability provider).

Required: No - Optional.

Valid Values:

false: Disables this limit (no maximum refresh limit)
0: No refreshes allowed (ad will not refresh)
1 or higher: Number of refreshes allowed before stopping

{
	"refresh" : {
		"maxLimit" : 100
	}
}

`refresh.maxEmpty`

Description: The maximum number of empty responses from GAM before stopping refreshes. The empty counter starts at 0 and increments each time GAM returns an empty response. Refreshes will stop when the count reaches this limit.

Notes: This limit is evaluated when scheduling refreshes for timed refresh (refreshTimed) and for viewable refresh when refresh.viewabilityProvider is wrapper. (Counters are still driven by GAM slot lifecycle events.)

Required: No - Optional.

Valid Values:

false or 0: Disables this limit (refreshes continue regardless of empty responses)
1 or higher: Number of empty responses tolerated before stopping refreshes
Setting to 1 means "stop after the first empty response"

{
	"refresh" : {
		"maxEmpty" : 100
	}
}

`refresh.maxConsecutiveEmpty`

Description: The maximum number of consecutive empty responses from GAM before stopping refreshes. The consecutive empty counter starts at 0 and increments each time GAM returns an empty response, but resets to 0 when a non-empty response is received. Refreshes will stop when consecutive empties reach this limit.

Notes: Same scope as refresh.maxEmpty: enforced for timed refresh and for viewable refresh when refresh.viewabilityProvider is wrapper.

Required: No - Optional.

Valid Values:

false or 0: Disables this limit (refreshes continue regardless of consecutive empty responses)
1 or higher: Number of consecutive empty responses tolerated before stopping refreshes
Setting to 1 means "stop after the first empty response"

{
	"refresh" : {
		"maxConsecutiveEmpty" : 100
	}
}

`refresh.forceRefreshRateForAdvertiser`

Description: Changes the refresh rate for a specific GAM advertiser/company. Takes an array of objects with advertiserId and refreshRate properties.

Required: Yes - Has default value if not set.

Default: [] (empty array)

{
	"refresh" : {
		"forceRefreshRateForAdvertiser" : [
			{"advertiserId": 4721606053, "refreshRate":30},
			{"advertiserId": 4607025053, "refreshRate":30},
			{"advertiserId": 4607025017, "refreshRate":30},
			{"advertiserId": 4805864332, "refreshRate":30},
			{"advertiserId": 4805864332, "refreshRate":30}
		]
	}
}

`refresh.accelerate`

Description: Accelerates refresh by reducing the refresh time by a specific number of seconds if the estimated CPM is higher than the specified value. Takes an array of objects with estCPM and seconds properties.

Required: No - Optional.

{
	"refresh" : {
		"accelerate" : [
		      {"estCPM": 1, "seconds": 3},
		      {"estCPM": 1.5, "seconds": 5},
		      {"estCPM": 2, "seconds": 10},
		      {"estCPM": 2.5, "seconds": 15}
		]
	}
}

`refresh.continueOnEmpty`

Description: Applies only to viewable refresh. If GAM returns an empty response, and viewable refresh is enabled, refresh will not stop. A one-time refresh is scheduled with the same refresh rate as the viewable one, effectively transforming the next viewable refresh into a timed refresh.

Required: No - Optional.

Notes:

refresh.maxLimit, refresh.maxEmpty, refresh.maxConsecutiveEmpty apply. Refreshes will be counted and will stop if any limit is reached.
refresh.accelerate applies. The refresh is accelerated if there is a bid according to settings.
refresh.pauseOutOfFocus applies; if enabled, it will not refresh while the tab is out of focus.
refresh.stopAdvertisers and refresh.forceRefreshRateForAdvertiser do not apply if the response is empty as there is no advertiser.

{
	"refresh" : {
		"continueOnEmpty" : true
	}
}

`refresh.viewabilityProvider`

Description: Defines the viewability provider for refresh.

Required: No - Optional.

Possible Values:

gam: Uses the GAM viewability event (impressionViewable) to schedule the next viewable refresh.
wrapper: Uses the wrapper’s internal viewability detection (IntersectionObserver: at least 50% of the slot element in view for one second) to schedule the next viewable refresh.

Notes (wrapper provider): When wrapper is selected, scheduling the next viewable refresh applies the same caps as other refresh paths: refresh.maxLimit, refresh.maxEmpty, and refresh.maxConsecutiveEmpty, plus refresh.accelerate, refresh.stopAdvertisers, and refresh.forceRefreshRateForAdvertiser when response/advertiser information is available from the slot.

{
	"refresh" : {
		"viewabilityProvider" : "wrapper"
	}
}

`deviceDetection`

Description: The method of detecting the size of the site.

Required: Yes - Has default value if not set.

Default: "window"

Possible Values:

window: Detects the size of the window/tab (if the window is resized or the tag is inside an iframe and cannot access the top window, it will detect that size).
screen: Detects the screen size, not taking into account the actual window/tab.

{
	"deviceDetection" : "window"
}

`dfp.collapseEmptyDivs`

Description: If GAM has an empty response, collapses the size of the divs.

Required: No - Optional.

{
	"dfp" : {
		"collapseEmptyDivs" : false
	}
}

`dfp.emptyCreativeFallback`

Description: If GAM has an empty response but there is a header bidding bid, delivers the ad without GAM.

Required: No - Optional.

{
	"dfp" : {
		"emptyCreativeFallback" : true
	}
}

`dfp.failedToFetchFallback`

Description: After a specific amount of time, adunits are checked if GAM displayed an ad. If not and there are Header Bidding bids available, delivers the ad without GAM.

Required: No - Optional.

{
	"dfp" : {
		"failedToFetchFallback" : 3000
	}
}

`dfp.failedToFetchFallbackRedefine`

Description: Extra wait (in milliseconds) used with refresh.gamStrategy: "redefine" when dfp.failedToFetchFallback is enabled. Redefine clears the slot sooner than classic refresh, so a longer check helps avoid showing a fallback while GAM is still responding. The effective wait is the larger of this value and dfp.failedToFetchFallback.

Status: Experimental — intended for use with refresh.gamStrategy: "redefine", which is not tested in production.

Required: No - Optional.

Default: 5000 (only applied when redefine strategy is active)

{
	"dfp" : {
		"failedToFetchFallback" : 3000,
		"failedToFetchFallbackRedefine" : 5000
	}
}

`dfp.houseFallback`

Description: Specifies creatives to serve in case there is no demand from GAM or Prebid. Requires dfp.emptyCreativeFallback or dfp.failedToFetchFallback to be enabled. The value is an object where keys are sizes and values are the HTML creative. It will deliver the creative corresponding to the size of the adunit. If the adunit has multiple sizes and multiple creatives are available, one will be randomly selected.

Required: No - Optional.

{
	"dfp" : {
		"emptyCreativeFallback": true,
        "failedToFetchFallback": 3000,
		"houseFallback":{
			"300x250" : "<!-- this is a house 300x250 -->",
			"336x280" : "<!-- this is a house 336x280 -->",
			"728x90" : "<!-- this is a house 728x90 -->",
			"468x60" : "<!-- this is a house 468x60 -->",
			"970x90" : "<!-- this is a house 970x90 -->",
			"970x250" : "<!-- this is a house 970x250 -->",
			"300x600" : "<!-- this is a house 300x600 -->",
			"320x50" : "<!-- this is a house 320x50 -->",
			"320x100" : "<!-- this is a house 320x100 -->"
		}
	}
}

`dfp.forceSafeFramesUnderFloor`

Description: Enables GAM's SafeFrames if the Header Bidding bid is under the floor.

Required: No - Optional.

Notes: If enabled, it will disable Amazon and bidders that are not compatible with Safe Frames.

{
	"dfp" : {
		"forceSafeFramesUnderFloor" : 2.1
	}
}

`dfp.forceSafeFramesForAdunits`

Description: Enables GAM's SafeFrames on specific adunits. The full adunit path must be specified.

Required: No - Optional.

Notes: If enabled, it will disable Amazon for the adunits it is enabled for. It will also disable bidders that are not compatible with Safe Frames.

{
	"dfp" : {
		"forceSafeFramesForAdunits" : ["/123/AdUnit1","/123/AdUnit2"]
	}
}

`dfp.forceSafeFrames`

Description: If true, it will enable GAM's SafeFrames.

Required: No - Optional.

Notes: If enabled, it will disable Amazon and bidders that are not compatible with Safe Frames.

{
	"dfp" : {
		"forceSafeFrames" : true
	}
}

`dfp.flexibleSafeFramesSignal`

Description: [NEW INNOVATIVE FEATURE] An industry-first solution for granular SafeFrame control at the impression level. Instead of forcing SafeFrames on all inventory (which limits bidder participation and monetization), Flexible Safe Frames Signal provides intelligent, bid-level control by setting the hb_sframe key-value based on winning bid characteristics. This revolutionary approach allows publishers to:

Required: No - Optional.

Maximize Revenue: Only apply SafeFrames when needed, keeping high-performing bidders active on most inventory
Surgical Precision: Target specific bidders, advertiser domains, categories, or ad units
Risk Management: Protect sensitive inventory or high-value pages with granular SafeFrame rules
Enhanced Reporting: Track which impressions are served within SafeFrames via the hb_sframe key-value
Smart Optimization: Different SafeFrame strategies for different inventory segments

When enabled, the module sets the hb_sframe key-value for every impression. All conditions are evaluated with OR logic - if ANY condition matches, the signal is set to 1, otherwise 0. When disabled, no key-value is set.

Parameters:

enabled (boolean, required): Set to true to activate the module and start setting the hb_sframe key-value. When false or not set, the module is inactive and no key-value is set.
bidders: Array of bidder codes. Enables SafeFrames for specific bidders (e.g., protect against specific SSPs).
adomains: Array of advertiser domains. Enables SafeFrames for specific advertisers (e.g., competitor exclusion or brand safety).
acats: Array of IAB category codes. Enables SafeFrames for specific ad categories (e.g., sensitive verticals).
adunits: Array of GAM ad unit paths. Enables SafeFrames for specific inventory locations (e.g., homepage only).

Output: When enabled, sets the hb_sframe key-value to 1 (SafeFrames recommended) or 0 (standard rendering) for every impression. When disabled, no key-value is set.

Use Cases:

Brand Safety: "Enable SafeFrames for specific advertiser domains or sensitive categories"
Selective Enforcement: "Enable SafeFrames only on homepage and article pages, not in-feed inventory"
Bidder Management: "Enable SafeFrames for specific bidders with compliance concerns"
Category Control: "Enable SafeFrames for sensitive content categories requiring additional protection"

Default: Not configured (feature inactive)

Code Examples:

// Example 1: Enable SafeFrames for specific bidders
{
	"dfp" : {
		"flexibleSafeFramesSignal" : {
			"enabled": true,
			"bidders": ["rubicon", "appnexus", "pubmatic"]
		}
	}
}

// Example 2: Enable SafeFrames for specific advertiser domains
{
	"dfp" : {
		"flexibleSafeFramesSignal" : {
			"enabled": true,
			"adomains": ["competitor.com", "sensitive-advertiser.com"]
		}
	}
}

// Example 3: Enable SafeFrames for sensitive categories
{
	"dfp" : {
		"flexibleSafeFramesSignal" : {
			"enabled": true,
			"acats": ["IAB7-39", "IAB8-18", "IAB23"]
		}
	}
}

// Example 4: Enable SafeFrames for specific ad units
{
	"dfp" : {
		"flexibleSafeFramesSignal" : {
			"enabled": true,
			"adunits": ["/21833886396/homepage/leaderboard", "/21833886396/article/sidebar"]
		}
	}
}

// Example 5: Combined conditions (any match triggers SafeFrames)
{
	"dfp" : {
		"flexibleSafeFramesSignal" : {
			"enabled": true,
			"bidders": ["rubicon"],
			"adomains": ["competitor.com"],
			"acats": ["IAB7-39"],
			"adunits": ["/21833886396/homepage/leaderboard"]
		}
	}
}

Notes:

Set enabled: true to activate the module; when disabled or not set, no key-value is set
All conditions use OR logic - if ANY condition matches, hb_sframe is set to 1
The key-value is set at the slot level for each ad impression
Can be used with GAM creative templates or line item targeting for conditional SafeFrame rendering
Compatible with all header bidding demand sources and GAM features
Does not automatically disable bidders (unlike global SafeFrame settings)

`prebid`

Description: Prebid configuration.

Required: No - Optional.

Reference: Prebid documentation setConfig

{
	"prebid" : {
	    "priceGranularity" : {
	        "buckets": [
	                    {
                            "precision": 2,
                            "max": 20,
                            "increment": 0.01
	                    }
	                ]
	    },
	    "schain": {
	    	"validation": "strict",
	    	"config": {
				"ver":"1.0",
				"complete": 1,
				"nodes": [{ "asi":"network.com", "sid":"abc123", "hp":1 }]
			}
		}
	}
}

`prebid.bidCaching`

Description: Stores bids to be reused in future auctions. If false, it is disabled.

Required: No - Optional.

Properties:

maxLength: The maximum size of the bid in bytes, to prevent bids with very large creatives.
floor: Stores only bids above this CPM.

{
	"prebid" : {
		"bidCaching" : {
	    	"maxLength": 100000,
	    	"floor": 0.10
	    }
	}
}

`prebid.floors` dynamic schema fields from `ortb2` (wrapper extension)

Description: When the Price Floors module is enabled and prebid.floors.data.schema.fields includes one or more supported dynamic fields Values are resolved from current ortb2 and matched case-insensitively.

If a value is not available, the wrapper returns * so Price Floors can match wildcard/default rules.

Required: No - Optional (works only when Price Floors is configured).

Works only if:

Price Floors module is enabled and has prebid.floors.data.schema.fields.
For country, region, city, os, browser: those values exist in ortb2 (typically via wrapper.firstPartyData: true, or another source that sets ortb2 before auction).
For eids: user IDs are available in ortb2.user.ext.eids (typically when userSync.userIds is configured and IDs are present).

Supported dynamic schema fields:

country -> ortb2.device.geo.country (alpha-2 or alpha-3; normalized to lowercase alpha-3 for matching)
region -> ortb2.device.geo.region
city -> ortb2.device.geo.city
os -> ortb2.device.sua.platform.brand (operating system / platform brand)
browser -> primary browser from ortb2.device.sua.browsers[0].brand
eids -> ortb2.user.ext.eids[].source (see matching below)

Normalization behavior:

All extracted scalar values are lowercased.
country rule keys accept alpha-2 or alpha-3 and are normalized to lowercase alpha-3.
eids sources are normalized to a sorted, deduplicated list; at match time the wrapper returns a single source token for Price Floors exact matching.
Rule matching stays case-insensitive.

eids matching: A floor rule matches when any source listed in the rule’s eids segment (comma-separated) is present in the auction’s ortb2.user.ext.eids list. Example: rule pubcid.org matches an auction with eids id5-sync.com,pubcid.org.

Warning: Rule order matters for eids when multiple rules could match. When a user has more than one EID source and separate floor rules exist for each source, the first matching rule in the values object wins — not the highest floor value. Place higher-priority rules earlier in the values map to control which floor is applied.
Example: A user has eids ["id5-sync.com", "pubcid.org"] and the config is:
"values": {
  "usa|pubcid.org":   19,
  "usa|id5-sync.com": 20
}
The floor applied will be 19 (usa|pubcid.org) because that rule appears first, even though usa|id5-sync.com has a higher value. To ensure the higher floor is applied, place the higher-valued rule first:
"values": {
  "usa|id5-sync.com": 20,
  "usa|pubcid.org":   19
}

Example: single dynamic schema field (`country`)

{
  "wrapper": {
    "firstPartyData": true
  },
  "prebid": {
    "floors": {
      "data": {
        "currency": "USD",
        "schema": {
          "fields": ["country"]
        },
        "values": {
          "rou": 1.0,
          "deu": 0.8
        },
        "default": 0.1
      }
    }
  }
}

Example: multiple dynamic schema fields

{
  "prebid": {
    "floors": {
      "data": {
        "currency": "USD",
        "schema": {
          "fields": ["country", "os"]
        },
        "values": {
          "rou|windows": 1.2,
          "rou|android": 0.9,
          "*|*": 0.1
        }
      }
    }
  }
}

Example: combine Prebid native + wrapper dynamic schema fields

{
  "prebid": {
    "floors": {
      "data": {
        "currency": "USD",
        "schema": {
          "fields": ["mediaType", "size", "country"]
        },
        "values": {
          "banner|300x250|rou": 1.5,
          "banner|*|*": 0.4,
          "*|*|*": 0.1
        }
      }
    }
  }
}

`userSync.triggerAction`

Description: Defines the user interaction that will trigger a user sync.

Required: No - Optional.

Possible Values: scroll, click, idle, timed.

{
  "userSync": {
    "triggerAction": "click"
  }
}

`userSync.triggerDelay`

Description: Delay (in milliseconds) after the triggerAction occurs before initiating user sync.

Required: No - Optional.

{
  "userSync": {
    "triggerDelay": 2000
  }
}

`prebidBidderSpecific`

Description: Prebid configuration for specific bidders. Can take an array for multiple bidders or an object for a single one.

Required: No - Optional.

Reference: Prebid documentation setBidderConfig

{
    "prebidBidderSpecific" : [
    	{
        	"bidders" : ["rubicon","pubmatic"],
        	"config" : {
    		    "schain": {
    		    	"validation": "strict",
    		    	"config": {
    					"ver":"1.0",
    					"complete": 1,
    					"nodes": [{ "asi":"network.com", "sid":"abc123", "hp":1 }]
    				}
    			}
        	}
        },
    	{
        	"bidders" : ["gourmetads"],
        	"config" : {
    		    "schain": {
    		    	"validation": "strict",
    		    	"config": {
    					"ver":"1.0",
    					"complete": 1,
    					"nodes": [{ "asi":"othernetwork.com", "sid":"cdf345", "hp":1 }]
    				}
    			}
        	}
        }
    ]
}

`amazon`

Description: Configures the Amazon/A9 wrapper.

Required: No - Optional.

Properties:

enabled: Enables/disables the wrapper.
pubID: The Amazon ID, from the AM or Dashboard.
adServer: The ad server.

{
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag"
	}
}

`amazon.declareRefresh`

Description: Optional parameter for Amazon/A9 Config that will send the adRefresh parameter as configuration.

Required: No - Optional.

Reference: Amazon/A9 Config documentation

Possible Values:

true: Sends adRefresh to 0 for initial requests and 1 for refresh requests.
false: Does not send adRefresh at all.

{
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag",
	    "declareRefresh" : true
	}
}

`amazon.schain`

Description: Optional parameter for Amazon/A9 Config that will send the schain parameter as configuration.

Required: No - Optional.

Reference: Schain Object

Notes: The object passed will be assigned to the schain property of the Amazon configuration.

Code Examples:

{
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag",
	    "schain" : {
           "ver":"1.0",
           "complete": 1,
           "nodes": [{ "asi":"example.com", "sid":"1234", "hp":1 }]
        }
	}
}

`amazon.timeout`

Description: Sets a custom timeout for Amazon/A9 bid requests in milliseconds. When configured, Amazon will use this timeout value independently from the Prebid/wrapper timeout. This allows you to optimize Amazon's bidding window separately from other header bidding partners.

Required: No - Optional.

How It Works:

If set to a valid number (greater than 0), Amazon will use this custom timeout for bid requests
If set to false, 0, or not included, Amazon will use the default Prebid/wrapper timeout
The timeout applies to both the Amazon fetchBids call and the wrapper's internal fallback mechanism
When a custom timeout is set, a log message will indicate that Amazon is using a custom timeout value

Use Cases:

Give Amazon more time to respond when they historically return slower but valuable bids
Reduce Amazon's timeout when you need faster page loads and Amazon responds quickly
Test different timeout strategies for Amazon independently from other bidders

Valid Values:

false: Use default Prebid timeout (default behavior)
0: Use default Prebid timeout (same as false)
Any positive number: Custom timeout in milliseconds (e.g., 1500, 2500)

Default: false (uses Prebid/wrapper timeout)

Code Examples:

// Example 1: Amazon uses custom 1500ms timeout (Prebid uses default 2000ms)
{
	"wrapper": {
		"timeout": 2000
	},
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag",
	    "timeout": 1500
	}
}

// Example 2: Amazon uses default Prebid timeout (2000ms)
{
	"wrapper": {
		"timeout": 2000
	},
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag",
	    "timeout": false
	}
}

// Example 3: Give Amazon extra time (2500ms) while other bidders use 2000ms
{
	"wrapper": {
		"timeout": 2000
	},
	"amazon" : {
    	"enabled" : true,
	    "pubID": "123",
	    "adServer": "googletag",
	    "timeout": 2500,
	    "declareRefresh": true
	}
}

Notes:

Amazon's timeout is independent from Prebid's timeout
If Amazon times out, the auction will continue and ads will render normally
The wrapper includes a safety mechanism to ensure ads render even if Amazon fails or times out
When amazon.timeout is set, you'll see a log message: __ A9/Amazon : Using custom timeout: [value]

`forceReWrittingPBJS`

Description: If true, it clones the Prebid global variable as pbjs to avoid conflicts with GAM creatives. When there are multiple instances of Prebid on the page, this must be disabled.

Required: No - Optional.

{
	"forceReWrittingPBJS" : true
}

`debug`

Description: Sets the wrapper's built-in logging level for the browser console. Turning this on in the config makes the wrapper log its activity for every visitor, which is useful in staging but should normally be left off in production (use the per-visitor URL flags in Troubleshooting instead). Setting it to 'details' enables verbose, opt-in logging.

Required: No - Optional.

Possible Values:

true: Standard debug logging.
'details': Verbose logging (equivalent to the [globalVar]_debug=DETAILS URL flag).
false or omitted: No debug logging (default).

{
	"debug" : "details"
}

adunits.json

Description: This file contains settings individually for each adunit of the wrapper.

Notes:

Each entry is an adunit.
Cannot have multiple adunits mapped to the same div.
You can have multiple divs mapped to the same adunit.

Each adunit has the following properties:

`adunit`

Description: The GAM adunit path.

{
	"adunit" : "/123/abc"
}

`device`

Description: An array of devices (as defined in deviceDetection.json) where the adunit will display.

{
	 "device": ["bigDesktop","desktop","tablet"]
}

`mediaTypes`

Description: MediaTypes in the format accepted by Prebid.

Reference: Prebid documentation AdUnit Reference

{
	"mediaTypes" : {"banner" : {"sizes" : [[728,90],[970,90],[970,250],[728,250]] }}
}

`conditionalMediaTypes`

Description: MediaTypes for each device type (as defined in deviceDetection.json). It will overwrite the default MediaTypes if the device is detected.

{
	"conditionalMediaTypes" : {
        "bigDesktop":       {"banner" : {"sizes" : [[728,90],[970,90],[970,250],[728,250],[1200,280]] }},
        "desktop" :         {"banner" : {"sizes" : [[728,90],[970,90],[970,250],[728,250]] }},
        "tablet" :          {"banner" : {"sizes" : [[728,90],[728,250]] }},
        "mobile" :          {"banner" : {"sizes" : [[1,1]] }}
    }
}

`additionalNonHBSizes`

Description: Sizes that are added to the GAM request, but not the header bidding requests.

{
	"additionalNonHBSizes" : ["fluid"]
}

`conditionalNonHBSizes`

Description: Additional sizes for each device type (as defined in deviceDetection.json). It will overwrite the default additionalNonHBSizes if the device is detected.

{
	"conditionalNonHBSizes" : {
	        "bigDesktop":       ["fluid"],
	        "desktop" :         ["fluid"],
	        "tablet" :          ["fluid"],
	        "mobile" :          [[1,1]]
	    }
}

`forceGAMSizes`

Description: When set, the sizes sent to GAM for this ad unit are replaced entirely by this array (instead of banner sizes plus additionalNonHBSizes). Use when you need GAM to request specific sizes regardless of HB sizes. Same format as sizes: array of [width, height] pairs or "fluid".

{
	"forceGAMSizes" : [[300,250],[300,600]]
}

`conditionalForceGAMSizes`

Description: Force GAM sizes per device type (as defined in deviceDetection.json). Overwrites the default forceGAMSizes when the device is detected. Each key is a device label; value is an array of sizes.

{
	"conditionalForceGAMSizes" : {
	        "bigDesktop": [[970,250],[728,90]],
	        "desktop" :   [[728,90]],
	        "tablet" :    [[300,250]],
	        "mobile" :    [[320,50],[300,250]]
	    }
}

`outofpage`

Description: If true, defines the adunit as Out Of Page.

Default: false

{
	"outofpage" : true
}

`targeting`

Description: Key-value name combination to send as targeting to GAM. Takes an object where the key of the object is the name of the key-value. The values can be a string or an array of strings.

{
	"targeting" : 	{
			"pos" : "top",
			"age" : "13",
			"gender" : "m"
    }
}

`lazyLoaded`

Description: If true, enables lazy loading for the adunit.

Default: false

{
	"lazyLoaded" : true
}

`richMediaFormat`

Description: Enables a rich media format for the adunit. Takes an object with type and options properties.

Default: -

{
	"richMediaFormat": {"type" : "adhesion" , "options" : {"closeButton":"true"}}
}

`refreshTimed`

Description: The time in seconds after which the adunit will be automatically refreshed. Set to 0 to disable timed refresh.

Default: 0

{
	"refreshTimed" : "30"
}

`refreshViewable`

Description: The time in seconds after which the adunit will be refreshed once it becomes viewable. Set to 0 to disable viewable refresh.

Default: 0

{
	"refreshViewable" : "30"
}

`css`

Description: CSS styles to apply to the div.

Default: -

{
	"css" : "padding: 2px; margin: 1px;"
}

`bids`

Description: An array of Prebid bidder configurations for the adunit. Each bidder object contains the bidder name and its parameters.

Reference: Full list of Prebid bidders and parameters can be found here.

Default: []

{
	"bids": [
		{"bidder": "onetag",	"params": { "pubId": "abc"}},
		{"bidder": "amx", 	"params": {"tagId": "dfg"}},
		{"bidder": "connectad", "params": {"siteId": 123,"networkId": 123}}
        ]
}

`bids` filters:

Description: Uses the specific bid entry only if the condition is satisfied; otherwise, the bid will be ignored.

`size` filter

Description: Uses the specific bid if the size set in the filter matches one of the requested sizes.

Value: An array of width and height: [width,height].

{
	"bids": [
		{"bidder": "amx", 		"params": { "tagId": "tag-for-all-size"}},
		{"bidder": "amx", 		"params": { "tagId": "tag-for-728x90"}, "size":[728,90]},
		{"bidder": "amx", 		"params": { "tagId": "tag-for-300x250"}, "size":[300,250]}
        ]
}

`device` filter

Description: Uses the specific bid if the device set in the filter matches the detected device.

Value: An array of values from the devices listed in the deviceDetection.json file (e.g., ["desktop","tablet","mobile"]).

{
	"bids": [
		{"bidder": "amx", 		"params": { "tagId": "tag-for-all-device"}},
		{"bidder": "amx", 		"params": { "tagId": "tag-for-desktop"}, "device":["desktop"]},
		{"bidder": "amx", 		"params": { "tagId": "tag-for-mobile"}, "device":["mobile"]}
        ]
}

`testParameter` filter

Description: Uses the specific bid only if the value of testParameter is set to true in the URL query string. It is used to create test pages.

Example: If the value is set to testBidder, for the bid to be used, the URL where the wrapper is called must have testBidder=true (e.g., https://example.com?testBidder=true).

{
	"bids": [
		{"bidder": "amx", 		"params": { "tagId": "generic-tag"}},
		{"bidder": "amx", 		"params": { "tagId": "test-tag"}, "testParameter":"testBidder"}
        ]
}

deviceDetection.json

Description: This file defines the types of devices that will be used in adunits.json. The condition is based on the screen or window size, depending on how it is configured in config.json at deviceDetection.

Properties (for each device entry):

name: The name of the device.
condition: A condition that needs to be respected for that device to be detected.

Notes:

Conditions with any of the <, =, > operators are accepted.
Can use macro {SCREENWIDTH} for the size of the window/screen.
It must cover the full width of the screen possibilities from 0 to infinite.
The devices must not overlap.

Default:

[
	{"name" : "desktop", 	"condition" : "{SCREENWIDTH} >= 1024"},
	{"name" : "tablet", 	"condition" : "{SCREENWIDTH} < 1024 && {SCREENWIDTH} >= 768"},
	{"name" : "mobile", 	"condition" : "{SCREENWIDTH} < 768"}
]

modules.json

Description: This file contains all modules used by Prebid. Each network will have one module. The generic syntax is biddernameBidAdapter. There are some exceptions.

Notes:

indexExchange module is named ixBidAdapter.
Bidders using an alias will use the module of the parent bidder (e.g., districtm, gourmetads will use appnexusBidAdapter).

[
    "ixBidAdapter",
    "aolBidAdapter",
    "gumgumBidAdapter",
    "openxBidAdapter",
    "yieldmoBidAdapter",
    "pubmaticBidAdapter",
    "33acrossBidAdapter",
    "conversantBidAdapter",
    "sharethroughBidAdapter",
    "rhythmoneBidAdapter",
    "onetagBidAdapter",
    "connectadBidAdapter"
]

PreviousGlossary

NextCustomization

Last updated 1 month ago