Load an ad

Prerequisites

• Complete the Get started guide.

Loading ads

Native ads are loaded with the ad-loader class (AdLoader in Swift, GADAdLoader in Objective-C), which sends messages to its delegate according to the ad-loader delegate protocol.

In addition to the system-defined native format, you can also create your own custom native ad formats that can be used for direct-sold native ads. Custom native ad formats let you pass arbitrary structured data to your app. These ads are represented by the CustomNativeAd class in Swift (GADCustomNativeAd in Objective-C).

In the current Google Mobile Ads SDK for iOS (12.x), the Swift API drops the GAD prefix: GADAdLoader is exposed in Swift as AdLoader, GADNativeAd as NativeAd, GADNativeAdView as NativeAdView, GADMediaView as MediaView, GADMediaContent as MediaContent, and GAMRequest as AdManagerRequest. The Objective-C class names remain unchanged.

Initialize the ad loader

Before you can load an ad, you have to initialize the ad loader. The following code demonstrates how to initialize an ad-loader:

Swift

adLoader = AdLoader(adUnitID: "/75894840/app-adunit-demo/native",
    rootViewController: self,
    adTypes: [ .native ],
    options: [ /* ad loader options objects */ ])
adLoader.delegate = self

Objective-C

self.adLoader = [[GADAdLoader alloc]
      initWithAdUnitID:@"/75894840/app-adunit-demo/native"
    rootViewController:rootViewController
               adTypes:@[ GADAdLoaderAdTypeNative ]
               options:@[ /* ad loader options objects */ ]];
self.adLoader.delegate = self;

The adTypes array should contain one or more of the following constants:

• GADAdLoaderAdTypeNative (Objective-C) / .native (Swift)
• GADAdLoaderAdTypeCustomNative (Objective-C) / .customNative (Swift)

Implement the ad loader delegate

The ad loader delegate needs to implement protocols specific to your ad type. For native ads, the native-ad-loader delegate protocol includes a message that's sent to the delegate when a native ad has loaded.

Swift

public func adLoader(_ adLoader: AdLoader,
            didReceive nativeAd: NativeAd)

Objective-C

- (void)adLoader:(GADAdLoader *)adLoader
    didReceiveNativeAd:(GADNativeAd *)nativeAd;

The custom-native-ad-loader delegate protocol includes a message that's sent to the delegate when a custom template ad has loaded.

Swift

func adLoader(_ adLoader: AdLoader,
  didReceive customNativeAd: CustomNativeAd)

Objective-C

- (void)adLoader:(GADAdLoader *)adLoader
    didReceiveCustomNativeAd:(GADCustomNativeAd *)customNativeAd;

Request ads

Once your ad-loader is initialized, call its load(_:) / loadRequest: method to request an ad:

Swift

adLoader.load(AdManagerRequest())

Objective-C

[self.adLoader loadRequest:[GAMRequest request]];

The load method accepts the same ad-request objects as banners and interstitials. You can use request objects to add targeting information, just as you would with other ad types.

Load multiple ads (optional)

To load multiple ads in a single request, set the multiple-ads-options object when initializing an ad-loader.

Swift

let multipleAdOptions = MultipleAdsAdLoaderOptions()
multipleAdOptions.numberOfAds = 5
adLoader = AdLoader(adUnitID: "/75894840/app-adunit-demo/native",
    rootViewController: self,
    adTypes: [ .native ],
    options: [ multipleAdOptions ])

Objective-C

GADMultipleAdsAdLoaderOptions *multipleAdsOptions =
    [[GADMultipleAdsAdLoaderOptions alloc] init];
multipleAdsOptions.numberOfAds = 5;
self.adLoader = [[GADAdLoader alloc]
      initWithAdUnitID:@"/75894840/app-adunit-demo/native"
    rootViewController:rootViewController
               adTypes:@[ GADAdLoaderAdTypeNative ]
               options:@[ multipleAdsOptions ]];

The number of ads per request is capped at five, and it's not guaranteed that the SDK will return the exact number of ads requested.

Returned Google ads will all be different from each other, though ads from reserved inventory or third-party buyers are not guaranteed to be unique.

Do not use the multiple-ads-options class if you're using mediation, as requests for multiple native ads don't currently work for ad unit IDs that have been configured for mediation.

Determining when loading has finished

After an app calls the load method, it can get the results of the request using calls to:

• adLoader:didFailToReceiveAdWithError: (Objective-C) / adLoader(_:didFailToReceiveAdWithError:) (Swift)
• adLoader:didReceiveNativeAd: (Objective-C) / adLoader(_:didReceive:) (Swift)

A request for a single ad will result in one call to one of those methods.

A request for multiple ads will result in at least one callback to the above methods, but no more than the maximum number of ads requested.

In addition, the ad-loader delegate offers the adLoaderDidFinishLoading callback. This delegate method indicates that an ad loader has finished loading ads and no other ads or errors will be reported for the request. Here's an example of how to use it when loading several native ads at one time:

Swift

class ViewController: UIViewController, NativeAdLoaderDelegate {

  var adLoader: AdLoader!

  override func viewDidLoad() {
    super.viewDidLoad()

    let multipleAdOptions = MultipleAdsAdLoaderOptions()
    multipleAdOptions.numberOfAds = 5
    adLoader = AdLoader(adUnitID: "/75894840/app-adunit-demo/native",
        rootViewController: self,
        adTypes: [ .native ],
        options: [ multipleAdOptions ])

    adLoader.delegate = self
    adLoader.load(AdManagerRequest())
  }

  func adLoader(_ adLoader: AdLoader,
       didReceive nativeAd: NativeAd) {
    // A native ad has loaded, and can be displayed.
  }

  func adLoaderDidFinishLoading(_ adLoader: AdLoader) {
    // The adLoader has finished loading ads, and a new request can be sent.
  }

}

Objective-C

@interface ViewController () <GADNativeAdLoaderDelegate, GADVideoControllerDelegate>
@property(nonatomic, strong) GADAdLoader *adLoader;

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  GADMultipleAdsAdLoaderOptions *multipleAdsOptions =
      [[GADMultipleAdsAdLoaderOptions alloc] init];
  multipleAdsOptions.numberOfAds = 5;
  self.adLoader = [[GADAdLoader alloc]
        initWithAdUnitID:@"/75894840/app-adunit-demo/native"
      rootViewController:rootViewController
                 adTypes:@[ GADAdLoaderAdTypeNative ]
                 options:@[ multipleAdsOptions ]];

  self.adLoader.delegate = self;
  [self.adLoader loadRequest:[GADRequest request]];
}

- (void)adLoader:(GADAdLoader *)adLoader
    didReceiveNativeAd:(GADNativeAd *)nativeAd {
  // A native ad has loaded, and can be displayed.
}

- (void)adLoaderDidFinishLoading:(GADAdLoader *) adLoader {
  // The adLoader has finished loading ads, and a new request can be sent.
}

@end

Handling failed requests

The above protocols extend the ad-loader delegate protocol, which defines a message sent when ads fail to load.

Swift

public func adLoader(_ adLoader: AdLoader,
    didFailToReceiveAdWithError error: Error)

Objective-C

- (void)adLoader:(GADAdLoader *)adLoader
    didFailToReceiveAdWithError:(NSError *)error;

Warning: Attempting to load a new ad from the adLoader:didFailToReceiveAdWithError: delegate method is strongly discouraged. If you must load an ad from adLoader:didFailToReceiveAdWithError:, limit ad load retries to avoid continuous failed ad requests in situations such as limited network connectivity.

Get notified of native ad events

To be notified of events related to native ad interactions, set the delegate property of the native ad to an object that implements the native-ad delegate protocol (NativeAdDelegate in Swift, GADNativeAdDelegate in Objective-C):

Swift

nativeAd.delegate = self

Objective-C

nativeAd.delegate = self;

Then implement the delegate to receive the following calls:

Swift

func nativeAdDidRecordImpression(_ nativeAd: NativeAd) {
  // The native ad was shown.
}

func nativeAdDidRecordClick(_ nativeAd: NativeAd) {
  // The native ad was clicked on.
}

func nativeAdWillPresentScreen(_ nativeAd: NativeAd) {
  // The native ad will present a full screen view.
}

func nativeAdWillDismissScreen(_ nativeAd: NativeAd) {
  // The native ad will dismiss a full screen view.
}

func nativeAdDidDismissScreen(_ nativeAd: NativeAd) {
  // The native ad did dismiss a full screen view.
}

func nativeAdIsMuted(_ nativeAd: NativeAd) {
  // The native ad was muted.
}

Objective-C

- (void)nativeAdDidRecordImpression:(GADNativeAd *)nativeAd {
  // The native ad was shown.
}

- (void)nativeAdDidRecordClick:(GADNativeAd *)nativeAd {
  // The native ad was clicked on.
}

- (void)nativeAdWillPresentScreen:(GADNativeAd *)nativeAd {
  // The native ad will present a full screen view.
}

- (void)nativeAdWillDismissScreen:(GADNativeAd *)nativeAd {
  // The native ad will dismiss a full screen view.
}

- (void)nativeAdDidDismissScreen:(GADNativeAd *)nativeAd {
  // The native ad did dismiss a full screen view.
}

- (void)nativeAdIsMuted:(GADNativeAd *)nativeAd {
  // The native ad was muted.
}

Best practices

Follow these rules when loading ads.

• Apps that use native ads in a list should precache the list of ads.
• When precaching ads, clear your cache and reload after one hour.
• Do not call the load method on an ad-loader until the first request finishes loading.

Display your ad

Once you have loaded an ad, all that remains is to display it to your users. Head over to our Native Advanced guide to see how.