Unified Bidding | Android Integration (Draft)

(iOS NextGen SDK version 21.7.8)

Introduction

Smaato’s in-app header bidding solution, Unified Bidding, is a holistic bidding model that uses real-time pricing competition to provide publishers with maximum competition and control over their inventory.

Take advantage of the our in-app header bidding solution by integrating with the Smaato NextGen SDK today.

Your Advantage

We are observing more and more demand partners moving away from multiple integrations. Following the TradeDesk’s public announcement that they will only allow one integration per supply source, many other demand partners are now following suit.

Currently, we have seen up to 230% higher revenue when comparing Smaato Unified Bidding versus TAM integrations. We have also observed around a 300% increase in revenue via the direct connection due to the additional revenue accumulated.

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.

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:

Bid Adjustment % ValueBid Price (before adjustment)Bid Price (after adjustment)
100%$1$1
70%$1$.70
120%$1$1.20

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 AdsSMAAdMobSmaatoBannerAdapter
    • For Interstitial AdsSMAAdMobSmaatoInterstitialAdapter
    • For Rewarded Video AdsSMAAdMobSmaatoRewardedVideoAdapter
    • For Native AdsSMAAdMobSmaatoNativeAdapter
  • 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

Demo App for Sample Integration

Download latest Demo App Apk from here.

Smaato Android SDK Setup and Initialization

Gradle Dependencies

Configure your Android project

To setup SmaatoSDK dependencies for your project see NextGen SDK Android Integration Guide.

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://s3.amazonaws.com/smaato-sdk-releases/"
        }
    }
}

Set the compile options to Java 8, (i.e. place the following line into your application module build.gradle file):

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

UnifiedBidding module dependency setup

Application module build.gradle file

dependencies {
    implementation 'com.smaato.android.sdk:smaato-sdk-unified-bidding:21.8.4'
}

Unified Bidding Module Initialization

Smaato Unified Bidding module will automatically be enabled for the publisher that is set on SDK initialization if the module has previously been integrated.

Additionally, it is recommended to configure the SDK with user information. This is an optional step and can be implemented at a later time using the following configurations:

SmaatoSdk.setKeywords(...);
SmaatoSdk.setSearchQuery(...);
SmaatoSdk.setGender(...);
SmaatoSdk.setAge(...);
SmaatoSdk.setLatLng(...);
SmaatoSdk.setRegion(...);
SmaatoSdk.setLanguage(...);
SmaatoSdk.setZip(...);
SmaatoSdk.setCoppa(...);
SmaatoSdk.setGPSEnabled(...);

GPSEnabled flag allows to get user’s location by Smaato SDK automatically and put it inside ad requests.

Key-Value Targeting for Unified Bidding

KeyValuePairs is the public component that allows creating targeting parameters.

A new setKeyValuePairs method was introduced for each ad type and allows publishers to pass the keywords to be included in the request.

Constraints of setting KeyValuePairs:

  • Can be added up to 7 values per key. If one key contains more than 7 values, the SDK adds to the query request only 7 values.
  • Can add up to 7 key-value pairs per request. If the dictionary contains more than 7 key-value pairs, the SDK adds to the query request only 7 key-value pairs.
  • Key is String type and the Value is an Array of String type.

KeyValuePairs.class API

/**
 * If key is already exists in the dictionary, value is appended to the existing objects. Otherwise, key-value pair is added.
 */
void addTargetingValue(@NonNull String key, @NonNull String value);
  
/**
 * If key is already exists in the dictionary, value takes its place. Otherwise, key-value pair is added.
 */
void setTargetingValue(@NonNull String key, @NonNull String value);
  
/**
 * If key is already exists in the dictionary, values takes its place. Otherwise, key-value pairs are added.
 */
void setTargetingValues(@NonNull String key, @NonNull String... values);
  
/**
 * Empties the KeyValuePair of its values.
 */
void removeAllKeyValuePairs();
  
/**
 * Removes specific key-value pair set from the targeting.
 */
void removeKeyValuePair(@NonNull String key);
  
/**
 * Returns all key-value pairs that will be added to the query request.
 */
@NonNull
Map<String, Set<String>> getAllKeyValuePairs();

To use Key Value Targeting for Unified Bidding, please use the following UnifiedBidding.class public API

UnifiedBidding.class API

/**
 * @return {@link KeyValuePairs} object if one was set by {@link UnifiedBidding#setKeyValuePairs(KeyValuePairs)}
 */
@Nullable
public static KeyValuePairs getKeyValuePairs() {...}
 
/**
 * Sets an {@link KeyValuePairs} object to target more specific ads.
 *
 * @param keyValuePairs to be set
 */
public static void setKeyValuePairs(@Nullable KeyValuePairs keyValuePairs) {...}

NextGen SDK Integration

The NextGen SDK supports several standard banner dimensions, which should be used for Prebid requests. They are declared in UBBannerSize enum. Please use an appropriate value for the parameter in the UnifiedBidding.prebidBanner() method call as shown in the following examples.

UBBannerSize.class

/**
 * Banner sizes supported in the SDK
 */
public enum UBBannerSize {
   /**
    * XXLarge (320x50)
    */
   XX_LARGE_320x50(AdDimension.XX_LARGE),
 
   /**
    * Medium Rectangle (300x250)
    */
   MEDIUM_RECTANGLE_300x250(AdDimension.MEDIUM_RECTANGLE),
 
   /**
    * Leaderboard (728x90)
    */
   LEADERBOARD_728x90(AdDimension.LEADERBOARD),
 
   /**
    * Skyscraper (120x600)
    */
   SKYSCRAPER_120x600(AdDimension.SKYSCRAPER);
 
   @NonNull
   public final AdDimension adDimension;
 
// ... }

UnifiedBidding.PrebidListener

/**
 * A listener for Prebid requests.
 * <p>
 * Should be passed for one of {@link #prebidBanner}, {@link #prebidInterstitial},
 * as a mandatory parameter to register for receiving callbacks.
 * <p>
 */
public interface PrebidListener {
 
/**
 * A callback which will be invoked on a completion of prebid request and one of the following result
 *
 * @param ubBid an {@link UBBid} object in case of success prebid response
 * @param prebidRequestError an {@link UBBidRequestError} object in case of failed one.
 */
void onPrebidResult(@Nullable UBBid ubBid, @Nullable UBBidRequestError prebidRequestError);
}

Prebid Requests public API

UnifiedBidding.class

/**
 * Requests a prebid data for Banner Ads.
 *
 * @param adSpaceId AdSpace ID (assigned by Smaato). Can not be {@code null}. If {@code null} is passed, then
 *                  {@link PrebidListener#onPrebidResult} will be called with {@link UBError#INVALID_REQUEST } error.
 *                  Unified Bidding support should be enabled for this adSpaceId in Smaato SPX
 * @param bannerSize {@link UBBannerSize} for this request.
 * @param listener {@link PrebidListener} for this request.
 *                  SmaatoSdk keeps {@link java.lang.ref.WeakReference } on listener to prevent memory leaks.
 *                  It's responsibility of SmaatoSdk's user to keep instances from being collected by garbage collector.
 */
public static void prebidBanner(@NonNull String adSpaceId,
                                @NonNull UBBannerSize bannerSize,
                                @NonNull PrebidListener listener) {...}
 
/**
 * Requests a prebid data for Interstitial Ads.
 *
 * @param adSpaceId AdSpace ID (assigned by Smaato). Can not be {@code null}. If {@code null} is passed, then
 *                  {@link PrebidListener#onPrebidResult} will be called with {@link UBError#INVALID_REQUEST } error.
 *                  Unified Bidding support should be enabled for this adSpaceId in Smaato SPX
 * @param listener {@link PrebidListener} for this request.
 *                  SmaatoSdk keeps {@link java.lang.ref.WeakReference } on listener to prevent memory leaks.
 *                  It's responsibility of SmaatoSdk's user to keep instances from being collected by garbage collector.
 */
public static void prebidInterstitial(@NonNull String adSpaceId, @NonNull PrebidListener listener) {...}
 
 
/**
 * Requests a prebid data for Rewarded Interstitial Ads.
 *
 * @param adSpaceId AdSpace ID (assigned by Smaato). Can not be {@code null}. If {@code null} is passed, then
 *                  {@link PrebidListener#onPrebidResult} will be called with {@link UBError#INVALID_REQUEST } error.
 *                  Unified Bidding support should be enabled for this adSpaceId in Smaato SPX
 * @param listener  {@link PrebidListener} for this request.
 *                  SmaatoSdk keeps {@link java.lang.ref.WeakReference } on listener to prevent memory leaks.
 *                  It's responsibility of SmaatoSdk's user to keep instances from being collected by garbage collector.
 */
public static void prebidRewardedInterstitial(@NonNull String adSpaceId, @NonNull PrebidListener listener) {...}
 
 
/**
 * Requests a prebid data for Native Ads.
 *
 * @param adSpaceId AdSpace ID (assigned by Smaato). Can not be {@code null}. If {@code null} is passed, then
 *                  {@link PrebidListener#onPrebidResult} will be called with {@link UBError#INVALID_REQUEST } error.
 *                  Unified Bidding support should be enabled for this adSpaceId in Smaato SPX
 * @param listener  {@link PrebidListener} for this request.
 *                  SmaatoSdk keeps {@link java.lang.ref.WeakReference } on listener to prevent memory leaks.
 *                  It's responsibility of SmaatoSdk's user to keep instances from being collected by garbage collector.
 */
public static void prebidNative(@NonNull String adSpaceId, @NonNull PrebidListener listener) {...}
 
 
/**
 * Requests a prebid data for Outstream Video Ads.
 *
 * @param adSpaceId AdSpace ID (assigned by Smaato). Can not be {@code null}. If {@code null} is passed, then
 *                  {@link PrebidListener#onPrebidResult} will be called with {@link UBError#INVALID_REQUEST } error.
 *                  Unified Bidding support should be enabled for this adSpaceId in Smaato SPX
 * @param listener  {@link PrebidListener} for this request.
 *                  SmaatoSdk keeps {@link java.lang.ref.WeakReference } on listener to prevent memory leaks.
 *                  It's responsibility of SmaatoSdk's user to keep instances from being collected by garbage collector.
 */
public static void prebidOutstream(@NonNull String adSpaceId,
                                @NonNull UBBannerSize bannerSize,
                                @NonNull PrebidListener listener) {...}




Prebid response objects

UBBid.class

/**
 * The object which is provided with failed Prebid response as a parameter for
 * {@link UnifiedBidding.PrebidListener#onPrebidResult(UBBid, UBBidRequestError)} callback
 */
public class UBBid {
 
   /**
    * Adjusted bid price on the base of the chosen granularity of ad displaying
    */
   public final float bidPrice;
 
   /**
    * Helper method provides metadata dictionary that allows to fetch related ad creative in case of bid prices auction win.
    */
   @NonNull
   public final Map<String, Object> metadata;
 
// {...} }

UBPrebidRequestError.class

/**
 * The Error which is provided with failed Prebid response as a parameter for
 * {@link UnifiedBidding.PrebidListener#onPrebidResult(UBBid, UBBidRequestError)} callback
 */
public class UBBidRequestError {
 
   /**
    * {@link UBError} the reason of failed Prebid request
    */
   @NonNull
   public final UBError error;
 
   /**
    * Publisher ID, that has been passed to {@link SmaatoSdk#init}.
    */
   @Nullable
   public final String publisherId;
 
   /**
    * AdSpace ID, that has been passed to Prebid request.
    */
   @Nullable
   public final String adSpaceId;
 
   /**
    * {@link UBBannerSize} ubBannerSize, that has been passed to
    * {@link UnifiedBidding#prebidBanner(String, UBBannerSize, UnifiedBidding.PrebidListener)} request.
    */
   @Nullable
   public final UBBannerSize ubBannerSize;
 
// {...}




Unified Bidding Example Requests

Banner 320×50 Prebid Request

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

  1. First, find the line of code where you create a AdManagerAdView banner instance to add Smaato Unified Bidding prebid call.
  2. Next, add the UnifiedBidding.prebidBanner(...) 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 onPrebidResult callback method and use Prebid data from UBBid 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 AdManagerAdRequest and call loadAd

Generic

UnifiedBidding.prebidBanner("<AD_SPACE_ID>", UBBannerSize.XX_LARGE_320x50, (ubBid, ubBidRequestError) ->
{
    if (ubBidRequestError != null)
     {
       Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
     }
    if (ubBid != null)
     {
       String ubId = ubBid.getMetadata().get(UBBid.MetadataKeys.UNIQUE_ID).toString();
       AdRequestParams adRequestParams = AdRequestParams.builder().setUBUniqueId(ubId).build();
       bannerView.loadAd( "< AD_SPACE_ID >", BannerAdSize.<SIZE>, adRequestParams);
     }
}));

GAM Specific

AdManagerAdView adView = new AdManagerAdView(this);
adView.setAdSizes(AdSize.BANNER);
adView.setAdUnitId("YOUR_GAM_AD_UNIT_ID");
UnifiedBidding.prebidBanner(/*"SMAATO_ADSPACE_ID"*/, UBBannerSize.XX_LARGE_320x50, (ubBid, prebidRequestError) ->
{ if (ubBid != null)
  {
    // Let's assume this is the max price of your line items (you will want to change this float to yours)
    float maxPrice = 0.1F; String bidKeyword;
    if (ubBid.bidPrice > maxPrice) {
      bidKeyword = String.format(Locale.US, "smaato_cpm:%.2f", maxPrice);
    }
    AdManagerAdRequest kvpRequest = new AdManagerAdRequest.Builder().addCustomTargeting("smaub", bidKeyword).build();
 } else if (prebidRequestError != null) {
   /* Timber.e(prebidRequestError.error.toString()) */
 } adView.loadAd(kvpRequest);
});

Interstitial request

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

  1. First, find the line of code where you initialise the AdManagerInterstitialAd instance to add Smaato Unified Bidding.
  2. Next, add the UnifiedBidding.prebidInterstitial(...) method call to your code in the same way shown in the examples below.
  3. Then, move the load method call to the onPrebidResult callback method and use Prebid data from UBBid bid* instance to build correct targeting string for Smaato Line Item (which you have created early via GAM Dashboard).  Finally, pass the UB bidKeyword string in Key-value form inside AdManagerAdRequest and call loadAd.

GAM Specific

private AdManagerInterstitialAd mAdManagerInterstitialAd;
UnifiedBidding.prebidInterstitial(/*"SMAATO_ADSPACE_ID"*/, (ubBid, prebidRequestError) ->
{
  if (ubBid != null) {
    // Let's assume this is the max price of your line items (you will want to change this float to yours)
    float maxPrice = 0.1F;
    String bidKeyword;
    if (ubBid.bidPrice > maxPrice) {
       bidKeyword = String.format(Locale.US, "smaato_cpm:%.2f", maxPrice);
    }
    AdManagerAdRequest kvpRequest = new AdManagerAdRequest.Builder().addCustomTargeting("smaub", bidKeyword).build();
  } else if (prebidRequestError != null) {
    /* Timber.e(prebidRequestError.error.toString()) */
  }
  AdManagerInterstitialAd.load(this,"YOUR_GAM_AD_UNIT_ID", kvpRequest, new AdManagerInterstitialAdLoadCallback() {
  
  @Override public void onAdLoaded(@NonNull AdManagerInterstitialAd interstitialAd) {
   // The mAdManagerInterstitialAd reference will be null until
   // an ad is loaded.
   mAdManagerInterstitialAd = interstitialAd;
   Log.i(TAG, "onAdLoaded");
  }
 
  @Override public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
   // Handle the error
   Log.i(TAG, loadAdError.getMessage()); mAdManagerInterstitialAd = null;
  }
 });
});

Generic

UnifiedBidding.prebidInterstitial("<AD_SPACE_ID>", (ubBid, ubBidRequestError) ->
{
  if(ubBidRequestError != null)
  {
   Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
  }
  if (ubBid != null)
  {
   String ubId = ubBid.getMetadata().get(UBBid.MetadataKeys.UNIQUE_ID).toString();
   AdRequestParams adRequestParams = AdRequestParams.builder().setUBUniqueId(ubId).build();
   Interstitial.loadAd("<AD_SPACE_ID>", eventListener, adRequestParams);
  }
});

Rewarded request

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

  1. First, find the line of code where you load the GAM Ad `RewardedAd` to add Smaato Unified Bidding.
  2. Next, add the `UnifiedBidding.prebidRewardedInterstitial` method call to your code in the same way shown in the examples below.
  3. Then, move the load method call to the PrebidListener callback method and use Prebid data from UBBid bid* instance to build correct targeting string for Smaato Line Item (which you have created early via GAM Dashboard). 
  4. Finally, pass the UB bidKeyword string in Key-value form inside AdManagerAdRequest and call loadAd.

GAM Specific

private RewardedAd mRewardedAd;
private final String TAG = "MainActivity";
UnifiedBidding.prebidRewardedInterstitial("SMAATO_ADSPACE_ID", prebidListener);
private final UnifiedBidding.PrebidListener prebidListener = (ubBid, ubBidRequestError) ->
Threads.runOnUi(() -> {
 if (ubBidRequestError != null) {
   Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
 }
 if (ubBid == null) {
   Log.d(TAG, "SmaatoSdk PreBid error: empty response");
   return;
 }   
 float maxPrice = 0.1F;
 String bidKeyword;
 if (ubBid.bidPrice > maxPrice) {
   bidKeyword = String.format(Locale.US, "smaato_cpm:%.2f", maxPrice);
 });
 AdManagerAdRequest kvpRequest = new AdManagerAdRequest.Builder().addCustomTargeting("smaub", bidKeyword).build();
 RewardedAd.load(this, "YOUR_GAM_AD_UNIT_ID", kvpRequest, new RewardedAdLoadCallback()
  {
   @Override public void onAdFailedToLoad(@NonNull LoadAdError loadAdError)
   {
    // Handle the error.
    Log.d(TAG, loadAdError.getMessage());
    mRewardedAd = null;
   }
   @Override public void onAdLoaded(@NonNull RewardedAd rewardedAd)
   {
    mRewardedAd = rewardedAd;
    Log.d(TAG, "Ad was loaded.");
   }
 });
});

Generic

UnifiedBidding.prebidRewardedInterstitial("<AD_SPACE_ID>", (ubBid, ubBidRequestError) -> Threads.runOnUi(() -> {
if (ubBidRequestError != null)
 {
  Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
 }
if (ubBid != null)
 {
 String ubId = ubBid.getMetadata().get(UBBid.MetadataKeys.UNIQUE_ID).toString();
 AdRequestParams adRequestParams = AdRequestParams.builder().setUBUniqueId(ubId).build();
 RewardedInterstitial.loadAd( "<AD_SPACE_ID>", eventListener, adRequestParams);
 }
}));

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 UBBid 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 AdManagerAdRequest and call adLoader.loadAd.

GAM Specific

UnifiedBidding.prebidNative(/"SMAATO_ADSPACE_ID"/, (ubBid, prebidRequestError) -> {
if (ubBid != null) {
// Let's assume this is the max price of your line items (you will want to change this float to yours)
float maxPrice = 0.1F;
 
String bidKeyword;
 if (ubBid.bidPrice > maxPrice)
 {
  bidKeyword = String.format(Locale.US, "smaato_cpm:%.2f", maxPrice);
 }      
 AdManagerAdRequest kvpRequest = new AdManagerAdRequest.Builder().addCustomTargeting("smaub", bidKeyword).build();
 AdLoader adLoader = new AdLoader.Builder(this, "YOUR_GAM_AD_UNIT_ID")
                .forNativeAd(this::onNativeAdLoaded)
                .withAdListener(new AdMobAdListener())
                .withNativeAdOptions(new NativeAdOptions.Builder().build())
                .build();
 adLoader.loadAd(kvpRequest);
 } else if (prebidRequestError != null) {
  /* Timber.e(prebidRequestError.error.toString()) */
 }
});

Generic

UnifiedBidding.prebidNative("<AD_SPACE_ID>", (ubBid, ubBidRequestError) ->
 {
  if (ubBidRequestError != null)
  {
   Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
  }
  if(ubBid != null)
  {
  String ubId = ubBid.getMetadata().get(UBBid.MetadataKeys.UNIQUE_ID).toString();
  NativeAdRequest nativeAdRequest = NativeAdRequest.builder().uniqueUBId(ubId).adSpaceId("<AD_SPACE_ID>").build();
  NativeAd.loadAd( this, nativeAdRequest, nativeAdListener;
 }
});  

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 AdManagerAdView banner 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 onPrebidResult callback method and use Prebid data from UBBid 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 AdManagerAdRequest and call loadAd

GAM Specific

AdManagerAdView adView = new AdManagerAdView(this);
adView.setAdSizes(AdSize.BANNER);
adView.setAdUnitId("YOUR_GAM_AD_UNIT_ID");
UnifiedBidding. prebidOutstream(/"SMAATO_ADSPACE_ID"/, UBBannerSize.XX_LARGE_320x50, (ubBid, prebidRequestError) -> {
 if (ubBid != null) {
 // Let's assume this is the max price of your line items (you will want to change this float to yours)
 float maxPrice = 0.1F;
 String bidKeyword;
 if (ubBid.bidPrice > maxPrice) {
  bidKeyword = String.format(Locale.US, "smaato_cpm:%.2f", maxPrice);
 }
 AdManagerAdRequest kvpRequest = new AdManagerAdRequest.Builder().addCustomTargeting("smaub", bidKeyword).build();
 kvpRequest.customTargeting = ubKVP;
 } else if (prebidRequestError != null){
 /* Timber.e(prebidRequestError.error.toString()) */
}
adView.loadAd(kvpRequest);
});

Generic

UnifiedBidding.prebidOutstream("<AD_SPACE_ID>", UBBannerSize.LEADERBOARD_728x90, (ubBid, ubBidRequestError)
{
 if (ubBidRequestError != null)
  {
   Log.d(TAG, "SmaatoSdk PreBid error: " + ubBidRequestError.error);
  }
 if (ubBid != null)
  {
   String ubId = ubBid.getMetadata().get(UBBid.MetadataKeys.UNIQUE_ID).toString();
   AdRequestParams adRequestParams = AdRequestParams.builder().setUBUniqueId(ubId).build();
   bannerview.loadAd("<AD_SPACE_ID>", BannerAdSize.LEADERBOARD_728x90, adRequestParams); }
}));

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 SharedPreferences using the following keys:

KeyTypeDescription
KeyTypeDescription
IABConsent_CMPPresentBooleanSet to “YES” if a CMP that follows the IAB specification is present in the application.
IABConsent_SubjectToGDPRString1” = Subject to GDPR
0” = Not subject to GDPR
-1” = Undetermined (default before initialization)
IABTCF_gdprAppliesString1” = GDPR applies in current context
0” = GDPR does not applies in current context
-1” = GDPR is unknown
IABConsent_ConsentStringStringBase64-encoded consent string as defined in Consent string and vendor list format v1.1
IABConsent_ParsedPurposeConsentsStringString of “0”s and “1”s, where the character at position N indicates the consent status to purposeID N as defined in the Global Vendor List
IABConsent_ParsedVendorConsentsStringString of “0”s and “1”s, where the character at position N indicates the consent status to vendorID N as defined in the Global Vendor List

Proguard Configuration

If you’re using Proguard in your project, please add the following lines to your Proguard config file, as per your requirements:

-keep public class com.smaato.sdk.** { *; } -keep public interface com.smaato.sdk.** { *; }

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 SharedPreferences with key “IABUSPrivacy_String” in the US Privacy String format (CCPA Opt-Out Storage Format).

The Smaato NextGen SDK reads this value in the key “IABUSPrivacy_String” if it exists and uses this as an optional parameter for all ad requests.

Sample of US Privacy String Saving in SharedPreferences

SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(context)
SharedPreferences.Editor editor = sharedPref.edit();
editor.putString("IABUSPrivacy_String", "iab string");
editor.commit();
Doc Feedback Product Feedback

Last Modified: October 28, 2022 at 5:16 pm