SOMA API

Home » Publisher Documentation » 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.

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:

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.

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

OTT Parameters

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. 

Request URLs

Endpoint

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.track.smaato.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.track.smaato.net/start?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "firstQuartile",
                  "content" : "http://vet.track.smaato.net/firstQuartile?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "midpoint",
                  "content" : "http://vet.track.smaato.net/midpoint?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "thirdQuartile",
                  "content" : "http://vet.track.smaato.net/thirdQuartile?sessionId=0a49ee2f-4b83-49b9-904e-b42e8ea25ca8&adSourceId=e37030f4-17b5-42f0-aeed-246b6dccd7f7&originalRequestTime=1628848084308&e=china"
                }, {
                  "event" : "complete",
                  "content" : "http://vet.track.smaato.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

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

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"
               }
            }
         ]
      }
   }
}

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

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

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:

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

General Response Headers

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

Last Modified: August 31, 2023 at 11:48 am