Banner

Overview

Banner ads are loaded and displayed by SASBannerView instances.

To load and display a banner ad, you will need:

• A fully configured Smart Display SDK.
• An instance of SASAdPlacement that will be used to perform ad calls to the delivery engine.
• An instance of SASBannerView that will load and show the banner ad.
• An object implementing the SASBannerView.BannerListener listener interface to monitor banner ad lifecycle events.

The next sections describe in details how to create and load a banner ad.

You can also refer to the samples if you want to copy/paste the whole integration.

Configuring the SDK

The Smart Display SDK needs to be configured with your own site ID and base URL before making any ad calls. You will have to call the method configure() of the SASConfiguration shared instance to do so.

This method must be called at least once, as soon as possible.
Ideally call it in the onCreate() method of your Application class. For instance:

public class MyApplication extends MultiDexApplication {
  @Override
  public void onCreate() {
    super.onCreate();

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456);
  }

class MyApplication : MultiDexApplication() {
  @Override
  public void onCreate() {
    super.onCreate()

    // 123456 is used as an example, be sure to use your own siteID
    SASConfiguration.getSharedInstance().configure(this, 123456)
  }

Any subsequent valid call to the configure() method will update the current configuration with the newly supplied parameters.

Creating a placement

You will need an ad placement to perform an ad call. A placement identifies a part of your inventory where you want to display ads.

Creating an ad placement is done by instantiating a SASAdPlacement object using mandatory parameters site ID, page ID, format ID and an optional keyword targeting String that and can be null (more info in the API documentation).

  SASAdPlacement adPlacement = new SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING);
  

  val adPlacement = SASAdPlacement(SOME_SITE_ID, SOME_PAGE_ID, SOME_FORMAT_ID, SOME_KEYWORD_TARGETING)
  

Note that for testing purposes, it is possible to instantiate a generic ad placement that will always deliver an ad from a particular type. This is done by using one of the constants of the SASAdPlacement class.

Creating a banner view

A banner ad is displayed by an instance of the SASBannerView class.
Since this class is a subclass of the Android View class, there are two ways of instantiating it :

• In an XML layout file where your banner should be displayed (most straightforward):

  
          <com.smartadserver.android.library.ui.SASBannerView
          android:id="@+id/banner"
          android:layout_width="match_parent"
          android:layout_height="50dp"
          android:visibility="visible" />
            
          

  You then assign to a variable the SASBannerView instance automatically instantiated when inflating the layout file this way:

  
          SASBannerView mBannerView = this.findViewById(R.id.banner);
          

  
            // nothing to do, use the view id you defined in the XML directly into your activity.
          

• By code directly:

  
          SASBannerView mBannerView = new SASBannerView(context);
          

  
          val bannerView = SASBannerView(context)
          

  Note that when instantiating a SASBannerView by code, it does not belong to any View hierarchy, it is up to you to add it to your view hierarchy with appropriate Android LayoutParams as you would for any other Android View

Using a loader view

If you want to display an overlay view of your choice on the banner when an ad is currently being loaded, you can set a loader view on the banner using the setLoaderView(View loaderView) method.

Note that this loader view will be automatically added and removed as the ad starts and finishes loading.

Loading an ad

Once the banner view is properly instantiated, an ad can be loaded using the ad placement created earlier.

mBannerView.loadAd(adPlacement);

bannerView.loadAd(adPlacement)

The banner creative will be automatically displayed when loaded.

Listening to ad loading events

You can listen to ad loading events (as well as other banner view related events) by setting an object implementing the SASBannerView.BannerListener interface on the banner view.

bannerListener = new SASBannerView.BannerListener() {
  @Override
  public void onBannerAdLoaded(SASBannerView bannerView, SASAdElement adElement) {
    Log.i("Sample", "Banner loading completed");
  }

  @Override
  public void onBannerAdFailedToLoad(SASBannerView bannerView, Exception e) {
    Log.i("Sample", "Banner loading failed: " + e.getMessage());
  }

  @Override
  public void onBannerAdClicked(SASBannerView bannerView) {
    Log.i("Sample", "Banner was clicked");
  }

  @Override
  public void onBannerAdExpanded(SASBannerView bannerView) {
    Log.i("Sample", "Banner was expanded");
  }

  @Override
  public void onBannerAdCollapsed(SASBannerView bannerView) {
    Log.i("Sample", "Banner was collapsed");
  }

  @Override
  public void onBannerAdResized(SASBannerView bannerView) {
    Log.i("Sample", "Banner was resized");
  }

  @Override
  public void onBannerAdClosed(SASBannerView bannerView) {
    Log.i("Sample", "Banner was closed");
  }

  @Override
  public void onBannerAdVideoEvent(SASBannerView bannerView, int videoEvent) {
    Log.i("Sample", "Video event " + videoEvent + " was triggered on Banner");
  }
};

mBannerView.setBannerListener(bannerListener);

bannerView.bannerListener = object : SASBannerView.BannerListener {
  override fun onBannerAdLoaded(banner: SASBannerView?, adElement: SASAdElement?) {
    Log.i("Sample", "Banner loading completed")
  }

  override fun onBannerAdFailedToLoad(banner: SASBannerView?, e: Exception?) {
    Log.i("Sample", "Banner loading failed: $e")
  }

  override fun onBannerAdClicked(banner: SASBannerView?) {
    Log.i("Sample", "Banner was clicked")
  }

  override fun onBannerAdExpanded(banner: SASBannerView?) {
    Log.i("Sample", "Banner was expanded")
  }

  override fun onBannerAdCollapsed(banner: SASBannerView?) {
    Log.i("Sample", "Banner was collapsed")
  }

  override fun onBannerAdClosed(banner: SASBannerView?) {
    Log.i("Sample", "Banner was closed")
  }

  override fun onBannerAdResized(banner: SASBannerView?) {
    Log.i("Sample", "Banner was resized")
  }

  override fun onBannerAdVideoEvent(banner: SASBannerView?, event: Int) {
    Log.i("Sample", "Video event $event was triggered on banner")
  }
}

You can use the onBannerAdLoaded and onBannerAdFailedToLoad methods to show or hide the banner respectively, try to reload an in case of failure, and so on. You will find a list of all the available methods in the API documentation.

Handler mainLooperHandler = new Handler(Looper.getMainLooper());
mainLooperHandler.post(new Runnable() {
  @Override
  public void run() {
    // execute you UI sensitive code here
  }
});

  Handler(Looper.getMainLooper()).post {
  // execute you UI sensitive code here
}

How to adapt the banner size after loading

Although the SASBannerView instance takes care of resizing the creative to make it fit properly while preserving its ratio, you can go further and resize the SASBannerView's height to match the creative's width/height ratio, hence eliminating empty spaces around the creative.

This is often the case when your SASBannerView needs to deliver 300x50, 300x250 formats or even 16/9 video, etc�

Use the getOptimalHeight() method of your SASBannerView instance to retrieve the appropriate height for your banner. This method will compute the perfect height for your banner instance based on creative's width and height ratio. This method can take a width as parameter, which comes handy when you want your banner to fit all the width of screen for example.

Please also note that you can access the actual creative's width and height (in pixels) through the SASAdElement object displayed by the SASBannerView.

The best place to add the resizing code is in your onBannerAdLoaded listener:

public void onBannerAdLoaded(SASBannerView bannerView, SASAdElement adElement) {
  // UI sensitive code needs to be executed on UI thread
  mBannerView.executeOnUIThread(new Runnable() {
    @Override
    public void run() {
      // for example, adapt your banner's height to match creative's ratio
      // (mBannerView is the reference on the SASBannerView instance)
      mBannerView.getLayoutParams().height = mBannerView.getOptimalHeight();
      // apply layout change
      mBannerView.setLayoutParams(mBannerView.getLayoutParams()); 
    }
  });		
}

override fun onBannerAdLoaded(banner: SASBannerView?, adElement: SASAdElement?) {
  // UI sensitive code needs to be executed on UI thread
  bannerView.executeOnUIThread {
    // for example, adapt your banner's height to match creative's ratio
    // (bannerView is the reference on the SASBannerView instance)
    bannerView.layoutParams = bannerView.layoutParams.apply { 
      this.height = bannerView.optimalHeight 
    }
  }
}

How to adapt parallax banner settings for your app

The In-App Parallax is an inline ad which shows a piece of background during scroll interactions. It supports image, agency scripts and html5 (with no interaction).

This format is designed to be displayed inside a SASBannerView attached to Scrollview, this scrollview cannot be zoomable and the parallax effect doesn't apply when scrolling horizontally.

Here are the supported classes (as well as the extended ones):

• ListView
• RecyclerView
• ScrollView

By default the parallax animation will use the whole device screen to display the creative, but in some cases, the banner view will not be visible from the bottom to the top of the app, for example in app using:

• App bars
• TabLayouts
• Other custom UI views that could cover the banner view displayed in the scrollview

 
// To avoid having the parallax going below the actionBar, we have to set the parallax margin top, which is its top limit.
// To do so, first we get the action bar height
int actionBarHeight = 0;
// Calculate ActionBar height
TypedValue tv = new TypedValue();
if (getTheme().resolveAttribute(android.R.attr.actionBarSize, tv, true))
{
   actionBarHeight = TypedValue.complexToDimensionPixelSize(tv.data,getResources().getDisplayMetrics());
}
// Then we set its height as parallaxMarginTop. Note that you can do the same with the bottom margin by using the setParallaxMarginBottom() method.
mBannerView.setParallaxMarginTop(actionBarHeight);   

// To avoid having the parallax going below the actionBar, we have to set the parallax margin top, which is its top limit.
// To do so, first we get the action bar height
var actionBarHeight = 0
// Calculate ActionBar height
val tv = TypedValue()
if (requireActivity().theme.resolveAttribute(android.R.attr.actionBarSize, tv, true)) {
    actionBarHeight = TypedValue.complexToDimensionPixelSize(tv.data, resources.displayMetrics)
}

// Then we set its height as parallaxMarginTop. Note that you can do the same with the bottom margin by using the setParallaxMarginBottom() method.
bannerView.setParallaxMarginTop(actionBarHeight.toInt())

If you need to animate manually the parallax effect, you can set directly (and periodically) the parallax offset using this method: setParallaxOffset on your SASBannerView instance.

Disposing of a banner view

Once you are done using a banner view, typically when its hosting Activity is being destroyed, you should call the onDestroy method of the SASBannerView to release the resources it was using.

/**
* Overriden from Activity class
*/
@Override
protected void onDestroy() {
    mBannerView.onDestroy();
    super.onDestroy();
}

/**
* Overriden from Activity class
*/
override fun onDestroy() {
bannerView.onDestroy()
super.onDestroy()
}