Skip to end of metadata
Go to start of metadata

 

 Click here to expand Version History!

Version History

VersionDateAuthorComment
3.1.102/03/2009MOAdded link to list of Mobile Network Codes (MNC). Updated sample XML response. Shortened introduction. Added examples to the HTML response. Parameter ‘carrier’ is not mandatory.
3.1.2.04/23/2009MOAdded section that describes the beacon support. Changes in the header forwarding section. Layout changes.
3.1.3.06/05/2009MOAdded development and production server URLs. 
3.1.4.07/02/2009MOExtended the http header forwarding section. Added description to error code 42. 
3.1.5.09/04/2009MOAdded instructions how to pass the UDID for iPhone apps. 
3.1.6. 12/10/2009MOChanges according to the new publisher portal and according to the automated rollout process. Included targeting parameter document. Minor changes. 
3.1.7.02/16/2010MOAdded parameters for analytics. Added medium rectangle format. Minor changes.
3.1.8.04/16/2010MONew URLs are smaato.net 
3.3.0.04/27/2011MORestructuring of the parameter section. New targeting parameters. Minor maintenance changes und updates. Section “OwnId” updated. Added privacy section. Video Ads. 
4.0.0.06/09/2011MOAdded Rich Media Ad Format. Important: Enhanced usage of parameter “format”. Added new parameters “dimensions” and “formatstrict”. 
4.0.1.10/26/2011MOMinor changes. Added multiline text ads (see XML response description). 
4.1.2.05/22/2012MOMajor updates to the handling of unique IDs (UDID, ODIN etc.). Removed parameter “client”. Added Parameter “apiver” (mandatory). Parameter ‘formatstrict’ is not mandatory anymore. Changes value range of “dimension” parameter.
4.1.3.09/28/2012MOAdded Apple Advertising Identifier.
4.1.4.07/01/2012MORemoved ODIN and MACMD5 (not allowed from iOS 7). Added interstitial ads.
4.1.505/06/2014MORevised interstitials ad formats. Added Google advertising ID. Added “COPPA” parameter. Added MRAIDVER parameter.
5.003/19/2015NCIntroduced VAST video ads & Native Ads.
API 5.0.108/18/2015NCAdded OpenRTB-conform VAST No Ad Available Response.
API 5.0.211/17/2016BRAdded Outstream & Rewarded Video

Introduction

The SOMA API is the publisher interface used for communication with the Smaato Open Mobile Advertising infrastructure ("SOMA"). The SOMA API is designed to fulfill the needs of mobile publishers as well as mobile application and game developers.

The API can be requested by calling a specific URL with a query string of certain parameters. The SOMA server will respond via HTML or XML.

Important Note:

If you’re looking to ad-enable mobile apps, please have a look at our SDKs for all major platforms.

For a copy and paste client side integration into your mobile site or app, check out our Ad Tag.

If you’re looking for a server-based integration and you’re running a Java or PHP-based server environment, you may want to shorten the integration by using our PHP and JSP code snippets.

Adspace Sizes

The Adspace is the area you have designated for advertisements on your mobile web site or application. On mobile web sites, the size of this space is dynamic in most cases. SOMA uses device recognition to select the best fitting banner size.

For in-application advertising, the size of the Adspace is usually fixed. It is required that you adjust the size of your Adspace according to the internationally accepted ad formats defined by the Mobile Marketing Association (MMA).

Your Adspace must fit one of the following sizes:

  • 320 x 50 (MMA XXLarge) – The most common format and our recommendation
  • 300 x 50 (MMA XLarge)
  • 216 x 36 (MMA Large)
  • 168 x 28 (MMA Medium)
  • 120 x 20 (MMA Small)

Please note: Larger formats are always preferable as they lead to higher click-through-rates and therefore higher revenues. See also: MMA Guidelines (PDF).

IAB ad formats

Smaato supports ads in the IAB medium rectangle (300 x 250), skyscraper (120 x 600) and leaderboard (728 x 90) format. The formats are designed to be used on tablets and on startup, interstitial or closing screens on smartphones.

Full Screen Ads

Smaato supports full screen ads that can be displayed for example as pre-roll, post-roll or interstitials.To request a full screen ad, use a full screen dimension parameter value (see parameter list below).


*New: VAST Video Ads
*

VAST Video can be used for example for Pre-/Post-/Mid-Roll ads. They can ONLY be requested with “format=vast”. VAST Video ads can only be requested in combination with the response format “XML”.

If you’re planning to use these formats, please contact us.

*New: Native Ads*

Smaato supports native ads. Those are ads that can be shown the way you want and will look as if they are part of the app content. They can ONLY be requested with “format=native”. If you’re planning to use these formats, please contact us

Request URLs

The URL used for making requests to SOMA Server is:

http://soma.smaato.net/oapi/reqAd.jsp

Privacy

Smaato is committed to protect privacy and data protection and strictly complies with applicable data protection laws. We require the client to inform the end user about the personable identifiable information it collects. Moreover, the client is obliged to give the end user the option to “Opt-out” from such action. If the end user chooses to “Opt-out” at any time, the client is required to promptly inform Smaato of an “Opt-out”.

Using the SOMA API

The SOMA API call consists of two separate http-requests. The first request can be established from a web server or from a mobile device directly. The response will contain the URL to download the image from the ad network’s server (or the ad text) and the click URL as well as URLs to beacons for 3rd party validation. The second request, which downloads the banner image and beacons (if applicable) must be made from the mobile device directly (!). Downloading the beacons is always required – even if the ad type is text!

Requesting advertisements from the SOMA API is done by calling the request URL (see below) with a set of parameters in the query string. The server responds with a HTML snippet to be pasted into your mobile site, or with an XML file. We recommend using the HTML response format.

Figure 1: Ad Request Flow Chart

HTTP Header Forwarding

When using a Client<->Server<->SOMA architecture (the request to SOMA is not done directly by a mobile device), all (!) http-headers that the publisher’s server receives from the mobile client need to be forwarded to SOMA.

Which headers are needed?

In general, we need to have ALL headers that your server receives from the communication with the mobile device forwarded. The only exceptions are custom headers that are set by your mobile application (for internal reasons).

Naming of the forwarded headers

We need to identify the forwarded headers and separate them from the headers from the communication with your server. For that reason, the headers need to be renamed. Please prefix all headers with “x-mh-” - even headers that have names starting with “x-”. The “x-” prefix has become a common way to indicate custom headers that are not standardized in any RFC (explanation on Microsoft TechNet).

Examples for original headers (your server received from the mobile device):

X-Wap-Profile: http://www.blackberry.net/go/mobile/profiles/uaprof/9000_umts/4.6.0.rdf
Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
User-Agent: BlackBerry9000/4.6.0.162 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111
X-Forwarded-For: 203.177.91.193, 62.159.30.165, 67.69.254.254
X-Operamini-Phone-Ua: BlackBerry

Examples for the prefixed forwarded headers (your server forwards to the SOMA server):

x-mh-X-Wap-Profile: http://www.blackberry.net/go/mobile/profiles/uaprof/9000_umts/4.6.0.rdf
x-mh-Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
x-mh-User-Agent: BlackBerry9000/4.6.0.162 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111
x-mh-X-Forwarded-For: 203.177.91.193, 62.159.30.165, 67.69.254.254
x-mh-X-Operamini-Phone-Ua: BlackBerry

Beacons

Like the online advertising market did several years ago, the mobile advertising market starts demanding trusted parties to validate traffic, data and performance.

Beacons, or so-called tracking pixels, help to count the view of the advertiser’s ad via a third party and to double check ad server delivery.

A beacon is a transparent 1x1 GIF, which has to be requested by the mobile device directly after the banner image or the text ad, is displayed.

How to handle beacons correctly:

The beacon portion of the response starts with the opening tag <beacons>, and closes with </beacons>.

Within this portion, each beacon will accordingly start with <beacon>, and end with </beacon>.

Response Example (Beacon Excerpt)
<beacons>
	<beacon>http://ec2-50-19-220-110.compute-1.amazonaws.com/oapi/getBeacon.jsp;jsessionid=F0A642E6EA7C613A98457B229A44B9BD.f114</beacon>
	<beacon>http://click.moadlink.com/tinyurl/4381db-06b5-48db-ba51-8f3c7aag</beacon>
</beacons>

Responses may return multiple beacons; please note that all of them need to be handled.

Please make sure to set up the beacon call so that it is immediately called after the ad creative is displayed, but not before that!

This especially refers to e.g. the following case: if an interstitial is being loaded in the background, the beacon(s) should be called as soon as the creative is displayed, not as soon as it’s fully been returned.

Please also respect the following:

  • Modifying or redirecting the beacon URL, loading the beacon via JavaScript or placing the beacon in a frame or layer are not allowed
  • In the HTML code, the beacon must be placed right after the ad

AdSpaceID/PublisherID (parameters)

You can retrieve your IDs from the Smaato publisher portal.

Unique ID Parameters (IDFA, Google Advertising ID, Android ID)

Certain high-priced campaigns of our ad network partners require to anonymously identify users. The parameters above are used to transfer different types of these IDs.

For mobile application traffic at least one of these parameters is required.

Query String

It is important that you take care that the query string is separated and encoded correctly. Please refer to the encoding guidelines, e.g. RFC 3986 or Wikipedia if you are not sure.

A quick overview:

  • ? separates the query string from the rest of the URL.
  • & separates the field-value pairs (parameters).
  • ; separates the J-Session parameter
  • The syntax for a parameter is [fieldname]=[value].
  • Only the following characters are allowed: 
    • Letters (A-Z and a-z)
    • Numbers (0-9)
    • The characters '.', '-', '~' and '_'
  • Space is encoded as +.
  • All other special characters are encoded with percent-encoding (e.g. %40 means @)
  • Use commas to separate multiple values of the same parameter (e.g. kws=hello,world,app)
Example:
http://soma.smaato.net/oapi/reqAd.jsp?adspace=0&pub=0&devip=123.45.67.89&device=Nokia1680c-2%2F2.0+%2805.61%29+Profile%2FMIDP-2.1+Configuration%2FCLDC-1.1&format=all&response=XML

General Parameters

ParameterMandatoryDescriptionTypeExample

apiver

yes

The version of the API you’re using (version of this document).

integer
502
adspaceyesAdSpaceID (assigned by Smaato). ID “0” can be used for unattended testing purpose.integer
123456789
pubyesPublisherID (assigned by Smaato). ID “0” can be used for unattended testing purpose.integer
4711

devip

yes (‘no’ if the device is requesting directly or if you’re sending an x-forwarded-for header)The IP address of the requesting mobile device (this may differ from the request IP e.g. if a publisher’s web server is between the mobile device and SOMA).IP
123.45.678.90
dividyes (for mobile web)

Mobile Web only: The ID of the div (or equally suitable HTML element) that you're using to serve the ad. This needs to be formatted in the following way: smt-[AdspaceID]

Please note: If you fail to do this, ad display may not work.

stringsmt-123456789
refyes (‘no’ if the device is requesting directly or if you’re sending the correct referer header of the requesting webpage)Referer: The URL that identifies the address of the webpage where the ad request is coming from.stringhttp%3A%2F%2Fwww.example.com
deviceyes (‘no’ if the device user agent is sent as a header)The user agent of the device's defaultstring
Mozilla%2F5.0%20(Linux%3B%2
0U%3B%20Android%202.2.1%3B%
20en-us%3B%20Nexus%20One%20
Build%2FFRG83)
%20AppleWebKit%2F533.1%20(K
HTML%2C%20like%20Gecko)%20V
ersion%2F4.0%20Mobile%20Saf
ari%2F533.1
mraidver 

1 – MRAID 1.x
2 – MRAID 2.x

integer
2

nsupport

no 

The requested native ad component names separated by comma. If not set, at least a title and a click through url will be included in the ad response. 

String: 

Comma separated values. 

title, txt, icon, image, ctatext 

vastver 

Yes (if format=video) 

Set to 2

integer 

2

nver 

Yes (if format=native) 

Set to 1 

integer 

videotypeYes (if format=video) 

Choose between:

  • instream-pre
  • instream-mid
  • instream-post
  • outstream
  • interstitial
  • rewarded
stringinstream-pre
formatyes

The format of the ad to be returned:

  • all: Image, text or rich media (strongly recommended!)
  • img: Any image format
  • txt: Text
  • richmedia: Rich media
  • video: Video Ads (Note: “response” must be “XML”)
  • native: Native Ads (Note: “response” must be “XML”) 
string
img
formatstrictnoDefault: false. When the format parameter is handled as “strict” only the desired format will be delivered. If it’s not strict, an alternative format might be delivered, if the desired format is not available.boolean
true
dimensionno

The desired dimension of ad to be returned:

  • xxlarge (recommended): this is the most common size (320 x 50)
  • medrect: IAB Medium Rectangle (300 x 250)
  • sky: IAB Skyscraper (120 x 600)
  • leader: IAB Leaderboard (728 x 90)
  • full_320x480: Interstitial ad for smartphones (portrait - switch dimensions for landscape)
  • full_640x960: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_640x1136: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_768x1024: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_800x1280: Interstitial ad for tablets (portrait - switch dimensions for landscape)
string
xxlarge
dimensionstrictno

Default: false.
When the dimension parameter is handled as “strict” only the desired dimension will be delivered. If it’s not strict, an alternative dimension might be delivered, if the desired format is not available.

boolean
false
iosadidyes (for iOS applications)Apple’s Advertising Identifier. See herestring
1D76F5D1-1983-47C8-B18D-119D52E4597A
iosadtrackingyes (for iOS applications)Apple’s advertisingTrackingEnabled Property. See here. (false = user has decided against tracking – this is the opposite way around as on Android)boolean
true
googleadidyes (for Android Applications)Google Android Advertising ID. See http://bit.ly/MBMTTJstring
40d9e394-740a-4225-83f1-766a04154b83
googledntyes (for Android Applications)Android limit ad tracking preference. (true = user has decided against tracking – this is the opposite way around as on iOS)boolean
true
androididnoThe Android device’s Android ID (Settings.Secure.ANDROID_ID)string
9774d56d682e549c
bbidyes (for BlackBerry Applications)The BlackBerry Device IDstringe3365064be00b474622467f06493a2d282a464ad
wpidyes (for Windows Phone Applications)The Windows Phone Device IDstring513339592119231246
responseyesDesired format of the response. xml, html or json. (must be XML for Video).string
html
coppayes (traffic from the US)

“0” will indicate that your content should not be treated as child-directed for purposes of COPPA.
“1” will indicate that your content should be treated as child-directed for purposes of COPPA.

0 or 1
0
carriernoName of the current carrier.string
o2uk
carriercodenoMCC and MNC code of the current carrier. Format: carriercode={mcc}{mnc}. In the example the MCC is 234 and the MNC is 02.integer
23402
heightnoHeight of the ad space. Recommended for in-application advertising.integer
36
widthnoWidth of the ad space. Recommended for applications.integer
36
sessionnoA MD5 hash generated at the start of every session and used throughout the whole session. We recommend hashing the device’s hardware ID and the time of session start.mD5
c30f5ddc0be5031ddbdcc962cce07ac9

Additional Targeting Parameters

The following parameters can be sent with the ad request in order to allow Smaato a more precise targeting of ads. Even though all of these parameters are optional it is strongly recommended to fill as many of them as possible. Better targetable inventory has a higher value to advertisers and is therefore very likely to be better monetized.
Important: Please inform your users what data you’re sending to third parties and allow them to opt-out. 

Parameter NameDescriptionRange Of ValuesExample
Content
kwsTags (free text, case insensitive) describing the content.string: comma separated values
motorsport, news, cars
User
ageThe user’s age. 2-digit number. If only a range is available, use the mean average.integer
30
genderThe user's gender.m, fm
qsQuery String: A search term entered by the user within the mobile site.

string: comma separated values

coffee, san+francisco
Location: Information on the user’s location
gpsGPS coordinates of the user's location.string: Latitude and longitude in decimal degrees format, comma separated
37.530676,-122.262447
regionThe region or state, the user is located in.string
california
zipThe postal code of the user's location.string
94402
Device
devicemodelThe device model. For iOS devices: The exact model.string
iPhone3,1
devicemakeThe device manufacturer.string
Apple
areacodeThe current location area code (LAC).string
+40

SOMA HTML Response

The server response will include one or both of the following header-information:

1. “SomaError”

This header will be sent if any error occurs. If no error occurred, this header will not be sent.

2. “SomaUserID”

If this header is sent within the response, the value MUST be used for ALL future requests of this specific user. Example: SomaUserID: 900

The HTML code, depending on the ad-format, looks like:

<p>
<a href="[link to the landing page]">
<img src="[link to the image]" ... />
</a>
<img src="[link to the beacon]" width="1" height="1" border="0" />
</p>

Example (image):

<p>
	<a rel="nofollow" href="http://54.173.249.96/oapi/clickAd;jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a">
		<img src="http://54.173.249.96/oapi/getAd;jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a" border="0" alt="" width="320" height="48"/>
	</a>
		<img border="0" src="http://54.173.249.96/oapi/getBeacon;jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a" alt=""/>
</p>

If it is a text-ad the response looks like:

<p>
<a href="[link to the landing page]">
Text-Ad-Text
</a>
<img src="[link to the beacon]" width=”1” height=”1” border=”0” />
</p>

Example (text):

<p>
<a rel="nofollow" href="http://54.165.21.96/oapi/clickAd;jsessionid=4C1146C02497571C10CE5A5B9CC8CDB3.soma-i-f046f701">
Please visit smaato.com! </a>
<img border="0" src="http://54.165.21.96/oapi/getBeacon;jsessionid=4C1146C02497571C10CE5A5B9CC8CDB3.soma-i-f046f701" alt=""/>
</p>

Example (Richmedia /JavaScript):

<script type=’text/javascript’>
// some javascript code
</script> <noscript>Advertisement</noscript>
<img border="0" src="http://soma.smaato.net/oapi/getAd;jsessionid=88F36D0C333AF30C6A3EEF0ECB8592E7.soma-i-dc746830" alt="">

Example for No Ad Available:

The header will contain the SomaError code 42; Currently no ad available.

<p>&nbsp;</p>

SOMA XML Response

Example (Image/Text):

<response xmlns="http://soma.smaato.com/oapi/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://soma.smaato.com/oapi/ http://www.smaato.com/definitions/xsd/smaatoapi_v2.xsd">
<sessionid>5D9885EACBF823C16316FD37A89D57E5.soma-i-d9d58835</sessionid> <status>success</status>
<user>
<id>900</id>
<ownid>358240057024713</ownid> </user>
<ads>
<ad id="0" type="TXT">
<log-id/>
<valid start="0" end="0" max="1"/> <link/>
<action target="http://54.175.97.51/oapi/clickAd;jsessionid=5D9885EACBF823C16316FD37A89D57E5.soma-i-d9d58835" acc="server"/>
<adtext>Please visit smaato.com!</adtext>
<beacons>
<beacon>
http://54.175.97.51/oapi/getBeacon;jsessionid=5D9885EACBF823C16316FD37A89D57E5.soma-i-d9d58835
</beacon> </beacons> </ad> </ads> </response>

Example (VAST Video):

<VAST version="2.0">
<Ad id="223626102">
<InLine>
<AdSystem version="2.0">Smaato</AdSystem> <AdTitle>In-Stream Video</AdTitle>
<Description>A test creative with a description.</Description> <Survey/>
<Creatives>
<Creative sequence="1" AdID="">
<Linear>
<Duration>00:00:15</Duration>
<TrackingEvents>
<Tracking event="start"><![CDATA[http://soma.smaato.net/videoStart]]></Tracking>
<Tracking event="midpoint"><![CDATA[http://soma.smaato.net/midPoint]]></Tracking>
<Tracking event="midpoint"><![CDATA[http://soma.smaato.net/midPoint2]]></Tracking>
<Tracking event="firstQuartile"><![CDATA[http://soma.smaato.net/firstQuartile]]></Tracking>
<Tracking event="firstQuartile"><![CDATA[http://soma.smaato.net/firstQuartile2]]></Tracking>
<Tracking event="thirdQuartile"><![CDATA[http://soma.smaato.net/thirdQuartile]]></Tracking>
<Tracking event="thirdQuartile"><![CDATA[http://soma.smaato.net/thirdQuartile]]></Tracking>
<Tracking event="complete"><![CDATA[http://soma.smaato.net/complete]]></Tracking>
<Tracking event="complete"><![CDATA[http://soma.smaato.net/complete2]]></Tracking>
<Tracking event="mute"><![CDATA[http://soma.smaato.net/mute]]></Tracking>
<Tracking event="pause"><![CDATA[http://soma.smaato.net/pause]]></Tracking>
<Tracking event="fullscreen"><![CDATA[http://soma.smaato.net/fullscreen]]></Tracking>
<Tracking event="fullscreen"><![CDATA[http://soma.smaato.net/fullscreen2]]></Tracking>
</TrackingEvents>
<AdParameters/>
<VideoClicks>
<ClickThrough><![CDATA[ http://www.smaato.com ]]></ClickThrough>
<ClickTracking id="DART"><![CDATA[http://soma.smaato.net/clickTracking]]></ClickTracking>
<ClickTracking id="ThirdParty"><![CDATA[http://soma.smaato.net/clickTracking2]]></ClickTracking>
</VideoClicks>
<MediaFiles>
<MediaFile id="1" delivery="streaming" type="video/mp4" bitrate="457" width="300" height="225"><![CDATA[http://smaato-ads.s3.amazonaws.com/1340012129241.mp4]]></MediaFile>
</MediaFiles>
</Linear>
</Creative>
<Creative sequence="1" AdID="">
<CompanionAds><Companion height="50" width="320" id="555750">
<HTMLResource><![CDATA[<img src="http://smaato-ads.s3.amazonaws.com/140076851990989.jpg" height="50" width="320">]]></HTMLResource>
</Companion></CompanionAds> </Creative>
</Creatives>
</InLine>
</Ad>
</VAST>

Example (Rich Media/JavaScript):

<response xmlns="http://soma.smaato.com/oapi/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://soma.smaato.com/oapi/ http://www.smaato.com/definitions/xsd/smaatoapi_v2.xsd">
<sessionid>2D085D2024BB001344ABE19E72DEE244.soma-i-b1b9a84a</sessionid> <status>success</status>
<user>
<id>900</id>
<ownid>358240057024713</ownid> </user>
<ads>
<ad id="0" type="RICHMEDIA"> <log-id/>
<valid start="0" end="0" max="1"/> <mediadata>
<![CDATA[
<script src=\"mraid.js\"><\/script>\r\n<div class=\"celtra-ad-v3\">\r\n
style=\"display: none\" onerror=\"\r\n (function(img) {\r\n {\'clickUrl\':\'\',\'clickEvent\':\'advertiser\',\'externalAdServer\':\'Custom\'};\r\n var req = document.createElement(\'script\');\r\n req.id = params.scriptId = \'celtra-script-\' + (window.celtraScriptIndex = (window.celtraScriptIndex||0)+1);\r\n params.clientTimestamp = new Date\/1000;\r\n var src = (window.location.protocol == \'https:\' ? \'https\' : \'http\') + \':\/\/ads.celtra.com\/9d69ec31\/mraid-ad.js?\';\r\n for (var k in params) {\r\n
+ encodeURIComponent(k) + \'=\' + encodeURIComponent(params[k]);\r\n }\r\n
src;\r\n img.parentNode.insertBefore(req, img.nextSibling);\r\n })(this);\r\n
]]>
</mediadata>
<link/>
<action target="" type=""/>
<beacons>
<beacon>http://54.173.249.96/oapi/getAd;jsessionid=2D085D2024BB001344ABE19E72DEE244.soma-i-b1b9a84a</beacon>
</beacons>
</ad>
</ads>
</response>

Example (Native Ads):

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://soma.smaato.com/oapi/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://soma.smaato.com/oapi/ http://www.smaato.com/definitions/xsd/smaatoapi_v2.xsd">
   <sessionid>83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d</sessionid>
   <status>success</status>
   <user>
      <id>900</id>
      <ownid />
   </user>
   <ads>
      <ad id="0" type="NATIVE">
         <log-id />
         <valid start="0" end="0" max="1" />
         <beacons>
            <beacon>http://soma.smaato.net/oapi/adspacer.gif</beacon>
            <beacon>http://52.17.141.198/oapi/getAd;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d?requestUrl=http%3A%2F%2F52.17.141.198%2Foapi%2Fimg%2Fadspacer.gif</beacon>
         </beacons>
         <SNAST>
            <adtitle>Smaato</adtitle>
            <adtext>The Leading Global Mobile RTB Ad Exchange andi SSP</adtext>
            <iconimage>
               <icon width="80" height="80">http://52.17.141.198/oapi/getAd;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d?redirectUrl=http%3A%2F%2Fdemofiles.smaato.com%2Fnativeads%2Ficon.png</icon>
            </iconimage>
            <mainimage>
               <image width="1200" height="627">http://52.17.141.198/oapi/getAd;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d?redirectUrl=http%3A%2F%2Fdemofiles.smaato.com%2Fnativeads%2Fmainimage.png</image>
            </mainimage>
            <starrating>4.5</starrating>
            <ctatext>Read more</ctatext>
            <beacons />
            <clickurl>http://52.17.141.198/oapi/clickAd;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d</clickurl>
         </SNAST>
      </ad>
   </ads>
</response>

SOMA XML Response Value Description

status: The status of the response. Possible values are “success” or “error” (see error codes below).

user: Information about the user:

  • id: Deprecated
  • ownid (optional): The unique hardware ID of the device sent during the request.

ads: The meta data of the ads returned (usually one ad)
ad

  • id: The unique id of the ad.
  • type: The type of the ad. Possible values are IMG for banner ads, TXT for text ads, VIDEO for video ads or RICHMEDIA for richmedia (JavaScript / HTML5) ads. Depending on the campaign, the IMG type may be more detailed (GIF,JPEG or PNG).
  • width (optional): The width of the image ad.
  • height (optional): The height of the image ad.
  • log-id: The unique id generated by the ad-server to store the appropriate tracking information.
  • valid: The validity period of the ad.
  • start: Start-date from when the ad can be shown (in milliseconds since 01.01.1970).
  • end: End date until the ad can be shown (in milliseconds since 01.01.1970).
  • max: Describes how often the ad can be shown (usually 1).

link: The link to the ad itself. Empty if it is a text-ad or video ad.

mediafiles: (Video Ads only) The meta data of the video ads returned (usually one file)

mediafile: The URI of the video ad file.

  • delivery: The delivery scheme (normally “progressive”)
  • bitrate: The bitrate of the video.
  • type: The MIME-Type of the video.

mediadata: (Rich Media only): The HTML/JavaScript code of the ad.

action: Describes the action(s) associated to the ad.

  • type …of the action. Possible values can be LINK (more to follow).
  • target URI, e.g. URL of the landing page or a WTAI call.
  • acc …states, where the accounting takes place. Currently Server is supported.

adtext (optional for image ads, n/a for video ads): Main advertising text.

adtextdescription: Additional (descriptive) lines of ad text (up to 3 lines to be displayed below the main ad text).

descriptionline: Additional line of ad text.

snast: native ad tag that will contain the creative items

adtitle: The ad title, 

adtext: The ad text.

iconimage: icon image tag that will contain the icons (usually one)

icon: The icon URL (80 x 80 px recommended)

mainimage: The main image tag that contains the images (usually one)

image: The image URL (1200 x 627 px recommended)

starrating: a float e.g. 4.5, which is usually served when the creative is related to an app advertisement.

ctatext: The text that should be used for the click to action button e.g. "Install" or "Learn more"

clickurl: click url that should be used to redirect the user when he clicks on the ad

beacons: Tracking pixels that have to be requested when the ad is displayed.

beacon: The URL to a beacon.

 

For documentation on VAST XML response values, please refer to the IAB's VAST 2.0 Documentation.

XML Error Response

If an error occurs while processing the request or no ad can be delivered an error will be sent.

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://soma.smaato.com/oapi/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://soma.smaato.com/oapi/ http://www.smaato.com/definitions/xsd/smaatoapi_v2.xsd">
   <sessionid>1E22125B052C061E9797737A0EB3F9C2.soma-i-9b86276a</sessionid>
   <status>error</status>
   <user>
      <id>900</id>
      <ownid>358240057024713</ownid>
   </user>
   <error>
      <code>42</code>
      <desc>Currently no ad available</desc>
   </error>
</response>

Please note: From API Version 5.0.1 on, VAST No Ad Available Responses are returned according to OpenRTB specifications:

VAST No Ad Available Response:

<VAST version="2.0"/>

Possible request error codes (for XML and HTML responses)

ID

Description

Comment

42

Currently no ad available

No ad is currently available matching the requesting parameter. The following descriptions are possible (between <desc> and </desc>:

-        Currently no ad available The standard response.

-        BOT-Request: (User-Agent: bot.txt(207.154.59.124) The request has been identified to be a bot request.

-        Invalid IP-Request: (10.1.1.1) The DEVIP parameter was set to an invalid IP address (e.g. private IPs)

84

Missing parameters inside request

One or more of the mandatory parameters was not sent.

101

User-ID could not be created

The server failed to create a new user id. After receiving, this error should be provided to Smaato as soon as possible.

106

Bad request

The “pub” or “adspace” parameter has an invalid value / missing parameter.

107

./.

Different error descriptions. Please provide the description after receiving this error.

SOMA JSON Response

We also provide responses in JSON (please note: as HTML, JSON doesn't work for video!) - if you're interested in that, just set the response parameter to json. This is an example response: 

{  
   "sessionid":"EC463AEC3B6300C1A0963FCC112450BF.soma-i-0d82229163740900e",
   "status":"SUCCESS",
   "type":"IMG",
   "link":"http://creatives.smaato.com/creatives/1455872039590.jpg",
   "target":"http://52.210.25.165/oapi/clickAd;jsessionid=EC463AEC3B6300C1A0963FCC112450BF.soma-i-0d82229163740900e",
   "width":120,
   "height":20,
   "beacons":[  
      "http://52.210.25.165/oapi/getAd;jsessionid=EC463AEC3B6300C1A0963FCC112450BF.soma-i-0d82229163740900e"
   ]
}

  • No labels