NextGen SDK | Android Integration

Integration Guide for Publishers with Smaato as a Primary

(Android NextGen SDK version 21.1.4)

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:

Key Type Description
IABConsent_CMPPresent Boolean

Set to “YES” 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 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

Ads for Testing Purposes

Publisher ID: 1100042525  
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

Integrating an Android App

1.) Set up your account on SPX

https://spx.smaato.com/

2.) Configure your Android project

2.1) 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/"
        }
    }
}

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

2.3) 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.1.4'

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

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

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

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

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

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

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

Mandatory permissions:

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

Optional permissions: 

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

2.5) 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" />

2.6) 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"

2.7) 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

3.) Initialize Smaato SDK in your Application

3.1) Add to your Application.OnCreate() method to the following line, to initializes the Smaato SDK:

SmaatoSdk.init(this, publisherId);

3.2) You can configure additional parameters for the SDK by passing the Config parameter to the init method.

Config config = Config.builder()
        .setLogLevel(LogLevel.INFO)
        .setHttpsOnly(false)
        .build();


SmaatoSdk.init(this, config, publisherId);

3.3) 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(...);

4.) Showing Banner Ads

4.1) 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" />

4.2) In Activity/Fragment, that uses the above layout, get BannerView:

BannerView bannerView = (BannerView) findViewById(R.id.bannerView);

4.3) Call loadAd() with your adspaceId and desired bannerAdSize in order to start Ad loading:

bannerView.loadAd(adspaceId, bannerAdSize);

4.5) Optionally, you can also set BannerView.EventListener to listen to events describing the advertisement lifecycle:

bannerView.setEventListener(new BannerView.EventListener() {
    @Override
    public void onAdLoaded(@NonNull BannerView bannerView) {}
    @Override
    public void onAdFailedToLoad(@NonNull BannerView bannerView, @NonNull BannerError bannerError) {}
    @Override
    public void onAdImpression(@NonNull BannerView bannerView) {}
    @Override
    public void onAdClicked(@NonNull BannerView bannerView) {}
    @Override
    public void onAdTTLExpired(@NonNull BannerView bannerView) {}
});

4.6) When your UI component (that hosts the BannerView) is being destroyed, BannerView.destroy() should be called in order to properly release BannerView resources. E.g.:

class YourActivity {
    ...
    @Override
    public void onDestroy() {
        super.onDestroy();
        bannerView.destroy();
    }
}

5.) Showing Interstitial Ads

5.1) Call Interstitial.loadAd() with your adspaceId and eventListener in order to start Ad loading:

Interstitial.loadAd(adspaceId, eventListener);

5.2) Passed EventListener will be used to deliver events describing the advertisement lifecycle:

public interface EventListener {
 
    /**
     * This method will be invoked when an advertisement is successfully received.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdLoaded(@NonNull InterstitialAd interstitialAd);
 
    /**
     * This method will be invoked when an advertisement request is failed.
     * <p>
     * It is invoked on main thread only.
     *
     * @param interstitialRequestError {@link InterstitialRequestError} the error.
     */
    void onAdFailedToLoad(@NonNull InterstitialRequestError interstitialRequestError);
 
    /**
     * This method will be invoked when an advertisement failed during loading or showing.
     * <p>
     * It is invoked on main thread only.
     *
     * @param interstitialError {@link InterstitialError} the error.
     */
    void onAdError(@NonNull InterstitialAd interstitialAd, @NonNull InterstitialError interstitialError);
 
    /**
     * This method will be invoked when a fullscreen interstitial ad is opened.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdOpened(@NonNull InterstitialAd interstitialAd);
 
    /**
     * This method will be invoked when a fullscreen interstitial ad is closed.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdClosed(@NonNull InterstitialAd interstitialAd);
 
    /**
     * This method will be invoked when user clicked on an ad.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdClicked(@NonNull InterstitialAd interstitialAd);
 
    /**
     * This method will be invoked when an impression occurred.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdImpression(@NonNull InterstitialAd interstitialAd);
 
    /**
     * This method will be invoked on when an advertisement's TTL(time to live) is expired.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     *
     * @param interstitialAd {@link InterstitialAd} advertisement object View that received onAdTtlExpired event
     */
    void onAdTTLExpired(@NonNull InterstitialAd interstitialAd);
}

5.3) Optionally, you can change the background color for an InterstitialAd (default is black):

interstitialAd.setBackgroundColor(0xff123456);

5.4) Call showAd(activity) on a received InterstitialAd object:

new EventListener() {
    @Override
    public void onAdLoaded(@NonNull InterstitialAd interstitialAd) {
        interstitialAd.showAd(activity);
    }
    ...
};

6.) Showing Rewarded Interstitial Ads

6.1) Call RewardedInterstitial.loadAd() with adspaceId and EventListener in order to start Rewarded Interstitial Ad loading.

RewardedInterstitial.loadAd(adspaceId, eventListener);

6.2) As for Interstitial, EventListener will be used to deliver events describing the advertisement lifecycle:

/**
 * A listener to provide with {@link RewardedInterstitial#loadAd} request
 * <p>
 * Events are always delivered on main thread.
 */
public interface EventListener {
 
    /**
     * This method will be invoked when an advertisement is successfully received.
     * <p>
     * It is invoked on main thread only.
     */
    void onAdLoaded(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
 
    /**
     * This method will be invoked when an advertisement request is failed.
     * <p>
     * It is invoked on main thread only.
     *
     * @param rewardedRequestError {@link RewardedRequestError} failed request data object that contains next
     *                         	ad request parameters: publisherId, adspaceId
     *                         	and rewardedAdError {@link RewardedError}
     */
    void onAdFailedToLoad(@NonNull RewardedRequestError rewardedRequestError);
 
    /**
     * This method will be invoked when an advertisement failed during showing.
     * <p>
     * It is invoked on main thread only.
     *
     * @param rewardedInterstitialAd {@link RewardedInterstitialAd} advertisement object that received onClose event
     * @param rewardedError      	{@link RewardedError}
     */
    void onAdError(@NonNull RewardedInterstitialAd rewardedInterstitialAd, @NonNull RewardedError rewardedError);
 
    /**
     * This method will be invoked when an advertisement is closed by user.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     * {@link RewardedInterstitialAd} advertisement object that received onClose event
     */
    void onAdClosed(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
 
    /**
     * This method will be invoked on when an advertisement is clicked by user.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     * {@link RewardedInterstitialAd} advertisement object that received onClick event
     */
    void onAdClicked(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
 
    /**
     * This method will be invoked when an advertisement's playback is started.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     * {@link RewardedInterstitialAd} advertisement object that received onStart event
     */
    void onAdStarted(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
 
    /**
     * This method will be invoked when an advertisement's playback is completed successfully.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     * {@link RewardedInterstitialAd} advertisement object that received onRewarded event
     */
    void onAdReward(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
 
    /**
     * This method will be invoked when an advertisement's TTL(time to live) is expired.
     * <p>
     * Will be invoked on main thread only.
     * <p>
     * {@link RewardedInterstitialAd} advertisement object that received onTtlExpired event
     */
    void onAdTTLExpired(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
}

6.3) When the ad is loaded and available for presentation call show() on a received RewardedInterstitialAd object:

EventListener eventListener = new EventListener() {
    @Override
    public void onAdLoaded(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {
        rewardedInterstitialAd.show();
    }
    ...
}

Modified: October 11, 2019 at 2:13 pm