Impression Delivery and Tracking

The following sections explain the workflow of ad delivery, impression tracking, and other related events which occur when these ad types are traded through BidSwitch.

Note

Any logic described in this section, especially information related to Supplier behavior is based on the most common case, but it may differ greatly depending on specific Suppliers.

v5.0 Display

When integrated with BidSwitch using v5.0 of the protocol,creatives are delivered and tracked using the following workflow.

Stage 1.
The Buyer returns the bid response with the following example creative in the adm field using an iframe tag, or similar HTML markup tag. For more information, see the 5.x Updating Overview section.
{
   "bid":{
      "adm":"<iframe src=\"http://buyer.com/imp?bc=12345a&price=${AUCTION_PRICE}\"/>"
   }
}

Note

The v4.3 option is also allowed in v5.0. You can supply the impression URL in the adm or nurl field. The difference between the versions is the usage of the ${AUCTION_PRICE} macro. See the 5.x Updating Overview section for the details.

Stage 2.
BidSwitch parses the adm.iframe data, wraps and URL-encodes it, then sends this to the Supplier.
<iframe src=\"http://bsw.com/imp?price=${BSW_PRICE}\
&redirect=http%3A%2F%2Fbuyer.com%2Fimp%3Fbc%3D12345a%26price%3D%24%7BAUCTION_PRICE%7D"\>
Stage 3.
The Supplier replaces the price macro with the winning price, and then it is sent to the browser.
Stage 4.
The browser then runs the adm field data in the the following sequence.
  1. BidSwitch is called first, and it updates the pricing (if in media mode)

  2. Then BidSwitch sends a 302 redirect to the iframe URL with BidSwitch’s revised price.

    <iframe src=\"http://buyer.com/imp?bc=12345a&price=${AUCTION_PRICE}"/>
    
  3. The browser follows the 302 redirect to the buyer URL.

  4. The Buyer redirects to where the real creative asset is located.

v4.3 Display

When integrated with BidSwitch using v4.3 of the protocol, display creatives are delivered and tracked using the following workflow.

Stage 1.
The Buyer returns the bid response with the ad URL in the adm field, and the winning price in the nurl field.
{
   "bid":[
      {
         "adm":"<a href=\"http://adserver.com/click?adid=12345\"></a>",
         "nurl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}"
      }
   ]
}
Stage 2
BidSwitch parses and encodes the information in the adm and nurl fields and sends this is sent to the Supplier.
Stage 3.
The Supplier sends the adm field link to the browser, and the user clicks the URL.
Stage 4.
The nurl field containing the ${AUCTION_PRICE} is usually called from the user browser, but can also be called in server-to-server. In the case of a browser call, it is added to the creative markup as a pixel in the following manner.
  • BidSwitch takes the nurl, and wraps it in the impression call URL.
  • It adds this to the creative markup as a pixel.
  • Once this pixel is called, BidSwitch receives the impression call and then responds to the browser with a HTTP 302 redirect to the nurl URL. The BidSwitch impression URL contains the nurl as a parameter in encoded form.

Video

Overview

Video is delivered using VAST and works the same for v4.3 & v5.0. Buyers respond to the bid request with the VAST XML URL specified in the bid.ext.vast_url field. Note: There is a slight difference for native video delivery, with the VAST XML URL specified in the bid.ext.native.vast_url field.

This is delivered to the Supplier, and the assets specified in the VAST XML are called by the video player to deliver the video and trigger the impression tracking.

{
   "bid":[
      {
         "nurl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",
         "ext":{
            "vast_url":"http://adserver.com/vast?impid=102"
         }
      }
   ]
}

Note

The call to the video URL is not counted as impression. Impression tracking is done via an nurl field call and is delayed until after the video has completed buffering. Impression event calls specified in the VAST document will also be called, but without the clearing price information.

Video Delivery and Impression Tracking Sequence

Stage 1.
The VAST XML in the bid response is delivered to the Supplier which contains the ${AUCTION_PRICE} macro, impression tracking URL, and the VAST Ad Tag.
<?xml version="1.0" encoding="UTF-8"?>
<VAST version="2.0">
<Ad id="ccdc86a0-b972-4996-bb8d-777728ae8f8f">
<Wrapper>
<AdSystem>BidSwitch</AdSystem>
<VASTAdTagURI><![CDATA[http://sandbox.bidswitch.net/vast/9Qs-4U0LnG9Ly9O_7KBdjybEkP_kH9f8D6wW0TK4oRFXQdOP1D50JBRocW-FQnBh_eiU8e7Cl-hHn4WxgEqUquHQ3uqDSQLra_PTbe0CpcoiQjXrygPfb3x_Z9M1gly3ZWFDi7uS1OnvqEkhjojf58espkvLlbvcefTtaSXJDXrXESoadGKIKWz-ueyMpYTluYLWg1f7xaVQ_ZLwok8_bYNw2807QW5RPbHN_EIkZbHIxtawCIN_fNTNpzqSPC46O0YOydbP3h5FoXsK9l0q2H3t54PDOj2OiJBspLMXVP9UwguozwR-cLymuTuAf_-P6GI94UtT4fxJZF6Ah7rCoxtPA7tyAHSrZLonjngI3hXL3DnL2HIhjYIYrbcwNV9B-KCXquBaIzyBbBSsHET0B6JVXcaUvyuhftCxWHYizJfx3Cb6E6rRvKinKKlsVeKkdZTzfmN721KzNwQ]]></VASTAdTagURI>
<Error><![CDATA[http://staging-eu-gce.bidswitch.net/vast_error/CKwBnBHYSg2Q5SprGhe_AiV_vItjkDymv5e9zUHbSQDP7CeoLkhtNYV3GLblSQHHwDoRs_WlecXnKOeC0_gqcbb0zMkZZ2EEWTFcV1UodSNQwcDfFFptohCuvhcDKmKYGjL-3MtVbhRieFrhTmOKK5uuhrFwHHCrs4g4L9p4EG1OKVSdssGUp1cB-A6KAFcgqq1fNalHJekEBsGwTvetx5m4sVqe24Nq6XABDHMINn5nIBvGeGgfZyRmmkcGNHivksEZRG2if1uiUbS_oM5Uu2OzZE4-k-tSM-xrsZhPGI4PlD9UV37_EGWTG6AFV7DR6DQTf9tbu4C10lzRp9vBFP3X_Xx0F80-2iBbIfLTjUWryUeC4Imd_TJwux4MNYsXx1BoGankV0scB2-PxHX1A0y4sZjE-e3wKYdngRMz7K99egGk_oAAkV_qog8yZcj_4ScmMHneOdOWmOT7_l3_WvoQb-BXci3O8JbSGEScq2qIwZt1WNSKGyie4jbOfnXAYBRlp9ePObY6o844CRQ/]]></Error>
<Impression><![CDATA[http://staging-eu-gce.bidswitch.net/imp/${AUCTION_PRICE}/http%3A%2F%2Fsandbox.bidswitch.net%2Fimp%2Ftracker%2F9Qs-4f06ojy2XTmapBooyassv40jDGiU4HfprbqhTKC6ezBOWizC5tdL1MN774BMyprcGfouyNLQNQn9mCRpamaO-dog7oEEo1Q9Wt4Rg6Itp7Q9crx5BzF_qkOZfF2hPMM0JH8n5Y5AZ3H_28IqOTxaYGUBXiOM7iyCKvvdpHq4Ys7cnrKGV8BgUdo6l5asY-Wq7NXngmehXkvTkAL9sdotmuyL_ukS6NHAMZGHzwML7pMcI02_cYs6rhFNRsVRFPtblraoXwLp1m_c6_g34udImsMzsFEVG0Tyr7M7McxBfdudyLRA6yU2jpyZX8Cm8czyk4o9AfMAQcC39LUQUF7H-ux34jj3oGt2U0lYFK9GtZMtfIYd6pflYB-RItZqCpo26hOjiweW8u484cc5wB-enovRglJmdbiLCF2kf24ER4fvlWe9V2jFfQWtz63yatqDAZ2INwxA0aY%2F%24%7BAUCTION_PRICE%7D/CKwBnBHYSg2Q5SprGhe_AiV_vItjkDymv5e9zUHbSQDP7CeoLkhtNYV3GLblSQHHwDoRs_WlecXnKOeC0_gqcbb0zMkZZ2EEWTFcV1UodSNQwcDfFFptohCuvhcDKmKYGjL-3MtVbhRieFrhTmOKK5uuhrFwHHCrs4g4L9p4EG1OKVSdssGUp1cB-A6KAFcgqq1fNalHJekEBsGwTvetx5m4sVqe24Nq6XABDHMINn5nIBvGeGgfZyRmmkcGNHivksEZRG2if1uiUbS_oM5Uu2OzZE4-k-tSM-xrsZhPGI4PlD9UV37_EGWTG6AFV7DR6DQTf9tbu4C10lzRp9vBFP3X_Xx0F80-2iBbIfLTjUWryUeC4Imd_TJwux4MNYsXx1BoGankV0scB2-PxHX1A0y4sZjE-e3wKYdngRMz7K99egGk_oAAkV_qog8yZcj_4ScmMHneOdOWmOT7_l3_WvoQb-BXci3O8JbSGEScq2qIwZt1WNSKGyie4jbOfnXAYBRlp9ePObY6o844CRQ/]]></Impression>
<Impression><![CDATA[http://staging-eu-gce.bidswitch.net/sync?ssp=axonix&dsp_id=58&imp=1]]></Impression>
<Creatives />
</Wrapper>
</Ad>
</VAST>
Stage 2.
The primary ad server replaces the price macro in the VAST wrapper and passes it to video player
Stage 3
The video player requests the VAST file specified in the <VASTAdTagURI> tag from the secondary ad server which responds with the ad (the real media files).
Stage 4
When the video is buffered in the player, it calls the tracking events within the <Impression>...</Impression> tags specified in both the VAST wrapper and VAST inline documents.
Stage 5
The BidSwitch impression handler is called, Then BidSwitch sends a 302 redirect to the nurl with BidSwitch’s revised price. The player follows the 302 redirect to the Buyer URL.

Native

Native creatives are delivered a similar way to Banner ads.

Stage 1.
The Buyer responds to the bid request with the link to the ad in the ext.native.link field, the impression tracking URL in the imptracker field, and the ${AUCTION_PRICE} in the nurl field.
{
 "bid":[
    {
       "nurl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",
       "ext":{
          "native":{
             "link":{
                "url":"http://adserver.com/click?impid=102"
             },
             "imptrackers":[
                "https://adserver.com/native?impid=102"
             ]
          }
       }
    }
 ]
}
Stage 2.
BidSwitch sends this to the supplier. The supplier formats the data in the appropriate way for the publisher and passes it to browser or application, then calls the BidSwitch nurl while replacing the ${AUCTION_PRICE} with the actual win price.
Stage 3.
The BidSwitch impression handler is called, then BidSwitch calls the Buyer nurl with BidSwitch’s revised price.