XML Feeds

XML feeds is a traffic format in which ads are formatted using the eXtensible Markup Language. XML feeds are characterized by these features:

  • The response may contain several advertisements (multibid).

  • Trading takes place according to the CPC model, where the resulting cost measured by the number of clicks on ads (unlike CPM where the price is calculated on the basis of ad impressions).

  • Works for pop and push ad formats.
     

We use XML format for push and pop traffic trading, as Push and Pop are much more widely distributed in XML than in OpenRTB. Along with the CPC pricing model, this makes the XML format much more profitable. XML works only xml to xml and does not interact with RTB and VAST. Basically, Pop and push formats are equal in terms of technical implementation, but you can distinguish them considering Click rate value. For Pop format CTR is likely to be higher than push and is often about 50%.

 

Bidding and pricing between XML endpoints

In this format, the seller does not determine the price; it is determined by the advertiser using the data specified in the macros. However, you can set up Minimal Bidfloor on supply side to settle the minimal limit of the price in the response. That means that we will not consider the responses with the price lower than Min Bidfloor value.

Essentially, XML price is captured from demand response. But you can manipulate it as well. There is the field called Default CPC that you can set up. We will consider the value from there if there is no price provided in the XML response.

In addition, there is no margin on the SSP side, only on the DSP side. If Min bidfloor is not set, then we send CPC = CPC - platform’s margin on DSP side.

If the Min bidfloor field value on the SSP side is not empty, then it will not receive responses with [CPC - Margin] = less than Min bidfloor (CPC based on data from the response, or Default CPC if there is no field in the response).

Examples:

  1. Min bidfloor = $10. CPC in the response= $12. DSP Margin = 10%.
    $12 * 0.9 = $10.8, which is higher than Min bidfloor. The response with this CPC price is acceptable.

  2. Min bidfloor = $10. CPC in the response = $11. DSP Margin = 10%.
    $11 * 0.9 = $9.9, which is lower than Min bidfloor. Such response will not be accepted.

  3. Min bidfloor = 0. CPC in the response = $12. Margin = 20%.
    Response is acceptable.

 

If the macro {count} is replaced by a number greater than 1, then the response will contain the specified amount of advertising (sorted by the maximum price, regardless of the endpoint). In this case, the spend is calculated by the number of clicks.

If there is more than one response, then the response with the highest original CPC wins.

 

After the request is received, we parse the macros and check:

  • IP validity

  • UA validity

Then we send GET requests to DSPs (in accordance with the endpoint’s filters).

Then we are getting responses.

Then, we send the bid (in accordance with the formula ‘CPC – margin’).

Once the ad is loaded to a web page or an application, the impression URL is fired, and we count an impression. When a click occurs, we track and count this event via the click URL.


Important count method notes that should be considered when comparing discrepancy with the partners:


1. When responses from demand side comes in, it contains imp and click URLs inside. At this stage we cache them and store them in Data Base. We provide supply partners with the response with our imp and click URLs and when they really happen, we call DSP’s URLs stored in Data Base.

2. We do not allow double click for 1 request, because it is more likely to be fraud. So 1 request can be associated with 1 impression and 1 click only.


 


 

XML integration

Please, note: the same company can’t have OpenRTB and XML endpoints at the same time.

Therefore, if an OpenRTB company needs to have also XML endpoint, then another one company must be created.

SSP side

To create an XML endpoint, go to the SSP endpoints list in the Main section, and click [New Endpoint]:

 

You will see a new endpoint’s page:

 

The following information must be specified for the SSP side:

Required fields:

  • Name

  • Connection Type – XML Feed.

  • Company – the company that owns the endpoint.

  • Region

 

Optional settings:

  • Spend limit

  • Min Bid Floor – minimally acceptable bid floor. This function is needed just to set the minimal earning, but mainly the price is declared by demand side and the system always searches for match between supply and demand price pre-defined in XML response from demand side.

 

Platform Statistic API link

Such link allows to set (and test) an API link for statistics.

 

SSP’s statistic API link

This is an auto-generated API link to provide the SSP partner with statistics.

The link may look like:

http://partnerdomain.com/api/report/xml/%7Bssp%7Cdsp%7D?token={token}&endpoint={dsp_id|ssp_id}&from={date_from}}&to={date_to}

 

Filter Lists:

DSP (only XML DSPs are available). 

 

Generate Endpoint

There will be an auto-generated link, that looks like the following link:

http://endpoint.domain.com/?seat=constseat&token=consttoken&ua={ua}&ip={ip}&url={url}&domain={network}&empty=204

 

Provide the partner with this link to call for a bid request. 

The publisher sends a request via this link with the replaced macros, so the resulting request should look like the following:

http://endpoint.domain.com/?seat=121294t&token=90412814&ua=(ua=Mozilla%2F5.0+%28Windows+NT+10.0%3B+Win64%3B+x64%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F80.0.3987.163+Safari%2F537.36)&ip=123.24.12.21&url=somedomainurl1.com/article/14&domain=somedomainurl1.com&empty=204

 

Macros that can be added to the autogenerated link to provide additional information in a bid request.

The list of available macros that you can include in the link:
domain (&domain={network})
image_size (&image_size={image_size})
image_required (&image_required={image_required})
icon_size (&icon_size={icon_size})
icon_required (&icon_required={icon_required})
country (&country={country})
user_id (&user_id={user_id})
lang (&lang={lang})

subscription_timestamp (&subscription_timestamp={timestamp})

format (&format=json)

count (&count={count})

 

List of supported macros, that can be provided by the partner (even if not specified in our link):

seat

Required

Your unique identifier

token

Required

Authorization token

{ua}

Required

User Agent (ua=Mozilla%2F5.0+%28Windows+NT+10.0%3B+Win64%3B+x64%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F80.0.3987.163+Safari%2F537.36)

{ip}

Required

IP (IP address, MUST support IPV4, IPV6,&ip=90.164.191.192 ) 

{url}

Required

URL of the page where ads from this feed will be displayed

{network}

Optional

Encoded referrer domain (Usually push publisher don’t pass domain in the referrer, so to avoid any issues with traffic origin this parameter should send NETWORK domain, e.g. &domain=http%3A%2F%2Fsmarthub.com ALWAYS)

{image_size}

Optional

Main image size in format ###x###. Default value: 150x150.

{image_required}

Optional

If set to 1, it allows only ads with main image to be returned. Default value: 0.

{icon_size}

Optional

Icon image size in format ###x###.

{icon_required}

Optional

If set to 1, it allows only ads with icon image to be returned. Default value: 0.

{country}

Recommended

Country of a request (three symbol country abbreviation, e.g. KOR)

{user_id}

Optional

Unique user ID

{lang}

Optional

Two-symbol language abbreviation, e.g. en

{timestamp}

Recommended

UNIX timestamp, e.g. 1586763000 Which is equivalent to:

04/13/2020 @ 7:30am (UTC)

{format}

Optional

When adding this macro explicitly substitute & format = json

{count}

Optional

The integer number indicating the number of ads requested. If the macro is not replaced, then consider 1 by default.

 

 

Click ‘Macros’ to open the entire list of macros available:

 

 

DSP side

To create an XML endpoint, go to the DSP endpoints list in the Main section, and click [New Endpoint]:

You will see a new endpoint’s page:

 

 

Set the following fields:

Required fields:
Name
Connection Type – XML Feed.
Company – the company that owns the endpoint.
Region
Margin

Click TTL – time-to-live of the click info (24 hours by default, 12 hours optional). This is about how long we are waiting for click to happen in order to count. This is something similar to expiry window for impression in RTB environment.

 

Optional fields:
Default CPC – the default cost-per-click to be applied if there is no such field in the response
Spend Limit
QPS Limit
Ad Types
Statistic API link
 

Filter Lists:

SSP (allow or block; only XML SSPs are available). 

Countries (allow or block).

Mismatched IP Filter - if the impression occured for IP that differs from the IP in the request, we block such traffic for that DSP using a key: sspId+IP+domain (from URL).
Double Click Filter - must track double clicks in one second (synchronizing of all cores) and stop sending requests to this DSP with the key sspId+IP+domain (from URL).


 

The response would be in the following format:

XML:

<results>

<ad>

<title>${ad.title}</title>

<desc>${ad.desc}</desc>

<link-url>${ad.linkUrl}</link-url>

<bid-price>${ad.bidPrice}</bid-price>

<click-url>${ad.clickUrl}</click-url>

//one of

<image-url>${ad.imageUrl}</image-url>

<icon-url>${ad.iconUrl}</icon-url>

</ad>

</results>

JSON:

{

results: [

{

title: ad.title,

desc: ad.desc,

  linkUrl: ad.linkUrl,

bidPrice: ad.bidPrice,

clickUrl: ad.clickUrl,

//one of

imageUrl: ad.imageUrl,

iconUrl: ad.iconUrl

        },

]

}

 

 

Report


 

Columns:

  1. Date 

  2. SSP Endpoint

  3. DSP Endpoint

  4. GEO - we get the country from the request. If not specified or not correct - we obtain it from Maxmind. If the country is not known / incorrect - then we don’t send a request (and add it to the dropped requests statistics).

  5. Requests - the number of requests to this SPP endpoint.

  6. Responses - the number of responses from the DSP.

  7. All impressions - the number of impressions. 

  8. Icon impressions - how many times icons were shown (the number of impressions based on icons)

  9. Image impressions - how many times images were shown (the number of impressions based on images)

  10. All clicks - the number of clicks.

  11. Icon clicks - how many clicks occured (the number of clicks based on icons)

  12. Image clicks - how many times clicks occured (the number of clicks based on images)

  13. CTR - (Clicks count*100/impressions count) percentage.

  14. Errors - errors while parsing. Reasons: no creative, no CPC (and any errors that made it impossible to send a response).

  15. SSP spend - amount to be paid to the SSP (the cost of the click for SSP = CPC from DSP – margin).

  16. DSP spend - amount that must be paid by DSP (CPC from DSP)

  17. Profit - calculated by the formula: DSP Spend – SSP Spend.


 

Billing

 

Billing section contains the statistics received via API links. If an XML company is selected, then instead of Impressions, the Clicks will be displayed, and the statistics will only be based on Clicks.