Native Ads

Native ads are ad assets that are presented to users through 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 Google Mobile Ads SDK—is then responsible for displaying them.

Broadly speaking, there are two parts to successfully implementing native ads: Loading an ad using the SDK and then displaying the ad content in your app.

This page shows how to use the SDK to load native ads.

Prerequisites

• Complete the Get started guide.

Always test with test ads

When building and testing your apps, make sure you use test ads rather than live, production ads.

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

/21775744923/example/native

It's been specially configured to return test ads for every request, and you can 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 Google Mobile Ads SDK's test ads work, see Test ads.

Load 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:

adLoader = GADAdLoader(adUnitID: "/21775744923/example/native",
    // The UIViewController parameter is optional.
    rootViewController: rootViewController,
    adTypes: [ .native ],
    options: [ ... ad loader options objects ... ])
adLoader.delegate = self

self.adLoader = [[GADAdLoader alloc]
      initWithAdUnitID:@"/21775744923/example/native"
    // The UIViewController parameter is nullable.
    rootViewController:rootViewController
               adTypes:@[ GADAdLoaderAdTypeNative ]
               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 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.

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

- (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.

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

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

Request ads

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

adLoader.load(GAMRequest())

[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.

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.

Handling failed requests

The above protocols extend the GADAdLoaderDelegate protocol, which defines a message sent when ads fail to load.

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

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

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:

nativeAd.delegate = self

nativeAd.delegate = self;

Then implement GADNativeAdDelegate to receive the following delegate calls:

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.
}

- (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.
}

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.

• Don't call loadRequest: again on a GADAdLoader until the previous request finishes loading, as indicated by adLoaderDidFinishLoading:.

• Limit native ad caching to only what is needed. For example when precaching, only cache the ads that are immediately visible on the screen. Native ads have a large memory footprint, and caching native ads without destroying them results in excessive memory use.

• Destroy native ads when no longer in use.

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.