NextGen SDK | Android Integration

Home » Publisher Documentation » NextGen SDK | Android Integration

If you would like to access the documentation for Smaato’s legacy SDK (iOS versions 10.2.5 and prior, or Android versions 9.1.7 and prior), please click here.

Integration Guide for Publishers with Smaato as a Primary Ad Server

(Android NextGen SDK version 21.3.8)

Attention: If you are a publisher that has a custom adapter or intends to have a custom integration, please contact our Sales Engineering team before you begin.

Integrate the NextGen SDK

Set up your account on SPX

https://spx.smaato.com/

Configure your Android project

Add the following repository setup to your project’s main build.gradle file:

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

Important Note: Smaato SDK minSdkVersion is Android 4.1 (API level 16).

Add dependencies to your application module build.gradle file.

For all Ad Types, make sure the following dependency is in place:

implementation 'com.smaato.android.sdk:smaato-sdk:21.3.8'

For Banner ads, then make sure the following dependencies are in place:

implementation 'com.smaato.android.sdk:smaato-sdk-banner:21.3.8'

For Interstitial ads, then make sure the following dependencies are in place:

implementation 'com.smaato.android.sdk:smaato-sdk-interstitial:21.3.8'

For Rewarded ads, then make sure the following dependencies are in place:

implementation 'com.smaato.android.sdk:smaato-sdk-rewarded-ads:21.3.8'

Add the following permissions to your application AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

If your application targets Android 5.0 (API level 21) or higher, then you need to add the following line to your application AndroidManifest.xml file:

<uses-feature android:name="android.hardware.location.network" />

If your application targets Android 9 Pie (API level 28) or higher, in order to send HTTP requests (so that more Ads can be shown), then you need to configure the networkSecurityConfig attribute in the application tag in AndroidManifest.xml:

android:networkSecurityConfig="@xml/network_security_config"

Now create the network_security_config.xml in the XML resource directory with:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

For more details regarding the Network security configuration, please see the official Google documentation: https://developer.android.com/training/articles/security-config

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.** { *; }

Initialize the NextGen SDK

Add the following to your YourApplication.OnCreate() method, to initialize the Smaato SDK. Additionally, it is recommended to configure the SDK with user information. This is an optional step and can be implemented at a later time.

import android.app.Application;
import com.smaato.sdk.core.AdContentRating;
import com.smaato.sdk.core.Config;
import com.smaato.sdk.core.Gender;
import com.smaato.sdk.core.SmaatoSdk;
import com.smaato.sdk.core.log.LogLevel;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // // initialize SDK first!
        Config config = Config.builder()
                // log errors only
                .setLogLevel(LogLevel.ERROR)
                // allow HTTPS traffic only
                .setHttpsOnly(true)
                .build();
        // initialize the Smaato SDK
        SmaatoSdk.init(this, config, "SMAATO_PUBLISHER_ID");
      
        // You can also initialize the Smaato SDK without configuration:
        // SmaatoSdk.init(this, "SMAATO_PUBLISHER_ID");

        // optional configuration
        SmaatoSdk.setSearchQuery("bitcoin, lamborghini, san-francisco");
        SmaatoSdk.setGender(Gender.MALE); // usually set after user logs in
        SmaatoSdk.setAge(40); // usually set after user logs in
        // allow the Smaato SDK to automatically get the user's location
        SmaatoSdk.setGPSEnabled(true);
    }
}

Important Note: Starting from NextGen SDK version 21.2.1, the new GPSEnabled flag allows the SDK to automatically get the user’s location when permission is given by the user. By default, this flag is set to off and the user location will not be provided in the ad request. To enable this the GPSEnabled flag must be set to yes.

Important Details About GDPR

The General Data Protection Regulation (GDPR) was created to provide European users with greater transparency and control over their personal information. As a publisher, you should integrate a Consent Management Platform (CMP) and request for user, vendor, and purpose consents as outlined in IAB Europe’s Mobile In-App CMP API v1.0: Transparency & Consent Framework. You can find an example implementation of a web-based CMP and the corresponding native wrappers here in the IAB’s GDPR-Transparency-and-Consent-Framework.

You can also make your own custom CMP. The collected end-user consent information needs to be stored in SharedPreferences using the following keys:

Important Note: Smaato SDK minSdkVersion is Android 4.1 (API level 16).

Key	Type	Description
IABConsent_CMPPresent	Boolean	Set to True if a CMP that follows the IAB specification is present in the application.
IABConsent_SubjectToGDPR	String	“1” = Subject to GDPR “0” = Not subject to GDPR “-1” = Undetermined (default before initialization)
IABConsent_ConsentString	String	Base64-encoded consent string as defined in Consent string and vendor list format v1.1
IABConsent_ParsedPurposeConsents	String	String 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_ParsedVendorConsents	String	String 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

Important Note: If the key IABConsent_SubjectToGDPR is set to “1”, then you as a publisher need to make sure the key IABConsent_ConsentString contains a valid consent string (user was asked to provide consent before serving the ad). Otherwise, such ad requests will be dropped on the server-side without a return.

Sample of GDPR Saving in SharedPreferences

import android.content.SharedPreferences;
import android.preference.PreferenceManager;

...
// User is not subject to GDPR
SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(context)
SharedPreferences.Editor editor = sharedPref.edit();
editor.putString("IABConsent_SubjectToGDPR", "0");
editor.commit();
// Use this example above to set values for the rest of the GDPR keys

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.

For more information about the CCPA regulation, please check out the Smaato FAQ. You can also review the IAB’s U.S. Privacy String documentation.

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 CCPA Saving in SharedPreferences

import android.content.SharedPreferences;
import android.preference.PreferenceManager;

...
// save the user's consent
SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(context)
SharedPreferences.Editor editor = sharedPref.edit();
editor.putString("IABUSPrivacy_String", "1YNN"); // for example "1YNN"
editor.commit();

IMPORTANT NOTE: Please review the IAB’s guidelines for entering and formatting the U.S. Privacy String (CCPA Opt-Out Storage Format). Our sample provided above (“1YNN”) for the US Privacy String demonstrates when the user has not made a choice to opt-out.

Further Examples of the U.S. Privacy String 1YNN: User has not made a choice to opt-out 1NYY: User has made a choice to opt-out 1—: A Digital Property has determined to use a U.S. Privacy string version 1 and that CCPA does not apply to the transaction.

Ads for Testing Purposes

Important Note: All ad spaces can be used on both Android and iOS platforms and do not require any SPX changes. It is mandatory to the use the ad space IDs provided in the table below for testing. You can use these ad space IDs without changing your production publisher ID, as long as you move back to your production ad space IDs when publishing your app.

Adspace ID	Type	Description
130626424	Rich Media	Banner / Med-rect / Leaderboard / Skyscraper
130635694	Static Image	Banner / Med-rect / Leaderboard / Skyscraper
130635706	MRAID	Banner / Med-rect / Leaderboard / Skyscraper
130626426	Rich Media / Video	Interstitial (Video with an end-card + Rich Media Interstitial for 320×480, 480×320, 1024×768 & 768×1024)
130626427	Video	Skippable Video
130626428	Rewarded	Rewarded Video
130635048	Rewarded	Rewarded Video without an end-card

Showing Banner Ads

Add BannerView to your layout XML:

<com.smaato.sdk.banner.widget.BannerView
    android:id="@+id/bannerView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />

In Activity/Fragment, that uses the above layout, get the BannerView, and call loadAd() with your adspaceId and desired bannerAdSize in order to start loading the banner. Optionally, you can also set BannerView.EventListener to listen to events describing the ad’s lifecycle. When your UI component (that hosts the BannerView) is being destroyed, BannerView.destroy() should be called in order to properly release BannerView resources.

import android.app.Activity;
import android.app.ActivityManager;
import android.content.ComponentName;
import android.content.Context;
import android.os.Bundle;
import android.util.Log;
import androidx.annotation.NonNull;
import com.smaato.sdk.banner.ad.BannerAdSize;
import com.smaato.sdk.banner.widget.BannerView;

public class YourActivity extends Activity {

    // find bannerView you setup in your activity.xml
    BannerView bannerView = (BannerView) findViewById(R.id.bannerView);

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // load banner with desired size
        bannerView.loadAd("SMAATO_ADSPACE_ID", BannerAdSize.XX_LARGE_320x50);
    }
  
  // You can also set BannerView.EventListener to listen to events describing the advertisement lifecycle:
  bannerView.setEventListener(new BannerView.EventListener() {
    @Override
    // banner ad successfully loaded
    public void onAdLoaded(@NonNull BannerView bannerView) {}
    @Override
    // banner ad failed to load
    public void onAdFailedToLoad(@NonNull BannerView bannerView, @NonNull BannerError bannerError) {}
    @Override
    // banner ad was seen by the user
    public void onAdImpression(@NonNull BannerView bannerView) {}
    @Override
    // banner ad was clicked by the user
    public void onAdClicked(@NonNull BannerView bannerView) {}
    @Override
    // banner ad Time to Live expired
    public void onAdTTLExpired(@NonNull BannerView bannerView) {}
});
  
  /* If your UI component (that hosts the BannerView) is being destroyed, 
  BannerView.destroy() should be called in order to properly release BannerView resources: */
  @Override
    public void onDestroy() {
        super.onDestroy();
        bannerView.destroy();
    }

}

Showing Interstitial Ads

Call Interstitial.loadAd() with your adspaceId and eventListener in order to start loading the interstitial. This passed eventListener will be used to deliver events describing the ad’s lifecycle. Optionally, you can change the background color for an InterstitialAd. The default is black. Lastly, when the ad is loaded and available for presentation, call showAd(activity) on a received InterstitialAd object to show it to the user.

Important Note: The Smaato NextGen SDK keeps {@link java.lang.ref.WeakReference} on eventListener to prevent memory leaks. It is the responsibility of SOMA SDK’s user to hold the reference to a passed eventListener instance in order to keep it from being collected by the garbage collector.

import android.app.Activity;
import android.app.ActivityManager;
import android.content.ComponentName;
import android.content.Context;
import android.os.Bundle;
import android.util.Log;
import androidx.annotation.NonNull;
import com.smaato.sdk.interstitial.Interstitial;
import com.smaato.sdk.interstitial.InterstitialAd;
import com.smaato.sdk.interstitial.InterstitialError;
import com.smaato.sdk.interstitial.InterstitialRequestError;
import com.smaato.sdk.interstitial.EventListener;

public class YourActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // load interstitial ad
        Interstitial.loadAd("SMAATO_ADSPACE_ID", eventListener);

    }
  
     EventListener eventListener = new EventListener() {
       @Override
       //show interstitial ad when it loaded successfully
       public void onAdLoaded(@NonNull InterstitialAd interstitialAd) {
          interstitialAd.setBackgroundColor(0xff123456);
          interstitialAd.showAd(YOUR_ACTIVITY_HERE);
       }

       @Override
       // interstitial ad failed to load
       public void onAdFailedToLoad(@NonNull InterstitialRequestError interstitialRequestError) {}

       @Override
       // interstitial ad had an unexpected error 
       public void onAdError(@NonNull InterstitialAd interstitialAd, @NonNull InterstitialError interstitialError) {}

       @Override
       // interstitial ad opened and was shown successfully
       public void onAdOpened(@NonNull InterstitialAd interstitialAd) {}

       @Override
       // interstitial ad was closed by the user
       public void onAdClosed(@NonNull InterstitialAd interstitialAd) {}

       @Override
       // interstitial ad was clicked by the user
       public void onAdClicked(@NonNull InterstitialAd interstitialAd) {}

       @Override
       // interstitial ad was viewed by the user
       public void onAdImpression(@NonNull InterstitialAd interstitialAd) {}

       @Override
       // interstitial ad Time to Live expired
       public void onAdTTLExpired(@NonNull InterstitialAd interstitialAd) {}
   };

}

Showing Rewarded Interstitial Ads

Call RewardedInterstitial.loadAd() with adspaceId and eventListener in order to start loading the rewarded interstitial. As for Interstitial, the eventListener will be used to deliver events describing the ad’s lifecycle. Lastly, when the ad is loaded and available for presentation, call show() on a received RewardedInterstitialAd object to show it to the user.

Important Note: The Smaato NextGen SDK keeps {@link java.lang.ref.WeakReference} on eventListener to prevent memory leaks. It is the responsibility of Soma SDK’s user to hold the reference to a passed eventListener instance in order to keep it from being collected by the garbage collector.

import android.app.Activity;
import android.app.ActivityManager;
import android.content.ComponentName;
import android.content.Context;
import android.os.Bundle;
import android.util.Log;
import androidx.annotation.NonNull;
import com.smaato.sdk.rewarded.RewardedInterstitial;
import com.smaato.sdk.rewarded.RewardedInterstitialAd;
import com.smaato.sdk.rewarded.RewardedError;
import com.smaato.sdk.rewarded.RewardedRequestError;
import com.smaato.sdk.rewarded.EventListener;

public class YourActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // load rewarded ad
        RewardedInterstitial.loadAd("SMAATO_ADSPACE_ID", eventListener);

    }
  
  EventListener eventListener = new EventListener() {
    @Override
    //show rewarded ad when it loaded successfully
    public void onAdLoaded(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {
      rewardedInterstitialAd.showAd();
    }
    
    @Override
    // rewarded ad failed to load
    public void onAdFailedToLoad(@NonNull RewardedRequestError rewardedRequestError) {}
    
    @Override
    // rewarded ad had an unexpected error
    public void onAdError(@NonNull RewardedInterstitialAd rewardedInterstitialAd, @NonNull RewardedError rewardedError {}
  
    @Override
    // rewarded ad was closed by the user
    public void onAdClosed(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {}
  
    @Override
    // rewarded ad was clicked by the user
    public void onAdClicked(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {}
  
    @Override
    // rewarded ad started playing
    public void onAdStarted(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {}
  
    @Override
    // rewarded ad finished playing and was watched all the way through
    public void onAdReward(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {
        // rewarded your user here!
    }
  
    @Override
    // rewarded ad Time to Live expired
    public void onAdTTLExpired(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {}
   };

}

Modified: May 6, 2020 at 10:29 am