Mocean Ad Request API
From Mocean Mobile Wiki
Description
This document describes how you can form server-side or client side ad requests to your mobile application or mobile website. The ad server is very flexible and can be accessible via a simple HTTP request with GET parameters that will be described below.
Sample server-side tags that implement the HTTP ad server request are also available for various programming languages and can be utilized on mobile pages.
Customized Mocean SDKs intended for featuring your apps with Mocean mobile advertising are provided for various platforms as well.
Basic Ad Request
The primary ad server is hosted at http://ads.mocean.mobi/ad.
Note: You can also specify another host header in your request to override the default host (ads.mocean.mobi). This can be configured via an email request to TechSupport
A basic ad request requires the following parameters:
| Parameter | Req? | Description | Code Sample |
|---|---|---|---|
| zone | Yes | The id of the zone of the publisher site. | zone=123 |
| ip | Yes | Client IP address. If present in the ad request, this parameter overrides the IP of the client making the request. Use this parameter if you are requesting ads on behalf of another client ip. | ip=173.3.77.115 |
| ua | Yes | The browser user agent of the device making the request. Being passed directly, it redefines the value retrieved from ’User-Agent’ header field. | ua=SCH-R211 UP.Browser/6.2.3.8 (GUI)MMP/2.0 |
| url | No | The URL of the page that the ad is requested for. | url=http://mydomain.com/sample_page/ |
| udid | No | A custom unique identifier with MD5 hashing. Pass this if your system has its own unique identifiers for each user. | udid=1bef50453858d317a8471087aaf1614a |
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)
Ad Response Formats
The ad server supports responses in 4 formats: HTML, XML, JSON and Javascript. You can also specify the type of ads to be returned. Here are the parameters that can be utilized for this purpose:
| Parameter | Req? | Description | Code Sample |
|---|---|---|---|
| key | No | Output format. Default format uses key=1 (HTML). Parameter key should be set to 3, 5 or 6 in order to use XML output, JSON or Javascript, respectively. NOTE: To return JSONP format, use 'key'=5 or 'key'=6 together with 'callback' parameter. | key=1 |
| type | No | Type of ads to be returned (1 - text, 2 - image, 4 - richmedia ad). You can set different combinations with these values. For example, 3 = 1 + 2 (text + image), 7 = 1 + 2 + 4 (text + image + richmedia) and so on. Default value is ’-1’ that means any type of ads can be returned. NOTE: This parameter only works for direct line items, not on ad feeds! | type=7 |
| adstype | No | DEPRECATED. Type of ads (1 - text only, 2 - image only, 3 - image and text). Default value is 3. | adstype=3 |
| jsvar | No | FOR JAVASCRIPT OUTPUT FORMAT ONLY! A name of a variable that will be assigned with the value of hash, returned when key =6. | jsvar=123 |
| callback | No | A string value that will be integrated into JSONP output if 'key'=5 or 'key'=6. | callback=hello |
Sample of a request:
Default HTML Response
With key=1 (default HTML), a text ad response will be as follows:
<a href="http://ads1.mocean.mobi/redir/2c060330-c120-11df-bff1-001ec9fd3a50/0">Ad text here</a>
<img src="http://www.externalpage.com/imgpixel.gif" width="1"height="1"/><br/>
and a banner ad response will look like this:
<a href="http://ads1.mocean.mobi/redir/2c060330-c120-11df-bff1-001ec9fd3a50/0">
<img src="http://img.ads1.mocean.mobi/img/1284592774_95723535_320x50.jpg" border="0"/>
</a>
<img src="http://www.externalpage.com/imgpixel.gif" width="1" height="1"/><br/>
If no ads are available, nothing is returned.
XML Response
With key=3 (XML), a text ad response will be as follows:
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="text">
<url><![CDATA[http://ads1.mocean.mobi/redir/8ca52940-c121-11df-bff1-001ec9fd3a50/0]]></url>
<text><![CDATA[Test Mode Ad]]></text>
<track><![CDATA[http://www.externalpage.com/imgpixel.gif]]></track>
</ad>
</mojiva>
and a banner ad response will be as follows:
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="image/jpeg">
<url><![CDATA[http://ads1.mocean.mobi/redir/afed8f60-c120-11df-bff1-001ec9fd3a50/0]]></url>
<img><![CDATA[http://img.ads1.mocean.mobi/img/1284592774_95723535_320x48.jpg]]></img>
<track><![CDATA[http://www.externalpage.com/imgpixel.gif]]></track>
</ad>
</mojiva>
where:
- <ad> - the ad returned. type="text" or type="image/jpeg" identifies the type of the ad (text or graphic).
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad.
- <track> - pixel tracking url.
If there is no pixel tracking present (custom or network level), then <track> would be empty, like this:
<track><![CDATA[]]></track>
JSON Response
To get a JSON response specify 'key=5' in your ad request.
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=5&type=3
Sample of a text ad response:
({"url" : "http://ads1.mocean.mobi/redir/995c6970-eb22-11df-8f56-001d096a03fe/0", "text" : "Text ad", "track" : "http://ads1.mocean.mobi/img/995c6970-eb22-11df-8f56-001d096a03fe"})
Sample of a banner ad response:
({"url" : "http://ads1.mocean.mobi/redir/3d620600-c121-11df-bff1-001ec9fd3a50/0",
"img" : [ "http://img.ads1.mocean.mobi/img/1284592774_95723535_80x15.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_80x15.wbmp",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_120x20.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_168x28.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_216x36.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_300x50.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_320x50.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_320x48.jpg" ],
"track" : [ "http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50" ]})
The following elements are returned:
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad. The ’img’ parameter returns all possible sizes available for the ad.
- <track> - pixel tracking url.
Javascript Response
To get a Javascript response, specify 'key=6' and 'jsvar=VARIABLE_NAME' in your ad request.
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=6&jsvar=123&type=3
Sample of a text ad response:
var 123 = [{"url" : "http://ads1.mocean.mobi/redir/995c6970-eb22-11df-8f56-001d096a03fe/0/6134", "text" : "Text ad", "track" : "http://ads1.mocean.mobi/img/995c6970-eb22-11df-8f56-001d096a03fe"}];
Sample of a banner ad response:
var 123 = [{"url" : "http://ads1.mocean.mobi/6cc109e0-d2ec-11e0-ac7e-0019b9f99000/0/6186",
"img" : "http://img.ads1.mocean.mobi/img/1256612788_1551852963_300x50.jpg",
"type": "image/jpeg",
"track" : "http://ads1.mocean.mobi/img/6cc109e0-d2ec-11e0-ac7e-0019b9f99000"}];
JSONP Response
To get a JSONP response specify 'key=5' or 'key=6' together with 'callback= ' parameter in your ad request.
Sample of a request with 'key=5' :
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=5&callback=hello
Sample of a response:
hello([{"url" : "http://ads1.mocean.mobi/redir/3d620600-c121-11df-bff1-001ec9fd3a50/0/13330",
"img" : [ "http://img.ads1.mocean.mobi/img/1284592774_95723535_80x15.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_80x15.wbmp",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_120x20.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_168x28.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_216x36.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_300x50.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_320x50.jpg",
"http://img.ads1.mocean.mobi/img/1284592774_95723535_320x48.jpg" ],
"track" : [ "http://ads1.mocean.mobi/img/d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50",
"http://ads1.mocean.mobi/img/3d620600-c121-11df-bff1-001ec9fd3a50" ]}]);
Sample of a request with 'key=6' :
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=6&callback=hello
Sample of a response:
hello([{"url" : "http://ads.test.mocean.mobi/redir/4237fcb0-5375-11e1-9c33-0019b9f99000/0/13330",
"img" : "http://img.ads.test.mocean.mobi/img/4f3/3dc/9ae98b0/image_320x50.png",
"type": "image/png",
"track" : "http://pixel.com/643490460648319"}]);
If no ads are available, it will return the following:
hello([{"error" : "No ads available"}]);
Returning Multiple Ads
You can request several ads (up to 5) at a time by specifying count parameter in your query.
| Parameter | Req? | Description | Code Sample |
|---|---|---|---|
| count | No | Number of ads that can be displayed in response to a request (from 0 to 5). Default value is 1. | count=2 |
When specifying 'count=2' in the request along with 'type=3', both text and banner ads will be returned in the corresponding format.
Default HTML
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=1&type=3&count=2
Sample of a response (HTML):
<a href="http://ads1.mocean.mobi/redir/42340730-d2e3-11e0-ac7e-0019b9f99000/0/6186">
<img src="img.ads1.mocean.mobi/img/1271132910_337937880_320x50.jpg" border="0"/>
</a>
<img src="http://ads1.mocean.mobi/redir/42340730-d2e3-11e0-ac7e-0019b9f99000" width="1" height="1" /><br/>
<a href="http://ads1.mocean.mobi/img/42340730-d2e3-11e0-ac7e-0019b9f99000/0/6134">Test mode ad</a>
<img src="http://ads.test.mocean.mobi/img/42340730-d2e3-11e0-ac7e-0019b9f99000" width="1" height="1" /><br/>
XML
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=3&type=3&count=2
Sample of a response (XML):
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="text">
<url>
<![CDATA[ http://ads1.mocean.mobi/redir/baf6bf80-eb23-11df-8f56-001d096a03fe/0/6134]]>
</url>
<track>
<![CDATA[http://ads1.mocean.mobi/img/baf6bf80-eb23-11df-8f56-001d096a03fe]]>
</track>
<text><![CDATA[Test mode ad]]></text>
</ad>
<ad type="image/jpeg">
<url>
<![CDATA[http://ads1.mocean.mobi/redir/baf6bf81-eb23-11df-8f56-001d096a03fe/0/13330]]>
</url>
<img>
<![CDATA[http://img.ads1.mocean.mobi/img/1271132910_337937880_320x50.jpg]]>
</img>
<track>
<![CDATA[http://ads1.mocean.mobi/img/baf6bf81-eb23-11df-8f56-001d096a03fe]]>
</track>
</ad>
</mojiva>
Possible elements returned may be as follows:
- <ad> - the ad returned. Here type="text" or type="image/jpeg" determines the ad type.
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad with specified image size and mime type.
- <track> - pixel tracking url.
JSON
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=5&type=3&count=2
Sample of a response (JSON):
({"url":"http://ads1.mocean.mobi/redir/892b77a2-619a-11e0-959a-001d096a03fe/0/13330",
"img":["http://img.ads1.mocean.mobi/img/1274064780_407736399_80x15.wbmp",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_80x15.jpg",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_120x20.jpg",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_168x28.jpg",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_216x36.jpg",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_300x50.jpg",
"http://img.ads1.mocean.mobi/img/1274064780_407736399_320x50.jpg"],
"track":["http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe",
"http://ads1.mocean.mobi/img/892b77a2-619a-11e0-959a-001d096a03fe" ]}
{"url":"http://ads1.mocean.mobi/redir/892b77a1-619a-11e0-959a-001d096a03fe/0/5993",
"text":"Test mode ad",
"track":"http://ads1.mocean.mobi/img/892b77a1-619a-11e0-959a-001d096a03fe"})
Possible response elements may be as follows:
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad.
- <track> - pixel tracking url.
Javascript
Sample of a request:
http://ads.mocean.mobi/ad?zone=15562&ip=173.3.77.115&ua=Mozilla/5.0 (Windows; U; Windows NT 5.2; ru; rv:1.9.0.19) Gecko/2010031422 Firefox/3.0.19 (.NET CLR 3.5.30729)&key=6&jsvar=123&type=3&count=2
Sample of a response (Javascript):
var 123 = [{"url" : "http://ads1.mocean.mobi/redir/bb8ae390-d39e-11e0-b83a-0019b9f99000/0/6186",
"img" : "http://img.ad1.mocean.mobi/img/1256612788_1551852963_320x50.jpg",
"type": "image/jpeg",
"track" : "http://ads1.mocean.mobi/img/bb8ae390-d39e-11e0-b83a-0019b9f99000"},
{"url" : "http://ads1.mocean.mobi/redir/bb8e17e0-d39e-11e0-b83a-0019b9f99000/0/2645",
"text" : "New text ad",
"track" : "http://ads1.mocean.mobi/img/bb8e17e0-d39e-11e0-b83a-0019b9f99000"}];
Third Party
Default HTML
Mocean simply relays all content from a 3rd party ad network. It puts all content (richmedia,text, banners) in a similar structure. The default HTML mode simply relays the content as is.
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=5637&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18(KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=1&type=3
Sample of a response (HTML)
<div style='background:black; width:300px; height:50px;'>
<table width=300 height=50 border=0 cellspacing=0>
<tr>
<td width='38'>
<a target='_top' href='http://ads.mocean.mobi/redir/e32a9b20-69cc-11e0-a60d-0019b9f99000/0/7672'><img border='0' width='38' height='38' src='http://http.cdnlayer.com/mdotm/3838.png'/></a>
</td>
<td width='262' style='text-align:center; vertical-align: middle;'>
<a style='color: white; font-size: 10pt; font-family: Arial; font-weight: bold; text-decoration: none;' href='http://ads.mocean.mobi/redir/e32a9b20-69cc-11e0-a60d-0019b9f99000/1' target='_top'>Get Ridiculous Deals with Groupon</a>
</td>
</tr>
</table>
</div>
<img src="http://ads.mocean.mobi/img/e32a9b20-69cc-11e0-a60d-0019b9f99000" width="1" height="1"/>
XML
Below is the same content in XML mode.
Sample of an ad request:
Sample of a response (XML)
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="thirdparty" feed="Tapad">
<url>
<![CDATA[http://ads.mocean.mobi/redir/17bf9ac0-69cd-11e0-a60d-0019b9f99000/0/7672]]>
</url>
<text><![CDATA[]]></text>
<img>
<![CDATA[http://http.cdnlayer.com/mdotm/groupon_38x38.jpg]]>
</img>
<track>
<![CDATA[http://ads.mocean.mobi/img/17bf9ac0-69cd-11e0-a60d-0019b9f99000]]>
</track>
<content>
<a href="http://rtb-test.dev.tapad.com:8080/click?redirect=http%3A%2F%2Fwww.tapad.com&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5fUlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRhX2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRjYS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg3D%3D">
<img src="http://rtb-test.dev.tapad.com:8080/creative/banner?creative_id=2&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5fUlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRhX2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRjYS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%3%3D&ta_win_prc=0.0100"></img>
</a><img src="http://ads1.mocean.mobi/img/0b6f84a0-8d9b-11e0-aab9-001d096a03fe" width="1" height="1"/>
</content>
<response>
<a href="http://rtb-test.dev.tapad.com:8080/click?redirect=http%3A%2F%2Fwww.tapad.com&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5fUlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRhX2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRjYS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%3D%3D">
<img src="http://rtb-test.dev.tapad.com:8080/creative/banner?creative_id=2&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5fUlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRhX2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRjYS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%3D%3D&ta_win_prc=0.0100"></img></a>
</response>
</ad>
</mojiva>
The following elements are returned:
- <ad> - the ad returned. type="thirdparty" feed="Tapad" - specify that the ad is external and the name of the Ad Feed partner.
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad.
- <content> – all the ad content is placed in this node as is from 3rd party.
- <response> - the original response from the third party ad server.
JSON
Sample of an ad request:
Sample of a response (JSON)
({"url":"http://ads.mocean.mobi/redir/554767b0-69cd-11e0-a60d-0019b9f99000/0/7672","text":"",
"img":["http://http.cdnlayer.com/mdotm/3838.png"],
"track":["http://ads.mocean.mobi/img/554767b0-69cd-11e0-a60d-0019b9f99000"],
"content":"<div style=\'background:black; width:300px; height:50px;\'>
<table width=300 height=50 border=0 cellspacing=0>
<tr>
<td width=\'38\'>
<a target=\'_top\' href=\'http://ads.mocean.mobi/redir/554767b0-69cd-11e0-a60d-019b9f99000/0/7672\'>
<img border=\'0\' width=\'38\' height=\'38\' src=\'http://http.cdnlayer.com/mdotm/3838.png\'/>
</a>
</td>
<td width=\'262\' style=\'text-align:center;vertical-align:middle;\'>
<a style=\'color: white; font-size: 10pt; font-family: Arial; font-weight: bold; text-decoration: none;\' href=\'http://ads.mocean.mobi/redir/554767b0-69cd-11e0-a60d-0019b9f99000/1\' target=\'_top\'>Get Ridiculous Deals with Groupon</a>
</td>
</tr>
</table>
</div>
<img src=\"http://ads.mocean.mobi/img/554767b0-69cd-11e0-a60d-0019b9f99000\" width=\"1\" height=\"1\" />",
"response":"<div style=\'background:black; width:300px; height:50px;\'>
<table width=300 height=50 border=0 cellspacing=0>
<tr>
<td width=\'38\'>
<a target=\'_top\' href=\'http://ads.mocean.mobi/redir/554767b0-69cd-11e0-a60d-019b9f99000/0/7672\'>
<img border=\'0\' width=\'38\' height=\'38\' src=\'http://http.cdnlayer.com/mdotm/3838.png\'/>
</a>
</td>
<td width=\'262\' style=\'text-align:center;vertical-align:middle;\'>
<a style=\'color: white; font-size: 10pt; font-family: Arial; font-weight: bold; text-decoration: none;\' href=\'http://ads.mocean.mobi/redir/554767b0-69cd-11e0-a60d-0019b9f99000/1\' target=\'_top\'>Get Ridiculous Deals with Groupon</a>
</td>
</tr>
</table>
</div>
<img src=\"http://ads.mocean.mobi/img/554767b0-69cd-11e0-a60d-0019b9f99000\" width=\"1\" height=\"1\" />"})
The following elements are returned:
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad.
- <content> – all the ad content is placed in this node as is from 3rd party.
- <response> - the original response from the third party ad server.
Javascript
Sample of an ad request:
Sample of a response (Javascript)
var 123 = [{"url":"http://ads.mocean.mobi/redir/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50/0/7672","text":"",
"img":["http://http.cdnlayer.com/mdotm/3838.png"],
"track":["http://ads.mocean.mobi/img/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50"],
"content":"<div style=\'background:black; width:300px; height:50px;\'>
<table width=300 height=50 border=0 cellspacing=0>
<tr>
<td width=\'38\'>
<a target=\'_top\' href=\'http://ads.mocean.mobi/redir/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50/0/7672\'>
<img border=\'0\' width=\'38\' height=\'38\' src=\'http://http.cdnlayer.com/mdotm/3838.png\'/>
</a>
</td>
<td width=\'262\' style=\'text-align:center;vertical-align:middle;\'>
<a style=\'color: white; font-size: 10pt; font-family: Arial; font-weight: bold; text-decoration: none;\' href=\'http://ads.mocean.mobi/redir/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50/1\' target=\'_top\'>Get Ridiculous Deals with Groupon</a>
</td>
</tr>
</table>
</div>
<img src=\"http://ads.mocean.mobi/img/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50\" width=\"1\" height=\"1\" />",
"response":"<div style=\'background:black; width:300px; height:50px;\'>
<table width=300 height=50 border=0 cellspacing=0>
<tr>
<td width=\'38\'>
<a target=\'_top\' href=\'http://ads.mocean.mobi/redir/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50/0/7672\'>
<img border=\'0\' width=\'38\' height=\'38\' src=\'http://http.cdnlayer.com/mdotm/3838.png\'/>
</a>
</td>
<td width=\'262\' style=\'text-align:center;vertical-align:middle;\'>
<a style=\'color: white; font-size: 10pt; font-family: Arial; font-weight: bold; text-decoration: none;\' href=\'http://ads.mocean.mobi/redir/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50/1\' target=\'_top\'>Get Ridiculous Deals with Groupon</a>
</td>
</tr>
</table>
</div>
<img src=\"http://ads.mocean.mobi/img/6c6de3f0-d3b4-11e0-bfcc-001ec9fd3a50\" width=\"1\" height=\"1\" />"}];
NOTE: Javascript response is quite similar to JSON output for external creatives.
Third Party (Client Side SDK)
Below, examples of client-side external ad campaigns are given.
Default HTML
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=90038&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18(KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=1
Sample of a response (HTML)
<!-- client_side_external_campaign
<external_campaign version="1.0"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name="variables">123456789</param><param name="long">-73.9763</param><param name="lat">40.7619</param></external_params><track_url></track_url></external_campaign>
-->
NOTE: Parameters in the response depend on the external ad feed settings. The example given above contains parameters related to Generic's ad feeds.
XML
Below is the same content in XML mode.
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=90038&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18(KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=3
Sample of a response (XML)
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="thirdparty">
<url></url>
<text></text>
<track></track>
<content>
<!-- client_side_external_campaign
<external_campaign version="1.0"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name="variables">123456789</param><param name="long">-73.9763</param><param name="lat">40.7619</param></external_params><track_url></track_url></external_campaign>
-->
</content>
<response>
<!-- client_side_external_campaign
<external_campaign version="1.0"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name="variables">123456789</param><param name="long">-73.9763</param><param name="lat">40.7619</param></external_params><track_url>%TRACKURL%</track_url></external_campaign>
-->
</response>
</ad>
</mojiva>
The following elements are returned:
- <ad> - the ad returned. type = "thirdparty" specifies that the ad is external.
- <url> – click URL/destination URL.
- <text> – any ad text (either independently or below the ad).
- <img> – direct IMG URL of the ad.
- <content> – all the ad content is placed in this node as is from 3rd party.
- <response> - the original response from the third party ad server.
JSON
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=90038&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18(KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=5
Sample of a response (JSON)
({"url" : "", "text" : "", "track" : "",
"content" : "<!-- client_side_external_campaign\n<external_campaign version=\"1.0\"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name=\"variables\">123456789</param><param name=\"long\">-73.9763</param><param name=\"lat\">40.7619</param></external_params><track_url></track_url></external_campaign>\n-->",
"response" : "<!-- client_side_external_campaign\n<external_campaign version=\"1.0\"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name=\"variables\">123456789</param><param name=\"long\">-73.9763</param><param name=\"lat\">40.7619</param></external_params><track_url></track_url></external_campaign>\n-->" })
Javascript
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=90038&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18(KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key</span>=6&jsvar=123
Sample of a response (Javascript)
var 123 = [{"url" : "", "text" : "", "track" : "",
"content" : "<!-- client_side_external_campaign\n<external_campaign version=\"1.0\"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name=\"variables\">123456789</param><param name=\"long\">-73.9763</param><param name=\"lat\">40.7619</param></external_params><track_url></track_url></external_campaign>\n-->", </br>"response" : "<!-- client_side_external_campaign\n<external_campaign version=\"1.0\"><campaign_id>127374</campaign_id><type>RichMediaLibrary</type><external_params><param name=\"variables\">123456789</param><param name=\"long\">-73.9763</param><param name=\"lat\">40.7619</param></external_params><track_url></track_url></external_campaign>\n-->" }];
Rich Media
Default HTML
Mocean simply relays all content from a richmedia. The default HTML mode simply relays the content as is. Ensure the below ad calls have UA passed in as a parameter. To fetch rich media ads, specify type=7 in a request.
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=5636&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18 (KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=1&type=7
Sample of a response (HTML)
<script type="text/javascript" src="http://mojiva.com/js/mojiva_rm.mini.js"></script>
<div id="mm_top" style="cursor:pointer; width:320px; z-index:1; position:relative;">
<div id="mainClickOne" style="width:237px; height:50px; z-index:2; position:relative;"></div>
</div>
<div id="mm_link_div" style="cursor:pointer; height:130px; width:320px; position:relative;">
<div id="mojiva_ups_main_link" style="height:99px; width:320px; position: relative; z-index:10; top:100px;"></div>
</div>
<script>
var config = {
defaultImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_expand.gif",
collapseImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_collapse.gif",
fullImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_panel.gif",
campaign_id : "7691", bannerInBG : true, panelHeight : 200,
links : {mainClickOne : "http://ads.mocean.mobi/redir/ad7d5840-69cd-11e0-a60d-0019b9f99000/0/7691",
mojiva_ups_main_link : "http://ads.mocean.mobi/redir/ad7d5840-69cd-11e0-a60d-0019b9f99000/0/7691",
mm_link_div : "http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.mp4"},
bblinks : {mm_link_div : "http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.3gp"},
impTracker : [" http://ad.doubleclick.net/ad/N2938.157901.MOJIVA/B5174740.5;sz=1x1;pc=[TPAS_ID]; ord=1303139292? "]
};
window.onload = function() {Mojiva_RM.start();}
</script>
<noscript>
<a href="http://ads.mocean.mobi/redir/ad7d5840-69cd-11e0-a60d-0019b9f99000/0/7691">
<img src="http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_static.gif" width="320" height="50" border="0">
</a>
</noscript>
<img src="http://ads.mocean.mobi/img/ad7d5840-69cd-11e0-a60d-0019b9f99000" width="1" height="1" />
XML
Sample of an ad request:
Sample of a response (XML)
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="richmedia">
<url><![CDATA[http://ads.mocean.mobi/redir/c07b7d00-6ab8-11e0-8d7f-0019b9f99000/0/7691]]></url>
<track><![CDATA[http://ads.mocean.mobi/img/c07b7d00-6ab8-11e0-8d7f-0019b9f99000]]></track>
<content><script type="text/javascript" src=" http://mojiva.com/js/mojiva_rm.mini.js"></script>
<div id="mm_top" style="cursor:pointer; width:320px; z-index:1; position:relative;">
<div id="mainClickOne" style="width:237px; height:50px; z-index:2; position:relative;"></div>
</div>
<div id="mm_link_div" style="cursor:pointer; height:130px; width:320px; position:relative;">
<div id="mojiva_ups_main_link" style=" height:99px; width:320px; position: relative; z-index:10; top:100px;"></div>
</div>
<script>
var config = {
defaultImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_expand.gif",
collapseImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_collapse.gif",
fullImage : "http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_panel.gif",
campaign_id : "7691",
bannerInBG : true,
panelHeight : 200,
links : {mainClickOne : "http://ads.mocean.mobi/redir/c07b7d00-6ab8-11e0-8d7f-0019b9f99000/0/7691",
mojiva_ups_main_link : "http://ads.mocean.mobi/redir/c07b7d00-6ab8-11e0-8d7f-0019b9f99000/0/7691",
mm_link_div : "http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.mp4"},
bblinks : {mm_link_div : "http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.3gp"},
impTracker : [" http://ad.doubleclick.net/ad/N2938.157901.MOJIVA/B5174740.5;sz=1x1;pc=[TPAS_ID];ord=1303240255? "]
};
window.onload = function() { Mojiva_RM.start();}
</script>
<noscript>
<a href="http://ads.mocean.mobi/redir/c07b7d00-6ab8-11e0-8d7f-0019b9f99000/0/7691">
<img src="http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_static.gif" width="320" height="50" border="0">
</a>
</noscript>
<img src="http://ads.mocean.mobi/img/c07b7d00-6ab8-11e0-8d7f-0019b9f99000" width="1" height="1"/>
</content>
</ad>
</mojiva>
The following elements are returned:
- <ad> - the ad returned. type="richmedia" identifies that the ad is richmedia. All the ad content is placed in the <richmedia> node AS IS.
- <url> – click URL/destination URL.
- <track> - pixel tracking url.
- <content> - all the ad content is placed in this node.
JSON
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=5636&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18 (KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=5&type=7
Sample of a response (JSON)
({"url" : "http://ads.mocean.mobi/redir/e2e04470-6ab8-11e0-8d7f-0019b9f99000/0/7691",
"track" : "http://ads.mocean.mobi/img/e2e04470-6ab8-11e0-8d7f-0019b9f99000",
"content" : "<script type=\"text/javascript\" src=\"http://mojiva.com/js/mojiva_rm.mini.js\"></script>\n
<div id=\"mm_top\" style=\" cursor:pointer; width:320px; z-index:1; position:relative;\">
<div id=\"mainClickOne\" style=\"width:237px; height:50px; z-index:2; position:relative;\"></div>
</div>\n
<div id=\"mm_link_div\" style=\"cursor:pointer; height:130px; width:320px; position: relative;\">\n
<div id=\"mojiva_ups_main_link\" style=\"height:99px; width:320px; position: relative; z-index:10; top:100px;\"></div>\n
</div>\n
<script>\n\n
var config = {\n defaultImage: \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_expand.gif\",
collapseImage : \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_collapse.gif\",
fullImage : \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_panel.gif\",\n
campaign_id : \"7691\", bannerInBG : true, panelHeight : 200,\n
links : { mainClickOne :\"http://ads.mocean.mobi/redir/e2e04470-6ab8-11e0-8d7f-0019b9f99000/0/7691\",
mojiva_ups_main_link : \"http://ads.mocean.mobi/redir/e2e04470-6ab8-11e0-8d7f-0019b9f99000/0/7691\",
mm_link_div : \"http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.mp4\"},\n
bblinks : {mm_link_div : \"http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.3gp\"},\n
impTracker : [\"http://ad.doubleclick.net/ad/N2938.157901.MOJIVA/B5174740.5;sz=1x1;pc=[TPAS_ID];ord=1303240313? \"]\n
};\n\n
window.onload = function() {\n Mojiva_RM.start();\n}\n\n
</script>\n
<noscript>\n
<a href=\"http://ads.mocean.mobi/redir/e2e04470-6ab8-11e0-8d7f-0019b9f99000/0/7691\">\n
<img src=\"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_static.gif\" width=\"320\" height=\"50\" border=\"0\">
</a>\n
</noscript>"})
The following elements are returned:
- <url> – click URL/destination URL.
- <track> - pixel tracking url.
- <content> - all the ad content is placed in this node.
- <div> - ad settings determining its look, position, size, etc.
- <script> - script code of the ad.
- <noscript> - a part of the ad code that allows for your ad to be shown when the script code can not be run for any reason.
Javascript
Sample of an ad request:
http://ads.mocean.mobi/ad?zone=5636&ip=68.164.40.162&ua=Mozilla/5.0(iPhone; U; CPU iPhone OS 3_0 like Mac OS X; en-us) AppleWebKit/528.18 (KHTML, like Gecko) Version/4.0 Mobile/7A341 Safari/528.16&key=6&jsvar=123&type=7
Sample of a response (Javascript)
var 123 = [{"url" : "http://ads.mocean.mobi/redir/35febc32-d3ab-11e0-bfcc-001ec9fd3a50/0/7691",
"track" : "http://ads.mocean.mobi/img/35febc32-d3ab-11e0-bfcc-001ec9fd3a50",
"content" : "<script type=\"text/javascript\" src=\"http://mojiva.com/js/mojiva_rm.mini.js\"></script>\n
<div id=\"mm_top\" style=\" cursor:pointer; width:320px; z-index:1; position:relative;\">
<div id=\"mainClickOne\" style=\"width:237px; height:50px; z-index:2; position:relative;\"></div>
</div>\n
<div id=\"mm_link_div\" style=\"cursor:pointer; height:130px; width:320px; position: relative;\">\n
<div id=\"mojiva_ups_main_link\" style=\"height:99px; width:320px; position: relative; z-index:10; top:100px;\"></div>\n
</div>\n
<script>\n\n
var config = {\n defaultImage: \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_expand.gif\",
collapseImage : \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_collapse.gif\",
fullImage : \"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_panel.gif\",\n
campaign_id : \"7691\", bannerInBG : true, panelHeight : 200,\n
links : { mainClickOne :\"http://ads.mocean.mobi/redir/35febc32-d3ab-11e0-bfcc-001ec9fd3a50/0/7691\",
mojiva_ups_main_link : \"http://ads.mocean.mobi/redir/35febc32-d3ab-11e0-bfcc-001ec9fd3a50/0/7691\",
mm_link_div : \"http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.mp4\"},\n
bblinks : {mm_link_div : \"http://mobile.mojiva.com/richmedia/toyota/HD_SIGN-hi_res.3gp\"},\n
impTracker : [\"http://ad.doubleclick.net/ad/N2938.157901.MOJIVA/B5174740.5;sz=1x1;pc=[TPAS_ID];ord=1303240313? \"]\n
};\n\n
window.onload = function() {\n Mojiva_RM.start();\n}\n\n
</script>\n
<noscript>\n
<a href=\"http://ads.mocean.mobi/redir/35febc32-d3ab-11e0-bfcc-001ec9fd3a50/0/7691\">\n
<img src=\"http://mobile.mojiva.com/richmedia/toyota/320x250_toyota_static.gif\" width=\"320\" height=\"50\" border=\"0\">
</a>\n
</noscript>"}];
NOTE: Javascript output format has the same content code with JSON one in the richmedia case.
Test Ads
For testing purpose, you can use the following parameter to retrieve test banners and text ads.
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| test | No | Retrieve test ads. | test=1 |
NOTE: Be attentive! If this parameter is used in the request (no matter which value it has: 1 or 0), a test ad will be returned.
Sample of a request:
This request returns the following response:
Advertisers can also specify their own test ads within their network. These test ads will take precedence over the default test ads.
Information about test ads impressions and clicks is included into your impressions/clicks statistics as well.
Ad Call Timeout
If you need to limit the time of ad response, use the 'timeout' parameter as it is described below.
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| timeout | No | Specify timeout of ad call. This tells the ad server the maximum time you are willing to wait for an ad response (in milliseconds) (default: 3000, min:1000, max: 3000) | timeout=2000 |
Sample of a request:
If the response time exceeds the specified value, an empty response will be returned.
Requesting Specific Ads
Mocean Mobile Platform allows for requesting specific ad(s) or ads of the certain line item(-s) as well as requesting ads excluding some of them.
NOTE: TO USE THIS FUNCTIONALITY, MAKE SURE THE REQUESTED LINE ITEM OR THE LINE ITEM OF THE REQUESTED CREATIVE IS ADJUSTED APPROPRIATELY. To make creatives available to be requested directly, Direct request option should be set to 'Enabled' for the corresponding line item.
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| campaigns creatives | No | Returns the ad with the specified creative ID. You may specify several creative IDs desired to be returned separating them by commas. In this case the ad selection algorithm will be applied to the specified ads. | creatives=126545 creatives=123456,58795,2578 |
| excampaigns excreatives | No | Returns the ad excluding the specified creaive IDs. If you would like to exclude some creatives from the processing, specify their IDs (separated by commas). | excreatives=126545 excreatives=123456,58795,2578 |
| lineitems | No | Returns the creative that belongs to the line item of the specific ID. You may specify several line item IDs that creatives are desired to be returned (separate by commas). | limeitems=321654 limeitems=321654,125789 |
| exlineitems | No | Returns the creative that does not belong to the line item of the specific ID. Several line item IDs can be be also specified separated by commas. | exlimeitems=321654 exlimeitems=321654,125789 |
Sample of a request:
The ad with the requested ID(s) will be returned:
<a href="http://ads2.mocean.mobi/redir/418d26c2-ce2b-11e0-ad15-001ec9fd3a50/0/126545">
<img src="http://img.ads2.mocean.mobi/img/1504550696/image_480x75.png" border="0"/>
</a>
In case creatives / campaigns and lineitems are passed in the request at the same time, the ad server will try to return the creative that ID is specified in creatives/campaigns parameter. If the specified creative can't be shown for some reason, ad server will return a creative that belongs to specified lineitems.
Sample of a request:
The ad returned can be like the following:
<a href="http://ads2.mocean.mobi/redir/7df0e400-66bc-11e2-9bcf-0a3542e8faa1/0/85187">welcome to mOcean!</a>
In this example the ad (ID=85187) that belongs to the requested line item (ID=321654) is returned.
Line Items Ordering
It is allowed to specify the order of preference for ad serving. For this use the order parameter in your query. Order is set at the line item level.
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| order | No | Sorted list of line item IDs desired to be shown first. If ads of line items specified in the "order" parameter can not be served at the moment for any reason (e.g. limits exhausted, targeting is inactive, etc.), another available ad will be returned based on standard ad selection logic. | order=321654,125789,34567 |
Sample of a request:
The ad will be returned taking into account the order of line items:
<a href="http://ads2.mocean.mobi/redir/7df0e400-66bc-11e2-9bcf-0a3542e8faa1/0/85187">welcome to mOcean!</a>
Customizing Ads
You can further customize the look and feel of the ads returning from the platform directly via the ad request. Parameters available for this purpose are as follows:
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| border | No | Show borders around banner ads: 0 — no border(default), 1 — show border. | border=1 |
| textborder | No | Show borders around text ads: 0 — no border (default), 1 — show border. | textborder=1 |
| paramBG | No | Background color in HEX. | paramBG=#FFE6CC |
| paramBORDER | No | Border color for text ads in HEX. | paramBORDER=#FF3366 |
| paramLINK | No | Determine the color of links in HEX. | paramLINK=#FF00FF |
NOTE: If these parameters are not specified in the request directly, the appearance of ads shown on a site will be defined by parameters sent via site install code.
Sample of a request:
It returns a banner like this:
<a href="http://ads1.mocean.mobi/redir/3fc36a60-ebba-11df-8f56-001d096a03fe/0/13330">
<img border="1" src="http://img.ads1.mocean.mobi/img/1271132910_337937880_320x50.jpg"/>
</a>
or a text ad like this:
<table border = "0">
<tbody>
<tr>
<td style="border: 1px solid rgb(255, 51, 102); background-color: rgb(255, 230, 204);">
<a style="color: rgb(255, 0, 255); background-color: rgb(255, 230, 204);" href="http://ads1.mocean.mobi/redir/b182d2b1-ebd0-11df-8f56-001d096a03fe/0/6134"> Test mode ad </a><br/>
</td>
</tr>
</tbody>
</table>
Custom Ad Sizes
Mocean Mobile advertising network provides you a unique ability to set the size of ads shown on your site. For this purpose, use the parameters given below:
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| min_size_x | No | Minimal width of the ad banner to be shown. | min_size_x = 280 |
| min_size_y | No | Minimal height of the ad banner to be shown. | min_size_y = 30 |
| size_x | No | Maximal width of the ad banner to be shown. | size_x = 320 |
| size_y | No | Maximal height the ad banner to be shown. | size_y = 50 |
| size_required | No | If set to 1, returns image size (width and height) in a request. | size_required=1 |
- NOTE: To override sizing, you must supply both x and y parameters on the ad request. If you want to have a max size, you must use size_x and size_y. If you want to have a min size, you must use min_size_x and min_size_y. Min and max values do not need to be included at the same time.
All the image size parameters are optional. The algorithm of selecting ads when custom sizes are specified in ad request is represented in Selecting Ads with Custom Sizes.
Setting The Size of Ads Returned
To enable your site to display ads of certain sizes, you should specify any of the parameters above in your install code.
The example of setting size parameters in PHP install code is given below:
<?php>
...
function moceanv2_ad()
{...
$moceanv2_get.='&size_x=320';
$moceanv2_get.='&size_y=50';
$moceanv2_get.='&min_size_x=280';
$moceanv2_get.='&min_size_y=30';
...}
<?>
To get more detailed information about install code samples see Sample Code Snippets.
Default HTML
Sample of an ad request:
In result, the ad server will return the biggest banner (from all the banners matched) that can be shown on the user device with the following sizes:
280 <= width <= 320 and 30 <= height <= 50
Sample of a response (HTML)
<a href="http://ads2.mocean.mobi/redir/4e737d82-c9da-11e0-8569-001ec9fd3a50/0/5472">
<img src="http://img.ads2.mocean.mobi/img/1271132910_337937880_320x50.jpg" width="320" height="50" border="0"/>
</a>
<img src="http://ads2.mocean.mobi/redir/4e737d82-c9da-11e0-8569-001ec9fd3a50" width="1" height="1" /><br>
XML
Sample of a request:
Sample of a response (XML)
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<ad type="image">
<url><![CDATA[http://ads2.mocean.mobi/redir/72a6ea73-c9da-11e0-8569-001ec9fd3a50/0/5472]]></url>
<img width="320" height="50" type="image/jpeg"><![CDATA[http://img.ads2.mocean.mobi/img/1271132910_337937880_320x50.jpg]]></img>
<track><![CDATA[http://ads2.mocean.mobi/redir/72a6ea73-c9da-11e0-8569-001ec9fd3a50]]></track>
</ad>
</mojiva>
Javascript
To have a single ad of the appropriate size to be returned in a JSON response, use 'key=6' in your request.
Sample of a request:
Sample of a response (Javascript):
var 123 = [{"url" : "http://ads2.mocean.mobi/redir/c8c66e70-d2eb-11e0-ac7e-0019b9f99000/0/5472",
"img" : "http://img.ads2.mocean.mobi/img/1256612788_1551852963_320x50.jpg",
"type" : "image/jpeg",
"track" : "http://ads2.mocean.mobi/redir/c8c66e70-d2eb-11e0-ac7e-0019b9f99000",
"width" : "320",
"height" : "50"}];
NOTE: If you want to get a single banner of a certain size in JSON output format, you can use a request for Javascript (without specifying 'jsvar' parameter), replacing brackets "[" and "];" by "(" and ")" in the response, respectively.
Geolocation Parameters
The platform allows advertisers to target line items to any location within a certain radius of a latitude and longitude. Publisher can pass in the following parameters to enable local-targeted advertising:
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| lat | No | User location latitude value (given in degrees). It’s used together with ’long’ parameter. | lat=40.71435 |
| long | No | User location longitude value (given in degrees). It’s used together with ’lat’ parameter. | long=-74.00597 |
| country | No | Country of visitor; it overrides country detected by IP. It is ISO 3166 to be used for specifying country code. | country=US |
| mcc | No | Mobile country code. It is used for determing the country of visitor. You can see the list of MCCs here. | mcc=311 |
| region | No | Region of visitor. ISO 3166-2 is used for United States and Canada and FIPS 10-4 is used for other countries. | region=NY |
| city | No | City of the device user (with state). For US only. | city=New York, NY |
| area | No | Area code of a user. For US only. | area=212 |
| dma | No | DMA code of a user. For US only. | dma=734 |
| zip | No | Zip/Postal code of user. For US only. | zip=10013 |
NOTE: LAT/LONG PARAMETERS EXPLICITLY PASSED IN A USER REQUEST TAKE PRECEDENCE OVER THOSE 'RESTORED' FROM OTHER GEOLOCATION PARAMETERS (IP, CITY, ZIP).
For this purpose parameters specified above are to be added to the install code. Here is an example of setting geolocation parameters in PHP install code:
<?php>
...
function moceanv2_ad()
{...
$moceanv2_get.= ‘&city=’ . urlencoded(‘New York, NY’);
...}
Sample of an ad request:
Geo Location Targeting Detection
Once the ad request received, backend processes it and retrieves parameters that can be used for finding user location.
If no latitude and longitude values are passed, the user’s geolocation is calculated on the basis of any address parameters passed (city or area/dma/zip code).
If there are no address parameters as well, the approximate coordinates of the user can be determined by IP address.
Ad Selection
To detect ads that can be shown to the user satisfying geolocation targeting set for line items, backend makes a calculation of the distance between two geographic points: one specified in the line item targeting and another detected from the ad request. If the result is not more than the radius specified in the line item targeting, the ad can be shown on request.
Sample Code Snippets
The platform provides sample code snippets that implement the HTTP request to the ad server. Code snippets are available in the following programming languages: PHP, PHP CURL, JSP, ASP, CGI/PERL, VB.NET, C#, Ruby On Rails, JavaScript, and XHTML/WML.
You can get them in your custom network for each zone separately. Just copy and paste any of the sample codes and start retrieving ads instantly.
More detailed information about how to get install code snippets can be obtained from the User Guide.
Network Custom Parameters
Mocean Mobile advertising network enables its customers to add their own parameters and pass them in requests.
Being added by a network owner, custom parameters are saved to database and can be further used in targeting.
The example given below demonstrates the way how you can use custom parameters in the request.
Network owner creates a new custom parameter ’age’ in his network with the following settings:
- Name: age
- Type: number
Number Range: min=16, max=100 Default value: none
If you want to get ads targeted by a certain age (e.g. 25), add the parameter age to your request and specify its value.
Sample of a request:
In result, one of two of the following ads can be returned:
- the ad targeted by age=25 and matched by all other filters required;
- the ad not having age targeting at all but matched by all other filters required.
NOTE: TO DETERMINE WHICH AD IS TO BE RETURNED ON THE REQUEST, NOT ONLY TARGETING PARAMETERS ARE TAKEN INTO ACCOUNT BUT ALSO AD PRIORITIES AND SETTINGS.
Thereby, the ad targeted by age=50 can’t be returned on this request even if it is matched by all other filters.
In case multiple value is sent for a custom parameter like at the example below
the ad targeted against at least one of the specified values will be returned, i.e.:
- the ad targeted by age=25 and matched by all other filters required; OR
- the ad targeted by age=40 and matched by all other filters required; OR
- the ad not having age targeting at all but matched by all other filters required.
More detailed information about adding custom parameters can be obtained from the User Guide.
Error Messages
If an error occurred, an error message will be returned on your request. An error can occur for any of the following reason,
No ads available
No ads found on the request.
- Default HTML Failure Response
- For HTML format the empty answer will be returned.
- Header named as "X-Ad-Network-Status" with text "1 No Matching Ad" will be returned.
- XML Failure Response
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<error code='404'>No ads available</error>
</mojiva>
- JSON Failure Response
({"error" : "No ads available"})
- Javascript Failure Response
[{"error" : "No ads available"}];
Invalid parameters
Error code for this reason is -1. The following reasons can lead to this error,
- Zone hassn't been passed in or (if passed) doesn't not exist
- Zone requested (or a site the zone is belong to) has been deleted
- Zone requested is in site that hasn't been approved yet
- Zone specified in the request is in network that is inactive at the moment
- IP is incorrect
- Default HTML Failure Response
<!-- invalid params -->
- XML Failure Response
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<error code='-1'>Error has occured</error>
</mojiva>
- JSON Failure Response
({"error" : "-1"})
- Javascript Failure Response
[{"error" : "-1"}];
Request Timeout
The server timed out while retrieving the ad (error code is 408).
- Default HTML Failure Response
<!-- Error: 408 -->
- XML Failure Response
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<error code='408'>Error has occured</error>
</mojiva>
- JSON Failure Response
({"error" : "408"})
- Javascript Failure Response
[{"error" : "408"}];
Comprehensive Get Parameters List
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| zone | Yes | The id of the zone of publisher site. | zone=123 |
| ip | Yes | Client IP address. If present in the ad request, this parameter overrides the IP of the client making the request. Use this parameter if you are requesting ads on behalf of another client ip. | ip=173.3.77.115 |
| ua | Yes | The browser user agent of the device making the request. Being passed directly, it redefines the value retrieved from ’User-Agent’ header field. | ua=SCH-R211 UP.Browser/6.2.3.8 (GUI)MMP/2.0 |
| url | No | The URL of the page that the ad is requested for. | url=http://mydomain.com/sample_page/ |
| key | No | Output format. Default format uses key=1 (HTML). Parameter key should be set to 3, 5 or 6 in order to use XML output, JSON or Javascript, respectively. | key=1 |
| type | No | Type of ads to be returned (1 - text, 2 - image, 4 - richmedia ad). You can set different combinations with these values. For example, 3 = 1 + 2 (text + image), 7 = 1 + 2 + 4 (text + image + richmedia) and so on. Default value is ’-1’ that means any type of ads can be returned. NOTE: This parameter only works for direct line items, not on ad feeds! | type=7 |
| adstype | No | DEPRECATED. Type of ads (1 - text only, 2 - image only, 3 - image and text). Default value is 3. | adstype=3 |
| count | No | Number of ads that can be displayed in response to a request (from 0 to 5). Default value is 1. | count=1 |
| udid | No | A custom unique identifier with MD5 hashing. Pass this if your system has its own unique identifiers for each user. | udid=476fea48797b7336dabce7b979e8047a |
| test | No | Retrieve test ads. | test=1 |
| timeout | No | Specify timeout of ad call. This tells the ad server the maximum time you are willing to wait for an ad response (in milliseconds) (Min: 1000, max: 3000, default:3000) | timeout=1500 |
| creatives | No | Returns the ad with the specified creative ID. You may specify several creative IDs desired to be returned separating them by commas. In this case the ad selection algorithm will be applied to the specified ads. NOTE: TO USE THIS PARAMETER, MAKE SURE THE LINE ITEM OF THE REQUESTED CREATIVE IS ADJUSTED APPROPRIATELY. To make creatives available to be requested directly, Direct Request option should be set to 'Enabled' for the corresponding line item. | creatives=126545 creatives=123456,58795,2578 |
| excreatives | No | Returns the ad excluding the specified creative IDs. If you would like to exclude some creatives from the processing, specify their IDs (separated by commas). NOTE: TO USE THIS PARAMETER, MAKE SURE THE LINE ITEM OF THE REQUESTED CREATIVE IS ADJUSTED APPROPRIATELY. | excreatives=126545 excreatives=123456,58795,2578 |
| lineitems | No | Returns the creative that belongs to the line item of the specific ID. You may specify several line item IDs that creatives are desired to be returned (separate by commas). NOTE: TO USE THIS PARAMETER, MAKE SURE THE REQUESTED LINE ITEM IS ADJUSTED APPROPRIATELY. | limeitems=321654 limeitems=321654,125789 |
| exlineitems | No | Returns the creative that does not belong to the line item of the specific ID. Several line item IDs can be be also specified separated by commas. NOTE: TO USE THIS PARAMETER, MAKE SURE THE REQUESTED LINE ITEM IS ADJUSTED APPROPRIATELY. | exlimeitems=321654 exlimeitems=321654,125789 |
| order | No | Sorted list of line item IDs desired to be shown first. If ads of line items specified in the "order" parameter can not be served at the moment for any reason (e.g. limits exhausted, targeting is inactive, etc.), another available ad will be returned based on standard ad selection logic. | order=321654,125789,34567 |
| image | No | Used for getting the direct image. Creative must be an image for this to work. | image=1 |
| over_18 | No | Filter ads by over 18 content: 0 or 1 — deny over 18 content, 2 — only over 18 content, 3 - allow all ads including over 18 content. Default value is 0. NOTE: This parameter only works when the site has the over 18 checkbox enabled! | over_18=1 |
| keywords | No | Filter ads by keywords (delimited by commas: keywords=music,book). | keywords=games |
| border | No | Show borders around banner ads: 0 — no border(default), 1 — show border. | border=1 |
| textborder | No | Show borders around text ads: 0 — no border (default), 1 — show border. | textborder=1 |
| paramBG | No | Background color in HEX. | paramBG=#FFE6CC |
| paramBORDER | No | Border color for text ads in HEX. | paramBORDER=#FF3366 |
| paramLINK | No | Determine the color of links in HEX. | paramLINK=#FF00FF |
| min_size_x | No | Minimal width of the ad banner to be shown. | min_size_x = 280 |
| min_size_y | No | Minimal height of the ad banner to be shown. | min_size_y = 30 |
| size_x | No | Maximal width of the ad banner to be shown. | size_x = 320 |
| size_y | No | Maximal height the ad banner to be shown. | size_y = 50 |
| size_required | No | If set to 1, return image size (width and height) in html. | size_required=1 |
| lat | No | User location latitude value (given in degrees). It’s used together with ’long’ parameter. | lat=40.71435 |
| long | No | User location longitude value (given in degrees). It’s used together with ’lat’ parameter. | long=-74.00597 |
| country | No | Country of visitor; it overrides country detected by IP. It is ISO 3166 to be used for specifying country code. | country=US |
| mcc | No | Mobile country code. It is used for determining the country of visitor. You can see the list of MCCs here. | mcc=311 |
| mnc | No | Mobile Network Code. It is used in combination with a mobile country code (MCC) to uniquely identify a mobile phone operator/carrier | mnc=005 |
| region | No | Region of visitor. ISO 3166-2 is used for United States and Canada and FIPS 10-4 is used for other countries. | region=NY |
| city | No | City of the device user (with state). For US only. | city=New York, NY |
| area | No | Area code of a user. For US only. | area=212 |
| dma | No | DMA code of a user. For US only. | dma=734 |
| zip | No | Zip/Postal code of user. For US only. | zip=10013 |
| jsvar | No | FOR JAVASCRIPT OUTPUT FORMAT ONLY! A name of variable that is used to identify ad variable within a page. | jsvar=123 |
| callback | No | A string value that will be integrated into JSONP output if 'key'=5 or 'key'=6. | callback=hello |
| carrier | No | Wireless Carrier Name. You can view the full list of carriers supported by Mocean Mobile here. | carrier=Verizon |
| track | No | If "track=1" is sent, the ad server will automatically respond with 1x1 pixel url alongside the tag and will count an impression ONLY when this pixel is called. NOTE: In case a third party pixel is added to a line item (or from an ad feed) and pixel tracking is enabled on the line item, a compound tracking URL is added: "track" : "http://ads /.mocean.mobi/1/img/52837ed0-b5ab-11e1-9498-005056967d1e?redir=http%3A%2F%2Fad.doubleclick.net%2Fad%2FN5763.157901.MOJIVA.COM%2FB5113120.5%3Bsz%3D1x1%3Bord%3D1339628322%3F". | track=1 |
| no_external | No | If set to 1, it returns any ad except an external ad feed. | no_external=1 |
| imgstyle | No | A string value that will add a style attribute into <img> tag: <img src="http://img.ads.mocean.mobi/img/511/28a/1b46c13/image_320x50.jpg" border="0" style="text-align:center"> | imgstyle=text-align:center |
| encoding | No | If passed, allows to get the ad encoded. If not specified, UTF-8 is applied. | encoding=UTF-32 |
| target | No | Changing the <a> target for HTML responses. |
