Unified Bidding | iOS Integration

Home » Publisher Documentation » Unified Bidding | iOS Integration

Unified Bidding Integration Guide for Publishers with Smaato or GAM as a Primary Ad Server

(iOS NextGen SDK version 22.3.0)

• Introduction
• SPX Setup
  • Important Note About Fullscreen Adspaces
• Unified Bidding Configuration
• Introduction to Price Granularity
• Timeouts
• Bid Adjustment
• GAM Setup Process
• GAM Dashboard Setup
• Integrating an iOS App
  • Prerequisites
  • Choose Ad Formats
• Smaato iOS SDK Setup and Initialization
  • SDK Integration
• SDK Initialization Using AppDelegate Class
• Location Update
• Smaato SDK Integration
• Example Ad Requests
  • Banner  Request (320×50)
    • GAM Specific
    • Generic
  • Interstitial request
    • GAM Specific
    • Generic
  • Rewarded Video request 
    • GAM Specific
    • Generic
  • Native Ad request
    • GAM Specific
    • Generic
  • Outstream Ad request
    • GAM Specific
    • Generic
• Key-value targeting
  • Example code for Banners
  • Important Details About GDPR
• Important Details About CCPA
  • For Publishers with California- Based Users
  • Sample of US Privacy String Saving in NSUserDefaults

Introduction

Smaato has developed a brand new SDK, which has been built to support topics such as in-app header bidding and other advanced topics and formats.

For more details about Smaato’s NextGen SDK, please contact your Smaato Account Manager.

SPX Setup

1. In order to use Smaato’s Unified Bidding module, please ask your Smaato Account Manager to enable this feature in your SPX account.
2. Once Smaato’s Unified Bidding module is enabled for your account, you will see a new ‘’Header Bidding Configuration‘’ within the SPX dropdown menu.
3. In SPX, create a new Adspace and a new Smaato Exchange Line Item to be used by Smaato’s NextGenSDK.
4. As a best practice, you will need to use a distinct Adspace in SPX via Unified Bidding to avoid collisions. Otherwise, the NextGen SDK will not be able to guarantee that the served creative is the one that was originally requested/cached by the Unified Bidding request.

Please Note: Smaato’s Unified Bidding revenues will be associated to this Adspace.

Important Note About Fullscreen Adspaces

Currently, only the Interstitial Multi-Ad Format is compatible for Fullscreen Adspaces with Smaato NextGen SDK. In order to monetize your fullscreen Adspaces in SPX with Smaato NextGen SDK, you need to select the option for Interstitial (Display & Video). All other Fullscreen options will not work at this time.

Please check if the Interstitial (Display & Video) feature is enabled in your SPX account. If you do not see the option for Interstitial (Display & Video) in the Ad Format dropdown, please contact your Smaato Account Manager to enable this.

• When creating your Fullscreen Adspaces in SPX, choose the Interstitial (Display & video) option as the Ad format. (Image 1)
• For the Creative Type you will have three options to choose from (Image 2):
  • Display Only for Rich Media Ads.
  • Video Only for Video Ads.
  • Display and Video will support either Rich Media or Video Ads.

Image 1: Ad Format dropdown selection

Image 2: Creative Type dropdown selections

Unified Bidding Configuration

The Unified Bidding Configuration allows publishers to define some parameters needed by Smaato’s NextGen SDK.

Introduction to Price Granularity

• The Smaato Unified Bidding module will collect bids from demand partners and then pass the highest price to your primary ad server in the ad call. Therefore, you will need to create in your primary ad server one line item for each price point. You will also need to use key value targeting in the primary ad server to enable the Line Item that matches the bid price coming from Smaato’s NextGen SDK.
• To avoid having to create a Line Item for every one-cent increment ($0.01, $0.02, $0.03,…, $20.00), we recommend creating a Line Item for each 10 cent increment. Meaning that bids of $1.04 would be rounded into a single price point of $1.00. We also recommend starting with a $0.10 cent price granularity. When you are ready to go more granular with the price point to improve yield, you can configure this directly in SPX.
• Please make sure to reflect the modification of the price granularity in your ad server setup. You need to have one line item that matches every price point. The modification of the price granularity will be taken into account by Smaato Unified Bidding SDK after 24 hours.

Timeouts

• For each impression opportunity, Smaato Unified Bidding has an amount of time to receive a bid price. If the bid comes later than the roundtrip timeout, the bid will be omitted.
• The default value for the roundtrip timeout is 1,000 ms but you can modify this in SPX and the change will be loaded by the SDK after 24 hours.

Please Note: restrictive timeouts will have a negative impact on your monetization. In this case, we recommend starting with a timeout rate between 1,000 and 1,200 ms.

Bid Adjustment

• The Bid Adjustment parameter allows you to adjust the bid price before the bid is added as a Key-Value in the ad server ad call.
• This parameter is useful when you want to convert a gross price to a net price.
• By default, Smaato has set the bid adjustment value at 100%, but if you prefer to reduce or increase the bid price you may do so.

Here are some examples of bid adjustments:

GAM Setup Process

For each price point (of each line item you set up in SPX), you will need to create one line item in GAM.

You will also want to add a new Dynamic Key (with no value defined) called “smaub”, on Inventory >> Key-Values. For more information, see here

GAM Dashboard Setup

1. Go to the GAM Dashboard

2. Click on “Create Mediation Group” button

3. Select Ad format as per your needs. Possible options are Banner, Interstitial, Native, and Rewarded.

4. Set the desired parameters in the next tab.

5. On “Add Ad Unit” option under “Ad Unit“, select the ad unit that needs to be targeted with mediation.

6. Under “Ad sources“, click on “ADD CUSTOM EVENT”

• Provide Label and your desired eCPM
• Under “Configure ad units“, provide the class name details:
  • For Banner Ads: SMAAdMobSmaatoBannerAdapter
  • For Interstitial Ads: SMAAdMobSmaatoInterstitialAdapter
  • For Rewarded Video Ads: SMAAdMobSmaatoRewardedVideoAdapter
  • For Native Ads: SMAAdMobSmaatoNativeAdapter

• Pass parameter for the SPX Adspace ID:
  • adSpaceId=<YOUR_SPX_ADSPACE_ID>

6. Next, set the eCPM of the price that you want to target, for example, $0.10.

7. Don’t add day/time or day/part targeting.

8. Don’t add frequency capping.

In the Custom Targeting >> Key-Values targeting section you need to select “smaub” as your targeted key, and enter a value, for each line item that you have created. Please make sure that the value is “smaato_cpm:” and the price rate of the Line Item and repeat this process for each Line Item.

For example:

• For $0.10 enter the value smaato_cpm:0.10
• For $1.30 enter the value smaato_cpm:1.30
• For $20.00 enter the value smaato_cpm:20.00

Integrating an iOS App

Prerequisites

In order to integrate the NextGen SDK into your iOS project you will first need to install the following items:

• Xcode 10.2.1 (or later)
• Cocoapods (https://cocoapods.org)

Choose Ad Formats

In order to make the SDK’s binary size smaller it is split into several frameworks:

SmaatoSDKCore.framework
SmaatoSDKBanner.framework
SmaatoSDKInterstitial.framework
SmaatoSDKNative.framework
SmaatoSDKRichMedia.framework
SmaatoSDKVideo.framework
SmaatoSDKOpenMeasurement.framework
SmaatoSDKUnifiedBidding.framework

First, you need to make sure to link the application with the proper set of frameworks to allow the SDK to display the desired Ad Formats.

The table below shows possible configurations, i.e. if you want to display standard banner, link the application against the Core, Banner, Rich Media and OpenMeasurement frameworks. In this case Rich Media means HTML content rendering support.

1 – Mandatory dependency framework in any configuration of Smaato SDK. 
2 – Optional dependency framework for revenue maximization. Please contact your Smaato Account Manager for more details about our Unified Bidding technology. 
 

Smaato iOS SDK Setup and Initialization

Installation Requirements

1. Integration of AdMob iOS SDK into your project. If not integrated please see AdMob documentation.

2. Integration of cocoapods into your project. If not integrated see cocoapods documentation.
 

SDK Integration

With the modular structure of Smaato’s NextGen SDK, you can select different integration options. The following are configuration examples for your project Podfile:

Banner (with Rich Media support)

pod 'smaato-ios-sdk/Banner'
pod 'smaato-ios-sdk/Modules/UnifiedBidding'
pod 'smaato-ios-sdk-mediation-admob/Banner'

Interstitial (with Rich Media & Video support)

pod 'smaato-ios-sdk/Interstitial'
pod 'smaato-ios-sdk/Modules/UnifiedBidding'
pod 'smaato-ios-sdk-mediation-admob/Interstitial'

Interstitial (RichMedia & Image only, without Video)

pod 'smaato-ios-sdk/Modules/Interstitial'
pod 'smaato-ios-sdk/Modules/RichMedia'
pod 'smaato-ios-sdk/Modules/UnifiedBidding'
pod 'smaato-ios-sdk-mediation-admob/Interstitial'

Now you can run pod install

SDK Initialization Using AppDelegate Class

In the AppDelegate class, import SmaatoSDKCore module and configure SDK in “application:didFinishLaunchingWithOptions:“. Smaato’s Unified Bidding module will automatically be enabled for the publisher that is set on SDK initialization if the module has previously been integrated.

Objective-C

Swift

Please visit: https://developers.google.com/ad-manager/mobile-ads-sdk/ios/quick-start for GAM setup.

Location Update

Optional: Use the instance of CLLocationManager class to configure, start, and stop the Core Location services. If you provide device location data once or periodically, the geo-targeted ads are delivered. Such ads have higher conversions and click rate.
 
Class which conforms to CLLocationManagerDelegate protocol

Objective-C

Class which conforms to CLLocationManagerDelegate protocol

Swift

Smaato SDK Integration

Smaato SDK supports several standard banner dimensions, which should be used for Prebid request. They are declared in SMAUbBannerSize enum. Use appropriate value as parameter in prebidBannerForAdSpaceId() method call.

Banner sizes (public header of Smaato Unified Bidding framework)

Objective-C

Prebid request (public header of Smaato Unified Bidding framework)

Objective-C

Prebid response for publisher needs (public header of Smaato Unified Bidding framework)

Objective-C

Example Ad Requests

Unified Bidding module initialization without any changes:

In the AppDelegate class, import the SmaatoSDKCore module and configure SDK in “application:didFinishLaunchingWithOptions:“. The Smaato Unified Bidding module will automatically be enabled for the publisher ID used for SDK initialization if the module has previously been integrated.

Banner  Request (320×50)

To add Smaato Unified Bidding to your AdMob Banner, follow these steps:

1. First, find the line of code where you create an GAMBannerView banner instance to add Smaato Unified Bidding.
2. Next, add the [SmaatoSDK prebidBannerForAdSpaceId:] method call to your code in the same way shown in the examples below. The bannerSize parameter should match supported Smaato banner dimensions: standard size banner (320×50), medium rectangle size banner (300×250), leaderboard size banner (728×90), skyscraper banner size (120×600).
3. Then, move the loadAd method call to the completion callback of the prebidBannerForAdSpaceId method and use Prebid data from SMAUbBid bid* instance to build correct targeting string for the Smaato Line Item (which you have created earlier via the GAM Dashboard) and save unique Prebid banner creative identifier to be able to fetch exact banner creative from cache in case of auction win. Finally, pass the UB bidKeyword string in Key-value form inside GAMRequest and call loadAd. 

GAM Specific

Swift

Objective-C

Generic

Swift

Objective-C

Interstitial request

To add Smaato Unified Bidding to your Interstitial, follow these steps:

1. First, find the line of code where you call the GAMInterstitialAd instance to add Smaato Unified Bidding.
2. Next, add the [SmaatoSDK prebidInterstitialForAdSpaceId:] method call to your code in the same way shown in the examples below.
3. Then, move the loadAd method call to the completion callback of the prebidInterstitialForAdSpaceId method and use Prebid data from the SMAUbBid *bid instance to build the correct targeting string for the Smaato Line Item (which you have created earlier via the GAM Dashboard)  and save unique Prebid interstitial creative identifier to be able to fetch exact interstitial creative from cache in case of auction win. Finally, pass the UB bidKeyword string in Key-value form inside GAMRequest and call loadAd.

GAM Specific

Swift

Objective-C

Generic

Swift

Objective-C

Rewarded Video request 

To add Smaato Unified Bidding to your Rewarded Video Ad, you need to follow these steps: 

1. First, find the line of code where you load the GAM `RewardedAd` to add Smaato Unified Bidding.
2. Next, add the [SmaatoSDK prebidRewardedInterstitialForAdSpaceId:] method call to your code the same way it’s added in the examples below. 
3. Then, move load method call to the completion callback of prebidRewardedInterstitialForAdSpaceId method and use Prebid data from SMAUbBid *bid instance to build correct targeting string for Smaato LineItem (which you have created early via GAM Dashboard).
4. Finally, pass the UB bidKeyword string in Key-value form inside GAMRequest and call loadAd.

GAM Specific

Swift

Objective-C

Generic

Swift

Objective-C

Native Ad request

To add Smaato Unified Bidding to your Native Ad, follow these steps:

1. Add the `UnifiedBidding.prebidNative` method call to your code in the same way shown in the examples below.
2. Then, move the load method call to the PrebidListener callback method and use Prebid data from SMAUbBid *bid instance to build correct targeting string for Smaato Line Item (which you have created early via GAM Dashboard). 
3. Finally, pass the UB bidKeyword string in Key-value form inside GAMRequest and call loadAd.

GAM Specific

Swift

Objective-C

Generic

Swift

Objective-C

Outstream Ad request

To add Smaato Unified Bidding for Outstream Ads, follow these steps:

1. First, find the line of code where you create a GAMBannerView instance to add Smaato Unified Bidding prebid call.
2. Next, add the UnifiedBidding.prebidOutstream(...) method call to your code in the as shown in the examples below. The bannerSize parameter should match supported Smaato banner dimensions: standard size banner (320×50), medium rectangle size banner (300×250), leaderboard size banner (728×90), skyscraper banner size (120×600).
3. Then, move the loadAd method call to the PrebidListener callback method and use Prebid data from SMAUbBid *bid instance to build correct targeting string for Smaato Line Item (which you have created earlier via the GAM Dashboard). Finally, pass the UB bidKeyword string in Key-value form inside GAMRequest and call loadAd. 

GAM Specific

Swift

Objective-C

Generic

Swift

Objective-C

Key-value targeting

Introducing age, gender and key-value targeting with the following setup:

Age and gender values are collected from Smaato SDK (UserInfo) interface that is already provided by the SDK.

Regarding Key-Value pairs, once the value is set for banners or interstitials, that value is collected for Unified Bidding to the corresponding request as well. Meaning, if the keyValuePairs were set in the SDK for Banners, that value is added to the banner prebid request. So, it does not have to be set again for Unified Bidding. The same approach would be applied to the other types.

• set user age and/or gender to Smaato SDK
• initialise a SMAKeyValuePairs object and set your targeting parameters by using the public interface
• set the key-value pairs object to the proper property, to match the prebid request ad type.
• call prebid method

Example code for Banners

Objective-C

Swift

The same approach works for Interstitial videos, but setting KVP dictionary to keyValuePairs property from SMAInterstitial.

Objective-C

// Setting KV pairs for Interstitial request 
SMAInterstitial.keyValuePairs = KVP;

Important Details About GDPR

As a publisher, you should integrate a Consent Management Platform (CMP) and request for vendor and purpose consents as outlined in IAB Europe’s Mobile In-App CMP API v1.0: Transparency & Consent Framework. You can find a reference implementation of a web-based CMP and the corresponding native wrappers here in the IAB’s GDPR-Transparency-and-Consent-Framework.

If you are embedding your own custom CMP, the collected end-user consent information needs to be stored in NSUserDefaults using the following keys:

Objective-C

// User is not subject to GDPR 
[[NSUserDefaults standardUserDefaults] setObject:@"0" forKey:@"IABConsent_SubjectToGDPR"];

Important Details About CCPA

The California Consumer Privacy Act (CCPA) was created to provide California consumers with greater transparency and control over their personal information. In many ways, the CCPA is a first of its kind regulation in the United States that seeks to create broad privacy and data protection rules that apply to all industries doing business in the jurisdiction of California, rather than focusing on a single sector or specific data collection and use practices.

For more information about the CCPA regulation, please check out the Smaato FAQ.

For Publishers with California- Based Users

As a publisher, you need to make sure to request consent from California-based users (to give or refuse consent / to opt-out or opt-in ) about private data transfer. This answer should be saved in NSUserDefaults with key “IABUSPrivacy_String” in the US Privacy String format (CCPA Opt-Out Storage Format).

Sample of US Privacy String Saving in NSUserDefaults

Objective-C

Swift

NextGen SDK reads that value by key “IABUSPrivacy_String” if it exists and uses it as an optional parameter for all ad requests. NextGen SDK allows to read this CCPA US Privacy String from NSUserDefaults to be sure NextGen SDK uses the same value, that you saved in NSUserDefaults and avoid any misalignment and misunderstanding. CCPA US Privacy String is available via SmaatoSDK.usPrivacyString public class property.

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