Sample Request & Response (SSP Ad Server)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 24, 2017
Version 14Show Document
  • View in full screen mode

The PubMatic ad server will return different types of response formats depending upon the values of the operId and rs parameters provided in the request.

Following is a sample request and various responses.

HTTP Request

Sample Request

http://bid.pubmatic.com/AdServer/AdServerServlet?operId=1&pubId=504&siteId=505&adId=16639
&kadwidth=300&kadheight=250&pageURL=http://192.168.1.115/pub-test.html&kltstamp=2013-04-
02%2017%3A28%3A57&ranreq=0.6148488499487118&timezone=5.5&screenResolution=1366x768&inIframe
=0&adPosition=16x8&adVisibility=1

Note: You need to replace the operId parameter's value in the above request to generate the following responses.

 

Request Headers

Accept-Language:en-US,en;q=0.5
User-Agent:Mozilla/5.0 (Windows NT 6.1; WOW64; rv:19.0) Gecko/20100101 Firefox/19.0
RLNClientIpAddr:115.112.64.6

  

HTML Response

The PubMatic ad server will return a response in the HTML format for operId=1.  Following is a sample response:

<span class="PubAdAI"><script type="text/javascript">

document.write('<a target="_blank" href="http://pubmatic.com"><img width="300" height="250"
border="0" alt="" src="http://64.106.163.182/test.php?width=300&height=250"/></a>');
</script><script type="text/javascript"> document.write('<iframe name="pbeacon" frameborder="0"
allowtransparency="true" hspace="0" vspace="0" marginheight="0" marginwidth="0" scrolling="no" 
width="0"  height="0" style="position:absolute;top:-20000px;" src="http://aktrack.pubmatic.com/
AdServer/AdDisplayTrackerServlet?operId=1&pubId=504&siteId=505&adId=16639&adServerId=165&kefact=
0.700000&kaxefact=0.700000&kadNetFrequecy=2&kadwidth=300&kadheight=250&kadsizeid=9&kltstamp=
1364909602&indirectAdId=10739&adServerOptimizerId=1&ranreq=0.6148488499487118&kpbmtpfact=0.000000
&pageURL=http://192.168.1.115/pub-test.html"> </iframe>'); </script>

<!-- PubMatic Ad Ends --></span><!-- BID2052:B6394367-9BD7-4C8C-A5C9-14FC1F51B800 --><!--
etsdiff:400183 --><!-- u_ts:2013-04-02%2017%3A28%3A57, u_tz:5.5 -->

 

JavaScript Response

The PubMatic ad server will return a response in the JavaScript format for operId=3. Following is a sample response: 

document.write('<span class="PubAdAI">');var str = '%3Cscript%20type%3D%22text%2Fjavascript%22%
3E%0Adocument.write%28%27%3Ca%20target%3D%22_blank%22%20href%3D%22http%3A%2F%2Fpubmatic.com%22%
3E%3Cimg%20width%3D%22300%22%20height%3D%22250%22%20border%3D%220%22%20alt%3D%22%22%20src%3D%22
http%3A%2F%2F64.106.163.182%2Ftest.php%3Fwidth%3D300%26height%3D250%22%2F%3E%3C%2Fa%3E%27%29%3B%
0A%3C%2Fscript%3E';

document.writeln(unescape(str));

document.write('<iframe name="pbeacon" frameborder="0" allowtransparency="true" hspace="0"
vspace="0" marginheight="0" marginwidth="0" scrolling="no"  width="0"  height="0" style=
"position:absolute;top:-20000px;" src="http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?
operId=1&pubId=504&siteId=505&adId=16639&adServerId=165&kefact=0.700000&kaxefact=0.700000&kadNetFrequecy
=10&kadwidth=300&kadheight=250&kadsizeid=9&kltstamp=1364909871&indirectAdId=10739&adServerOptimizerId=1&
ranreq=0.6148488499487118&kpbmtpfact=0.000000&pageURL=http://192.168.1.115/pub-test.html"> </iframe>');

document.write('<!-- PubMatic Ad Ends --></span>');/* BID2050:19047987-C9A3-4EF5-97C6-
04D4B3EAD8CE */
/* etsdiff:326469 *//* u_ts:2013-04-02%2017%3A28%3A57, u_tz:5.5 *///     

JSON Response

The PubMatic ad server will return JSON responses in various formats for operId=102 or operId=201.

We recommend that you use operId 102 for Display Web Inventory and operId 201 for Mobile Inventory.

Following are the fields that you will observe in the JSON response. The JSON response will contain the following keys and their corresponding values:

                                                               

Field

Type

Description

ecpm

Float

eCPM of the ad impression served by PubMatic.

creative_tag

String

Creative's ad tag.

tracking_url

String

URL of the beacon, which is used to record impressions served by PubMatic. This URL must be called once the creative tag is executed on the user's browser.

Note: The PubMatic tracker call should get enclosed within the <script> tag and not in the <img> tag before rendering on actual page. Or else, few browsers execute the tracker call multiple times which may cause discrepancy issues.

click_tracking_url

String

URL of the beacon, which is used to record click tracking. This URL, when present, needs to be called once the creative is clicked.

Note: This is an optional field in the PubMatic response.

landing_page

String

URL of the advertiser's landing page, if available.

Note: This is an optional field in the PubMatic response.

wdeal

String

Represents the deal id that was associated with the winning impression

Note: This is an optional field in the PubMatic response.

creative_idString

Unique Identifier of the creative. This can be used as reference by publishers for creative control.

Note: This is an optional field in the PubMatic response.

iurlString

Sample image URL (without cache busting) for checking its content.

Note: This is an optional field in the PubMatic response.

dsp_camp_idString

ID of the campaign in the DSP's system which has won the impression.

Note: This is an optional field in the PubMatic response.

pm_buyer_idInteger

Indicates the PubMatic's buyer ID.

PubMatic maintains its own list of buyer IDs as well as DSP specific Buyer ID list as well.

Whenever DSP sends the DSP specific buyer ID, PubMatic finds the mapping for this buyer ID and provides the pubmatic-buyer-id in API response.

Note: Valid value for pm-buyer-id > 0.

pm-buyer_id is populated in API response, if DSP sends DSP specific Buyer ID in request and there is a mapping in the PubMatic system for DSP specific Buyer ID. Otherwise, pm-buyer-id is not populated in the API response.
crtypeInteger
Indicates the type of creative. Example: vast (VAST 1.0, VAST 2.0, VAST 3.0), MRAID (MRAID 1.0, MRAID 2.0), Image Ad, HTML5, JS, and FLASH.
Note: For more details, refer to the "Creative Type Attributes" table. This field is optional.

 

A "crtype" attribute is be added to the JSON response:

{
    "PubMatic_Bid": {
        "ecpm": 3.311,
        "oid": "CADBE652-9FBB-4B67-B43D-A4CFF5E14589",
        "creative_tag": "<span class=\"PubAPIAd\"><!DOCTYPE html PUBLIC \\\"-\n//W3C//DTD XHTML 1.0 Transitional//EN\\\" \\\"htt\np://www.w3.org/TR/xhtml1/DTD/xhtml1-\ntransitional.dtd\\\"><html xmlns=\\\"http://www.w3.org/1\n999/xhtml\\\" xml:lang=\\\"en\\\" lang=\\\"en\\\"\n>MY OPEN RTB CAMPAIGN WON ID:8405713B-4F37-48C1-887F-A93EC1A54A12 BID_ID:1 IMP_ID:1 SEAT_ID:511\nAD_ID:42283 PRICE:4.3043 CUR:USD </html></span> <!-- PubMatic Ad Ends -->",
        "tracking_url": "http://127.16.4.40/AdServer/AdDisplayTrackerServlet?operId=1&pubId=35169&siteId=35170&adId=42283&adServerId=243&kefact=3.311000&kaxefact=3.311000&kadNetFrequecy=1&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1431370482&indirectAdId=0&adServerOptimizerId=2&ranreq=0.6210113655405912&kpbmtpfact=4.304300&dcId=1&tldId=0&passback=0&imprId=CADBE652-9FBB-4B67-B43D-A4CFF5E14589&oid=CADBE652-9FBB-4B67-B43D-A4CFF5E14589&campaignId=7741&creativeId=0&pctr=0.000000&wDSPByrId=511&pageURL=file%3A%2F%2F%2Fhome%2Fpubmatic%2FDocuments%2Fadtags%2Frtb_115.html&lpu=www.advdomain.com",
        "landing_page": "www.advdomain.com",
        "creative_id": "creative111",
        "crtype": 1,
        "iurl": "http://localhost",
        "dsp_camp_id": "campaign111",
        "dsp_id": 6,
        "autorefresh_time": 0,
        "prefetch_data": 0
    }
}

 

Standard JSON Response

The PubMatic ad server will return a pure JSON response, by default, for operId=102 or 201:


{
  "PubMatic_Bid": {
    "ecpm": 0.7,
    "creative_tag": "<Creative_Tag>",
    "tracking_url": "<PubMatic_Tracking_URL>",
    "click_tracking_url": "<PubMatic_Click_Tracking_URL>",
    "creative_id": "creative121",
    "iurl": "http://www.example.com/image.img",
    "dsp_camp_id": "campaign121"
  }
}

 

Pure JSON Response with JS variable definition

The PubMatic ad server will return a pure JSON response with JS variable for operId=102/201&rs=3.

Default value of rid is 0.


var pubMaticBid_<rid>={
  "PubMatic_Bid": {
    "ecpm": 0.7,
    "creative_tag": "<Creative_Tag>",
    "tracking_url": "<PubMatic_Tracking_URL>",
    "click_tracking_url": "<PubMatic_Click_Tracking_URL>",
    "creative_id": "creative121",
    "iurl": "http://www.example.com/image.img",
    "dsp_camp_id": "campaign121"
  }
};

 

Padded JSON Response

The PubMatic ad server will return a Padded JSON response for operId=102/201&rs=2.

Default value of rid is 0.

 

processPubMaticBid({
  "PubMatic_Bid": {
    "ecpm": 0.7,
    "creative_tag": "<Creative_Tag>",
    "tracking_url": "<PubMatic_Tracking_URL>",
    "click_tracking_url": "<PubMatic_Click_Tracking_URL>",
    "creative_id": "creative121",
    "iurl": "http://www.example.com/image.img",
    "dsp_camp_id": "campaign121"
  },
    "meta_data": {
        "rid": "0"
    }
})

JSON Error Response

If PubMatic Ad Server responds back with an error JSON response containing the following fields.

             

Field

Description

error_code

Indicates the ID of the error reported by the system.

error_string

Indicates the description of the error code reported by the system.

 

In case, an error occurs while processing an ad request with operId=102 or 201, the PubMatic ad server will return the following error responses.

As a part of the integration, you must handle the given error responses during integration.

If you provide the wrong tag parameter values for pubId, siteId, or adId, you will receive the following error response:


{
    "PubMatic_Bid": {
        "error_code": -1,
        "error_string": "Ad details not found.Please check the ad tag parameters"
    }
}

 

If the PubMatic system does not have any creative to fill an impression, you will receive the following error response:

 

{
    "PubMatic_Bid": {
        "error_code": -2,
        "error_string": "Unable to serve the request at the moment."
    }
}

JSON Response for Real-time Advertiser Category and Advertiser Blocking

Scenario 1: Ad network wins the impression

In this case, the response contains the ID of the winning ad network in the "adnet_id" parameter as mentioned below.


{
    "PubMatic_Bid": {
        "ecpm": 0.2,
        "creative_tag": "<span class=\"PubAPIAd\"><h1>This is Media with $0.20</h1></span><!-- PubMatic Ad Ends -->",
        "tracking_url": "http://127.16.4.40/AdServer/AdDisplayTrackerServlet?operId=1&pubId=44539&siteId=44540&adId=77836&adServerId=11&kefact=0.200000&kaxefact=0.200000&kadNetFrequecy=1&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1424425436&indirectAdId=100163&adServerOptimizerId=1&ranreq=0.02049813430046943&kpbmtpfact=0.000000&dcId=1&tldId=0&passback=0&imprId=9D4100C0-3CA3-464D-8B8A-31740BE89E37&pageURL=http%3A%2F%2Fgads.pubmatic.com%2FJK_Tags%2FBlock_AdvCat_DomainRealtime.html",
        "adnet_id": 11,
        "autorefresh_time": 0,
        "prefetch_data": 0
    }
}

Scenario 2: DSP wins the impression

In this case, the response contains the following additional parameters:

                       

ParameterDescription
advertiser_idPubMatic-specific ID of the advertiser associated with the winning creative.
domain_idPubMatic-specific ID of the advertiser's domain associated with the winning creative.
iabcategory_idList of IAB category IDs of the advertiser associated with the winning creative.
dsp_idPubMatic-specific ID of the winning DSP.

 

 

{
    "PubMatic_Bid": {
        "ecpm": 100,
        "creative_tag": "<span class=\"PubAPIAd\"><script type=\"text/javascript\"> document.writeln('<iframe width=\"728\" scrolling=\"no\" height=\"90\" frameborder=\"0\" name=\"iframe0\" allowtransparency=\"true\" marginheight=\"0\" marginwidth=\"0\" vspace=\"0\" hspace=\"0\" src=\"http://172.16.4.78/Adtags/impression_throttlinh_campaign_2_creative.html?\"></iframe>');</script></span> <!-- PubMatic Ad Ends -->",
        "tracking_url": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=44539&siteId=44540&adId=77836&adServerId=243&kefact=100.000000&kaxefact=100.000000&kadNetFrequecy=7&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1424426022&indirectAdId=0&adServerOptimizerId=2&ranreq=0.5080646512499468&kpbmtpfact=100.000000&dcId=1&tldId=0&passback=0&imprId=46ABE2C8-4605-430E-A87D-B06DEB7A27F6&campaignId=15763&creativeId=0&pctr=0.000000&wDSPByrId=2423&pageURL=http%3A%2F%2F172.16.4.74%2FASD_777%2Fimpression_throttling_adtag_1.html&lpu=banned.com",
        "landing_page": "banned.com",
        "creative_id": "429863",
        "advertiser_id": 1551,
        "domain_id": 6,
        "iabcategory_id": [
            "IAB22"
        ],
        "dsp_id": 6,
        "autorefresh_time": 0,
        "prefetch_data": 0
    }
}

 

VAST Request and Response for Video

This section provides information on the sample VAST-specific request and response used for serving Video ads.

Request:

http://vid.pubmatic.com/AdServer/AdServerServlet?adtagtype=3&pubId=45710&siteId=45711&adId=77032&vadFmt=2&vminl
=15&vmaxl=45&vtype=1&vpos=1&vminbtr=300&vmaxbtr=600
 

Response:

<VAST version="2.0">
  <Ad id="76711">
    <InLine>
      <AdSystem>PubMatic</AdSystem>
      <AdTitle>VAST 2.0 Instream Test</AdTitle>
      <Description>VAST 2.0 Instream Test</Description>
      <Impression/>
      <Impression>
        <![CDATA[
          http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=45710&siteId=45711&adId=77032&adServerId=165&kefact=0.000000&kaxefact=0.000000&kadNetFrequecy=1&kadwidth=0&kadheight=0&kadsizeid=97&kltstamp=1392899258&indirectAdId=97536&adServerOptimizerId=1&ranreq=NORANDOMNUMBERSPECIFIED&kpbmtpfact=0.000000&dcId=2&tldId=0&passback=0&imprId=73452F2E-EE1B-45C9-9562-FB69085379A2&pageURL=NOPAGEURLSPECIFIED
          ]]>
      </Impression>
      <Creatives>
        <Creative AdID="76711">
          <Linear>
            <Duration>00:00:30</Duration>
            <VideoClicks>
              <ClickThrough>http://www.pubmatic.com</ClickThrough>
              <ClickTracking id="PubMatic">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=99
                  ]]>
              </ClickTracking>
            </VideoClicks>
            <TrackingEvents>
              <Tracking event="creativeView">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=1
                  ]]>
              </Tracking>
              <Tracking event="start">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=2
                  ]]>
              </Tracking>
              <Tracking event="midpoint">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=3
                  ]]>
              </Tracking>
              <Tracking event="firstQuartile">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=4
                  ]]>
              </Tracking>
              <Tracking event="thirdQuartile">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=5
                  ]]>
              </Tracking>
              <Tracking event="complete">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=6
                  ]]>
              </Tracking>
            </TrackingEvents>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" bitrate="500" width="400" height="300" scalable="true"maintainAspectRatio="true">http://stagingpub.net/PubMatic_test_video.mp4</MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <Creative AdID="76711-NonLinear">
          <NonLinearAds>
            <TrackingEvents>
              <Tracking event="creativeView">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=1
                  ]]>
              </Tracking>
              <Tracking event="start">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=2
                  ]]>
              </Tracking>
              <Tracking event="midpoint">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=3
                  ]]>
              </Tracking>
              <Tracking event="firstQuartile">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=4
                  ]]>
              </Tracking>
              <Tracking event="thirdQuartile">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=5
                  ]]>
              </Tracking>
              <Tracking event="complete">
                <![CDATA[
                  http://aktrack.pubmatic.com/track?operId=7&p=45710&s=45711&a=77032&wa=165&ts=1392899258&e=6
                  ]]>
              </Tracking>
            </TrackingEvents>
            <NonLinear height="50" width="300" minSuggestedDuration="00:00:15">
              <StaticResource creativeType="image/jpeg">
                http://stagingpub.net/PubMatic_NonLinearAd_300X50.jpg
              </StaticResource>
              <NonLinearClickThrough>http://www.pubmatic.com</NonLinearClickThrough>
            </NonLinear>
          </NonLinearAds>
        </Creative>
        <Creative AdID="76711-Companion">
          <CompanionAds>
            <Companion width="300" height="250">
              <StaticResource creativeType="image/jpeg">http://stagingpub.net/PubMatic_test_ad_300x250.png</StaticResource>
              <CompanionClickThrough>http://www.pubmatic.com</CompanionClickThrough>
            </Companion>
            <Companion width="728" height="90">
              <StaticResource creativeType="image/jpeg">
                http://stagingpub.net/PubMatic_CompanionAd_728X90.png
              </StaticResource>
              <CompanionClickThrough>http://www.pubmatic.com</CompanionClickThrough>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Attachments

    Outcomes