Getting Started

Download the Smaato iOS SDK

To download the latest version of our iOS SDK, you can either log in to your SPX account and get it from the integration section, or download it from our website at

For more information on versions and requirements, check out the Version History above.

Also, make sure to read our Terms of Usage.

Add the Smaato SDK to your Xcode project

Download and unzip the Smaato SDK

You'll find a file called iSoma.framework:

Drag & drop the iSoma.framework file into your Xcode application group/project navigator

Like this:

Also, you have to add “-ObjC” as “Other Linker Flags” in Build Settings.

If you'd happen to receive the error “Use of ‘@import’ when modules are disabled”, open iSoma.h (located in iSoma.framework > Headers) and uncomment the @import lines.

Special Instructions for iOS 9

For apps on iOS 9, you'll need to allow HTTP connections by adding an exception to your code.

Open up your application's info.plist file and add the following configuration:

Info for XCode Beta Users

If you're using a beta version of XCode, these values may not show up in the dropdown list. You will need to add them manually into your application's info.plist file, as per the following: 


Special Instructions for iOS 10

The new iOS SDK supports iOS 10 but comes with updated integration steps. Publishers need to update their applications info.plist file with the following settings:

Update 'Privacy Settings' in the Info.plist file

Some creatives might want to access photos, calendar or location only if the end user grants permission. To enable these on iOS 10, please add message for the following Privacy keys into the info.plist file for your application:

  • NSCalendarsUsageDescription
  • NSPhotoLibraryUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSCameraUsageDescription

Update ATS Settings in the Info.plist file

Many ad creatives still use non-http resources e.g. images, videos etc. But in iOS 10, ATS is enforced and it restricts rendering those media. To enable the SDK to render those media and play videos from HTTP location, add the following key in your "App Transport Security Settings":

  • NSAllowsArbitraryLoadsInWebContent : YES
  • NSAllowsArbitraryLoadsInMedia : YES

Adding Third Party Ad Networks

Smaato as primary (Client Side Mediation)

The Smaato iOS SDK includes Client Side Mediation Support for iAd, Google AdMob, Millennial Media, MoPub, and a custom SDK network.

In the .ZIP file you've downloaded, you'll find the following plugins - SOMAIAdPlugin.framework, SOMAAdMobPlugin.framework, SOMAMillennialMediaPlugin.framework and SOMAMoPubPlugin.framework.

To add iAd, Google AdMob, Millennial Media, Mopub: Add the respective plugin, as well as the respective third-party SDK.

To add a custom SDK network: Append your custom network class to the SOMAMediationPlugin class, and define your public method with a parameter to receive the data you defined in your SPX custom SDK network account.

Please note for interstitial ads:

If you want to mediate interstitial ads, please override the presentInterstitial method and implement your preferred interstitial presentation method. 

Note: Millennial Media (Client Side Mediation)

In order to mediate Millennial Media the following keys must be added to the info.plist:




Smaato as secondary 

We also provision for usage thru an AdMob or MoPub account via custom events. Follow the respective instructions below:


  1. Add Custom Event & Handler in the AdMob Dashboard:
    1. Click Edit mediation link on your Ad unit e.g. Top Banner on Home
    2. Click + New ad network button
    3. Click + Custom Event button
    4. Create a custom event with the following parameters:
      1. Class Name: SOMAAdMobBannerReceiver

      2. Label: Choose a name, e.g. “Smaato Optimization”

      3. Parameter: “publisher=yourPublisherID&adspace=yourAdSpaceID“

  2. Configure your XCode Project

    1. Add the SOMAAdMobBannerReceiver.h and SOMAAdMobBannerReceiver.m files to your project. These are included in the SDK .ZIP folder.


  1. Add a Custom Native Network under Networks in your MoPub account (click Add A Network)
    1. Name your Network (e.g. Smaato).
    2. Under “Set Up Your Inventory”, configure your ad units by entering the following values:

      (Use your PublisherId and AdspaceId values instead of "0")

  1. Configure your XCode Project
    1. Add the SOMAMoPubBannerAdapter.h and SOMAMopubBannerAdapter.m files to your project. These are included in the SDK .ZIP folder.
    2. (optional:)To set a global Publisher ID and Adspace ID, open the SOMAMoPubBannerAdapter.m file, uncomment the following lines and replace the default value with your Publisher ID and Adspace ID from your requestAdWithSize method.

//self.somaBanner.adSettings.publisherId = 0;
//self.somaBanner.adSettings.adSpaceId = 0;
Native Ads

MoPub native ads can now be mediated to show Smaato ads by using Mopub custom event settings on their Dashboard along with Smaato Adapters. Here's how:

  1. Create a Custom Native Network on the Mopub dashboard.

  2. Enter SOMAMoPubNativeCustomEvent in the field CUSTOM EVENT CLASS.

  3. Enter {"pub":"0","ad":"3075"} in the CUSTOM EVENT CLASS DATA field. This will show a demo native ad from Smaato. So, please update it according to your publisher id and adspace id.

Now, for configuring your iOS Application:
  1. Add the MoPub SDK and display a native ad unit.
  2. Add the Smaato iOS SDK into the project.
  3. Add the SOMAMoPubAdapter/Native folder to the project. This is available in the Smaato iOS SDK folder once you unzip the downloaded SDK.
  4. Edit the SOMAMoPubNativeCustomEvent.m class if you need any customization. 

Integrating Unity 

To integrate our SDK into your Unity project, open up your project, download and unzip the iOS SDK, and double click the iSomaUnityPlugin.unitypackage file in the Unity Plugin folder.

You'll get the following import dialogue:

Click "Main Camera", then "Add Component". In the search box, search for "iSoma Unity" and select it from the dropdown list. Doing this will add iSomaUnity plugin to the main camera.

Next, build the project for iOS and open it in Xcode.

Follow the common steps (drag & drop the iSoma.framework to the Xcode project, add “-ObjC“ in the “Other Linker Flags” from the “Build Settings” tab of the target), and make sure the following frameworks are linked with in the “Build Phase” tab of the target:

  • UIKit
  • Foundation
  • StoreKit
  • CoreTelephony
  • SystemConfiguration
  • MessageUI
  • AdSupport
  • QuartzCore
  • CoreLocation
  • CoreImage
  • CoreFoundation
  • EventKit

If you run the project on a device or test emulator, you should see an ad!

If you get an error saying “Use of ‘@import’ when modules are disabled”, open iSoma.h and uncomment the @import lines.

Unity 5 Special Instructions

The latest Unity version 5 is preset to use IL2CPP as a default scripting backend instead of Mono. Thus, you'll need to re-set the scripting backend to Mono in every new project created with Unity 5.

To re-adjust this, follow these steps:

Open Build Settings –> Select iOS –> Click Player Settings –> Click Others –> Scripting Backend.

Interstitial ads:

Open the iSomaUnity.cs file in the Unity editor, comment out line 148 (“addNewBanner (ref adSettings);”), and uncomment line 151 (“addNewInterstitial(ref adSettings);”)


Listening to available delegate callbacks is possible in iSomaUnity.cs; the callbacks being:

  1. bannerLoaded
  2. bannerLoadFailed
  3. willEnterFullscreen
  4. didExitFullscreen

Adobe Air Extension

We now also offer an extension for Adobe Air - here's how to set it up:

  • Login to SPX and download iOS SDK.
  • Unzip it and go to the AdobeAirExtension folder.
  • Find the SmaatoSDK.ane file
  • In the Flash Builder, select your project
  • Enter the Properties window by right clicking or by selecting Project in the main menu
  • Select Flex Build Path
  • Enter the Native Extensions tab
  • Click on Add ANE...
  • In the dialogue, select the SmaatoSDK.ane file from the Smaato iOS SDK folder.
  • In the project properties, as mentioned above, select and expand Flex Build Packaging
  • Select Apple iOS
  • Go into the Native Extensions tab
  • Check the Package option.


Next, create the controller:

import SmaatoSDKController;			
private var controller:SmaatoSDKController = SmaatoSDKController.instance;

Load the ad:


Add the delegate class:

package views
	public class SomaDelegate extends SmaatoAdViewDelegate
		public function SomaDelegate()
		override public function adLoaded(isInterstitial:Boolean):void{
			trace("delegate: adLoaded");
		override public function adFailed(isInterstitial:Boolean):void{
			trace("delegate: adFailed");
		override public function adWillEnterFullscreen(isInterstitial:Boolean):void{
			trace("delegate: adWillEnterFullscreen");
		override public function adDidExitFullscreen(isInterstitial:Boolean):void{
			trace("delegate: adDidExitFullscreen");
		override public function adDidWillHide(isInterstitial:Boolean):void{
			trace("delegate: adDidWillHide");

Assign a delegate:

public function init(event:FlexEvent):void {
	controller.delegate = new SomaDelegate();


Just call the following method:


Important Notes

  • At present, only one AdView and one Interstitial ad view can be used.
  • Due to Adobe Air Native Extension limitations, the banner is added to the UIWindow. if you need to hide it, it needs to be hidden manually as per the following:

    // and to show it again:

Integrating Swift

From version 8.x onward, the Smaato iOS SDK comes with a built-in Swift module structure. Just drag and drop the framework to the Swift project and you're set - no bridging headers required.

Setting Up Ad Views

You can either add an ad view in the UI of your XCode project, or manually (i.e. code-based):

in the UI

  • Drag a UIView and position it at a suitable place on your screen - typically at the top or bottom.
  • Set its height and width to 50px and 320px respectively.
  • Open the Identity Inspector (CMD+Option+3) and replace the class name with “SOMAAdView”.
  • Under User Defined Runtime Attributes, set your Publisher and Adspace ID values as intended.


Import iSoma framework header into your view controller file:

#import <iSoma/iSoma.h>

In the viewDidLoad method, add the following lines:

SOMAAdView* adview = [SOMAAdView new];
adview.frame = CGRectMake(0, 70, 320, 50);
[self.view addSubview:adview];
adview.adSettings.publisherId = 0;
adview.adSettings.adSpaceId = 0;
[adview load];


If you like to get notified about various ad events, implement the SOMAAdViewDelegate in your view controller and override the methods.
You can either use the Xcode Interface Builder to connect delegate Outlet or you can set it manually by:


adView.delegate = self;


The following  delegate methods are available:

– (UIViewController*)somaRootViewController{
return self;
– (void)somaAdViewWillLoadAd:(SOMAAdView *)adview{
// Here make sure that the adview or its parent is currently positioned inside the viweable area. If ad is covered, it will not show.

– (void)somaAdViewDidLoadAd:(SOMAAdView *)adview{
// called when the Ad is ready to be shown. Banners are automatically shown but you have to explicitly show the interstitial ads.

– (void)somaAdView:(SOMAAdView *)adview didFailToReceiveAdWithError:(NSError *)error{
// if failed to load ad or if ad is covered or partially obstruted or load is called too frequently or there is already loaded but not yet shown.

– (void)somaAdViewWillEnterFullscreen:(SOMAAdView *)adview{
// it is called before going into expanded state.

– (void)somaAdViewDidExitFullscreen:(SOMAAdView *)adview{
// called when expanded fullscreen ad is closed.

– (void)somaAdViewWillHide:(SOMAAdView *)adview{
// called when the ad is hidden by SDK for some reason.

– (void)somaAdViewApplicationWillGoBackground:(SOMAAdView *)adview;
// is called when some redirect in the app leads over to another app (i.e. minimizes the current app)

 Please take note that the somaAdViewApplicationWillGoBackground delegate may not work in conjunction with SDK Client-Side Mediation; some ad networks don't support such a callback, which will prevent the method from working.


The most reliable way to monitor the life cycle of your app's events (e.g. to detect delegate issues such as the above) is overriding the application delegate method, or observing related notifications provided by iOS itself (e.g. *UIApplicationWillResignActiveNotification*).

Now, if there is an error due to too-frequent load calls or if the adview is covered, following callback will be called with appropriate information:

- (void)somaAdView:(SOMAAdView *)adview didFailToReceiveAdWithError:(NSError *)error;

A new callback is added to the delegate when an ad tries to auto-redirect without any user interaction:

- (void)somaAdViewAutoRedrectionDetected:(SOMAAdView *)adview;


Use the SOMAAdView class in the Interface Builder, or in your code in analogy to the previous use.

SOMAAdView* adview = [SOMAAdView new];
adview.frame = CGRectMake(0, 70, 320, 50);


Use the SOMAInterstitialAdView class in the Interface Builder, or in your code in analogy to the previous use.

Interstitials don't show up automatically, so you'll need to display it manually with the help of this delegate method:

– (void)somaAdViewDidLoadAd:(SOMAAdView *)adview{
[adview show];

Toaster Ads

Toaster ads are banners with a close button.

They should be placed at the bottom of the view.

When loaded, the ad will slide in. The close button hides the toaster. Once it's hidden, the toaster will not auto-reload; you'll have to manually reload it.

Use the SOMAToasterAdView class in the Interface Builder, or in your code to instantiate a SOMAAdView object. Set its size to 320×50 pixels.

Medium Rectangle Ads

Use the SOMAMedRectAdView class in the Interface Builder, or in your code to instantiate a SOMAAdView object. Set its size to 300×250 pixels.


Use SOMASkyscraperAdView class in the Interface Builder, or in your code to instantiate a SOMAAdView object. Set its size to 120×600 pixels.


Use SOMALeaderboardAdView class in the Interface Builder, or in your code to instantiate a SOMAAdView object. Set its size 728×90 pixels.

VAST Video Ads

Integrate an Interstitial Ad using the SOMAInterstitialVideoAdView class. 

VAST Integration
// Step 1: Instantiate and start loading
SOMAInterstitialAdView* adview = [[SOMAInterstitialVideoAdView alloc] init];
adView.delegate = self;
// Step 2:  Present the ad once loaded in the following SOMAAdViewDelegate method:
- (void)somaAdViewDidLoadAd:(SOMAAdView*)adview{;

The demo project that comes along with the SDK .ZIP contains a reference implementation. 

Native Ads

With Native Ads, the publishers need to supply different UI components to the SDK to perform the final rendering of a.

However, it is recommended that all UI components should be added to a dedicated UIView container to handle the clicks by the SDK. Only when the container is registered with the SDK, the ad will be visible, clicks are enabled and beacons are called.

Native Integration
// Step 1: Declare a property in the view controller header:
@property SOMANativeAd* nativeAd;
// Step 2: Instantiate:
self.nativeAd = [[SOMANativeAd alloc] initWithPublisherId:@"0" adSpaceId:@"0"];
self.nativeAd.delegate = self;
// Step 3: Configure UI components
self.nativeAd.labelForTitle = self.title; // an UILable instance to render the title
self.nativeAd.labelForDescription = self.text; // an UILable instance to render the description
self.nativeAd.imageViewForIcon = self.icon; // an UIImageView instance to render the icon
self.nativeAd.imageViewForMainImage =; // an UIImageView instance to render the big image

// Step 4: Load the ad
[self.nativeAd load];
// Stop 5: Once the ad is loaded, make the final configuration and then register the container
- (void)somaNativeAdDidLoad:(SOMANativeAd*)nativeAd{
	self.callToAction.text = nativeAd.callToAction; // UILable instance for the "call-to-action" e.g. Install, Visit etc.
	[self updateRating:nativeAd.rating]; // Optional: native ad comes with a floating point rating e.g. 4.5. Typically shown in stars.

	// Finally, register the container. Make sure all the native ad UI components are children to this container view.
	[nativeAd registerViewForUserInteraction:self.container];

// thats it!

Native Ad Templates

*NEW* Native Ad Templates

From SOMA iOS SDK version 8.0.4 on, you can use Native Ad Templates geared for most popular and common in-app uses:

  • Content Wall
  • Content Stream
  • News Feed
  • App Wall
  • Chat List
  • Carousel

Integrating a layout needs even less coding than before! Here is a step-by-step guide to add a 'News Feed' layout to a native ad:

Step 1:

Instantiate a native ad and set the delegate as always:

self.nativeAd = [[SOMANativeAd alloc] initWithPublisherId:@"0" adSpaceId:@"3075"]; // PUT your information
self.nativeAd.delegate = self;


Step 2:

Set the desired layout and load!

self.nativeAd.layout = SOMANativeAdLayoutNewsFeed; //Example; refer to minimum height values list below for all options
self.[nativeAd load];


Step 3:

Register the native ad container view for user interaction once the ad is loaded. Edit the delegate method as below:

- (void)somaNativeAdDidLoad:(SOMANativeAd*)nativeAd{
 [self.nativeAd registerViewForUserInteraction:self.nativeAdContainerView];

Please Note

Review the layout and adjust its height accordingly to render correctly if necessary; minimum height values typically required are:

  • SOMANativeAdLayoutCarousel: 280
  • SOMANativeAdLayoutAppWall: 50
  • SOMANativeAdLayoutNewsFeed : 50
  • SOMANativeAdLayoutChatList: 50
  • SOMANativeAdLayoutContentWall:300
  • SOMANativeAdLayoutContentStream: 250

Configuring Ad Settings

All Ad Views have an adSettings property which is an instance of SOMAAdSettings.

It offers various configuration options. However, all the configuration options listed below, can be also set globally by updating the [iSoma defaultAdSettings] property.

Default Publisher and AdSpace Id

Once set, all ads will be using this values for publisher id and ad space id.

To set it, write the following code in applicationDidFinishLaunching method of the AppDelegate:

– (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary* )launchOptions{
[iSoma setDefaultPublisherId:YOUR_PUB_ID adSpaceId:YOUR_ADSPACE_ID];

Custom Location

If location services aren't available or if you want use offline location values, set them like this:


adSettings.longitude = -10.0000000;// some longitude value
adSettings.latitude = 53.5500000;// some latitude value



The Children’s Online Privacy Protection Act of 1998 (COPPA) can be enabled or disabled like this:


adSettings.coppaEnabled = YES;// default is NO


Strict Ad Dimension

Sometimes if ad is not available in desired format e.g. text, ads of other format e.g. Image is served.
To disable this and to enable ads only of desired format set formatStrict property.


adSettings.dimensionStrict = YES;// default is YES


Keywords and Search queries

Settings keywords and search queries may result in contextual ads. These can be setup as following:


adSettings.keywords = @”Your,key,words”;
adSettings.searchQuery = @”some,search,query”;


Configure User Profile

You can set user profile to individual ad or globally by updating adView.adSettings.userProfile
or [iSoma userProfile] respectively.
Its properties and possible values are listed below:

Property namePossible valuesDescription
ageInteger valueAge of the user

Gender of the user






Yearly income range of the user






Ethnicity of the user



Education level of the user


User interest


Marital status of the user
countryStringCountry of the user
countryCodeStringCountry Code of the user
regionStringregion of the user
cityStringcity of the user
zipStringzip of the user

Auto Reload Interval

Auto reload interval can be set by updating adSettings as:

adSettings.autoReloadEnabled = YES;
adSettings.autoReloadInterval = 30;//Minimum is 10 seconds.

Auto reload interval can be also configured using Iterrace Builder by defining runtime attribute as following:

Disable auto showing ads

When an adview is configured with Interface Builder, ads are automatically shown. If you wan’t to disable automatidally showing the ads by SDK e.g you want to show the ad manally you should define the following following runtime attribute of type Boolean and uncheck it:

Then show the ad in code as:

[adView show];

Pausing and Resuming Ad Views

An ad view can be paused and resumed as following:


[adView pause];// pauses the adview
[adView resume];// resumes the adview



Please Note

If the view is not visible or the view controller is not the currently active e.g. when used in UINavigationController or UITabbarController, the ads are automatically paused.

You have to resume it manually when the view controller is visible again.

A good place would be inside UINavigationControllerDelegate or UITabbarControllerDelegate methods.


Using the Demo App

A demo app is included in the .ZIP archive; it shows an example of how to integrate, use and configure our SDK.

The demo app allows you to:

  • Use your Publisher and AdSpace IDs
  • Request multiple Ad Units (Text, Image, Rich Media, Medium Rectangle)
  • Configure refresh time
  • Use a standard BannerView
  • Use an Interstitial
  • Use a toaster
  • and instantiate banners directly using the Xcode interface builder

Crash Reporting

Anonymous crash reporting helps us improve our services, and we don't collect any user- or app-specific information.

Crash reporting can be enabled or disabled by setting YES or NO respectively to the following global variable: *SOMA_CRASHREPORTING_ENABLED*.


Terms of Usage

Smaato is committed to protect privacy and data protection and therefore you are required to comply with the relevant applicable privacy policy regulations.

Further, you are obliged to inform the end user about the data and information you collect, use and share, as well as the purpose of such collection.

Moreover, you must also inform the end user that third-party SDKs - including Smaato’s - may collect, store, share and/or transfer various anonymous end user IDs, including - among others - Android ID, IMEI and Facebook Attribute ID for the purpose of targeted advertising.

By installing this SDK, you agree to:

  • comply with all applicable laws and regulations 
  • maintain and abide by a privacy policy that makes appropriate disclosures to users
    • including disclosures about technologies like the aforementioned and 
    • that third parties may receive or gather information about such users.

You further agree that you have obtained any necessary consent from users regarding such disclosures or such information gathering.