Zeropark Documentation

Programmatic RTB integration (XML, JSON, OpenRTB)

The Programmatic RTB integration supports multiple feed formats (XML, JSON, OpentRTB*) and allows publishers to participate in Zeropark’s real-time bidding ad exchange (RTB auction). 

Once the integration process is complete, publishers are able to send their queries to the Programmatic feed (also called Zeroclick feed). Upon receiving a visit request from a publisher, Zeropark replies back with a bid derived in an RTB auction.

During the RTB auction, visitors are auctioned off to an extensive network of Zeropark advertisers allowing publishers to receive the highest bid available for a given visit.

*OpenRTB feed language needs a custom approach and should be discussed with the Zeropark Publisher team on an individual basis.

Integration overview:
  • Feed Language: XML, JSON, OpenRTB

  • Accepted Traffic: Pop, Domain, Search (Tiles)

  • Bid Format: CPV/CMP or CPC

  • Auction: external; internal

Integration flow:
  1. For Programmatic RTB integration types, a Zeroclick feed is needed.

  2. When an auction request is sent via Zeroclick feed to Zeropark, we parse it and reply with the auction bid and campaign URL.

  3. If Zeropark’s bid wins the auction, the visitor (sent by the publisher) will be redirected to the campaign URL under “redirecturl” parameter attached in the response. 

  4. Publishers need to choose the desired integration type and then set up the ad tag’s name and fallback URL.

    Note

    Publishers can overwrite a fallback set in their publisher account by sending &fallbackurl parameter in the request.

  5. An example request for chosen integration type will be visible in your Zeropark account once the feed is set up.

  6. Please remember to fill the parameters examples (domains, keywords) with actual data. 

  7. Sending the right parameters helps matching publisher traffic with the right supply.

  8. Sending real domains is crucial as blind domain feeds won’t be accepted.

  9. Once a feed is accepted, publishers can start sending requests. 

  10. If XML, JSON or OpenRTB integration is not possible, or publishers prefer to use a simple redirect option, creating a Direct URL ad tag is also possible.

Prerequisites:
  • Create a publisher account on Zeropark.com

  • Receive a feed ID

Feed queries specification:
  • Every query must be unique; feed responses cannot be cached.

  • The Zeroclick feed contains a range of required parameters, which must be passed in the feed call.

  • Publishers can add more parameters than the ones required by Zeropark or described below.

  • Parameters always come after the Zeropark domain with the protocol: http://feed.zeropark.com/zeroclick

  • They are provided after ‘?’ indicating the start of query parameters and separated with ‘&’. 

  • Parameters in a request can be placed randomly. 

  • All parameters must be URL encoded. Most web programming languages provide a method of encoding the URL to ensure that invalid characters are not included in the HTTP GET request.

  • Reference can be made to the HTTP specification from W3C for URL encoding details (http://www.w3.org/). 

  • OpenRTB offers similar parameters but the naming may vary (e.g. site.domain instead of domain).

Feed parameters specification:
  • Publishers can add more parameters than the ones required by Zeropark or described below.

  • Parameters always come after the Zeropark domain with the protocol: http://feed.zeropark.com/zeroclick

  • They are provided after ‘?’ indicating the start of query parameters and separated with ‘&’. 

  • Parameters in a request can be placed randomly. 

  • All parameters must be URL encoded. Most web programming languages provide a method of encoding the URL to ensure that invalid characters are not included in the HTTP GET request.

  • Reference can be made to the HTTP specification from W3C for URL encoding details (http://www.w3.org/). 

  • OpenRTB offers similar parameters but the naming may vary (e.g. site.domain instead of domain).

Feed request syntax:

For XML:

http://feed.zeropark.com/zeroclick?feedid=<feedid>&domain=<domain>&useragent=<useragent>&ip=<ip>&keywords=<keyword1,keyword2>&responseformat=XML&domainid=<domainid>&pubid=<pubid>&secure=true&fallbackurl=<fallback.com>

For JSON:

http://feed.zeropark.com/zeroclick?feedid=<feedid>&domain=<domain>&useragent=<useragent>&ip=<ip>&keywords=<keyword1,keyword2>&responseformat=JSON&domainid=<domainid>&pubid=<pubid>&secure=true&fallback=<fallback.com>

The required parameters include:

  • domain URL of the site where the user was generated. If not provided then we need domainid (one below).

  • ip visitor’s IP(v4) address in the dotted format to determine geolocation.

  • useragent visitor’s device specification (browser, OS, etc.) for device targeting.

  • feedid our unique ID assigned to that feed/Ad tag.

  • fallbackurl sending this parameter in the request will overwrite the fallback set from the feed level. This is especially helpful for Search traffic integration when a user needs to be redirected specifically to a brand page.

Example of XML query call using with the ‘domain’ parameter:

http://feed.zeropark.com/zeroclick?domain=example.com&ip=195.116.242.159&useragent=Mozilla/5.0%20%28Macintosh%3B%20U%3B%20Intel%20Mac%20OS%20X%3B%20en-US%3B%20rv%3A1.8.1.4%29%20Gecko/20070515%20Firefox/2.0.0.4&keywords=videos,movies&feedid=6019173b-675e-4852-98f4-d5g56fcgg861&x_for_ip=81.18.207.226&fallbackurl=fallback.com 

Publishers often include the following parameters, too:

  • domainid ID of the site where the user was generated. Domainid is not required if the domain parameter is provided, but both are recommended.

  • responseformat XML/JSON. For a publisher to set a response format.

  • pubid id of the external publisher who generated the user.

  • keywords keywords associated with the visited domain or site that generated.

  • deviceid mobile device id: IDFA, ADID, Android ID or WAID, if available.

  • secure true/false flag to enforce HTTPS protocol in our campaigns.

Feed response syntax:

For XML: Same syntax as HTML, but with custom (extensible) tags. Used for sending data between servers.

<?xml version= “1.0” encoding= “utf-8”?> 
<result>
<bid> [bid value] </bid>
<redirecturl> [url] </redirecturl> 
<clickid> [clickid] </clickid>
<campaignid> [campaign id] </campaignid>
</result>

The Zeroclick feed response contains the following parameters:

  • result the root element of the feed response document.

  • bid top net bid value for one visitor, expressed in USD.

  • redirect URL URL where the visitor should be redirected to.

  • clickid the ID assigned by Zeropark to each click (optional).

  • campaignid the ID assigned by Zeropark to each campaign.

Sample response:

<?xml version= “1.0” encoding= “utf-8”?> 
<result>
<bid> 0.123 </bid> 
<redirecturl> zk.zeroredirect1.com/zcvisitor/e22b18b0-b2fe-11e4-9c5d-126d14f8d723 </redirecturl> 
<clickid> e22b18b0-b2fe-11e4-9c5d-126d14f8d723 </clickid>
<campaignid>8d5ceab2-4df6-499f-bc63-dc078a35d9aa</campaignid>
</result>

In case of no coverage, the feed will return a bid of “0”.

Sample Response with no advertiser:

<?xml version= “1.0” encoding= “utf-8”?>
<result>
<bid> 0 </bid> 
<redirecturl></redirecturl> 
<clickid></clickid>
<campaignid></campaignid>
</result>

For JSON: Upgraded way of sending data between servers with the use of JavaScript. The same information as sent in the XML response but in a different format.

{
"bid": "0.02300",
"redirecturl": "http://proserpina-zeb.com/163761dd-1874-4435-8a13-772bde842677?campaignid		          =8d5ceab2-4df6-499f-bc63-dc078a35d9aa",
"clickid": "163761dd-1874-4435-8a13-772bde842677",
"campaignid": "8d5ceab2-4df6-499f-bc63-dc078a35d9aa"
}