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 publisher site. | zone=123 |
| ip | Yes | The IP address of the carrier gateway which the device is connecting over. Being passed directly, it redefines the IP address the request has been received from. | 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 campaigns, not on ad feeds! | type=7 |
| adstype | No | DEPRECATED. Type of ads (1 - text only, 2 - image only, 3 - image and text, 6 - SMS ad). Default value is 3. SMS ads can be returned in XML format ONLY and should be used along with key=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>
If there is no pixel tracking present (custom or network level), then <track> would be empty, like this:
<track><![CDATA[]]></track>
For getting SMS ads specify the corresponding ad type in the request. Response format for SMS ads matches with one for text ads.
Note: For SMS ads, the URL is shortened to 35-40 characters.
If no ads are available, the following is returned:
<?xml version="1.0" encoding="UTF-8"?>
<mojiva>
<error code='404'>No ads available</error>
</mojiva>
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 ’url’ parameter contains the CLICK URL and the ’img’ parameter returns all possible sizes available for the campaign. The ’track ’ parameter would contain the pixel tracking URL.
If no ads are available, it will return the following:
({"error" : "No ads available"})
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/f2e6d6e0-6199-11e0-959a-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"}];
If no ads are available, it will return the following:
var 123 = [{"error" : "No ads available"}];
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",
"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" ]}]);
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]]>
</url>
<track>
<![CDATA[http://ads1.mocean.mobi/img/7a09fb80-6199-11e0-959a-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]]>
</url>
<img>
<![CDATA[http://img.ads1.mocean.mobi/img/1271132910_337937880_320x50.jpg]]>
</img>
<track>
<![CDATA[http://ads1.mocean.mobi/img/7a09fb81-6199-11e0-959a-001d096a03fe]]>
</track>
</ad>
</mojiva>
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/aa76b140-f2d7-11df-99f5-001d096a03fe/0",
"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"})
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">
<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=JnRhX3NzcF9pZD1NT0NFQU5f
UlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRh
X2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRj
YS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg3D%3D">
<img src="http://rtb-test.dev.tapad.com:8080/creative/banner?creative_id=2&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5f
UlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRh
X2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRj
YS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%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=JnRhX3NzcF9pZD1NT0NFQU5f
UlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRh
X2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRj
YS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%3D%3D">
<img src="http://rtb-test.dev.tapad.com:8080/creative/banner?creative_id=2&ta_pinfo=JnRhX3NzcF9pZD1NT0NFQU5f
UlREJnRhX2JpZD1iYjhhOTAwMC1jZjBiLTQ5YmEtODM5OS04YmEyMWQ1MjZhODkmdGFfdGFjdGljX2lkPTEmdGFfY2FtcGFpZ25faWQ9MSZ0YV9jcmVhdGl2ZV9pZD0yJnRh
X2NvbnRleHRfaWQ9QkxJTkQmdGFfZGlkPWZjMWQ5OWU4LWEwMTktNGJkZi1iM2RlLTZjYmY4ZmNlNGFmOCZ0YV9wZl9pZD1Db21wdXRlciZ0YV9waWQ9ZTA3NGVlNzMtNWRj
YS00NTYyLWE3YjQtZDcyOTQwNWRkZTJkJnRhX3NzcF9kZXZfaWQ9NTkxMGJiMjk1ODJiNjM4YWY4NDFiMWZhMzgxOGU0YjFlZTExNzMzZg%3D%3D&ta_win_prc=0.0100"></img></a>
</response>
</ad>
</mojiva>
<url> – click URL/destination URL.
<text> – any ad text (either independently or below the ad).
<img> – direct IMG URL of ad.
<content> – all the ad content is placed in the this node as is from 3rd party.
<response> - the original response from the third party 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 original response from the third party server marked with the response tag.
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 Third Party Campaigns.
Third Party (Client Side SDK)
Below, examples of client-side external 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 integration. The example given above contains parameters related to Generic's external campaigns.
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>
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>
All the ad content is placed in the <richmedia> node AS IS.
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>"})
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 a NULL response will be returned.
Requesting Specific Ads
Mocean Mobile Platform also supports a direct request to a specific ad(s).
NOTE: TO USE THIS FUNCTIONALITY, MAKE SURE THE REQUESTED CAMPAIGN (AD) IS ADJUSTED APPROPRIATELY. To enable a campaign to be requested directly, you need selecting one of the following ad modes for this campaign: 'Serve Ads On External only' or 'Serve Ads on Both (this network and external ones)'.
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| campaigns | No | Returns the ad with specified ID. If you want several ads to be returned, specify their IDs (separated by commas). | campaings=126545
campaigns=123456,58795,2578 |
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>
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">
<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"> 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 |
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 campaigns 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 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 which campaigns with geolocation targeting set can be displayed to the user, backend makes a calculation of the distance between two geographic points: one specified in the campaign targeting and another detected from the ad request. If the result is not more than the radius specified in the campaign targeting, the campaign 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 campaigns 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 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 CAMPAIGN 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.
More detailed information about adding custom parameters can be obtained from the User Guide.
Selecting Ads with Custom Sizes
Click here to view the ads selection scheme
Comprehensive Get Parameters List
| Parameter | Required | Description | Code Sample |
|---|---|---|---|
| zone | Yes | The id of the zone of publisher site. | zone=123 |
| ip | Yes | The IP address of the carrier gateway which the device is connecting over. Being passed directly, it redefines the IP address the request has been received from. | 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 campaigns, not on ad feeds! | type=7 |
| adstype | No | DEPRECATED. Type of ads (1 - text only, 2 - image only, 3 - image and text, 6 - SMS ad). Default value is 3. SMS ads can be returned in XML format ONLY and should be used along with key=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 (default: 1000ms, max: 3000ms) | timeout=1500 |
| campaigns | No | Returns the campaign with the specified ID. If you want several campaigns to be returned, specify their IDs (separated by commas).
NOTE: TO USE THIS FUNCTIONALITY, MAKE SURE THE REQUESTED CAMPAIGN (AD) IS ADJUSTED APPROPRIATELY. To enable a campaign to be requested directly, you need selecting one of the following ad modes for this campaign: 'Serve Ads On External only' or 'Serve Ads on Both (this network and external ones)'. | campaigns=126545
campaigns=123456,58795,2578 |
| excampaigns | No | Returns the ad excluding the specified campaign IDs. If you want several campaigns to be excluded, specify their IDs (separated by commas). | excampaigns=126545
excampaigns=123456,58795,2578 |
| premium | No | Filter ads by premium status (0 - non-premium, 1 - premium only, 2 - both). Default value is 0. | premium=2 |
| over_18 | No | Filter ads by over 18 content: 0 or 3 — allow all ads including over 18 content, 1 — deny over 18 content, 2 — only over 18 content. Default value is 0. | over_18=1 |
| keywords | No | Filter ads by keywords (delimited by keywords=music, commas). | 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 |
| 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 |
