Load an ad

Prerequisites

• Complete the Get started guide.

Loading ads

Native ads are loaded with the GADAdLoader class, which send messages to their delegates according to the GADAdLoaderDelegate 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 GADCustomNativeAd class.

Initialize the ad loader

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

Swift

adLoader = GADAdLoader(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
• GADAdLoaderAdTypeCustomNative

Implement the ad loader delegate

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

Swift

public func adLoader(_ adLoader: GADAdLoader,
            didReceive nativeAd: GADNativeAd)

Objective-C

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

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

Swift

func adLoader(_ adLoader: GADAdLoader,
  Receive customNativeAd: GADCustomNativeAd)

Objective-C

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

Request ads

Once your GADAdLoader is initialized, call its loadRequest: method to request an ad:

Swift

adLoader.load(GAMRequest())

Objective-C

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

The loadRequest: method in GADAdLoader accepts the same GAMRequest 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 GADMultipleAdsAdLoaderOptions object when initializing a GADAdLoader.

Swift

let multipleAdOptions = GADMultipleAdsAdLoaderOptions()
multipleAdOptions.numberOfAds = 5;
adLoader = GADAdLoader(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 GADMultipleAdsAdLoaderOptions 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 loadRequest:, it can get the results of the request using calls to:

• adLoader:didFailToReceiveAdWithError: in GADAdLoaderDelegate
• adLoader:didReceiveNativeAd: in GADNativeAdLoaderDelegate

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, GADAdLoaderDelegate 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, GADNativeAdLoaderDelegate {

  var adLoader: GADAdLoader!

  override func viewDidLoad() {
    super.viewDidLoad()

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

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

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

  func adLoaderDidFinishLoading(_ adLoader: GADAdLoader) {
    // 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 GADAdLoaderDelegate protocol, which defines a message sent when ads fail to load.

Swift

public func adLoader(_ adLoader: GADAdLoader,
    didFailToReceiveAdWithError error: NSError)

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 the native ad interactions, set the delegate property of the native ad:

Swift

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

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

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

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

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

func nativeAdWillLeaveApplication(_ nativeAd: GADNativeAd) {
  // The native ad will cause the app to become inactive and
  // open a new app.
}

Objective-C

nativeAd.delegate = self;

Then implement GADNativeAdDelegate to receive the following delegate calls:

Swift

- (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)nativeAdWillLeaveApplication:(GADNativeAd *)nativeAd {
  // The native ad will cause the app to become inactive and
  // open a new app.
}

Objective-C

nativeAd.delegate = self;

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 loadRequest: on a GADAdLoader 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.