Redirect RTB integration (XML, JSON, Open RTB)

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 can 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.

• Feed Language: XML, JSON, OpenRTB
• Bid Format: CPV/CPM
• Auction: external; internal

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. The next step is to configure the appropriate feed by the Account Manager.

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

5. An example request for a 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 match 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 feed is also possible.

• Create a publisher account on Zeropark.com
• Receive a feed ID

• 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).

• 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).

XML Request Example:

https://feed.zeropark.com/zeroclick?feedid=<feedid>&domain=<domain>&useragent=<useragent>&ip=<ip>&keywords=<keyword1,keyword2>>&responseformat=XML&domainid=<domainid>

JSON Request Example:

https://feed.zeropark.com/zeroclick?feedid=<feedid>&domain=<domain>&useragent=<useragent>&ip=<ip>&keywords=<keyword1,keyword2>>&responseformat=JSON&domainid=<domainid>

The required parameters include:

• domain URL of the site where the user was generated.
• 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 Zeropark's unique ID assigned to that feed.
• fallbackurl When the visit is invalid or unsold, the visitor will be sent to the fallback URL provided by the publisher. Sending this parameter in the request will overwrite the fallback set from the feed level.

Example of XML query call using 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 (source) who generated the user.
• keywords keywords associated with the visited domain or site where visitor was generated.
• deviceid mobile device id: IDFA, ADID, Android ID or WAID, if available.
• secure Secure flag set to true enforces HTTPS protocol in all URLs and limits campaigns to ones that provide valid HTTPS redirection.

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>example.com/zcvisitor/e22b18b0-b2fe-11e4-9c5d-126d14f8d723</redirecturl> 
<clickid>e22b18b0-b2fe-11e4-9c5d-126d14f8d723</clickid>
<campaignid>8d5ceab2-4df6-499f-bc63-dc078a35d9aa</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"
}