Early Access - Get Started with Banner Ads - Android or Amazon SDK v. 6.5.0

Contents

Banner Ads

Vungle supports Banner video ads starting with Android SDK version 6.5.0. The container size to render banner ads can be 320x50, 300x50 or 728x90 (for tablets).
Banner ads can be set anywhere on the screen and the user can continue using the app while the ad is being played.

This guide shows banner specific API and instruction on how to use them. Please refer to our main Android SDK integration documentation for the SDK requirements and additional information.

Banner Size

Dimensions

AdConfig.AdSize.BANNER

320x50

AdConfig.AdSize.BANNER_SHORT

300x50

AdConfig.AdSize.BANNER_LEADERBOARD

728x90 (for tablets)

Initialize Vungle SDK

Vungle.init("VUNGLE_APP_ID", getApplicationContext(), new InitCallback() {
    @Override
    public void onSuccess() { }

    @Override
    public void onError(VungleException exception) { }
});

Loading a Banner Ad

Loading a banner ad works different than other ad formats. There is specific Banners API that you use to load, play and check for ad availability. You would need to specify size of the banner that you want to load and SDK will automatically refresh it with the time interval that you configured on the dashboard. The placement must be also configured to support banner feed so please contact your Vungle account manager to enable banner ad for a placement.

Banners.loadBanner("BANNER_ID", AdConfig.AdSize.BANNER, new LoadAdCallback() {
   @Override
   public void onAdLoad(String id) { }

   @Override
   public void onError(String id, VungleException exception) { }
});

Displaying a Banner Ad

Since the view size is fixed, the container which is used to display Banner ads must be specified to be one of the supported sizes 320x50, 300x50 or 728x90 (for tablets), and the view can be placed anywhere on the screen. This container is a LayOut it must have a size equal to or greater than the banner size being used. You can place said LayOut anywhere on the screen. Then you will pass the size of banner you are using Banners API.

Pass this object when calling Banners.loadBanner to specify the size you displaying and use Banners.getBanner to get the Banners ad object. finally call the addView method to associate the container with the Banner ad.

private RelativeLayout bannerContainer = findViewById(...);
// Check for banner ad availability and get VungleBanner
if (Banners.canPlayAd("BANNER_ID", AdConfig.AdSize.BANNER)) {
  VungleBanner vungleBanner = Banners.getBanner("BANNER_ID", AdConfig.AdSize.BANNER, new PlayAdCallback() {
    @Override
    public void onAdStart(String id) { }

    @Override
    public void onAdEnd(String id, boolean completed, boolean isCTAClicked) { }

    @Override
    public void onError(String id, VungleException exception) { }
  });
// Add VungleBanner to a view container bannerContainer.addView(vungleBanner); }

Closing a Banner Ad

Because the banner ad view has been added to your container view, it must also be removed in case the ad view disappears from the screen, the activity or fragment is destroyed, or the parent view container is recycled or destroyed. Without closing the ad, attempting to play another banner ad will cause unexpected behaviour in your app.

vungleBanner.destroyAd();

Advanced Banner Configuration

For most cases, above integration will be sufficient and VungleBanner will be managed. However, if VungleBanner view is inside a ListView or RecyclerView, the managed VungleBanner will not work correctly. The moment the user scrolls the ad offscreen and scrolls back, the ad will be finished and no longer there. For such case, we have advanced API to fine control the VungleBanner.

VungleBanner Class API

These APIs give developers fine control over how to treat the VungleBanner across various lifecycle events in the developer application. In a majority of use cases, developers will not need to invoke these methods. Simply adding a VungleBanner into a parent view is enough. For special cases where a view will be recycled (i.e. RecyclerView, ListView, etc…) or where we need to handle visibility manually (in certain older android devices, webview will not automatically pause when offscreen).

Name Function Notes
disableLifeCycleManagement(boolean disabled) Invoke to disable automatic management of banner Must be set to true for renderAd and setAdVisibility to work
renderAd* Renders the ad if it is not visible It can also load new ad
setAdVisibility* Notifies the view container when banner is visible screen Pause and resume banner
destroyAd Call to destroy when no longer needed, the view container is no longer usable Frees banner resources 
finishAd* Stops current ad, send report and allow another ad to be loaded after (only applicable for certain integration into RecyclerView or ListView) Frees banner resources 

*Must invoke vungleBannerAd.disableLifeCycleManagement(true) before using this API

Understanding Managed vs Un-managed

When you get a VungleBanner by default it is a managed VungleBanner view. This means that the moment you add this view into a parent container, Vungle will take care of when to show an ad, and when to destroy an ad to send the report. Visibility events are also take care of and developers do not have to tell us when a banner view object is on screen or not. In cases where a developer will not have a VungleBanner view inside a recyclable view or ViewHolder pattern this is the preferred way to use VungleBanner.

In cases in which a VungleBanner view is inside a ListView or RecyclerView, the managed VungleBanner will not work correctly. The moment the user scrolls the ad offscreen and scrolls back, the ad will be finished and no longer there.

Banner_Flow_Chart-2.jpg

We added a disableLifeCycleManagement(boolean disable) to allow developers to be able to handle the lifecycle of the VungleBanner manually in these cases.

When you set: (before you add the VungleBanner to a view or bind the view)

vungleBannerAd.disableLifeCycleManagement(boolean disabled)

You will have to call:

  • VungleBanner.renderAd() when the view is bound
  • VungleBanner.setAdVisibility(true|false) when the ad is recycled or no longer visible
  • VungleBanner.destroyAd() when the VungleBanner object is no longer needed

Best Practices

  1. Before attempting to show a banner ad always try to check if the parent activity is finishing before binding the VungleBanner to a view.
    if (activity != null && activity.isFinishing()) {
      return;
    }
  2. Do not change the LayoutParams of VungleBanner. This could negativity impact how the banner is displayed and result in your ad not being visible.
  3. Do not put the ad in a container size smaller than the requested ad. If you’re requesting a regular banner (320x50) ensure that your parent container is at least 320dp x 50dp.

Sample Code for Advanced Integration

VungleBannerAdAdapter.java

 

Was this article helpful?

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!