XML/JSON Feed Documentation

Transcription

1 Overview The AdXpansion XML feed has been designed as an advanced feature for web and mobile developers who wish to integrate AdXpansion advertisements into their applications. AdXpansion provides the ability for publishers to create a special zone type and use an API call to generate an XML/JSON feed. Currently, the API supports only text-ads and returns results that include a Title, Subtitle, Thumbnail Image, etc. The API call allows flexibility in the number of ads delivered, the size of the images provided, the format of the response (XML/JSON) and other related properties. How to create an XML zone Feed requests require a special agreement which can be discussed and signed with your account manager. Once you have been given access to this feature, you can create and manage your feed settings in the same way you create and manage any of your other ad. zones. How to request a feed A feed request is an HTTP GET request to our XML API URL containing query string parameters that identify your zone and your options. Certain fields are required (those in red) while others are optional (those in braces and green). Examples of feed requests will follow. ID>&q=<KEYWORDS>&img=<1x1 56x56 72x72 128x128>&ip=<END USER-IP ADDRESS>&ua=<END USER-USER AGENT>&ref=<REFERRING URL>[&num=<NUMBER OF RESULTS>][&ss=<SUBSOURCE ID>] [&al=<accepted LANGUAGES>][&format=<xml json>] Explanation for query string parameters: Parameter Key Value Type Description Default Value Example Is Required? zone_id Numeric The numeric identifier of your zone, as displayed in the AdXpansion dashboard. N/A Yes Page 1 of 9

2 q URL-encoded string This is a URL_encoded query, context and/or set of keywords to match for advertisements. N/A Find%20beautiful%20women%20to %20date%20online! Yes img One of the following strings: '1x1', '56x56', '72x72' or '128x128' This is the image size. We currently offer the 3 listed sizes as well as a transparent 1x1 pixel. If an unsupported size is provided, we will return the transparent 1x1 pixel. Note that this image must be displayed in order to properly track your impressions and clicks. 1x1 56x56 Yes ip IP address as string This is expected to be the IP address of the end-user who is requesting the feed. Note that this is not the IP address of the server originating the request. N/A Yes ua URL-encoded string This is expected to be the URLencoded User-Agent string sent to your application by the end-user's browser. N/A Mozilla%2f5.0+ (Windows+NT+6.1%3b+Win64%3b +x64%3b+rv%3a25.0)+gecko %2f Firefox%2f25.0 Yes ref URL-encoded string This is expected to be the URLencoded URL (origin) of page or application that will display the ad. N/A http%3a%2f %2Fwww.yoursitename.com %2Fresults.php%3Fqu%3DFind %20beautiful%20women%20to %20date%20online! Yes num Numeric This is the number of ads to return in the feed results. Note that the maximum number allowed is 50. Negative numbers are not allowed No ss String This is an optional subsource parameter that you can provide in order to get a breakdown of traffic, CTRs and ecpms by subsource. Note that the maximum allowed length on this parameter's value is 20 characters. Empty/bl ank source1234 No Page 2 of 9

3 al String This is expected to be a string of acceptable languages and is expected to match the format of the acceptlanguage HTTP header. en-us fr-fr No format One of the following strings: 'xml' or 'json' This is an optional format parameter. It allows you to request the feed results in JSON instead of XML if that is your prefered consumption format. xml json No Examples of feed requests XML: %20online!&img=128x128&ip= &ua=Mozilla%2f5.0+ (Windows+NT+6.1%3b+Win64%3b+x64%3b+rv%3a25.0)+Gecko%2f Firefox %2f25.0&ref=http%3A%2F%2Fwww.adxpansion.com&num=1 JSON: %20online!&img=128x128&ip= &ua=Mozilla%2f5.0+ (Windows+NT+6.1%3b+Win64%3b+x64%3b+rv%3a25.0)+Gecko%2f Firefox %2f25.0&ref=http%3A%2F%2Fwww.adxpansion.com&num=1&ss=partner1234&al=en-US&format=json Page 3 of 9

4 XML Results Note that all the data enclosed in the <![CDATA[]> tags is raw. Is it's not XML formatted or HTML encoded. It should not be interpreted in any way. XML results will be formatted like this: <?xml version="1.0"?> <results> <result id="a Unique ID for the result."> <title><![cdata[the Title for the ad.]]></title> <subtitle><![cdata[the Subtitle for the ad.]]></subtitle> <description><![cdata[the Description for the ad.]]></description> <display_url><![cdata[the URL or Widget title for the ad.]]></display_url> <bid>the Value in earnings for this ad.</bid> <image width="the Width of the image." height="the Height of the image."><![cdata[the URL to request in order to display the thumbnail image.]]></image> <click><![cdata[the URL to link to with the ad.]]></click> </result> <result id="a Unique ID for the result."> </result> <result id="a Unique ID for the result."> </result> </results> Page 4 of 9

5 XML result example: <?xml version="1.0"?> <results> <result id="fa9c0cc ec802ce6a8cd5f2e6f"> <title><![cdata[young, fresh and ready for the picking.]]></title> <subtitle><![cdata[teen Oasis for only $2.95]]></subtitle> <description><![cdata[exclusive movies from these hot and fresh teens. Watch them in HD!]]></description> <display_url><![cdata[myteensoasis.com]]></display_url> <bid>0.0001</bid> <image width="128" height="128"><![cdata[ iuid=fa9c0cc ec802ce6a8cd5f2e6f&img=128x128]]></image> <click><![cdata[ </result> </results> Empty results will look like this: <?xml version="1.0"?> <results /> If an error occurs, it will look like this: <?xml version="1.0"?> <errors> <error id="1"> <type>invalid request</type> <message>invalid request</message> </error> </errors> Page 5 of 9

6 JSON Results JSON results will be formatted like this: "results": "result": [ ],, "id": "A Unique ID for the result.", "title": "The Title for the ad.", "subtitle": "The Subtitle for the ad.", "description": "The Description for the ad.", "display_url": "The URL or Widget title for the ad.", "bid": The Value in earnings for this ad., "image": "The URL to request in order to display the thumbnail image.", "click": "The URL to link to with the ad.", "width": The Width of the image., "height": The Height of the image. Page 6 of 9

7 JSON result example: "results": "result": [ "id": "6cbdee7140ac02d38072edb2293dfb29", "title": "Young, fresh and ready for the picking.", "subtitle": "Teen Oasis for only $2.95", "description": "Exclusive movies from these hot and fresh teens. Watch them in HD!", "display_url": "MyTeensOasis.com", "bid": , "image": " iuid=6cbdee7140ac02d38072edb2293dfb29\u0026img=128x128", "click": " "width": 128, "height": 128 ] Empty results will look like this: If an error occurs, it will look like this: "errors": "error": [ ] "id": 1, "type": "Invalid request", "message": "Invalid request" Page 7 of 9

8 Examples of how we typically render our text ads: Normal view: List view: Mouse-over view: Important to remember! In order to get paid for every click generated, you must display the image we provide in the feed results, every time you display an ad. This is required to allow tracking of impressions. Page 8 of 9

9 For help or more information: Contact your account manager. AdXpansion 3300 Cote Vertu Suite 406 Montreal, Quebec Canada H4R 2B7 Office: Toll Free: Fax: Page 9 of 9