Skip to main content

BidRoll Configuration

This markdown page provides documentation for all types defined in the given TypeScript definitions.

BidRollConfig​

BidRoll Library configuration object.

Properties:​

  • adPath (Optional): The Google Ad Manager Ad Unit Path. If using Spiny's ad server, this is not required. (Type: string)
  • units: Configured Unit Registry. Keyed by unit code. (Type: UnitConfig[]| Record<string,UnitConfig>)
  • getIncElementId (Optional): Function for generating incremental ad unit element IDs. (Type: IncElementIdGenerator)
  • failoverTimeout: Failover timeout is the max timeout in milliseconds to wait for bid requests processes to complete before short circuiting to the ad server request. (Type: number)
  • prebid (Optional): Prebid Module Configuration. (Type: PrebidModuleConfig)
  • amazon (Optional): Amazon Module Configuration. (Type: ApstagConfig)
  • autoRefresh (Optional): Auto refresh configuration. (Type: AutoRefreshConfig)
  • targeting (Optional): Page level targeting. (Type: Record<string, string>)
  • firstPartyData (Optional): First Party Data for enhanced ad requests. (Type: FirstPartyData)
  • adRefresh (Optional): Refresh settings. Primarily used for throttling. (Type: { throttle?: AdThrottleConfig })

Example​

There are several ways to update the BidRoll configuration.

// At Initialization
bidroll.init(implementationBidRollConfig);
// On client side page navigation or infinite scroll
bidroll.newPageView(newPageViewBidRollConfig);
// Outright updating the configuration
bidroll.setConfig(newBidRollConfig);

UnitConfig​

Unit configuration object.

Properties:​

  • code: Unit code. This is the unique identifier for the unit. (Type: string)
  • inherit (Optional): Utilized during the JavaScript runtime, this is the inherit code for a different unit configuration that this configuration inherits from. (Type: string)
  • increment (Optional): Utilized during the JavaScript runtime, increments the unit code by a number. (Type: number)
  • fixed (Optional): Boolean flag indicating whether or not a unit has a position: fixed style applied to it. This prevents the need for BidRoll having to determine if a unit is fixed or not. (Type: boolean)
  • sizes: Compatible ad size for this placement. (Type: PreValSizes)
  • bids: Bidder configurations for this unit. Comprised of Prebid bid configs and Amazon inclusion config. Important: Geo-specific bidder configurations are not currently supported. Only the region all is supported at this time. We will be introducing geolocation-specific bidders in a future release. (Type: Array<UnitBid>)
  • element (Optional): Utilized in the JavaScript runtime, this is the HTML Element corresponding to the unit. (Type: HTMLElement)
  • targeting (Optional): Unit-specific targeting. (Type: Record<string, unknown>)
  • oop (Optional): Boolean flag indicating whether or not this unit is out of page. (Type: boolean)
  • lazyLoad (Optional): Boolean flag indicating whether or not this unit is lazy-loaded. Additionally, it can be configured with a lazy load configuration object. (Type: boolean|LazyLoadConfig
  • elementId (Optional): String corresponding to the ad unit element ID. (Type: string)
  • mediaTypes (Optional): Granular ad unit media type configuration to be passed to Prebid. (Type: unknown)
  • autoRefresh (Optional): Ad unit-specific auto-refresh configuration. (Type: AutoRefreshConfig)
  • filters (Optional): Ad filters to apply to this unit. (Type: AdFilterDesignation)

AdThrottleConfig​

Ad refresh throttle configuration. Prevents refreshes from occurring in rapid succession.

Properties:​

  • timeout: Timeout to wait in milliseconds before allowing a refresh to occur. (Type: number)
  • units (Optional): Unit-specific throttle timeouts. Keyed by unit code. (Type: Record<string, number>)

GenerateParamsOptions​

Bidder Param Generation Config. Various contexts will be available to generate bidder params. The primary motivation for this capability is defining size level bid configs as shown in the example below however other properties are available in the generate template properties:

  • bidConfig - The current bid configuration ( pregeneration )
  • unit - The current unit configuration (See UnitConfig)
  • targeting - Page targeting
  • config - BidRoll Configuration (See BidRollConfig)

Properties:​

  • loopBy: Loop by these keys in the unit configuration. (Type: string[])
  • params: Params to generate. The value can be a string or a template string with the following variables provided: config, targeting, bidroll context, unit, and the loopBy key. (Type: Record<string, unknown>)

Example​

Config Example:

{
  // ... Unit Config
  "code": "mobile_top",
  "sizes": [ [300,250], [320,50], "fluid" ],
  "bids": [
    {
      "bidder": "bidder",
      "params": {
        "siteId": "555"
      },
      "generate": {
        "loopBy": {
          "size": "unit.sizes"
        },
        "params": {
          "placementId": "${ unit.code }-${ Array.isArray(size) ? size.join('x') : size }"
        }
      }
    }
  ]
}

Runtime Result:

{
  "code": "mobile_top",
  "sizes":  [ [300,250], [320,50], "fluid" ],
  "bids": [
    {
      "bidder": "bidder",
      "params": {
        "siteId": "555",
        "placementId": "mobile_top-300x250"
      }
    },
    {
      "bidder": "bidder",
      "params": {
        "siteId": "555",
        "placementId": "mobile_top-320x50"
      }
    },
    {
      "bidder": "bidder",
      "params": {
        "siteId": "555",
        "placementId": "mobile_top-fluid"
      }
    },
  ]
}

SingleFilter​

Single Ad Filter Config.

Properties:​

  • key: Object key to filter on. (Type: string)
  • strategy (Optional): Filter strategy. "any" will pass if any of the conditions are met. "all" will pass if all of the conditions are met. Defaults to "any". (Type: "any"|"all")
  • not (Optional): Negate the filter. If true, the filter will pass if the condition is not met. (Type: boolean)
  • oneOf (Optional): If the value matches any of the values in the array, the filter will pass. (Type: unknown[])
  • equal (Optional): If the value matches, the filter will pass. (Type: unknown)
  • greaterThan (Optional): If the number value is greater than this value, the filter will pass. (Type: number)
  • lessThanOrEqual (Optional): If the number value is less than or equal to this value, the filter will pass. (Type: number)
  • greaterThanOrEqual (Optional): If the number value is greater than or equal to this value, the filter will pass. (Type: number)
  • lessThan (Optional): If the number value is less than this value, the filter will pass. (Type: number)
  • > (Optional): If the value is greater than this value, the filter will pass. (Type: number)
  • < (Optional): If the value is less than or to this value, the filter will pass. (Type: number)
  • <= (Optional): If the value is less than or equal to this value, the filter will pass. (Type: number)
  • >= (Optional): If the value is greater than or equal to this value, the filter will pass. (Type: number)
  • == (Optional): If the value is equal to this value, the filter will pass. (Type: unknown)
  • != (Optional): If the value is not equal to this value, the filter will pass. (Type: unknown)
  • in (Optional): Exactly like "oneOf", the filter will pass if the value matches any of the values in the array. (Type: unknown[])
  • contains (Optional): If the value contains this filter value, the filter will pass. (Type: unknown)

FilterConfig​

Filter configuration. Can be a single filter(SingleFilter) or a registry of filters, keyed by the object key the filter pertains to.

AdFilterDesignation​

Ad filter designation. Used to determine which filters to apply to an ad. Current predefined filters include:

  • bodyClass
  • device - mobile or desktop only at this time
  • orionContext - documented here
  • targetin - page targeting tracked by BidRoll
  • unitTargeting
  • window - window variable
  • localStorage
  • cookie
  • unitConfig
  • config - BidRoll Config

Example​

{
  // ... Rest of unit configuration
  "filters": {
    "defs": {
      // If the Orion Content ID is 555, 777, or 888 exclude this ad
      "orionContext": {
        "page.contentId": {
          "strategy": "all",
          "onOf": [555, 777, 888],
          "not": true
        }
      },
      // If the body class contains 'subscriber', 'subscribe',
      // or 'checkout' exclude this ad from being processed
      "bodyClass":{
        "strategy": "all",
        "contains": ["subscriber","subscribe","checkout"],
        "not": true
      },
      // If the detected device is NOT mobile exclude
      // this ad from being processed
      "device": {
        "strategy": "all",
        "equals": "mobile"
      }
    }
  }
}

Properties:​

  • strategy (Optional): Overarching filter strategy. "any" will pass if any of the conditions are met. "all" will pass if all of the conditions are met. Defaults to "any". (Type: "any"|"all")
  • defs: Filter definitions. (Type: Object)

ViewPortDimension​

Viewport dimension designations. Used to define size mappings. Possible values include max-width, max-height, min-width, and min-height.

ApstagConfig​

Amazon Header Bidding Config.

Properties:​

  • pubID: Amazon Publisher ID. (Type: string)
  • adServer: Ad Server designation. (Type: string)
  • timeout: Amazon Bidder Timeout. (Type: number)

PrebidModuleConfig​

Configuration for BidRoll's Prebid Module.

Properties:​

  • raw (Optional): Standard Prebid Configuration. (Type: PrebidConfig)
  • timeout (Optional): Timeout for Prebid to respond with bids. (Type: number)
  • bidderSettings (Optional): Prebid bidder settings. (Type: Partial<PrebidBidderSettings>)
  • auto (Optional): Flag registry for BidRoll to automatically handle certain Prebid settings. Currently only supports ortb2. (Type: Record<keyof PrebidConfig, boolean>)

AutoRefreshConfig​

Configuration for BidRoll's autorefresh feature.

Properties:​

  • enabled (Optional): Whether or not autorefresh is enabled. (Type: boolean)
  • secondsInView: The number of seconds the ad must be in view before refreshing. (Type: number)
  • percentageVisible: The percentage of the ad that must be in view before refreshing. (Type: number)
  • once (Optional): Flag to only refresh once. (Type: boolean)
  • count (Optional): The number of times to auto-refresh the ad. (Type: number)

FirstPartyData​

Configuration for passing first party data to the ad requests. It's important to note that all first party data for end users is one-way encrypted before being transmitted to partners. The unencrypted user-identifiable data is not stored or transmitted elsewhere.

Properties:​

  • user (Optional): First party data of the end user. (Type: object)
  • user.email (Optional): The end user's email address. (Type: string)
  • user.phoneNumber (Optional): The end user's phone number. (Type: string)

IncElementIdGenerator​

Signature: (code: string, increment: number) => string Default: (code, increment) => code + "-" + increment

Function for generating an incremental unit's element ID. This is configured at runtime as a function. The function takes the unit code and increment and should generate an ID with a matching element.

UnitMediaTypes​

The media type configurations of the unit.

Please refer to the Prebid documentation here for all possible configuration values.

Properties:​

  • banner (Optional): Display banner configuration. (Type: unknown)
  • video (Optional): Video configuration. (Type: unknown)
  • native (Optional): Native configuration. (Type: unknown)

SizeMap​

Size map configuration object. You can define either viewportDimension & viewportAmount or mediaMatch but not both.

info

window.matchMedia is used to determine if the size map should be used.

Properties:​

  • viewportDimension (Optional): Viewport dimension to use for the size map. (Type: ViewPortDimension)
  • viewportAmount (Optional): Viewport amount to use for the size map. Please ensure including the unit of measure. (Type: string)
  • sizes: Sizes to use for the size map. (Type: Array<[number, number]|string>)
  • mediaMatch (Optional): Media match to use for the size map. (Type: string)

PreValSizes​

Pre-evaluation sizes configuration object. This is used to determine the size of the unit before it is processed.

UnitBid​

Unit bid configuration object.

Properties:​

  • generate (Optional): Generation configuration object for dynamic parameters. (Type: GenerateParamsOptions)
  • bidder: Bidder code to use for the unit. (Type: string)
  • params: Bidder parameters. (Type: Record<string, unknown>)

LazyLoadConfig​

Unit Lazy Load configuration object.

All values are defaulted to the general configuration's lazy load configuration.

Properties:​

  • rootMargin (Optional): Root margin to use for lazy load. The value you match the rootMargin passed to the IntersectionObserver constructor. (Type: string)
  • threshold (Optional): A single threshold value as passed into the threshold option of the IntersectionObserver constructor. (Type: number)
  • root (Optional): The element ID or element (in JavaScript runtime) to use as the viewport for checking visibility of the target. Defaults to the body element. (Type: HTMLElement|string)