Native Ads

Key Point: Learn more about native ads in our Native Ads Playbook. For a complete walkthrough of an example project, visit our Codelab. Samples are available for Swift and Objective-C. You can also check out some customer success stories: case study 1, case study 2.

Native ads are ad assets that are presented to users via UI components that are native to the platform. They're shown using the same classes you already use in your storyboards, and can be formatted to match your app's visual design. When a native ad loads, your app receives an ad object that contains its assets, and the app (rather than the SDK) is then responsible for displaying them. This differs from other ad formats, which don't allow you to customize the appearance of the ad.

This guide will show you how to use the Google Mobile Ads SDK to implement native ads in an iOS app, as well as some important things to consider along the way.

Broadly speaking, there are two parts to successfully implementing native ads: loading an ad via the SDK and displaying the ad content in your app. This page discusses ad loading using the SDK.

Prerequisites

• Import the Google Mobile Ads SDK, either by itself or as part of Firebase.

Always test with test ads

Before you begin, remember that when building and testing your apps, you should be sure that you're using test ads rather than live, production ads. Testing with production ads could lead to suspension of your account.

The easiest way to load test ads is to use our dedicated test ad unit ID for all native advanced ads on iOS:

ca-app-pub-3940256099942544/3986624511

It's been specially configured to return test ads for every request, and you're free to use it in your own apps while coding, testing, and debugging. Just make sure you replace it with your own ad unit ID before publishing your app.

For more information about how the Mobile Ads SDK's test ads work, see Test Ads.

Loading ads

There are two system-defined formats for native ads: app install and content.

Both types of ads are represented by one class: GADUnifiedNativeAd. An instance of this class contains the assets for the native ad. Note that depending on the type of ad represented by the GADUnifiedNativeAd, some fields will not be populated (i.e., they will be nil).

Native ads are loaded via GADAdLoader objects, which send messages to their delegates according to the GADAdLoaderDelegate protocol.

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: "ca-app-pub-3940256099942544/3986624511",
    rootViewController: self,
    adTypes: [ kGADAdLoaderAdTypeUnifiedNative ],
    options: [ ... ad loader options objects ... ])
adLoader.delegate = self

Objective-C

self.adLoader = [[GADAdLoader alloc]
      initWithAdUnitID:@"ca-app-pub-3940256099942544/3986624511"
    rootViewController:rootViewController
               adTypes:@[ ... ad type constants ... ]
               options:@[ ... ad loader options objects ... ]];
self.adLoader.delegate = self;

You'll need an ad unit ID (you can use the test ID), constants to pass in the adTypes array to specify which native formats you want to request, and any options you wish to set in the options parameter. The list of possible values for the options parameter can be found in the Setting Native Ad Options page.

The adTypes array should contain this constant:

• kGADAdLoaderAdTypeUnifiedNative

Implement the ad loader delegate

The ad loader delegate needs to implement protocols specific your ad type. For unified native ads:

• GADUnifiedNativeAdLoaderDelegate This protocol includes a message that's sent to the delegate when a unified native ad has loaded:

  Swift

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

  Objective-C

  - (void)adLoader:(GADAdLoader *)adLoader
      didReceiveUnifiedNativeAd:(GADUnifiedNativeAd *)nativeAd;
  

Request the ad

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

Swift

adLoader.load(GADRequest())

Objective-C

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

The loadRequest: method in GADAdLoader accepts the same GADRequest objects as banners and interstitials. You can use request objects to add targeting information, just as you would with other ad types.

When to request ads

Apps displaying native ads are free to request them in advance of when they'll actually be displayed. In many cases, this is the recommended practice. An app displaying a list of items with native ads mixed in, for example, can load native ads for the whole list, knowing that some will be shown only after the user scrolls the view and some may not be displayed at all.

While prefetching ads is a great technique, it's important that you don't keep old ads around forever without displaying them. Any native ad objects that have been held without display for longer than an hour should be discarded and replaced with new ads from a new request.

Note: When reusing a GADAdLoader, make sure you wait for each request to complete before calling loadRequest: again.

Determining when loading has finished

After an app calls loadRequest:, it can get the results of the request via calls to:

• adLoader:didFailToReceiveAdWithError: in GADAdLoaderDelegate
• adLoader:didReceiveUnifiedNativeAd: in GADUnifiedNativeAdLoaderDelegate

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.

Note: Requests for multiple native ads don't currently work for AdMob ad unit IDs that have been configured for mediation. Publishers using mediation should avoid using the GADMultipleAdsAdLoaderOptions class when making requests.

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, GADUnifiedNativeAdLoaderDelegate {

  var adLoader: GADAdLoader!

  override func viewDidLoad() {
    super.viewDidLoad()

    let multipleAdsOptions = GADMultipleAdsAdLoaderOptions()
    multipleAdsOptions.numberOfAds = 5

    adLoader = GADAdLoader(adUnitID: YOUR_AD_UNIT_ID, rootViewController: self,
        adTypes: [GADAdLoaderAdType.unifiedNative],
        options: [multipleAdsOptions])
    adLoader.delegate = self
    adLoader.load(GADRequest())
  }

  func adLoader(_ adLoader: GADAdLoader,
                didReceive nativeAd: GADUnifiedNativeAd) {
    // A unified 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 () <GADUnifiedNativeAdLoaderDelegate, 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:YOUR_AD_UNIT_ID
          rootViewController:self
                     adTypes:@[kGADAdLoaderAdTypeUnifiedNative]
                     options:@[multipleAdsOptions]];
  self.adLoader.delegate = self;
  [self.adLoader loadRequest:[GADRequest request]];
}

- (void)adLoader:(GADAdLoader *)adLoader
    didReceiveUnifiedNativeAd:(GADUnifiedNativeAd *)nativeAd {
   // A unified 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. You can use the GADRequestError object to determine the cause of the error.

Swift

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

Objective-C

- (void)adLoader:(GADAdLoader *)adLoader
    didFailToReceiveAdWithError:(GADRequestError *)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

nativeAd.delegate = self

Objective-C

nativeAd.delegate = self;

Then implement GADUnifiedNativeAdDelegate to receive the following delegate calls:

Swift

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

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

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

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

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

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

Objective-C

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

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

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

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

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

- (void)nativeAdWillLeaveApplication:(GADUnifiedNativeAd *)nativeAd {
  // The native ad will cause the application to become inactive and
  // open a new application.
}

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.