Banner & MREC Ads

The following sections show you how to load and then show and hide a banner or MREC ad.

See also

“Why mobile banners ads persist in a video and playable world” from AppLovin’s Blog.

Loading a Banner or MREC

Note

If your integration requires displaying MREC ads in a content feed, AppLovin recommends this technique:

1. Create the minimal amount of instances possible.
2. Stop auto-refresh.
3. Manually refresh the contents by calling loadAd (re-use the MAAdView instances).

You can find an example implementation in the AppLovin demo app (Objective-C, Swift).

Banners

Objective-C

To load a banner, create a MAAdView object that corresponds to your ad unit and call its loadAd method. To show that ad, add the MAAdView object as a subview of your view hierarchy. Implement MAAdViewAdDelegate so that you are notified when your ad is ready. This also notifies you of other ad-related events.

#import "ExampleViewController.h"
#import <AppLovinSDK/AppLovinSDK.h>

@interface ExampleViewController()<MAAdViewAdDelegate>
@property (nonatomic, strong) MAAdView *adView;
@end

@implementation ExampleViewController

- (void)createBannerAd
{
  self.adView = [[MAAdView alloc] initWithAdUnitIdentifier: @"«ad-unit-ID»"];
  self.adView.delegate = self;

  // Banner height on iPhone and iPad is 50 and 90, respectively
  CGFloat height = (UIDevice.currentDevice.userInterfaceIdiom == UIUserInterfaceIdiomPad) ? 90 : 50;

  // Stretch to the width of the screen for banners to be fully functional
  CGFloat width = CGRectGetWidth(UIScreen.mainScreen.bounds);

  self.adView.frame = CGRectMake(x, y, width, height);

  // Set background or background color for banners to be fully functional
  self.adView.backgroundColor = «background-color»;

  [self.view addSubview: self.adView];

  // Load the ad
  [self.adView loadAd];
}

#pragma mark - MAAdDelegate Protocol

- (void)didLoadAd:(MAAd *)ad {}

- (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error {}

- (void)didClickAd:(MAAd *)ad {}

- (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error {}

#pragma mark - MAAdViewAdDelegate Protocol

- (void)didExpandAd:(MAAd *)ad {}

- (void)didCollapseAd:(MAAd *)ad {}

#pragma mark - Deprecated Callbacks

- (void)didDisplayAd:(MAAd *)ad { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
- (void)didHideAd:(MAAd *)ad { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }

@end

Swift

To load a banner, create a MAAdView object that corresponds to your ad unit and call its loadAd method. To show that ad, add the MAAdView object as a subview of your view hierarchy. Implement MAAdViewAdDelegate so that you are notified when your ad is ready. This also notifies you of other ad-related events.

class ExampleViewController: UIViewController, MAAdViewAdDelegate
{
  var adView: MAAdView!

  func createBannerAd()
  {
    adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»")
    adView.delegate = self

    // Banner height on iPhone and iPad is 50 and 90, respectively
    let height: CGFloat = (UIDevice.current.userInterfaceIdiom == .pad) ? 90 : 50

    // Stretch to the width of the screen for banners to be fully functional
    let width: CGFloat = UIScreen.main.bounds.width

    adView.frame = CGRect(x: x, y: y, width: width, height: height)

    // Set background or background color for banners to be fully functional
    adView.backgroundColor = «background-color»

    view.addSubview(adView)

    // Load the first ad
    adView.loadAd()
  }

  // MARK: MAAdDelegate Protocol

  func didLoad(_ ad: MAAd) {}

  func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) {}

  func didClick(_ ad: MAAd) {}

  func didFail(toDisplay ad: MAAd, withError error: MAError) {}

  // MARK: MAAdViewAdDelegate Protocol

  func didExpand(_ ad: MAAd) {}

  func didCollapse(_ ad: MAAd) {}

  // MARK: Deprecated Callbacks

  func didDisplay(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
  func didHide(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
}

SwiftUI

To load a banner, create a UIViewRepresentable object, a wrapper that lets you integrate MAAdView, a UIKit view type object, into your SwiftUI view hierarchy. Also provide a custom Coordinator class for the wrapper object that conforms to MAAdViewAdDelegate. This notifies you when your ad is ready, and notifies you of other ad-related events. Inside the wrapper’s makeUIView method, create a MAAdView object that corresponds to your ad unit. Call its loadAd method. To show that ad, add the UIViewRepresentable wrapper object inside your SwiftUI view hierarchy.

You can find implementation examples in the AppLovin-MAX_SDK_iOS Github repository.

import AppLovinSDK

struct ExampleSwiftUIWrapper: UIViewRepresentable
{
  func makeUIView(context: Context) -> MAAdView
  {
    let adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»")
    adView.delegate = context.coordinator

    // Set background or background color for banners to be fully functional
    adView.backgroundColor = «background-color»

    // Load the first Ad
    adView.loadAd()

    return adView
  }

  func updateUIView(_ uiView: MAAdView, context: Context) {}

  func makeCoordinator() -> Coordinator
  {
    Coordinator()
  }
}

extension ExampleSwiftUIWrapper
{
  class Coordinator: NSObject, MAAdViewAdDelegate
  {
    // MARK: MAAdDelegate Protocol

    func didLoad(_ ad: MAAd) {}

    func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) {}

    func didClick(_ ad: MAAd) {}

    func didFail(toDisplay ad: MAAd, withError error: MAError) {}

    // MARK: MAAdViewAdDelegate Protocol

    func didExpand(_ ad: MAAd) {}

    func didCollapse(_ ad: MAAd) {}

    // MARK: Deprecated Callbacks

    func didDisplay(_ ad: MAAd) { /* use this for impression tracking */ }
    func didHide(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
  }
}

// SwiftUI view to show ad
struct ExampleSwiftUIBannerAdView: View
{
  // Banner height on iPhone and iPad is 50 and 90, respectively
  let height: CGFloat = (UIDevice.current.userInterfaceIdiom == .pad) ? 90 : 50

  // Stretch to the width of the screen for banners to be fully functional
  let width: CGFloat = UIScreen.main.bounds.width

  var body: some View {
    ExampleSwiftUIWrapper()
      .frame(width: width, height: height)
  }
}

MRECs

Objective-C

To load an MREC ad, create a MAAdView object corresponding to your ad unit and call its loadAd method. To show the ad, add the MAAdView object as a subview of your view hierarchy. Implement MAAdViewAdDelegate so that you are notified when your ad is ready. This also notifes you of other ad-related events.

#import "ExampleViewController.h"
#import <AppLovinSDK/AppLovinSDK.h>

@interface ExampleViewController()<MAAdViewAdDelegate>
@property (nonatomic, strong) MAAdView *adView;
@end

@implementation ExampleViewController

- (void)createMRECAd
{
  self.adView = [[MAAdView alloc] initWithAdUnitIdentifier: @"«ad-unit-ID»" adFormat: MAAdFormat.mrec];
  self.adView.delegate = self;

  // MREC width and height are 300 and 250 respectively, on iPhone and iPad
  CGFloat width = 300;
  CGFloat height = 250;

  // Center the MREC
  CGFloat x = self.view.center.x - 150;

  self.adView.frame = CGRectMake(x, y, width, height);

  // Set background or background color for MREC ads to be fully functional
  self.adView.backgroundColor = «background-color»;

  [self.view addSubview: self.adView];

  // Load the ad
  [self.adView loadAd];
}

#pragma mark - MAAdDelegate Protocol

- (void)didLoadAd:(MAAd *)ad {}

- (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error {}

- (void)didClickAd:(MAAd *)ad {}

- (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error {}

#pragma mark - MAAdViewAdDelegate Protocol

- (void)didExpandAd:(MAAd *)ad {}

- (void)didCollapseAd:(MAAd *)ad {}

#pragma mark - Deprecated Callbacks

- (void)didDisplayAd:(MAAd *)ad { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
- (void)didHideAd:(MAAd *)ad { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }

@end

Swift

To load an MREC ad, create a MAAdView object corresponding to your ad unit and call its loadAd method. To show the ad, add the MAAdView object as a subview of your view hierarchy. Implement MAAdViewAdDelegate so that you are notified when your ad is ready. This also notifies you of other ad-related events.

class ExampleViewController: UIViewController, MAAdViewAdDelegate
{
  var adView: MAAdView!

  func createMRECAd()
  {
    adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»", adFormat: MAAdFormat.mrec)
    adView.delegate = self

    // MREC width and height are 300 and 250 respectively, on iPhone and iPad
    let height: CGFloat = 250
    let width: CGFloat = 300

    adView.frame = CGRect(x: x, y: y, width: width, height: height)

    // Center the MREC
    adView.center.x = view.center.x

    // Set background or background color for MREC ads to be fully functional
    adView.backgroundColor = «background-color»

    view.addSubview(adView)

    // Load the first ad
    adView.loadAd()
  }

  // MARK: MAAdDelegate Protocol

  func didLoad(_ ad: MAAd) {}

  func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) {}

  func didClick(_ ad: MAAd) {}

  func didFail(toDisplay ad: MAAd, withError error: MAError) {}

  // MARK: MAAdViewAdDelegate Protocol

  func didExpand(_ ad: MAAd) {}

  func didCollapse(_ ad: MAAd) {}

  // MARK: Deprecated Callbacks

  func didDisplay(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
  func didHide(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
}

SwiftUI

To load an MREC ad, first create a UIViewRepresentable object, a wrapper that lets you integrate MAAdView, a UIKit view type object, into your SwiftUI view hierarchy. Also provde a custom Coordinator class for the wrapper object that conforms to MAAdViewAdDelegate. This notifies you when your ad is ready, and notifies you of other ad-related events. Inside the wrapper’s makeUIView method, create a MAAdView object that corresponds to your ad unit and call its loadAd method. To show that ad, add the UIViewRepresentable wrapper object inside your SwiftUI view hierarchy.

You can find implementation examples in the AppLovin-MAX_SDK_iOS Github repository.

import AppLovinSDK

struct ExampleSwiftUIWrapper: UIViewRepresentable
{
  func makeUIView(context: Context) -> MAAdView
  {
    let adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»", adFormat: MAAdFormat.mrec)
    adView.delegate = context.coordinator

    // Set background or background color for banners to be fully functional
    adView.backgroundColor = «background-color»

    // Load the first Ad
    adView.loadAd()

    return adView
  }

  func updateUIView(_ uiView: MAAdView, context: Context) {}

  func makeCoordinator() -> Coordinator
  {
    Coordinator()
  }
}

extension ExampleSwiftUIWrapper
{
  class Coordinator: NSObject, MAAdViewAdDelegate
  {
    // MARK: MAAdDelegate Protocol

    func didLoad(_ ad: MAAd) {}

    func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) {}

    func didClick(_ ad: MAAd) {}

    func didFail(toDisplay ad: MAAd, withError error: MAError) {}

    // MARK: MAAdViewAdDelegate Protocol

    func didExpand(_ ad: MAAd) {}

    func didCollapse(_ ad: MAAd) {}

    // MARK: Deprecated Callbacks

    func didDisplay(_ ad: MAAd) { /* use this for impression tracking */ }
    func didHide(_ ad: MAAd) { /* DO NOT USE - THIS IS RESERVED FOR FULLSCREEN ADS ONLY AND WILL BE REMOVED IN A FUTURE SDK RELEASE */ }
  }
}

// SwiftUI view to show ad
struct ExampleSwiftUIMRECAdView: View
{
  // MREC width and height are 300 and 250 respectively, on iPhone and iPad
  let height: CGFloat = 250
  let width: CGFloat = 300

  var body: some View {
      ExampleSwiftUIWrapper()
          .frame(width: width, height: height)
  }
}

Destroying Banners and MREC Ads

You may no longer need a MAAdView instance. This may happen, for example, if the user purchases ad removal. Deallocate such a MAAdView instance in order to free resources.

Do not deallocate the MAAdView instance if you use multiple instances with the same Ad Unit ID.

Objective-C

[self.adView removeFromSuperview];
self.adView.delegate = nil;
self.adView = nil;

Swift

adView.removeFromSuperview()
adView.delegate = nil
adView = nil

Adaptive Banners

Note

Only Google bidding and Google AdMob, and Google Ad Manager support adaptive banners. MAX sizes banners from other networks normally.

Google recommends that developers include a 50px padding between the banner placement and the app content. This makes it less likely that users will accidentally click on the banner. 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 the width of the banner. You integrate adaptive banners in a similar way to how you integrate regular banners. However, you must set the height to the value returned by MAAdFormat.banner.adaptiveSize.height rather than to a constant like 50 or 90. Before you load the ad, set the banner extra parameter adaptive_banner to true as shown in the code below:

Objective-C

- (void)createBannerAd
{
  self.adView = [[MAAdView alloc] initWithAdUnitIdentifier: @"«ad-unit-ID»"];
  self.adView.delegate = self;

  // Get the adaptive banner height
  CGFloat height = MAAdFormat.banner.adaptiveSize.height;

  // Stretch to the width of the screen for banners to be fully functional
  CGFloat width = CGRectGetWidth(UIScreen.mainScreen.bounds);

  self.adView.frame = CGRectMake(x, y, width, height);
  [self.adView setExtraParameterForKey: @"adaptive_banner" value: @"true"];

  // Set background or background color for banners to be fully functional
  self.adView.backgroundColor = «background-color»;

  [self.view addSubview: self.adView];

  // Load the ad
  [self.adView loadAd];
}

Swift

func createBannerAd()
{
  adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»")
  adView.delegate = self

  // Get the adaptive banner height.
  let height: CGFloat = MAAdFormat.banner.adaptiveSize.height

  // Stretch to the width of the screen for banners to be fully functional
  let width: CGFloat = UIScreen.main.bounds.width

  adView.frame = CGRect(x: x, y: y, width: width, height: height)
  adView.setExtraParameterForKey("adaptive_banner", value: "true")

  // Set background or background color for banners to be fully functional
  adView.backgroundColor = «background-color»

  view.addSubview(adView)

  // Load the first ad
  adView.loadAd()
}

SwiftUI

struct ExampleSwiftUIWrapper: UIViewRepresentable
{
  func makeUIView(context: Context) -> MAAdView
  {
    let adView = MAAdView(adUnitIdentifier: "«ad-unit-ID»")
    adView.delegate = context.coordinator

    adView.setExtraParameterForKey("adaptive_banner", value: "true")

    // Set background or background color for banners to be fully functional
    adView.backgroundColor = «background-color»

    // Load the first Ad
    adView.loadAd()

    return adView
  }
  ⋮
}

// SwiftUI view to show ad
struct ExampleSwiftUIBannerAdView: View
{
  let height: CGFloat = MAAdFormat.banner.adaptiveSize.height

  // Stretch to the width of the screen for banners to be fully functional
  let width: CGFloat = UIScreen.main.bounds.width

  var body: some View {
    ExampleSwiftUIWrapper()
      .frame(width: width, height: height)
  }
}

Setting a Custom Width

For more specific integrations you can set a custom width by using the local extra parameters API (as of Google adapter version 10.2.0.2 and Google Ad Manager adapter version 10.2.0.1). You can fetch the appropriate height for your custom adaptive banner by using the adaptive size API.

Objective-C

CGFloat width = 400;
CGFloat height = [self.adView.adFormat adapativeSizeForWidth: width].height;
⋮
[self.adView setLocalExtraParameterForKey: @"adaptive_banner_width" value: @(width)];

Swift

let width: CGFloat = 400

// Get the adaptive banner height
let height: CGFloat = adView.adFormat.adaptiveSize(forWidth: width).height
⋮
adView.setLocalExtraParameterForKey("adaptive_banner_width", value: width)

SwiftUI

let width: CGFloat = 400

// Get the adaptive banner height
let height: CGFloat = MAAdFormat.banner.adaptiveSize(forWidth: width).height
⋮
adView.setLocalExtraParameterForKey("adaptive_banner_width", value: width)

Inline Adaptive Banners

Adaptive banners are anchored by default. Alternatively, you can enable inline adaptive banners, which are meant to appear in scrolling content. Inline adaptive banners are typically larger and taller than anchored adaptive banners. They have variable heights that can extend to the full height of the device screen.

Inline adaptive banners are supported starting with Android adapter version 23.2.0.1 and iOS adapter version 11.7.0.1. To enable, set the extra local parameter adaptive_banner_type to inline, as shown in the code below:

Objective-C

[adView setLocalExtraParameterForKey: @"adaptive_banner_type" value: @"inline"];

Swift

adView.setLocalExtraParameterForKey("adaptive_banner_type", value: "inline")

SwiftUI

adView.setLocalExtraParameterForKey("adaptive_banner_type", value: "inline")

You may want to set a maximum height, in points, for your inline adaptive banners. You can do this with code like the following, which uses a height of 100 points as an example:

Objective-C

[adView setLocalExtraParameterForKey: @"inline_adaptive_banner_max_height" value: @(100)];

Swift

adView.setLocalExtraParameterForKey("inline_adaptive_banner_max_height", value: 100)

SwiftUI

adView.setLocalExtraParameterForKey("inline_adaptive_banner_max_height", value: 100)

You may need to configure your UI in a way that depends on the adaptive banner size. If so, you can retrieve the width and height of the loaded ad, in points, with code like the following:

Objective-C

- (void)didLoadAd:(MAAd *)ad
{
  CGSize adViewSize = ad.size;
  CGFloat widthDp = adViewSize.width;
  CGFloat heightDp = adViewSize.height;
}

Swift

func didLoad(_ ad: MAAd)
{
  let adViewSize = ad.size
  let widthDp = adViewSize.width
  let heightDp = adViewSize.height
}

SwiftUI

func didLoad(_ ad: MAAd)
{
  let adViewSize = ad.size
  let widthDp = adViewSize.width
  let heightDp = adViewSize.height
}

Stopping and Starting Auto-Refresh

You may want to stop auto-refresh for an ad. You may want to do this, for instance, when you hide a banner ad or you want to manually refresh. Stop auto-refresh for a banner or MREC ad with the following code:

Objective-C

// Set this extra parameter to work around SDK bug that ignores calls to stopAutoRefresh()
[adView setExtraParameterForKey: @"allow_pause_auto_refresh_immediately" value: @"true"];
[adView stopAutoRefresh];

Swift

// Set this extra parameter to work around SDK bug that ignores calls to stopAutoRefresh()
adView.setExtraParameterForKey("allow_pause_auto_refresh_immediately", value: "true")
adView.stopAutoRefresh()

SwiftUI

// Set this extra parameter to work around SDK bug that ignores calls to stopAutoRefresh()
adView.setExtraParameterForKey("allow_pause_auto_refresh_immediately", value: "true")
adView.stopAutoRefresh()

Start auto-refresh for a banner or MREC ad with the following call:

Objective-C

[adView startAutoRefresh];

Swift

adView.startAutoRefresh()

SwiftUI

adView.startAutoRefresh()

Manually refresh the contents with the following call. You must stop auto-refresh before you call loadAd().

Objective-C

[adView loadAd];

Swift

adView.loadAd()

SwiftUI

adView.loadAd()