Debugging module

This module allows to “intercept” bids and replace their contents with arbitrary data for the purposes of testing and development.

Bids intercepted in this way are never seen by bid adapters or their backend SSPs, but they are nonetheless injected into the auction as if they originated from them.

For convenience, debugging configuration is persisted to the browser’s session storage, so that you may type pbjs.setConfig({debugging: ...}) in the console and reload the page to immediately see the effects. This means that you need to remember to deactivate debugging (or clear session storage) when you are done.

Usage example

The following will intercept all bids for the ad unit with code “test-div”, and replace them with mocks that have cpm: 10:

pbjs.setConfig({
  debugging: {
    enabled: true,
    intercept: [
      {
        when: {
          // intercept bids from bidderA that have adUnitCode === 'test-div'
          adUnitCode: 'test-div',
          bidder: 'bidderA'
        },
        then: {
          // mock their response with sane defaults and `cpm: 10`
          cpm: 10
        }
      },
    ]
  }
});

Intercept rules

intercept is a list of objects each containing the following:

Property Type Required? Description
when Function or Object yes Match rule - decides which bids should be intercepted by this rule
then Function or Object no Replace rule - decides the contents of the bids that are intercepted by this rule
options Object no Rule options

Rules are evaluated on each bid in the order they are provided: the first one that has a matching when definition takes the bid out of the normal auction flow and replaces it according to its then definition.

Match rules

The match rule can be provided as a function that takes the bid request as its only argument and returns true if the bid should be intercepted, false otherwise. The example above could be written as:

pbjs.setConfig({
    debugging: {
        enabled: true,
        intercept: [
            {
                when: (bidRequest) => bidRequest.adUnitCode === 'test-div',
                then: {
                    cpm: 10
                }
            }
        ]
    }
})

Alternatively, the rule can be expressed as an object, and it matches if for each key-value pair:

  • bidRequest[key] === value, or
  • value is a function and value(bidRequest[key]) is true, or
  • value is a regular expression and it matches bidRequest[key].

To illustrate, these definitions are equivalent:

{ 
    when: {
        adUnitCode: 'test-div'
    }
};
{ 
    when: {
        adUnitCode: (code) => code === 'test-div' 
    }
};
{ 
    when: {
        adUnitCode: /^test-div$/
    }
};

Replace rules

The replace rule can be provided as a function that takes the bid request as its only argument and returns an object with the desired response properties. The first example above could be written as:

pbjs.setConfig({
  debugging: {
    enabled: true,
    intercept: [
      {
        when: {
            adUnitCode: 'test-div',
        },
        then: (bidRequest) => ({cpm: 10})
      },
    ]
  }
});

Alternatively, the rule can be expressed as an object, and its key-value pairs will appear in the response as follows:

  • if value is a function, then bidResponse[key] will be set to value(bidRequest);
  • otherwise, bidResponse[key] will be set to value.

To illustrate, the following definitions are equivalent:

{
    then: {
        cpm: 10
    }
};
{
    then: {
        cpm: (bidRequest) => 10
    }
}

Rule options

Property Type Default value Description
delay Number 0 Delay (in milliseconds) before intercepted bids are injected into the auction. Can be used to simulate network latency.

Examples

Force a video bid

pbjs.setConfig({
  debugging: {
    enabled: true,
    intercept: [
      {
        when: {
          adUnitCode: "video-adunit",
          bidder: "bidderA'
        },
        then: {
          cpm: 10,
          mediaType: "video",
          source: "client",
          currency: "SEK",
          cpm: 50.00,
          creativeId: "11111",
          width: 640,
          height: 360,
          vastXml: "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"2.0\"><Ad id=\"TestAd\"><InLine><AdSystem>Prebid Test</AdSystem><AdTitle>VAST 2.0 Linear Ad</AdTitle><Error><![CDATA[http://myErrorURL/error]]></Error><Impression><![CDATA[]]></Impression><Creatives><Creative id=\"2014\" AdID=\"20150911\" sequence=\"1\"><Linear><Duration>00:00:15</Duration><TrackingEvents><Tracking event=\"creativeView\"><![CDATA[]]></Tracking><Tracking event=\"start\"><![CDATA[]]></Tracking><Tracking event=\"firstQuartile\"><![CDATA[]]></Tracking><Tracking event=\"midpoint\"><![CDATA[]]></Tracking><Tracking event=\"thirdQuartile\"><![CDATA[]]></Tracking><Tracking event=\"complete\"><![CDATA[]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[http://prebid.org/]]></ClickThrough><ClickTracking><![CDATA[]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" width=\"960\" height=\"540\" type=\"video/mp4\"><![CDATA[https://s3.amazonaws.com/files.prebid.org/creatives/PrebidLogo.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>"
        }
      },
    ]
  }
});

Force a Native Bid

Note: the native response asset IDs and types must match the request.

pbjs.setConfig({
  debugging: {
    enabled: true,
    intercept: [
      {
        when: {
          adUnitCode: "test-div",
          bidder: "bidderA"
        },
        then: {
          cpm: 10,
          bidder: "bidderA",
          mediaType: "native",
          source: "client",
          currency: "EUR",
          cpm: 1.00,
          creativeId: "222222",
          native: { ortb: {
            link: { url: "http://example.com" },
            assets: [{
              id: 1,
              title: { text: "Test Native Creative" }
            },{
              id: 2,
              data: {
                type: 2,
                value: "Test Description"
              }
            },{
              id: 3,
              img: {
                type: 3,
                url: "https://files.prebid.org/creatives/prebid300x250.png"
              }
            },{
              id: 4,
              data: {
                type: 1,
                value: "Prebid"
              }
            }]
          }}
        }
      }
    ]
  }
});