Reporting XML API Reference

Simple Publisher Reporting XML API has been designed to provide the publishers with requests (searches), clicks, invalid clicks, and revenue data for the desired period of time.

Request URL:

http://api.adx1.com/api/reports/?from=[from_date]&to=[to_date]&segment=[segment]&output=xml&api_key=[api_key]

Request parameters:

The XML Request should contain the parameters listed below:

Parameter  Type Description
from* Date Report start date. If not provided returns the report for the current server date. Example: &from=2016-04-02
to* Date Report end date. Example: &to=2016-04-08
segment* String Allowed values: hour dayplacement (corresponds to subid)
site_id (corresponds to feedid)
site_id:placement (allows to collect stats from sub IDs mapped to a separate feed ID)

Example: &segment=hour

output* string xml or json
api_key string Your API key

* – non-obligatory parameter

Example response:

<response>
<result>
<record>
<conversions>0</conversions>
<publisher_profit>15.266401853412</publisher_profit>
<bad_clicks>211</bad_clicks>
<bids>38521</bids>
<clicks>12530</clicks>
<requests>293764</requests>
<impressions>1291</impressions>
<total_conversions>0</total_conversions>
<name>2016-04-20</name>
<conversion_rate>0</conversion_rate>
<coverage>0.13113</coverage>
<bad_click_percent>1.656</bad_click_percent>
<ecpc>0.00122</ecpc>
<ecpm>0</ecpm>
<ecpa>0</ecpa>
<cvr_percent>0</cvr_percent>
<ctr_percent>0</ctr_percent>
</record>
</result>
<total>
<name>Total/</name>
<clicks>29121</clicks>
<conversion_rate>0</conversion_rate>
<total_conversions>0</total_conversions>
<requests>2973808</requests>
<conversions>0</conversions>
<bad_clicks>2796</bad_clicks>
<bids>410247</bids>
<coverage>0.13795</coverage>
<publisher_profit>75.87302963915</publisher_profit>
<bad_click_percent>8.76</bad_click_percent>
<ecpc>0.00261</ecpc>
<ecpm>0</ecpm>
<ecpa>0</ecpa>
<cvr_percent>0</cvr_percent>
<ctr_percent>0</ctr_percent>
</total>
</response>

Exchange Specific Guidelines for Native Ads

Please note your creatives should follow the guidelines provided below.

Technical Requirements

SSP Image Title Description Brand/ Sponsored by Other Notes
AdBlade Format: JPG preferred
Image size:1200x628px
File size: under 2 MB
Max 25 characters (short description) Max 100 characters (long description) N/A Not all short and long descriptions will appear together on every ad. Please make sure short and long descriptions make sense shown alone or together
AdsKeeper Format: JPEG, PNG Max 65 characters. Each word in the title should be capitalized Max 70 characters.
Only the first letter should be capitalized
N/A Title and advertising text should be both grammatically correct, unique and stylistically consistent
Adyoulike Landscape, 1800px (min)
Format: JPEG, PNG
File size: 100MB (max)
Tips: Image should be a raw file with no text, no logo
Max 60 characters with spaces Max 200 characters with spaces N/A Call to action: Max 60 characters with spaces
Avocarrot Min width: 300, min height: 250
Format: JPEG, PNG
N/A
N/A
N/A N/A Icon image – min width: 50, min height: 50 N/A
Disqus Ideal landscape aspect ratio of 4:3
Original source image of 640 x 480 or larger
No animated GIFs
Max 50 characters Max 175 characters
3 lines
Sponsored by: max 15 characters N/A
MGID Format: png, jpg, jpeg, jpg
Image size: 492×328 (min)
File size: 5 MB (max)
Max 65 characters
Each word in the title should be capitalized.
Max 70 characters.
Only the first letter should be capitalized
N/A Title and advertising text should be both grammatically correct, unique and stylistically consistent
NativeAds Image size: min 400×400 px, max 1200×627 px
Format: JPG, PNG, or non-GIF formats
File size: up to 3.5MB
The initial word and all major words must be capitalized N/A Brand names must follow correct grammar and formatting structure. All initial letters should be capitalized N/A
Patrius Image size: min 90×90 px
Format: JPG, PNG
Max 30 characters with spaces Max 60 characters with spaces Max 20 characters with spaces N/A
SmartyAds Image size: 600x314px (min) 1200x627px (max) Max 40 characters Max 30 characters Sponsored by: max 25 characters N/A
TripleLift No text on the image
Format: JPEG, PNG Image size: 300x300px (min), best size – 1200x1200px File size: 1 MB (max)
Max 30 characters with spaces Max 200 characters with spaces N/A No image in the Logo field

 

Content Requirements

SSP Prohibited Content Restricted Content
AdBlade
  • Alcohol
  • Illegal drugs usage or drug related paraphernalia
  • Online pharmacies
  • Tobacco
  • Firearms, weapons, fireworks, ammunition or explosives
  • Gambling (where prohibitied)
  • Any activities are unsafe, illegal or dangerous
  • Content that defames, misrepresents or contains disparaging remarks about other people, products or companies
  • Fake government grants
  • Cash advance/payday loan
  • PC clean up and software downloads
  • Pornographic
  • Violent
  • Derogatory of any ethnic, racial, gender, religious, professional or age group
  • Generally perceived as profane or obscene
  • Content that endorses any form of hate
  • Websites that contain harmful applications or programs such as viruses, spyware, malware
N/A
Adskeeper, MGID
  • Dating services facilitating sexual encounters
  • Exploitation or endangerment of minors
  • High-risk investments or impossible get-rich-quick schemes
  • Illegal subject matter or promotion of illegal activity
  • Illicit or digital drugs
  • Malware, phishing, or spam
  • Material that is abusive, discriminatory, exploitative, harassing, hateful, intolerant, obscene, offensive, threatening, violent, or vulgar
  • Misleading, inaccurate, or deceitful information
  • Online pharmacies
  • Poor grammar and misspellings
  • Pornography or erotica
  • Products or services claiming to predict the future
  • Slanderous reports
  • Terrorism
  • Tobacco or nicotine
  • Unauthorized celebrity endorsements
  • Violating third party rights: copyright, trademark, privacy, publicity, or other personal or proprietary rights
  • Weapons and explosives
  • Alcohol
  • Dating sites
  • E-cigarettes and vaping products
  • Financial services
  • Gambling
  • Political campaign advertising
  • Religion
  • Self-improvement products that claim unrealistic outcomes
  • Software downloads
  • Subscription services
  • Supplements
  • Sweepstakes or contests
  • Weight loss products
Adyoulike, Disqus, SmartyAds, TripleLift
  • Unmoderated UGC
  • Extreme Graphic/Explicit Violence
  • Pornography
  • Profane Content
  • Hate Content
  • Under Construction
  • Incentivized
  • Illegal Content
  • Warez
  • Spyware/Malware
  • Copyright Infringement
  • Cigars
  • Gambling
  • Cocktails/Beer
  • Wine
  • Religion & Spirituality
  • Dating
Avocarrot
  • Violence
  • Obscenity and sexual material
  • Alcohol & Tobacco
  • Anti or Hateful Speech
  • Drugs
  • Gambling
  • Prostitution
  • Content promoting Weapons
N/A
NativeAds A. Prohibited products, services or offers:    

  • Alcohol beverages
  • Illegal drugs or tobacco, including e-cigarettes
  • Class-action suits or malpractice claims
  • Degrees, diplomas or essays for sale
  • Firearms, weapons, ammunition, shooting lessons or certification
  • Fireworks or firecrackers
  • Gambling and related games, contests or sweepstakes
  • Illegal file sharing or hacking services
  • Political or religious ads promoting one group over another
  • Non-government approved pharmaceuticals and supplements
  • Securities, financial services, high-risk investments or business scams
  • Information harvesting
  • Excessively personal, niche or subscriber-only content
  • Content endangers, exploits or is generally inappropriate regarding minors
  • Weight loss and skincare products (i.e. Garcinia Cambogia)

B. Hateful, defamatory or offensive content:

  • Close up images of body parts, medical conditions, blood or bodily fluids
  • Hate, violence, suffering, exploitation or discrimination
  • Bigotry, baiting or similar techniques used to promote products, services or offers
  • Fear, tragic events, sensitive political or cultural topics leveraged to promote offers or products
  • Defames an individual, organization, competitor or group of people

C. Spam content: 

  • Sponsored links or other ads as the primary content or where the pages is for the purpose of arbitrage
  • Links to low quality content for SEO boosting
  • Hidden links or text, links not in context with content or links that redirect traffic to parent company

D. Sexually explicit or R-rated content:   

  • Total, partial or suggested nudity
  • Sexual descriptions, references, puns or innuendo
  • Content that is overtly sexual in nature
  • Cannot be classified as G, PG or PG-13
  • Escort, prostitution or other sexual services

E. Malware: 

  • Adware, malware, spyware, virus or Trojan horses
  • Tech support content (fake system prompts)

F. Government or law enforcement related content:     

  • U.S. or Canadian government offers, grants, buildings, documents, officials or symbols
  • Law enforcement officials or vehicles promoting unrelated offers
N/A

 

How to whitelist/blacklist sources and domains

Here is the instruction how to whitelist/block the publisher.

  1. Go to “Campaigns”.
  2. Scroll down till the end of the page until you find “advanced settings” link.
  3. Click “advanced settings” and find “Sources and domains whitelist / blacklist” section.
  4. Tick “Enable Sources and domains whitelist / blacklist” and choose “Sources and domains blacklist” or “Sources and domains whitelist” frame.
  5. Specify the traffic sources you want to whitelist/blacklist for this campaign by using one of the allowed formats.

Concerning the FORMATS,

  • domain – represents specific domain, e.g. example.com. When whitelisting/blacklisting a specific domain, it means all matching domains of all publishers will be whitelisted/blacklisted.
  • pub_id – represents ID of specific publisher, allows you to whitelist/blacklist the publisher itself with all its sites and placement IDs (subs).
  • site_id – represents ID of specific site, allows you to whitelist/blacklist publisher’s specific site. NB site_id is a unique ID of a specific site within specific publisher, it means choosing site_id you whitelist/blacklist certain publisher’s specific site only.
  • sub_id – represents specific placement ID (sub). When whitelisting/blacklisting a specific placement ID, it means all matching placement IDs (subs) of all publishers will be whitelisted/blacklisted.
  • pub_id:*:* – represents ID of certain publisher with all its sites (*) and placement IDs (*), allows you to whitelist/blacklist the publisher itself with all its sites and placement IDs.
  • pub_id:*:sub_id – represents specific placement IDs (subs) within certain publisher within any sites (*), allows you to whitelist/blacklist all placement IDs of one publisher within all its sites.
  • *:*:sub_id – represents specific placement IDs (subs) within any publisher (*) and any site (*). When whitelisting/blacklisting a specific placement ID within any publisher and any site, it means all matching placement IDs (subs) of all publishers within all sites will be whitelisted/blacklisted.
  • pub_id:site_id:* – represents certain publisher’s specific site with all its placement IDs (*), allows you to whitelist/blacklist certain site within one publisher with all its placement IDs (subs).
  • pub_id:site_id:sub_id – represents certain publisher’s specific placement ID within specific site, allows you to whitelist/blacklist certain placement ID within specific site of a specific publisher.
  • *:site_id:sub_id – represents specific placement ID within specific site and within specific publisher (as long as site_id is a unique ID that can be found only within specific publisher, any publisher (*) in this format is written to make it easier). When whitelisting/blacklisting due to this format, certain placement ID within specifiic site of a specific publisher will be whitelisted/blacklisted.
  • *:site_id:* – represents ID of specific site regardless of its placement IDs but within a specific publisher (as long as site_id is a unique ID that can be found only within specific publisher, any publisher (*) in this format is written to make it easier), allows you to whitelist/blacklist certain publisher’s specific site with all its placement IDs.
  • pub_id:domain:* – represents specific domain, e.g. example.com, within certain publisher regardless of its placement IDs (*), allows you to whitelist/blacklist certain publisher’s specific domain with all its placement IDs.
  • pub_id:domain:sub_id – represents certain publisher’s specific placement ID within specific domain, allows you to whitelist/blacklist certain placement ID within specific domain of a specific publisher.
  • *:domain:sub_id – represents specific placement IDs within specific domains regardless of publishers (*). When whitelisting/blacklisting due to this format, all matching placement IDs within matching domains within all publishers will be whitelisted/blacklisted.
  • *:domain:* – represents specific domains, e.g. example.com, within any publisher regardless of placement IDs. When whitelisting/blacklisting specific domain due to this format, it means all matching domains of all publishers with all placement IDs will be whitelisted/blacklisted.
  • * – represents an empty string, i.e. any value;

WITHIN ONE PUBLISHER you can whitelist/blacklist:

  • publisher itself with all its sites and placement IDs (subs) (use pub_id or pub_id:*:* format);
  • publisher’s specific sites (use site_id or pub_id:site_id or pub_id:site_id:* format);
  • publisher’s specific subs in the whole (use pub_id:sub_id or pub_id:*:sub_id format) or publisher’s specific subs within specific sites (use pub_id:site_id:sub_id format).

How to use postback URL

Postback URL allows you to send the information about conversions to the PPCmate reports. This way you to track ROI on the reports page and optimize campaigns to achieve better results.

You can access Postback URL on the campaign set up page. It will look like this:

http://rtb.adx1.com/log?action=conversion&key={click_id}&price=return_value_USD

Please replace the “return_value_USD” to whatever value you want to use a conversion price. This will later be reflected in the reports.

You can find more information regarding postback and how to use it here:

https://www.quora.com/What-is-a-Postback-URL

How to use a tracking pixel

You can use tracking pixels to collect website visitors into segments and then later target them in the campaign. Using pixels also allows you to send the information about conversions to the PPCmate reports and track conversions there.

There are 2 ways to add a pixel:

  1. Go to the Pixels page and click New pixel. Enter the pixel name, how long the visitor will remain in the segment and the advertiser you create this pixel for. After that the pixel will appear on the Pixels page. To get the code of the pixel you have just created please click Get Code.
  2. Create a new campaign and select Script from the available tracking types. You will see the code you need to upload on the website.

To target visitors you collected in the pixel data segment, please select your pixel under the Available segments – 2nd party data tab.

Tips to optimize a campaign

If you already know what type of offer you would like to advertise, the next thing would be to have various creatives for your offer. This will be really helpful later when we will be testing which creatives work and which don’t. You can use image banks or search engines to find images for your creatives.

Now, we need to use a postback URL. This will allow us to see which clicks provided conversions. We need to use the {CLICK_ID} macros and enter the $ value of the conversion in the pixel like this:

http://rtb.adx1.com/log?action=conversion&key={CLICK_ID}&price=5

The Postback URL can be accessed on the campaign page.

Now you need to upload your creatives in our system. We support several creatives within one campaign which is very convenient because it can save you a lot of time.

After that, we need to go to the Reports page and see how our campaign performs. Since we are sending the information about conversions to the reports using Postback URL we can optimize the campaign using this information.

For example, we can make a breakdown by domains and see ROI for each of the domains. To do this, we need to select Domains in the reports dimensions. After you found domains with the lowest ROI, you can block the domains with low ROI in the domains black list.

Another useful metric is a ROI breakdown by creatives. Since we are testing various creatives it is useful to see CTR and ROI for each of the creatives we uploaded. We can then stop the creatives with low CTR and ROI.

Sometimes as many as 100 creatives can be required to find the best ones.

Hopefully, after blocking low performing domains, creatives and testing different offers and landing pages you will be able to have positive ROI using our network.

Requests, Users and Rank

Requests indicates the number of ad opportunities that are available for your targeting. Whether or not a request will yield an impression depends on your CPM.

Users means how many unique users are available for your targeting.

Rank means the place of your ad in the in house auction. The higher the rank is, the more volume you will get.

How to now which SSP I will be getting traffic from?

To see available SSPs, please create either a Display or Native campaign. After that, please click Advanced settings and select Run on all sources checkbox from the Supply partners tab.

It will show you all available traffic sources for the channel you selected.

 

What macros can I use?

Here is the list of available macros:

[RANDOM_NUMBER]
[UNENCODED_CLICK_REDIRECT]
[ENCODED_CLICK_REDIRECT]
[DBL_ENCODED_CLICK_REDIRECT]
[USER_ID] – returns a unique ID of the visitor
[IFA] – returns a device IFA
[USERAGENT]
[IP]
[LAT]
[LON]
[REQUEST_ID]
[BID_ID]
[IMPRESSION_ID] – returns a unique impression ID
[CLICK_ID] – returns a unique click ID
[SITE_ID] – returns a unique website ID
[PUBLISHER_ID] – returns a unique ID of the publisher that can contain several websites
[SSP_ID] – returns a unique SSP ID
[HTTP_REFERRER] – returns HTTP referrer of the visitor
[PAGE_URL]
[DOMAIN] – returns the domain name
[PROTOCOL]
[PLACEMENT_ID] – returns a unique ad placement ID
[COUNTRY_CODE]
[COUNTRY] – returns a country name
[REGION]
[CITY]
[PLACE]
[APP_NAME]
[APP_BUNDLE]
[ORGANIZATION_NAME]
[AGENCY_NAME]
[ADVERTISER_NAME]
[CAMPAIGN_NAME]
[STRATEGY_NAME]
[CREATIVE_NAME]
[ORGANIZATION_ID]
[AGENCY_ID]
[ADVERTISER_ID]
[CAMPAIGN_ID] – returns a unique campaign ID in our system
[STRATEGY_ID]
[CREATIVE_ID] – returns a unique creative ID in our system
[WIDTH]
[HEIGHT]
[VIDEO_DURATION]
[WINNING_PRICE] – returns winning price of the impression

General Creative Guidelines

Prohibited Behaviour:

  • Auto-redirects
  • Pop (including pop ups, pop unders, pop overs, exit)
  • Auto-download
  • Spyware/Malware/ Viruses
  • Expandable ads (ads that automatically expand without user’s action)
  • Auto-refresh

Prohibited Content:

IAB25 Non-Standard Content:

  • IAB25-1 Unmoderated UGC
  • IAB25-2 Extreme Graphic/Explicit Violence
  • IAB25-3 Pornography
  • IAB25-4 Profane Content
  • IAB25-5 Hate Content
  • IAB25-6 Under Construction
  • IAB25-7 Incentivized

IAB26 Illegal Content:

  • IAB26-1 Illegal Content
  • IAB26-2 Warez
  • IAB26-3 Spyware/Malware
  • IAB26-4 Copyright Infringement
  • IAB9-9 Cigars

Gambling

Pharma

Restricted Content:

  • IAB8-5 Cocktails/Beer
  • IAB8-18 Wine
  • IAB23 Religion & Spirituality
  • IAB24 Uncategorized
  • IAB14-1 Dating

Please note that all supply partners adhere to IAB creative requirements.