Banner integration for Unity

Integrate banner ads in Unity by initializing the SDK, creating banner ad objects post-initialization, and setting appropriate ad sizes and positions.

Read time 8 minutes

Banners are a rectangular, system-initiated ads that can be either static or animated, and are served in a designated area around your live app content. 

Prerequisites
Prerequisites

  • Ensure that you have correctly integrated the ironSource SDK into your application. Integration is outlined here.
  • Ensure that you initialize the SDK using LevelPlay Initialization API.
  • Find the AdUnitID in LevelPlay dashboard.

Create Banner Ad Object, Set Size and Position
Create Banner Ad Object, Set Size and Position

The creation of the banner ad object should be done after receiving OnInitSuccess callback.

// Create the banner object and set the ad unit id 
bannerAd = new LevelPlayBannerAd(bannerAdUnitId);
LevelPlayAdSizeDescriptionDimensions in dp (Width X Height)
BANNERStandard banner320 x 50
LARGELarge banner320 x 90
MEDIUM_RECTANGLEMedium Rectangular (MREC)300 x 250
AdaptiveAutomatically renders ads to adjust size and orientation for mobile & tabletsDevice width X recommended height

To create the ad size follow one of these options: 

Adaptive ad size that adjusts to the screen width (recommended): This option returns BANNER or LEADERBOARD according to the device type. Networks that support the adaptive feature (Google, Yandex) will return a height based on their optimization logic.

  • For LevelPlay SDK 8.8.0+ you can determine the width and height of the adaptive banner that will be returned, before loading the banner, using the following:
LevelPlayAdSize adSize = LevelPlayAdSize.CreateAdaptiveAdSize();
int width = adSize.Width;
int height = adSize.Height;
  • For LevelPlay SDK below 8.8.0:
LevelPlayAdSize adSize = LevelPlayAdSize.CreateAdaptiveAdSize();

Specific banner size: This option allows you to set a specific banner size: BANNER, LARGE, MEDIUM_RECTANGLE.

LevelPlayAdSize adSize = LevelPlayAdSize.BANNER;

The default position for displaying a Banner on the screen is BottomCenter. Below is the complete list of all supported positions:

  • TopLeft
  • TopCenter
  • TopRight
  • CenterLeft
  • Center
  • CenterRight
  • BottomLeft
  • BottomCenter
  • BottomRight
bannerAd = new LevelPlayBannerAd(adUnitId, LevelPlayAdSize.BANNER
, LevelPlayBannerPosition.TopLeft);

You can also position a Banner at a specific (x, y) coordinate on the screen by creating a LevelPlayBannerPosition object, with x and y values defined in dp.

LevelPlayBannerPosition position = New LevelPlayBannerPosition(new Vector2(x, y));
bannerAd = new LevelPlayBannerAd(adUnitId, adSize, position, placementName, displayOnLoad, respectSafeArea);

Placements
Placements

We support placements in banners for reporting only. They should be set before the LoadAd to affect all reloaded ads.

// Set the placement name
LevelPlayBannerAd bannerAd = new LevelPlayBannerAd("bannerAdUnitId", LevelPlayAdSize.BANNER, placementName:"placementName");

Implement the Banner Events
Implement the Banner Events

Listen to the LevelPlayBannerAd events in your code. The SDK will notify all possible events listed below.

  • It is recommended to set the listener before loading the banner ad.
  • Each banner ad should have its own listener implementation.
  • Callbacks run on the main thread.
// Register to the events 
bannerAd.OnAdLoaded += BannerOnAdLoadedEvent;
bannerAd.OnAdLoadFailed += BannerOnAdLoadFailedEvent;
bannerAd.OnAdDisplayed += BannerOnAdDisplayedEvent;
bannerAd.OnAdDisplayFailed += BannerOnAdDisplayFailedEvent;
bannerAd.OnAdClicked += BannerOnAdClickedEvent;
bannerAd.OnAdCollapsed += BannerOnAdCollapsedEvent;
bannerAd.OnAdLeftApplication += BannerOnAdLeftApplicationEvent;
bannerAd.OnAdExpanded += BannerOnAdExpandedEvent;

// Implement the events
void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdLoadFailedEvent(LevelPlayAdError ironSourceError) {}
void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdDisplayFailedEvent(LevelPlayAdDisplayInfoError adInfoError) {}
void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}
void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}

LevelPlay Ad Info
LevelPlay Ad Info

The LevelPlayAdInfo parameter includes information about the loaded ad.

Load Banner Ad
Load Banner Ad

To load a banner ad use LoadAd.

bannerAd.LoadAd();

Pause and Resume Banner Refresh
Pause and Resume Banner Refresh

You can pause banner refresh in your code if the refresh value was defined in the platform. Use the following methods to stop the automatic refresh of the banner ad, or re-enable it after pausing. 

  • pauseAutoRefresh - pauses auto-refresh of the banner ad.
  • resumeAutoRefresh - resumes auto-refresh of the banner ad after it has been paused.
// Pause refresh
bannerAd.PauseAutoRefresh();
// Resume refresh
bannerAd.ResumeAutoRefresh();

Hide and Show Banners
Hide and Show Banners

As part of the banner constructor, you can load your banner in the background and share it on screen only when relevant. To control the ad visibility after loading, you can use these APIs: 

  • ShowAd – banner will be displayed on screen 
  • HideAd – banner will be hidden
// Show ad 
bannerAd.ShowAd(); 
// Hide ad 
bannerAd.HideAd();

Display Cutouts (Android Only)
Display Cutouts (Android Only)

A display cutout in Android devices is a designated area reserved for essential components such as cameras, sensors, or speakers, commonly used in smartphones and devices with edge-to-edge displays. The cutout can potentially limit the game view, affecting the placement of banners on the screen. To avoid overlap of the banner ad and the displayed cutouts, create LevelPlayBannerAd and set the respectSafeArea to true.

You can learn more about Google’s solution for display cutout in the Android developer documentation.

To support Android cutouts, create a LevelPlayBannerAd object with the respectSafeArea value as true (default value is false).

bannerAd = new LevelPlayBannerAd(bannerAdUnitId, respectSafeArea:true);

Destroy Banner Ad
Destroy Banner Ad

To destroy a banner, call the Destroy method.

A destroyed banner can no longer be shown again. To display more ads, create a new LevelPlayBannerAd object. 

bannerAd.DestroyAd();

Full Implementation Example of Banner Ads
Full Implementation Example of Banner Ads

Here is an example for creating and loading a banner ad using adaptive banner size.

public class BannerAdSample {
    private LevelPlayBannerAd bannerAd;
    void CreateBannerAd() {
        //Create banner instance
        bannerAd = new LevelPlayBannerAd("bannerAdUnitId");
        //Subscribe BannerAd events
        bannerAd.OnAdLoaded += BannerOnAdLoadedEvent;
        bannerAd.OnAdLoadFailed += BannerOnAdLoadFailedEvent;
        bannerAd.OnAdDisplayed += BannerOnAdDisplayedEvent;
        bannerAd.OnAdDisplayFailed += BannerOnAdDisplayFailedEvent;
        bannerAd.OnAdClicked += BannerOnAdClickedEvent;
        bannerAd.OnAdCollapsed += BannerOnAdCollapsedEvent;
        bannerAd.OnAdLeftApplication += BannerOnAdLeftApplicationEvent;
        bannerAd.OnAdExpanded += BannerOnAdExpandedEvent;
    }
    void LoadBannerAd() {
        //Load the banner ad 
        bannerAd.LoadAd();
    }
    void ShowBannerAd() {
        //Show the banner ad, call this method only if you turned off the auto show when you created this banner instance.
        bannerAd.ShowAd();
    }
    void HideBannerAd() {
        //Hide banner
        bannerAd.HideAd();
    }
    void DestroyBannerAd() {
        //Destroy banner
        bannerAd.DestroyAd();
    }
    //Implement BannAd Events
    void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}
    void BannerOnAdLoadFailedEvent(LevelPlayAdError ironSourceError) {}
    void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}
    void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}
    void BannerOnAdDisplayFailedEvent(LevelPlayAdDisplayInfoError adInfoError) {}
    void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}
    void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}
    void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}
}

LevelPlay Mediation Demo App
LevelPlay Mediation Demo App

The Integration Demo application demonstrates how to integrate banner Ad Unit APIs in your app.

Download Unity Demo Application

Verify your integration with our Integration Test Suite.

Next steps
Next steps

Follow our integration guides to integrate additional Banner Ad networks or configure additional ad formats: