Banner & MREC Ads

Banners from some networks may have heights that exceed 50 points now, as adaptive banners are the default in the latest AppLovin MAX Unity Plugin versions. The height will never be more than 15% of the device’s current orientation height, and never less than 50 points. See Adaptive Banners below for details.

Loading a Banner or MREC

To load a banner, use code like the following with your ad unit ID and desired ad view position:

  • #if UNITY_IOS
    string bannerAdUnitId = "ios_ad_unit_ID"; // Retrieve the ID from your account
    #else // UNITY_ANDROID
    string bannerAdUnitId = "android_ad_unit_ID"; // Retrieve the ID from your account
    #endif
      
    public void InitializeBannerAds()
    {
      // Banners are automatically sized to 320×50 on phones and 728×90 on tablets
      // You may call the utility method MaxSdkUtils.isTablet() to help with view sizing adjustments
      MaxSdk.CreateBanner(bannerAdUnitId, MaxSdkBase.BannerPosition.BottomCenter);
    
      // Set background or background color for banners to be fully functional
      MaxSdk.SetBannerBackgroundColor(bannerAdUnitId, banner_background_color);
    
      MaxSdkCallbacks.Banner.OnAdLoadedEvent      += OnBannerAdLoadedEvent;
      MaxSdkCallbacks.Banner.OnAdLoadFailedEvent  += OnBannerAdLoadFailedEvent;
      MaxSdkCallbacks.Banner.OnAdClickedEvent     += OnBannerAdClickedEvent;
      MaxSdkCallbacks.Banner.OnAdRevenuePaidEvent += OnBannerAdRevenuePaidEvent;
      MaxSdkCallbacks.Banner.OnAdExpandedEvent    += OnBannerAdExpandedEvent;
      MaxSdkCallbacks.Banner.OnAdCollapsedEvent   += OnBannerAdCollapsedEvent;
    }
    
    private void OnBannerAdLoadedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    private void OnBannerAdLoadFailedEvent(string adUnitId, MaxSdkBase.ErrorInfo errorInfo) {}
    
    private void OnBannerAdClickedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    private void OnBannerAdRevenuePaidEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    private void OnBannerAdExpandedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo)  {}
    
    private void OnBannerAdCollapsedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
  • #if UNITY_IOS
    string mrecAdUnitId = "ios_ad_unit_ID"; // Retrieve the ID from your account
    #else // UNITY_ANDROID
    string mrecAdUnitId = "android_ad_unit_ID"; // Retrieve the ID from your account
    #endif
    
    public void InitializeMRecAds()
    {
      // MRECs are sized to 300x250 on phones and tablets
      MaxSdk.CreateMRec(mrecAdUnitId, MaxSdkBase.AdViewPosition.Centered);
    
      MaxSdkCallbacks.MRec.OnAdLoadedEvent      += OnMRecAdLoadedEvent;
      MaxSdkCallbacks.MRec.OnAdLoadFailedEvent  += OnMRecAdLoadFailedEvent;
      MaxSdkCallbacks.MRec.OnAdClickedEvent     += OnMRecAdClickedEvent;
      MaxSdkCallbacks.MRec.OnAdRevenuePaidEvent += OnMRecAdRevenuePaidEvent;
      MaxSdkCallbacks.MRec.OnAdExpandedEvent    += OnMRecAdExpandedEvent;
      MaxSdkCallbacks.MRec.OnAdCollapsedEvent   += OnMRecAdCollapsedEvent;
    }
    
    public void OnMRecAdLoadedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    public void OnMRecAdLoadFailedEvent(string adUnitId, MaxSdkBase.ErrorInfo error) {}
    
    public void OnMRecAdClickedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    public void OnMRecAdRevenuePaidEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    public void OnMRecAdExpandedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}
    
    public void OnMRecAdCollapsedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo) {}

Set your banner background color to a #-prefixed hexadecimal RGB string, for example '#000000' (black) or '#fff200' (yellow).

The complete list of position options are:

  • TopLeft
  • TopCenter
  • TopRight
  • Centered
  • CenterLeft
  • CenterRight
  • BottomLeft
  • BottomCenter
  • BottomRight

You can also position an ad at a specific (x, y) coordinate on the screen by calling MaxSdk.CreateBanner(ad-unit-ID, x, y); or MaxSdk.CreateMRec(ad-unit-ID, x, y);. This sets the position of the top-left corner of the ad. The coordinate system represents the safe area bounds of the screen. Make sure to account for the width and height of the ad when you set these coordinates. The position (0, 0) is equivalent to TopLeft; the bottom-right corner of the safe area is (safeAreaWidth, safeAreaHeight). Note that Unity might have a different screen size or safe area size than Android or iOS. To convert between Unity’s screen size and the sizes used in Android or iOS, use code like the following:

var density = MaxSdkUtils.GetScreenDensity();
var dp = pixels / density;

Showing a Banner or MREC

To show a banner or MREC, make the following call:

  • MaxSdk.ShowBanner(ad_unit_ID);
  • MaxSdk.ShowMRec(ad_unit_ID);

Hiding a Banner or MREC

To hide a banner or MREC, make the following call:

  • MaxSdk.HideBanner(ad_unit_ID);
  • MaxSdk.HideMRec(ad_unit_ID);

Destroying Banners or MRECs

After you are no longer using the ad instance (for example, if the user purchased ad removal), call the DestroyBanner() or DestroyMRec() method to free resources. Do not call DestroyBanner() or DestroyMRec() if you use multiple ad instances with the same Ad Unit ID.

  • MaxSdk.DestroyBanner(ad_unit_ID);
  • MaxSdk.DestroyMRec(ad_unit_ID);

Getting Banner Position

To get the banner’s position and size, call GetBannerLayout(). This uses the same Unity coordinate system as explained in Loading a Banner.

Rect bannerLayout = MaxSdk.GetBannerLayout(ad_unit_ID);

Setting Banner Width

To manually set the banner’s width, call SetBannerWidth(). Be sure to set the banner width to a size larger than the minimum value (320 on phones, 728 on tablets). Banners under this width may not be considered viewable by the advertiser, and this will affect your revenue:

MaxSdk.SetBannerWidth(ad_unit_ID, width);

If you set the banner width below the minimum, you will see an error message in your logs. For example: [AppLovinSdk] [MAUnityAdManager] The provided width: 300.000000 is smaller than the minimum required width: 320.000000 for ad format: [MAAdFormat: BANNER]. Please set the width higher than the minimum required.

Adaptive Banners

The latest MAX Unity plugin (versions 4.3.1 and above) enables adaptive banners automatically on Google bidding and Google AdMob, and Google Ad Manager. This helps you to increase revenue. AppLovin recommends that you run tests to ensure that adaptive banners create the best experience for your users. Follow the instructions below if you want to disable adaptive banners.

Google recommends that developers include a 50px padding between the banner placement and the app content to reduce the likelihood of accidental clicks. Refer to Google’s “About Confirmed Click” policy for more information and best practices.

Adaptive banners are responsive banners with heights that derive from the device type and width of the banner. To create an adaptive banner, refer to the following instructions based on your AppLovin MAX Unity Plugin version:

AppLovin MAX Unity Plugin < 3.2.2
Adaptive banners are not available for versions of the MAX Unity Plugin before 3.2.2.
AppLovin MAX Unity Plugin 3.2.2–4.3.0
To create an adaptive banner, set the banner extra parameter adaptive_banner to true when you create the banner, as in the following example:
#if UNITY_IOS
string bannerAdUnitId = "ios_ad_unit_ID"; // Retrieve the ID from your account
#else // UNITY_ANDROID
string bannerAdUnitId = "android_ad_unit_ID"; // Retrieve the ID from your account
#endif
public void InitializeBannerAds() { // Adaptive banners are sized based on device width for positions that stretch full width (TopCenter and BottomCenter). // You may use the utility method `MaxSdkUtils.GetAdaptiveBannerHeight()` to help with view sizing adjustments MaxSdk.CreateBanner(bannerAdUnitId, MaxSdkBase.BannerPosition.BottomCenter); MaxSdk.SetBannerExtraParameter(bannerAdUnitId, "adaptive_banner", "true"); // Set background or background color for banners to be fully functional MaxSdk.SetBannerBackgroundColor(bannerAdUnitId, background_color); }
Call MaxSdkUtils.GetAdaptiveBannerHeight() to get the banner height, and then adjust your content accordingly.
AppLovin MAX Unity Plugin 4.3.1+
Banners from ad networks that support adaptive banners are adaptive by default. If you want to disable adaptive banners, set the banner extra parameter adaptive_banner to false when you create the banner, as in the following example:
#if UNITY_IOS
string bannerAdUnitId = "ios_ad_unit_ID"; // Retrieve the ID from your account
#else // UNITY_ANDROID
string bannerAdUnitId = "android_ad_unit_ID"; // Retrieve the ID from your account
#endif

public void InitializeBannerAds()
{
  MaxSdk.CreateBanner(bannerAdUnitId, MaxSdkBase.BannerPosition.BottomCenter);
  MaxSdk.SetBannerExtraParameter(bannerAdUnitId, "adaptive_banner", "false");

  // Set background or background color for banners to be fully functional
  MaxSdk.SetBannerBackgroundColor(bannerAdUnitId, background_color);
}
Call MaxSdkUtils.GetAdaptiveBannerHeight() to get the banner height, and then adjust your content accordingly.

TopCenter and BottomCenter banner positions span the full width of the screen. For other positions, the width is 320 (on phones) or 728 (on tablets). So, the MaxSdkUtils.GetAdaptiveBannerHeight(width) function also takes a width parameter and returns the appropriate adaptive height for the given banner width.

Stopping and Starting Auto-Refresh

There may be cases when you would like to stop auto-refresh, for instance, if you want to manually refresh banner ads. To stop auto-refresh for a banner ad, use the following code:

  • MaxSdk.StopBannerAutoRefresh(ad_unit_ID);
  • MaxSdk.StopMRecAutoRefresh(ad_unit_ID);

Start auto-refresh for a banner ad with the following code:

  • MaxSdk.StartBannerAutoRefresh(ad_unit_ID);
  • MaxSdk.StartMRecAutoRefresh(ad_unit_ID);

Manually refresh the contents with the following code. Note that you must stop auto-refresh before you call LoadBanner() or LoadMRec().

  • MaxSdk.LoadBanner(ad_unit_ID);
  • MaxSdk.LoadMRec(ad_unit_ID);