Do you want to buy traffic using XML/JSON feeds? Then this article is for you! Here, we will explain how to configure your feeds to buy traffic using XML/JSON from 3rd-party ad servers. If you would like to sell traffic using XML/JSON feeds, you might want to check out this article.
XML/JSON feeds (or server-side tags) are helpful for establishing communication between different ad servers to exchange ads.
Adserver.Online supports XML/JSON feeds for Banners, Direct Links, Popups, Push notifications, In-Page notifications, and Native ad formats.
VAST S2S/in-app tags are described in this article.
How to configure XML/JSON feeds to buy traffic
Firstly, you must enable server tag mode for a particular zone in its Publisher / SSP options. Otherwise, feeds will not work.
Also, you need to set up a revenue model for this zone.
Afterward, you will find an XML/JSON endpoint on the zone view page.
Finally, you must send the endpoint URL to your supply partner to configure it in their ad system.
Since feeds are not standardized, you also must provide the supply partner with feed documentation. The link to the documentation is located on the same page, below the endpoint URL.
Endpoint parameters
https://srv.aso1.net/feed/bidder?zid={zone_id}&type={type}&ip={ip}&referrer={referrer}&ua={user_agent}
Parameters
- zid – Required. Zone ID.
- type – Required. Feed type: link, popup, push, inpage, native
- ip – Required. IP address of the visitor.
- ua – Required. User-Agent header from the visitor's HTTP request. It must be in URL-encoded format.
- page – Optional. URL of the page where the ad will be displayed. It must be in URL-encoded format.
- referrer – Optional. URL of the page from where a visitor has come. It must be in URL-encoded format.
- uid – Optional but highly recommended. User's unique identifier.
- lang – Optional. The language of the visitor. It must be in an Accept-Language header format.
- refid , refid1– Optional. Reference ID (subid). Up to 50 alphanumeric and special characters are allowed. You will be able to view statistics for each refid, refid1.
- refid2 … refid9 – passthrough parameters. Therefore, there are no stats.
- format – Optional. xml, xml_ak, or json. xml by default. If you specify xml_ak then the response format will be compatible with AdKernel.
- pmodel – Optional. Pricing model filter. Possible values: 1 – CPM, 2 – CPC.
- cur – Optional. Overrides bid currency. Value is ISO-4217 alpha currency code. Supported currencies.
Response codes
- 200 – Successful response
- 204 – Empty response. No ads were found
- 400 – Required parameters are missing or incorrect
- 404 – Zone is inactive, or server tag is not enabled
Bids
As a buyer, you must specify bids or prices you are ready to pay for an impression (in case you win an auction in the supply party system).
Since a zone is responsible for the XML/JSON endpoint logic, the bid configuration is located on the zone form – Revenue Model fields in the Publisher / SSP section.
You can select between two bidding strategies: Flat Rates and Revenue Share.
In the case of Flat Rates, your bid will be constant. In the case of Revenue Share, the bid will depend on the campaign's rate.
Read more about how the calculation works.
Pricing Model
By default, the feed can respond with any available campaigns regardless of their pricing model.
It won't be an issue if you have only CPM or only CPC campaigns. However, if you have both, it will be a mess.
In the case of multiple pricing models in use, it's recommended to use the "pmodel" parameter to limit the endpoint to one of them.
For example, if you specify "&pmodel=1", the feed will only use CPM campaigns for bidding.
Currency
By default, the system uses the currency configured in the Settings / Common menu as the bid currency.
If the currency specified in the request (via the cur parameter) differs from the default, it will be automatically converted. Supported currencies.
For example, if your adserver currency is USD (set in the Settings / Common menu) but the cur=EUR parameter is specified, the bid will be automatically converted to EUR.
Reporting
Besides standard statistics, e.g., impressions and clicks that you can find in the Reports / Statistics menu, Adserver.Online provides extended data in these special reports:
1 . In the Reports / SSP responses report, you can find all incoming requests to your endpoints, including average bid, error rate, etc.
How to buy traffic using XML/JSON feeds – Examples
Please note that since Direct link and Popup are almost identical formats, we only made examples of Direct link.
Direct link endpoint with replaced placeholders
https://srv.aso1.net/feed/bidder?zid=34921&type=link&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<clickUrl>https://track.aso1.net/link?_d=UllSCgdRAwAABWVwGVQJcVgMDAAZRVQ%3D%3D&r=4033348884&clk=</clickUrl>
<idad>87033</idad>
<bid>1.2345</bid>
</result>
Direct link endpoint in AdKernel format
https://srv.aso1.net/feed/bidder?zid=34921&type=link&format=xml_ak&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<listing url="https://track.aso1.net/link?_d=UllSCgdRAw8DFVNZVg8JABVB14AV1NUUA%3D%3D&r=654711959&clk=" bid="1.2345"/>
</result>
Popup endpoint with replaced placeholders
https://srv.aso1.net/feed/bidder?zid=35128&type=popup&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<clickUrl>https://track.aso1.net/pop?_d=UllSCgdRAw8DFVUAVRAwQBWwBV&r=4668199820&clk=</clickUrl>
<idad>87291</idad>
<bid>1.2345</bid>
</result>
Push Notification endpoint with replaced placeholders
https://srv.aso1.net/feed/bidder?zid=44418&type=push&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<title>Test Push #1</title>
<description>Check out knowledge base for details</description>
<iconUrl>https://track.aso1.net/wtf.gif?yyyyyyy</iconUrl>
<imageUrl></imageUrl>
<clickUrl>https://track.aso1.net/click?_d=xxxxxxxx</clickUrl>
<pixelUrl></pixelUrl>
<idad>106199</idad>
<bid>0.01</bid>
</result>
InPage Notification endpoint with replaced placeholders
https://srv.aso1.net/feed/bidder?zid=100800&type=inpage&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<title>Flexible Ad Server</title>
<description>Your agile adserving solution</description>
<imageUrl>https://track.aso1.net/wtf.gif?yyyyyyyy</iconUrl>
<clickUrl>https://track.aso1.net/click?_d=xxxxxxxx</clickUrl>
<pixelUrl></pixelUrl>
<idad>209828</idad>
<bid>0.123</bid>
</result>
Native endpoint with replaced placeholders
https://srv.aso1.net/feed/bidder?zid=36078&type=native&ip=82.131.34.62&referrer=http%3A%2F%2Fexample.com&ua=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_14_2%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F71.0.3578.98+Safari%2F537.36
Response
<?xml version="1.0" encoding="UTF-8"?>
<result>
<title>Vertical template with image</title>
<description>Lorem ipsum dolor sit amet</description>
<imageUrl>https://track.aso1.net/wtf.gif?yyyyyyyyy</imageUrl>
<clickUrl>https://track.aso1.net/click?_d=xxxxxxxxxxx</clickUrl>
<iconUrl></iconUrl>
<cta>Buy now</cta>
<label>Ads</label>
<idad>88505</idad>
<pixelUrl></pixelUrl>
<bid>0.017</bid>
</result>
Conclusion
This article contains sufficient information on how to set up server-side tags and buy traffic using XML/JSON feeds. This feature might open new opportunities for your online business and help you scale up.
IMPORTANT: If you plan to buy traffic using the XML/JSON feeds, you should understand that you're about to participate in an auction. In this case, each XML/JSON request generates an ad server request. But that doesn't necessarily mean that each of your XML/JSON requests will result in an impression. That happens due to the nature of an auction when only XML/JSON requests that won the auction can result in impressions.
NB: Manuals/documentation from your partners are needed when you contact our support team with questions about XML/JSON integration.