Banner Ads - cleveradssolutions/CAS-Android GitHub Wiki

:zap: Before you start
Make sure you have correctly Initialize CAS.

Banner ads occupy a spot within an app's layout, either at the top or bottom of the device screen. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.

This guide shows you how to integrate banner ads from CAS into an Android app. Banner ads are displayed in CASBannerView objects from module CleverAdsSolutions, so the first step toward integrating banner ads is to include a CASBannerView in your view hierarchy. This is typically done either with the layout or programmatically.

Add to the layout

The first step toward displaying a banner is to place CASBannerView in the layout for the Activity or Fragment in which you'd like to display it. The easiest way to do this is to add one to the corresponding XML layout file. Here's an example that shows an activity's CASBannerView:

# main_activity.xml
...
  <com.cleversolutions.ads.android.CASBannerView 
      xmlns:ads="http://schemas.android.com/apk/res-auto"
      android:id="@+id/bannerView"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:gravity="center"
      ads:bannerSize="Standard320x50"/>
...

Note the following required attributes:
ads:bannerSize - Set the ad size you'd like to use.
See the banner size section below for details.

On create activity you should set Mediation manager to banner view:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  CASBannerView bannerView = findViewById<CASBannerView>(R.id.bannerView);
  bannerView.setManager(manager);
}

Create programmatically

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  CASBannerView bannerView = new CASBannerView(this, manager);

  // Add bannerView to your view hierarchy.
  addContentView(bannerView, new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT));
}

Ad Size

Size in dp (WxH) Description Availability AdSize
320x50 Standard Banner Phones and Tablets BANNER
728x90 IAB Leaderboard Tablets LEADERBOARD
300x250 IAB Medium Rectangle Phones and Tablets MEDIUM_RECTANGLE
Adaptive Adaptive banner Phones and Tablets getAdaptiveBanner()
320x50 or 728x90 Smart Banner Phones and Tablets getSmartBanner()

❕Typically, Smart Banners on phones have a BANNER size. Or on tablets a LEADERBOARD size.

Change the banner ad size using the following method:

AdSize adSize = AdSize.BANNER;
bannerView.setSize(adSize);

Adaptive Banners

Adaptive banners are the next generation of responsive ads, maximizing performance by optimizing ad size for each device.
To pick the best ad size, adaptive banners use fixed aspect ratios instead of fixed heights. This results in banner ads that occupy a more consistent portion of the screen across devices and provide opportunities for improved performance.

  • The height of adaptive banners cannot be less than 50 dp and more than 250 dp.
  • The width of adaptive banners cannot be less than 300 dp.
  • The adaptive banners use fixed aspect ratios instead of fixed heights.

Use the appropriate static methods on the ad size class, such as AdSize.getAdaptiveBanner(context, maxWidthDPI) to get an adaptive AdSize object.

// Get adaptive size with width parameter:
adSize = AdSize.getAdaptiveBanner(context, maxWidthDPI);
// Get adaptive size in full screen width:
adSize = AdSize.getAdaptiveBannerInScreen(context);

[!WARNING]
After changing the screen orientation, you should get the new adaptive ad size using the same method. And pass the size to the view. This will destroy the current ad content and load a new one.

Ad events

To further customize the behavior of your ad, you can hook onto a number of events in the ad's lifecycle: loading, presenting, clicking, and so on. You can listen for these events through the AdViewListener interface. To use an AdViewListener with Banner View, call the setAdListener() method:

bannerView.setAdListener(new AdViewListener() {
    @Override
    public void onAdViewLoaded(@NonNull CASBannerView view) {
      // Invokes this callback when ad loaded and ready to present.
    }

    @Override
    public void onAdViewFailed(@NonNull CASBannerView view, @NonNull AdError error) {
      // Invokes this callback when an error occurred with the ad.
      // To see the error code, see `AdError.getCode()`.
      // To see a description of the error, see `AdError.getMessage()`.
    }

    @Override
    public void onAdViewPresented(@NonNull CASBannerView view, @NonNull AdStatusHandler info) {
      // Invokes this callback when the ad did present for a user with info about the impression.
    }

    @Override
    public void onAdViewClicked(@NonNull CASBannerView view) {
      // Invokes this callback when a user clicks the ad.
    }
});

[!NOTE]
Read more about event onAdViewPresented with Impression level data.

Autoload Banner Ad

A isAutoloadEnabled() value that determines whether autoloading of ads in the receiver is enabled.
If enabled, you do not need to call the loadNextAd() method from next section to load ads.
Change the banner autoload ad using the following method:

bannerView.setAutoloadEnabled(true);

By default disabled if global state AdsSettings.loadingMode is LoadingManagerMode.Manual. And changes will override global state of AdsSettings.loadingMode for specific Banner View.

Load Banner Ad

You can use load regardless of the isAutoloadEnabled() value for interrupt ad impression and load next ad.

bannerView.loadNextAd();

[!WARNING]
Calling the loadNextAd() method if isAutoloadEnabled() is active will cause the current ad to be lost and a new ad to start loading.

Banner refresh rate

An ad unit’s automatic refresh rate determines how often a new ad request is generated for that ad unit.
We recommended using refresh rate 30 seconds. However, you can choose any value you want longer than 10 seconds.

Change the banner automatic refresh rate using the following method:

bannerView.setRefreshInterval(interval);
// OR disable auto refresh ads
bannerView.disableAdRefresh();

[!NOTE]

  • Ad requests should not be made when the device screen is turned off.
  • The isAutoloadEnabled() has no effect on refreshing the banner ad.

Check Ad Availability

You can ask for the ad availability directly by calling the following function:

boolean bannerLoaded = bannerView.isAdReady();

Banner Ad visibility

The banner is a normal view so you can feel free to change the visibility with the following method:

bannerView.setVisibility(View.GONE);
// And
bannerView.setVisibility(View.VISIBLE);

Free Ad memory

If you no longer need the bannerView, please call Destroy to free memory.

@Override
protected void onDestroy() {
  super.onDestroy();
  bannerView.destroy();
}

Hardware acceleration for video ads

In order for video ads to show successfully in your banner ad views, hardware acceleration must be enabled.

Hardware acceleration is enabled by default, but some apps may choose to disable it. If this applies to your app, we recommend enabling hardware acceleration for Activity classes that use ads.

If your app does not behave properly with hardware acceleration turned on globally, you can control it for individual activities as well. To enable or disable hardware acceleration, you can use the android:hardwareAccelerated attribute for the <application> and <activity> elements in your AndroidManifest.xml. The following example enables hardware acceleration for the entire app but disables it for one activity:

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

See the HW acceleration guide for more information about options for controlling hardware acceleration. Note that individual ad views cannot be enabled for hardware acceleration if the Activity is disabled, so the Activity itself must have hardware acceleration enabled.

🔗 Done! What’s Next?