SOMA API

Introduction

The Smaato Open Mobile Advertising (SOMA) infrastructure is the mainframe infrastructure to the Smaato exchange. The SOMA Application Programming Interface (API) is designed enable the needs of mobile and in-app publishers and developers to connect to the Smaato exchange (SOMA). The SOMA API can be requested by calling a specific URL with a query string of certain parameters and then the SOMA server will respond via JSON. Please follow this detailed guide for proper integration using the SOMA API and for further questions reach out to your dedicated Account Manager.

Important New Features

Native, Richmedia, Image, and Video (in China region) are only supported by JSON. VAST is only supported by XML(except in China region).

Click Tracking is now available and is mandatory to implement.

If you’re looking to ‘ad-enable’ a mobile application, please refer to our SDKs for information on all major platforms.

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

Adspace Sizes

The Adspace is the area you have designated for advertisements on your mobile website or application. 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:

SIZE DESCRIPTION
320 x 50 (MMA XXLarge) The most common format and our recommendation
768 x 1024 Fullscreen interstitial portrait mode – Tablet
1024 x 768 Fullscreen interstitial lanscape mode – Tablet
480 x 320 Fullscreen interstitial landscape mode
320 x 480 Fullscreen interstitial portrait mode
300 x 50 (MMA XLarge)  
216 x 36 (MMA Large)  
168 x 28 (MMA Medium)  
120 x 20 (MMA Small)  

Format Notes:

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).

VAST Video Ads

VAST Video can be used for example for Pre-/Post-/Mid-Roll ads. They can ONLY be requested with “format=video”. VAST video ads supports only xml response format (except in China region).

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

Native Ads

Smaato supports Native Ads. These 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”.

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 impression tracker beacons for 3rd party validation. The second request, which downloads the banner image and impression tracker beacons (if applicable) must be made from the mobile device directly (!). Downloading the impression trackers 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.

Figure 1: Ad Request Workflow

HTTP Header Forwarding

When using a Client<->Server<->SOMA architecture (the request to SOMA is not done directly by a mobile device) 

Which headers are needed?

In general, we need to have ALL headers that the publisher’s 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).

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

Accept-Encoding: gzip
User-Agent: Mozilla/5.0 (Linux; Android 4.0.4; Galaxy Nexus Build/IMM76B) AppleWebKit/535.19 (KHTML, like Gecko)
Chrome/18.0.1025.133 Mobile Safari/535.19
X-Forwarded-For: 203.177.91.193, 62.159.30.165, 67.69.254.254

Impression and Click Tracking

Impression Trackers

Impression trackers, a.k.a. tracking pixels, impression beacons, view beacons, help to count the view of the advertiser’s ad via a third party and to double check ad server delivery.

An impression tracker is a transparent 1×1 GIF, which has to be requested by the mobile device directly after the ad is displayed.

Click tracking

For API integrations, Smaato relies on publishers to call what we call a ‘click tracking’ beacon. In every ad response (Image, Rich Media, Native and Video), Smaato can include zero (if the click tracking is made in a different way by using the creative itself for example) to multiple beacons under the clicktrackers object.

The click tracking beacons are included as an array of URLs inside of the “clicktrackers” object (see sample below). All Click Tracking beacons in the response must be called as soon as the end user clicks on the ad.

An ad response can also contain multiple click URLs which need to be called in case of a click event  (see the “clicktrackers”: section in the response sample above). If you request ads using the API then you need to ensure that those click URLs are called from your client integration and not server side.

Response Example for IMG (Impression Tracker Excerpt)

{
   "image":{
      "img":{
         "url":"http://some.creative.url",
         "w":"320",
         "h":"50",
         "ctaurl":"http://landing.page.url/buyMe"
       },     
       "impressiontrackers": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
      ]
   }
}

Responses may return multiple impression trackers; please note that all of them need to be handled in the same way.

This especially refers to the following case:

  • If an interstitial is being loaded in the background, the impressiontracker(s) should be called as soon as the creative is displayed, not when it’s been fully returned.

Please also respect the following in regards to the set-up of Click trackers and Impression trackers:

  • Modifying or redirecting the impressiontrackers or clicktracker URLs, placing the impression trackers or click trackers in a frame or layer or loading via JavaScript are not allowed.

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).
  • 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:

https://api.ad.smaato.net/oapi/v6/ad?pub=0&adspace=0&format=display&extensions=omid

General Parameters

Parameter Mandatory Description Type Example
adspace Yes AdSpaceID (assigned by Smaato). ID “0” can be used for unattended testing purpose. integer 123456789
pub Yes PublisherID (assigned by Smaato). ID “0” can be used for unattended testing purpose. integer 4711
format Yes The format of the ad to be returned (All formats will be returned in JSON except Video which will be in XML):display: Image or rich media (strongly recommended!)img: Any image formatrichmedia: Rich mediavideo: Video Adsnative: Native Adssplash: ad type defined based on adspace configuration (SPX) string img
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
ref Yes for web traffic (‘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. string http%3A%2F%2Fwww.example.com
device Yes (‘no’ if the device user agent is sent as a header) The user agent of the device string 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 No 3 – MRAID 15 – MRAID 26 – MRAID 3 integer 2
vastver  Yes (if format=video)  2,3,4 or 4.1 integer  4
videotype No (if adspace videotype configured in SPX), otherwise Yes (if format=video)  Choose between:instream-preinstream-midinstream-postoutstreaminterstitialrewarded string instream-pre
dimension No 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
ifa Strongly recommended Identifier for advertising string 1D76F5D1-1983-47C8-B18D-119D52E4597A
dnt No Do not track status: (true = user has decided against tracking). If not set the we assume user is okay with tracking. Not that potential other signals like coppa, ccpa, and gdpr would of course limit tracking even when this one is not set. boolean  
androidid No The Android device’s Android ID (Settings.Secure.ANDROID_ID) string 9774d56d682e549c
coppa Yes “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.
integer 0 or 1 0
gdpr No 1 = subject to GDPR
0 = not subject to GDPR
value omited = unknown / unset (default)
integer0 or 1 0
gdpr_consent No Consent string according to iAB’s consent string format 1.1 string BOMT6szOMT6szAAABAENAAAAAAAAoAAA
us_privacy No   string
see possible values here
1YNN
skadn Yes (for SKAdNetwork support on iOS 14+) List of SKAdNetwork IDs string: comma separated values abc123.skadnetwork, 123abc.skadnetwork, a1b2c3.skadnetwork
skadnv Yes (for SKAdNetwork support on iOS 14+) Version of SKAdNetwork (2.0) string 2.0
att Yes (for iOS 14 support on iOS 14+) Apple AppTrackingTransparency (ATT) framework value (user’s IDFA permission)
0: undetermined
1: restricted
2: denied
3: authorized
integer

0 or 1 or 2 or 3
3
idfv Yes (for iOS 14 support on iOS 14+) Apple Identifier for Vendors (IDFV). See here string FKDALGIF-FAKSL-3IAK-39AL
height No Height of the ad space. Recommended for in-application advertising. integer 36
width No Width of the ad space. Recommended for applications. integer 36
privacyIcon No Whether to add privacy field for Native requests string0 or 1 or false or true 1
deeplinking No Whether the publisher supports deeplink-supported ad creatives (handling of our deep link schema):
Automatically handled by our NextGen SDK in iOS version 21.6.15+ and Android version 21.6.0+Handled by the publisher (API): Smaato Deep Linking Schema
true or false true
appver No (currently only required by vlion adnetwork connector in china) The app version string 1.1.1
allowNativeRichmedia No Whether the publisher supports Native Rich Media as an ad format (supports Native ads with HTML as an additional creative type, besides just static image, WebView needed instead of ImageView):Automatically handled by our NextGen SDK in iOS version 21.6.15+ and Android version 21.6.0+Handled by the publisher (API): use Response.ext.adm instead of Response.img true or false true
lgpd No Indicates if a request is a subject to LGPD (Brazil personal information regulation): 1 (is a subject to LGPD) or 0 (not a subject) integer
1 or 0
1
lgpd_consent No LGPD consent: 1 (consent given) or 0 (not given) integer
1 or 0
1
extensions No For enabling Open Measurement, pass “omid”. string omid

OTT Parameters

Parameter Mandatory Description Type Example
channelId Yes Id of the source of the video content (assets or broadcast) integer 12
adBreakId Yes Id of the ad break the request is for integer 400000021
playbackSession Yes Session for the user’s current viewing session (required for VMAP) string 40d9e394-740a-4225-83f1-766a04154b83
availDurationSec Yes(For Live channel) The duration in seconds of the ad availability slot integer 100
inventoryType Yes Indicate that SSAI request is from an app or a website, possible values: app or web string app
platform No Platform the user is watching video content on string Netflix
assetId No Unique identifier of the specific VOD content the user is watching (channelId is provided if Live) string 50d9e394-740a-4225-83f1-766a04154b83
assetTitle No Title of the specific VOD video content the user is watching string Endgame
assetGenre No Genre of the specific VOD video content the user is watching string action
assetEpisode No Episode number of the specific VOD video content the user is watching (can be for both movies and TV shows in terms of assetType), if applicable integer 1
assetSeries No Series of the specific VOD video content the user is watching (can be for both movies and TV shows in terms of assetType), if applicable string Star Wars
assetSeason No Season number of the specific VOD video content the user is watching (for TV shows in terms of assetType), if applicable string Season 3
assetType No Type of the specific VOD video content the user is watching (can be movie, tv-show, or short) string movie
assetLength No Length in seconds of the specific VOD video content the user is watching integer 100
assetSourceType No Indicates whether the specific video content the user is watching was originally produced (DIRECT) or if it’s licensed content (INDIRECT) integer 1
assetCategories No IAB categories of the specific VOD video content the user is watching (comma separated) string IAB1-1
assetKeywords No String of keywords that describe the specific VOD video content the user is watching (comma separated) string horror
assetStudio No The producer that created the specific VOD video content that the user is watching (channel name is used if Live) string Warner Bros
assetUrl No .mp4 URL of the specific VOD video content that the user is watching string http://akamaihd.net/video.300k.mp4
productionQuality No The production quality of the specific video content (VOD or Live) that the user is watching (UNKNOWN, PROFESSIONAL_PRODUCED for professionally-produced where a studio or company produced it, PROSUMER for prosumer where an amateur with professional equipment produced it, or USER_GENERATED for user-generated content where an amateur filmed it with their phone) integer 1

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 Name Mandatory Description Range Of Values Example
Key Value Pairs
cs_keyname No Using the prefix cs_ will allow us to identify key value pairs. Please make sure that what you define as an API parameter matches with your key value setup in the Smaato Platform. string: comma separated values. football,tennis,basketball
Content
kws No Tags (free text, case insensitive) describing the content. string: comma separated values motorsport, news, cars
User
age No The user’s age. 2-digit number. If only a range is available, use the mean average. integer 30
gender No The user’s gender. m, f, o, M, F, O m
qs No Query 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
gps No GPS coordinates of the user’s location. string: Latitude and longitude in decimal degrees format, comma separated 37.530676,-122.262447
region No The region or state, the user is located in. (Abbreviated with two letter state code) string CA (for California)
zip No The postal code of the user’s location. string 94402
geotype yes if gps is provided Source of location data; integer1 GPS/Location Services2 IP Address3 User provided (e.g., registration data) 1
ipservice yes if geotype=2 If geotype=2, please provide the enrichment service you use: integer1 ip2location2 Neustar (Quova)3 MaxMind4 NetAcuity (Digital Element) 3
Device
devicemodel No The device model. For iOS devices: The exact model. string iPhone3,1
connection No Network connection type string wifi

Request URLs

Endpoint

The Endpoint – /oapi/v6/ad – is used for making requests to the SOMA Server.

Example URL: api.ad.smaato.net

For maximum monetization results we strongly advise you to use this URL.

This Endpoint is also used to make requests in a secure SSL enabled environment.

Example Ad Request

https://api.ad.smaato.net/oapi/v6/ad?pub=0&adspace=0&format=display&extensions=omid

Example Ad Responses

SOMA Video/VAST Response

VAST Ads are supported by XML format only (except in China region)For documentation on VAST XML response values, please refer to the IAB’s VAST 2.0 Documentation.

Sample VAST Response

<VAST version="2.0">
    <Ad id="223626102">
        <InLine>
            <AdSystem version="2.0">Smaato</AdSystem>
            <AdTitle>Smaato Mobile Video</AdTitle>
            <Description>Press Play on Mobile Video Advertising</Description>
            <Survey/>
            <Impression>
                <![CDATA[
                  http://ets-us-east-1.track.smaato.net/v1/view?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e70ecf45fa8e30&originalRequestTime=1535447705863&expires=1535448605863&winurl=rsBTUn82AM1g4bGwBcBAh3gMv7gaABsAhJy0CJtG3hekp8qLiV0xbaZENjWBMaRY-5POt4aCYvvxrdWrwJ8qo2jKEOX0dtFMc3T4wvfXbo91VddS0urPsGxCiPT3OJQW4CTPzOL9pmcbnjGCyfubKtyZKtRc_sPzNnqoXoBL-y_n3F97HyF-uHeTjmgUbhOogMM57dwXX15P2HcEPHB7IGP_1VDzV4PVMJog5RqM3WMXS1g4myP8QGt6DqSc1S1WhHlqo5wsp1A8dWCd87HtNA%3D%3D%7Cc_8jfAnqtYhkb67D-h8R7Q%3D%3D
                ]]>
              </Impression>
            <Creatives>
                <Creative AdID="" sequence="1">
                    <Linear>
                        <Duration>00:00:12</Duration>
                        <TrackingEvents>
                            <Tracking event="start">
                                <![CDATA[ https://soma.smaato.net/videoStart ]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[ https://soma.smaato.net/midPoint ]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[ https://soma.smaato.net/midPoint2 ]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[ https://soma.smaato.net/firstQuartile ]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[ https://soma.smaato.net/firstQuartile2 ]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[ https://soma.smaato.net/thirdQuartile ]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[ https://soma.smaato.net/thirdQuartile ]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[ https://soma.smaato.net/complete ]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[ https://soma.smaato.net/complete2 ]]>
                            </Tracking>
                            <Tracking event="mute">
                                <![CDATA[ https://soma.smaato.net/mute ]]>
                            </Tracking>
                            <Tracking event="pause">
                                <![CDATA[ https://soma.smaato.net/pause ]]>
                            </Tracking>
                            <Tracking event="fullscreen">
                                <![CDATA[ https://soma.smaato.net/fullscreen ]]>
                            </Tracking>
                            <Tracking event="fullscreen">
                                <![CDATA[ https://soma.smaato.net/fullscreen2 ]]>
                            </Tracking>
                            <Tracking event="start">
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/start?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/firstQuartile?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/midpoint?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/thirdQuartile?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/complete?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </Tracking>
                        </TrackingEvents>
                        <AdParameters/>
                        <VideoClicks>
                            <ClickThrough>
                                <![CDATA[ https://www.smaato.com ]]>
                            </ClickThrough>
                            <ClickTracking id="DART">
                                <![CDATA[ https://soma.smaato.net/clickTracking ]]>
                            </ClickTracking>
                            <ClickTracking id="ThirdParty">
                                <![CDATA[ https://soma.smaato.net/clickTracking2 ]]>
                            </ClickTracking>
                            <ClickTracking>
                                <![CDATA[
                                  http://ets-us-east-1.track.smaato.net/v1/click?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </ClickTracking>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile bitrate="457" delivery="progressive" height="720" id="1" type="video/mp4" width="1280">
                                <![CDATA[
                                  https://demofiles.smaato.com/creatives/assets/video/Outstream%20Demo%20Asset%20Mockup.mp4?test=true
                                ]]>
                            </MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
                <Creative AdID="" sequence="1">
                    <CompanionAds>
                        <Companion height="250" width="300">
                            <HTMLResource>
                                <![CDATA[
                                  <a href="https://www.smaato.com/resources/adformats/#section1" target="_blank"><img src="https://smt-demofiles.s3.amazonaws.com/creatives/assets/images/600x500.png" alt="" /></a>
                                ]]>
                            </HTMLResource>
                            <TrackingEvents>
                                <Tracking event="creativeView">https://myTrackingURL/secondCompanion</Tracking>
                            </TrackingEvents>
                            <CompanionClickTracking>
                                <![CDATA[
                                  http://vet-us-east-1.track.smaato.net/companionClickTracking?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863
                                ]]>
                            </CompanionClickTracking>
                        </Companion>
                    </CompanionAds>
                </Creative>
            </Creatives>
            <Error>
                <![CDATA[
                  http://vet-us-east-1.track.smaato.net/error?sessionId=255b66a9-d91f-4dd5-b50f-0ae2e4a781ea&adSourceId=b32698c9-f344-4938-b3e7-0ecf45fa8e30&originalRequestTime=1535447705863&errorCode=$ERRORCODE$
                ]]>
            </Error>
        </InLine>
    </Ad>
</VAST>

SOMA JSON Responses

Below you will find JSON response examples for Image, Rich Media, Native Ads, and Video (in China region)

SOMA Video VAST-JSON Response (in China)

VAST-JSON Response Example: (with deep links)

{
  "VAST" : {
    "Ad" : [ {
      "id" : "229",
      "InLine" : {
        "Error" : [ {
          "content" : "http://vet.smaatolabs.net/error?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china&errorCode=[ERRORCODE]"
        } ],
        "Creatives" : {
          "Creative" : [ {
            "id" : "9873",
            "Linear" : {
              "TrackingEvents" : {
                "Tracking" : [ {
                  "event" : "start",
                  "content" : "http://vet.smaatolabs.net/start?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "firstQuartile",
                  "content" : "http://vet.smaatolabs.net/firstQuartile?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "midpoint",
                  "content" : "http://vet.smaatolabs.net/midpoint?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "thirdQuartile",
                  "content" : "http://vet.smaatolabs.net/thirdQuartile?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "complete",
                  "content" : "http://vet.smaatolabs.net/complete?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                } ]
              },
              "VideoClicks" : {
                "ClickTracking" : [ {
                  "content" : "http://ets.track.smaato.net/v1/click?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "content" : "https://deeplinkTracker1.com"
                }, {
                  "content" : "https://deeplinkTracker2.com"
                } ],
                "ClickThrough" : {
                  "content" : "https://deeplinkURL.com"
                }
              },
              "Duration" : {
                "content" : "00:00:01"
              },
              "MediaFiles" : {
                "MediaFile" : [ {
                  "width" : "370",
                  "type" : "application/x-shockwave-flash",
                  "content" : "http://ad.smaato.com/ads/vpaidad3.swf",
                  "height" : "270"
                } ]
              }
            }
          } ]
        },
        "Impression" : [ {
          "content" : "http://ets.track.smaato.net/v1/view?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china&expires=1628848144308&dpid=SejiqV9iLVAcnZM0hhO1KQ%3D%3D%7C--U8q07dbWiDYyVyLM2RDQ%3D%3D"
        }, {
          "id" : "LR",
          "content" : "http://ImpressionURLInsideTheVast"
        } ],
        "Extensions" : {
          "Extension" : [ {
            "AdServer" : "smaato",
            "Fallback" : {
              "content" : "https://fallbackURL.com"
            },
            "FallbackTracker" : [ {
              "content" : "https://fallbackTracker1.com"
            }, {
              "content" : "https://fallbackTracker2.com"
            } ],
            "type" : "deeplink",
            "creativeId" : "9873"
          } ]
        },
        "AdSystem" : {
          "version" : "4.11.1-3",
          "content" : "LiveRail"
        },
        "AdTitle" : {
          "content" : "LiveRail creative 1"
        }
      }
    } ],
    "version" : "4.1"
  }
}

Image Response type

Attribute Type Description
image Object The root object
image.clicktrackers Array An array of URLs that contains all click trackers. The click tracking URLs must be called as soon as the user clicks on the creative. (If deeplink trackers were provided in the adresponse, then those are added here as well)
image.fallbacktrackers Array Only populated if these fallback trackers were provided to us in the ad response.
image.img Object The creative object
image.img.ctaurl String The creative click url. This url needs to be called when the user clicks on the ad. (If a deeplink url is available then that is placed here instead)
image.img.fallbackurl String The fallback deeplink url. Only filled if adresponse returned us some deeplink data.
image.img.h Integer the height of the creative
image.img.url String The url of the image. Use this image to download and show the image creative in your app.
image.img.w Integer The width of the creative
image.impressiontrackers Array An array of URLs that contains all impression trackers. The impression trackers should be all called when the creative is visible on the screen.

Example Image Response

(With impression trackers & click trackers)

{
   "image":{
      "img":{
         "url":"http://some.creative.url",
         "w": 320,
         "h": 50,
         "ctaurl":"http://landing.page.url/buyMe"
       },     
       "impressiontrackers": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
      ]
   }
}

Rich Media/JavaScript Response Attributes

Attribute Type Description
richmedia Object Root object
richmedia.mediadata Object Creative object
richmedia.mediadata.content String The javascript code that needs to be rendered on the screen.
richmedia.mediadata..w Integer Creative width
richmedia.mediadata.h Integer Creative height
richmedia.mediadata.ctaurl String The creative click url. Filled with the deeplink url if that was provided instead.
richmedia.mediadata.fallbackurl String Deeplink fallback url.
richmedia.impressiontrackers Array An array of URLs that contains all impression trackers. The impression trackers should be all called when the creative is visible on the screen.
richmedia.clicktrackers Array An array of URLs that contains all click trackers. The click tracking URLs must be called as soon as the user clicks on the creative.
richmedia.fallbacktrackers Array An array of deeplink fallback trackers which is only populated if these were provided to us in the ad response.

Example Rich Media Response

(With impression trackers & click trackers) 

{
   "richmedia": {
        "mediadata": {
            "content": "<THE CONTENT>",
            "w": 800,
            "h": 600
        },
        "impressiontrackers": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
        ]
    }
}

Native Ads Response Type

Example Native Ads Response 

(With impression trackers & click trackers) 

{
   "native":{
      "ver": "1.1",
      "link":{
         "url":"http: //i.am.a/URL",
         "clicktrackers":[
            "http://www.mytracker.com/tracker.js",
            "http://www.mytracker.com/tracker.php"
        ]
      },
      "assets":[
         {
            "id": 1
            "title":{
               "text":"Learn about this awesome thing"
            }
         },
         {
            "id": 2
            "img":{
               "type": 1,
               "url":"http://www.myads.com/thumbnail1.png"
            }
         },
         {
            "id": 3,
            "img":{
                "type": 3,
               "url":"http://www.myads.com/largethumb1.png",
               "w":"800",
               "h":"600"
            }
         },
         {
            "id": 4,
            "data":{
               "type": 2,
               "value":"My Brand"
            }
         },
         {
            "id": 5,
            "data":{
               "type": 3,
               "value":"Rating in stars."
            }
         }
      ],
      "eventtrackers":[
         {
            "event":1,
            "method":1,
            "url":"http://www.mytracker.com/tracker.js"
         },
         {
            "event":1,
            "method":1,
            "url":"http://www.mytracker.com/tracker.php"
         }
      ],
      "ext":{
         "smaatoexts":[
            {
               "name":"Moat",
               "script":"<script>MOAT beacon<script/>",
               "conf":{
                  "moatClientLevel1":"20",
                  "moatClientLevel2":"2446",
                  "moatClientLevel3":"53",
                  "moatClientLevel4":"16969427",
                  "moatClientSlicer1":"17",
                  "moatClientSlicer2":"21"
               }
            }
         ]
      }
   }
}
For img and Data objects please refer to tables below to match each type id with the name and the description of the filed.

Data Asset Types

Below is a list of common asset element types of native advertising in OpenRTB Dynamic Native Ads API Specification Version 1.1

Type ID Name Description Format
1 sponsored Sponsored By message where response should contain the brand name of the sponsor. text
2 desc Descriptive text associated with the product or service being advertised. Longer length of text in response may be truncated or ellipsed by the exchange. text
3 rating Rating of the product being offered to the user. For example an app’s rating in an app store from 0-5. number formatted as string
4 likes Number of social ratings or “likes” of the product being offered to the user. number formatted as string
5 downloads Number downloads/installs of this product number formatted as string
6 price Price for product / app / in-app purchase. Value should include currency symbol in localised format. number formatted as string
7 saleprice Sale price that can be used together with price to indicate a discounted price compared to a regular price. Value should include currency symbol in localised format. number formatted as string
8 phone Phone number number formatted as string
9 address Address text
10 desc2 Additional descriptive text associated with the product or service being advertised text
11 displayurl Display URL for the text ad. To be used when sponsoring entity doesn’t own the content. IE sponsored by BRAND on SITE (where SITE is transmitted in this field). text
12 ctatext CTA description – descriptive text describing a ‘call to action’ button for the destination URL. text
500+ XXX Reserved for Exchange specific usage numbered above 500 Unknown

Image Asset Types :

Below is a list of common image asset element types of native advertising described in OpenRTB Dynamic Native Ads API Specification Version 1.1

Type ID Name
1 Icon
2 Logo
3 Main
500+ xxx

No Ad/ Error Response and Response Headers

VAST No Ad Available Response:

<VAST version="VAST_VERSION"/>
VAST_VERSION being something like e.g. 2.0 or 4.1

VAST-JSON No Ad Available Response (in China region):

{
  "VAST" : {
    "version" : "VAST_VERSION"
  }
}VAST_VERSION being something like e.g. 2.0 or 4.1

HTTP No Ad/Error Response

In case of no ad available or error the SOMA API will respond with following HTTP codes:

HTTP Code Description Comment
204 Currently no ad available No ad is currently available matching the requesting parameter.
400 General Exception Something went wrong on our side.
403 Forbidden This is returned e.g. when the request was blocked due to IVT

To know more about the kind of error, the SOMA API will add a description of the error in the response header X-SMT-MESSAGE

Message Description
Unknown or blocked publisher Returned when the publisher id is wrong or blocked internally.
Publisher Adspace mismatch When the publisher and adspace id don’t belong to each other. Please check your ids in SPX and try again.
Unknown or blocked or deleted adspace Adspace id blocked or removed
Invalid parameters for format VIDEO Missing parameters for the video ad request.
Invalid parameters for format Native Missing parameters for the native ad request.
General Exception All other errors

General Response Headers

SOMA also returns the Ad Type in the response headers when an Ad is being returned. 

Header Description Possible Values
X-SMT-ADTYPE Contains the ad response type to determine if the format is an image, rich media, native or video. Img, Richmedia, Native, Video
X-SMT-PRICE-TYPE Contains the ad response price type to determine if the value in “X-SMT-PRICE” header is net or gross value. PRICE-BEFORE-REV-SHARE, PRICE-AFTER-REV-SHARE
X-SMT-PRICE Contains the ad response CPM price. 1.34
Doc Feedback Product Feedback

Last Modified: June 20, 2022 at 3:09 pm