⚙️Configuration

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

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.

Notes: It must be an integer.

Default: 9999

{
	"id" : 12345
}

`code`

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

{
	"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.

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.

Default: false

{
	"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.

{
	"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.

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

Default: hb

{
	"targetingPrefix" : "chp"
}

`url`

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

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

`dfpAccount`

Description: The GAM account ID of the main account.

{
	"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.

{
	"dfpChildAccount" : "4567890123"
}

`adunitMapping`

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

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).

Default: adunit

{
	"adunitMapping" : "adunit"
}

`adunitMappingKey`

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

Default: pos

{
	"adunitMappingKey" : "location"
}

`gist`

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

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

`analytics.clarity`

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

Default: false

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

`analytics.gtm`

Description: Enables a GTM container.

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.

{
	"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.

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.

{
	"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.

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.

Default: 50

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

`wrapper.disableBidders`

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

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

`wrapper.disableClientSideAdapters`

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

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

`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.

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.

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.

Parameters:

href:
- Description: An array of patterns to match against the window.location.href. If this array exists and has length > 0, href pattern blocking is enabled.
- Possible Values:
  - Wildcard strings (e.g., /admin/*, *staging*). * matches any sequence of characters, ? matches a single character.
  - Regex strings, prefixed with regex: (e.g., regex:^https?://(dev|staging)\.example\.com/).
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": [
      "/admin/*",
      "*staging*",
      "regex:^https?://(dev|staging)\.example\.com/"
    ],
    "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.
For regex patterns, you can control flags within the pattern itself.
Country code matching is case-insensitive.

`wrapper.disableInitialProcessAdsOnPage`

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

Default: false

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

`wrapper.prebidServer.enabled`

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

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

`wrapper.prebidServer.accountId`

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

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

`wrapper.prebidServer.endpoint`

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

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Default: 1

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

`bidAdjustments.s2s`

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

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.

{
	"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.

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.

Default: false

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

`lazyLoading.scrollEventDelay`

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

Default: 400

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

`targeting.refreshIteration`

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

Default: refresh_count

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

`targeting.refreshedInventory`

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

Default: false

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

`targeting.refreshedAccelerateSeconds`

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

Default: false

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

`targeting.speed`

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

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.

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.

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.

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.

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

Default: false

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

`targeting.gads`

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

Default: false

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

`targeting.cookieEnabled`

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

Default: false

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

`targeting.browserLangCode`

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

Default: false

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

`targeting.referrer`

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

Default: false

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

`targeting.domain`

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

Default: false

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

`targeting.code`

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

Default: false

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

`targeting.id`

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

Default: false

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

`targeting.prerendering`

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

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.

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.

Default: false

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

`targeting.browser`

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

Default: false

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

`targeting.os`

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

Default: false

{
	"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).

Default: false

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

`refresh.stopAdvertisers`

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

Notes: Values must be numeric, not strings.

Default: false

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

`refresh.pauseOutOfFocus`

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

Default: false

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

`refresh.pauseOutOfView`

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

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.

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

Default: false

{
	"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.

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"

Default: false

{
	"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.

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"

Default: false

{
	"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.

Default: false

{
	"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.

Default: false

{
	"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.

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.

Default: false

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

`refresh.viewabilityProvider`

Description: Defines the viewability provider for refresh.

Possible Values:

gam: Uses the GAM viewability event.
wrapper: Uses the internal viewability detection for refresh.

Default: gam

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

`deviceDetection`

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

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.

Default: window

{
	"deviceDetection" : "window"
}

`dfp.collapseEmptyDivs`

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

Default: false

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

`dfp.emptyCreativeFallback`

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

Default: true

{
	"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.

Default: false

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

`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.

Default: false

{
	"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.

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

Default: false

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

`dfp.forceSafeFramesForAdunits`

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

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.

Default: false

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

`dfp.forceSafeFrames`

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

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

Default: false

{
	"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:

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.

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.

Properties:

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

Default: false

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

`userSync.triggerAction`

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

Possible Values: scroll, click, idle, timed.

Default: idle

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

`userSync.triggerDelay`

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

Default: 5000

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

`prebidBidderSpecific`

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

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.

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.

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.

Default: false

{
	"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.

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.

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.

Default: false

{
	"forceReWrittingPBJS" : true
}

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]]
	    }
}

`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"
]

PreviousHeader Bidding Wrapper Documentation 🚀NextCustomization

Last updated 28 days ago