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

**Required:** Yes - Will throw an error if missing.

**Notes:** It must be an integer.

```javascript
{
	"id" : 12345
}
```

### `code`

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

**Required:** Yes - Will throw an error if missing.

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

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

### `blockAutoBuild`

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

**Required:** No - Optional.

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

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

```javascript
{
	"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"`

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

### `dfpAccount`

**Description:** The GAM account ID of the main account.

**Required:** Yes - Has default value if not set.

**Default:** `"1234"`

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

```javascript
{
	"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:**

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

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

```javascript
{
	"adunitMappingKey" : "location"
}
```

### `gist`

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

**Required:** No - Optional.

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

### `analytics.clarity`

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

**Required:** No - Optional.

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

### `analytics.gtm`

**Description:** Enables a GTM container.

**Required:** No - Optional.

**Parameters:**

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

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

```javascript
{
	"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`

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

```javascript
{
	"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`

```javascript
{
	"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`

```javascript
{
	"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)

```javascript
{
	"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)

```javascript
{
	"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`

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

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

```javascript
{
	"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:**

```javascript
"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.disableInitialProcessAdsOnPage`

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

**Required:** No - Optional.

```javascript
{
	"wrapper" : {
		"disableInitialProcessAdsOnPage" : true
	}
}
```

### `wrapper.prebidServer.enabled`

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

**Required:** No - Optional.

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

### `wrapper.prebidServer.accountId`

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

**Required:** No - Optional.

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

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

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

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

```javascript
{
	"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`

```javascript
{
	"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`

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

```javascript
{
	"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`

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

```javascript
{
	"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`

```javascript
{
	"lazyLoading" : {
		"scrollEventDelay" : 400
	}
}
```

### `targeting.refreshIteration`

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

**Required:** No - Optional.

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

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

```javascript
{
	"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`

```javascript
{
	"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`

```javascript
{
	"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`

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

```javascript
{
	"targeting" : {
		"topicsapi" : true
	}
}
```

### `targeting.gads`

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

**Required:** No - Optional.

```javascript
{
	"targeting" : {
		"gads" : true
	}
}
```

### `targeting.cookieEnabled`

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

**Required:** No - Optional.

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

```javascript
{
	"targeting" : {
		"browserLangCode" : true
	}
}
```

### `targeting.referrer`

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

**Required:** No - Optional.

```javascript
{
	"targeting" : {
		"referrer" : true
	}
}
```

### `targeting.domain`

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

**Required:** No - Optional.

```javascript
{
	"targeting" : {
		"domain" : true
	}
}
```

### `targeting.code`

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

**Required:** No - Optional.

```javascript
{
	"targeting" : {
		"code" : true
	}
}
```

### `targeting.id`

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

**Required:** No - Optional.

```javascript
{
	"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:**

* [Prerendering Pages in Chrome](https://developer.chrome.com/docs/web-platform/prerender-pages)
* [Document Prerendering API](https://developer.mozilla.org/en-US/docs/Web/API/Document/prerendering)
* [Prebid.js Pull Request #12763](https://github.com/prebid/Prebid.js/pull/12763)

**Default:** `false`

```javascript
{
	"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`

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

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

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

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

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

**Required:** Yes - Has default value if not set.

**Default:** `[]` (empty array)

**Notes:** Values must be numeric, not strings.

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

### `refresh.pauseOutOfFocus`

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

**Required:** No - Optional.

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

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

```javascript
{
	"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

```javascript
{
	"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"

```javascript
{
	"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"

```javascript
{
	"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)

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

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

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

```javascript
{
	"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:**

1. `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).
2. `screen`: Detects the screen size, not taking into account the actual window/tab.

```javascript
{
	"deviceDetection" : "window"
}
```

### `dfp.collapseEmptyDivs`

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

**Required:** No - Optional.

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

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

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

**Required:** No - Optional.

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

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

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

```javascript
{
	"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:**

1. **`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.
2. **`bidders`**: Array of bidder codes. Enables SafeFrames for specific bidders (e.g., protect against specific SSPs).
3. **`adomains`**: Array of advertiser domains. Enables SafeFrames for specific advertisers (e.g., competitor exclusion or brand safety).
4. **`acats`**: Array of IAB category codes. Enables SafeFrames for specific ad categories (e.g., sensitive verticals).
5. **`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:**

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

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

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

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

```javascript
// 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](https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html)

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

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

### `userSync.triggerAction`

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

**Required:** No - Optional.

**Possible Values:** `scroll`, `click`, `idle`, `timed`.

```javascript
{
  "userSync": {
    "triggerAction": "click"
  }
}
```

### `userSync.triggerDelay`

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

**Required:** No - Optional.

```javascript
{
  "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](https://docs.prebid.org/dev-docs/publisher-api-reference/setBidderConfig.html)

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

```javascript
{
	"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](https://ams.amazon.com/webpublisher/uam/docs/reference/api-reference.html#adrefresh)

**Possible Values:**

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

```javascript
{
	"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](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md#object-schain)

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

**Code Examples:**

```javascript
{
	"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:**

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

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

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

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

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

### `device`

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

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

### `mediaTypes`

**Description:** MediaTypes in the format accepted by Prebid.

**Reference:** [Prebid documentation AdUnit Reference](https://docs.prebid.org/dev-docs/adunit-reference.html#adunitmediatypes)

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

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

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

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

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

```javascript
{
	"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`

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

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

### `lazyLoaded`

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

**Default:** `false`

```javascript
{
	"lazyLoaded" : true
}
```

### `richMediaFormat`

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

**Default:** `-`

```javascript
{
	"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`

```javascript
{
	"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`

```javascript
{
	"refreshViewable" : "30"
}
```

### `css`

**Description:** CSS styles to apply to the div.

**Default:** `-`

```javascript
{
	"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](https://docs.prebid.org/dev-docs/bidders.html).

**Default:** `[]`

```javascript
{
	"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]`.

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

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

```javascript
{
	"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):**

1. `name`: The name of the device.
2. `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:**

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hbwrapper.com/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.