Native ad options

Select platform: Android iOS

Native ads have many advanced features that allow you to make additional customizations and make the best possible ad experience. This guide shows you how to use the advanced features of native ads.

Prerequisites

• Integrate the Native ad format.

Asset controls

This section details how to customize the creative assets in your native ads. You have the option to specify a preferred aspect ratio for media assets and how the image assets are downloaded and displayed.

Preferred media aspect ratio controls

Media Aspect Ratio Controls let you specify a preference for the aspect ratio of ad creatives.

Important: Use of this API does not guarantee that all ad creatives will meet the preference specified.

Set GADNativeAdMediaAdLoaderOptions mediaAspectRatio with a GADMediaAspectRatio.

• When unset, the returned ad can have any media aspect ratio.

• When set, you will be able to improve the user experience by specifying the preferred type of aspect ratio.

The following example instructs the SDK to prefer a return image or video with a specific aspect ratio.

Swift

let nativeOptions = NativeAdMediaAdLoaderOptions()
nativeOptions.mediaAspectRatio = .any

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [nativeOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADNativeAdMediaAdLoaderOptions *nativeOptions = [[GADNativeAdMediaAdLoaderOptions alloc] init];
nativeOptions.mediaAspectRatio = GADMediaAspectRatioAny;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ nativeOptions ]];
NativeAdOptionsSnippets.m

Replace nativeAdUnitID with your ad unit ID.

Image download control

Image download control lets you decide if image assets or only URIs are returned by the SDK.

Set GADNativeAdImageAdLoaderOptions disableImageLoading with a BOOL value.

• Image download control are disabled by default.

• When disabled, Google Mobile Ads SDK populates both the image and the URI for you.

• When enabled, the SDK instead populates just the URI, allowing you to download the actual images at your discretion.

The following example instructs the SDK to return just the URI.

Swift

let nativeOptions = NativeAdImageAdLoaderOptions()
nativeOptions.isImageLoadingDisabled = true

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [nativeOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADNativeAdImageAdLoaderOptions *nativeOptions = [[GADNativeAdImageAdLoaderOptions alloc] init];
nativeOptions.disableImageLoading = YES;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ nativeOptions ]];
NativeAdOptionsSnippets.m

Image payload controls

Some ads have a series of images rather than just one. Use this feature to indicate whether your app is prepared to display all the images or just one.

• Image payload controls are disabled by default.

• When disabled, your app instructs the SDK to provide just the first image for any assets that contain a series.

• When enabled, your app indicates that it is prepared to display all the images for any assets that have more than one.

The following example instructs the SDK to return multiple image assets.

Swift

let nativeOptions = NativeAdImageAdLoaderOptions()
nativeOptions.shouldRequestMultipleImages = true

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [nativeOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADNativeAdImageAdLoaderOptions *nativeOptions = [[GADNativeAdImageAdLoaderOptions alloc] init];
nativeOptions.shouldRequestMultipleImages = YES;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ nativeOptions ]];
NativeAdOptionsSnippets.m

AdChoices placements

This section details how to position the AdChoices overlay. You have the option to set its placement to one of the four corners or render it within a custom view.

AdChoices position controls

The AdChoices position controls lets you choose which corner to render the AdChoices icon.

Set GADNativeAdViewAdOptions preferredAdChoicesPosition with a GADAdChoicesPosition value.

• If unset, the AdChoices icon position is set to the top right.

• If set, AdChoices is placed at the custom position as requested.

The following example demonstrates how to set a custom AdChoices image position.

Swift

let nativeOptions = NativeAdViewAdOptions()
nativeOptions.preferredAdChoicesPosition = .topRightCorner

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [nativeOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADNativeAdViewAdOptions *nativeOptions = [[GADNativeAdViewAdOptions alloc] init];
nativeOptions.preferredAdChoicesPosition = GADAdChoicesPositionTopRightCorner;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ nativeOptions ]];
NativeAdOptionsSnippets.m

AdChoices custom view

Warning: Access to this feature is limited. To request access, reach out to your account manager.

The AdChoices custom view feature lets you position the AdChoices icon in a custom location. This is different from AdChoices position controls, which only allows specification of one of the four corners.

Set the GADNativeAd.adChoicesView property with a GADAdChoicesView prior to rendering and the AdChoices content renders inside the GADAdChoicesView.

The following example demonstrates how to set a custom AdChoices view. The AdChoices icon renders inside the GADAdChoicesView:

Swift

private func createAdChoicesView(nativeAdView: NativeAdView) {
  // Define a custom position for the AdChoices icon.
  let customRect = CGRect(x: 100, y: 100, width: 15, height: 15)
  let customAdChoicesView = AdChoicesView(frame: customRect)
  nativeAdView.addSubview(customAdChoicesView)
  nativeAdView.adChoicesView = customAdChoicesView
}
NativeAdOptionsSnippets.swift

Objective-C

- (void)createAdChoicesViewWithNativeAdView:(GADNativeAdView *)nativeAdView {
  // Define a custom position for the AdChoices icon.
  CGRect customRect = CGRectMake(100, 100, 15, 15);
  GADAdChoicesView *customAdChoicesView = [[GADAdChoicesView alloc] initWithFrame:customRect];
  [nativeAdView addSubview:customAdChoicesView];
  nativeAdView.adChoicesView = customAdChoicesView;
}
NativeAdOptionsSnippets.m

Video controls

This section details how customize the playback experience for video ads. You have the option to set the initial mute state and implement custom playback controls.

Start mute behavior

The start muted behavior lets you disable or enable a video's starting audio.

Set GADVideoOptions startMuted with a BOOL value.

• The start muted behavior is enabled by default.

• When disabled, your app requests the video should begin with audio.

• When enabled, your app requests that the video should begin with audio muted.

The following example shows how to start the video with un-muted audio.

Swift

let videoOptions = VideoOptions()
videoOptions.shouldStartMuted = false

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [videoOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADVideoOptions *videoOptions = [[GADVideoOptions alloc] init];
videoOptions.startMuted = NO;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ videoOptions ]];
NativeAdOptionsSnippets.m

Custom playback controls

Warning: Access to this feature is limited. To request access, reach out to your account manager.

This lets you request custom video input controls to play, pause, or mute the video.

Set GADVideoOptions customControlsRequested with a BOOL value.

• Custom playback control are disabled by default.

• When disabled, your video will show SDK rendered input controls.

• When enabled you can then use GADVideoController play , GADVideoController pause , and GADVideoController setMute to control the video ad.

If the ad does have video content and custom controls are enabled, you should then display your custom controls along with the ad, as the ad won't show any controls itself. The controls can then call the relevant methods on the

GADVideoController.

The following example shows how request a video with custom playback controls.

Swift

let videoOptions = VideoOptions()
videoOptions.areCustomControlsRequested = true

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [videoOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADVideoOptions *videoOptions = [[GADVideoOptions alloc] init];
videoOptions.customControlsRequested = YES;

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ videoOptions ]];
NativeAdOptionsSnippets.m

Check if custom controls are enabled

Because it's not known at request time whether the returned ad will allow custom video controls, you must check whether it has custom controls enabled.

Swift

private func checkCustomControlsEnabled(nativeAd: NativeAd) -> Bool {
  let videoController = nativeAd.mediaContent.videoController
  return videoController.areCustomControlsEnabled
}
NativeAdOptionsSnippets.swift

Objective-C

- (BOOL)checkCustomControlsEnabledWithNativeAd:(GADNativeAd *)nativeAd {
  GADVideoController *videoController = nativeAd.mediaContent.videoController;
  return videoController.customControlsEnabled;
}
NativeAdOptionsSnippets.m

Render custom video controls

Render custom video controls using the following best practices:

1. Render the custom controls view as a child of the native ad view. This approach lets open measurement viewability calculations consider the custom controls as a friendly obstruction.
2. Avoid rendering an invisible overlay over the entire media view. Overlays block clicks on the media view, negatively impacting native ads performance. Instead, create a small overlay that is just large enough to fit the controls.

Note: For information on measurement and verification providers that have committed to the development of the open measurement viewability standard, see the Open Measurement Working Group.

Custom click gestures

Warning: Access to this feature is limited. To request access, reach out to your account manager.

Custom click gestures is a native ads feature that enables swipes on ad views to be registered as ad clicks. It is designed to work with apps that use swipe gestures for content navigation. This guide shows how to enable custom click gestures on your native ads.

Initialize a GADNativeAdCustomClickGestureOptions instance with your selected swipe direction. You also need to indicate whether you want taps to be allowed as clicks.

• Custom click gestures is disabled by default.

• When disabled, only taps will count as clicks.

• When enabled, swipe gestures will be counted as clicks, and you can specify whether taps can still count as clicks.

The following example shows you how to implement a custom swipe gesture to the right and preserves normal tap behavior.

Swift

let swipeGestureOptions = NativeAdCustomClickGestureOptions(
  swipeGestureDirection: .right,
  tapsAllowed: true)

adLoader = AdLoader(
  adUnitID: "nativeAdUnitID",
  rootViewController: self,
  adTypes: [.native],
  options: [swipeGestureOptions])
NativeAdOptionsSnippets.swift

Objective-C

GADNativeAdCustomClickGestureOptions *swipeGestureOptions =
    [[GADNativeAdCustomClickGestureOptions alloc]
        initWithSwipeGestureDirection:UISwipeGestureRecognizerDirectionRight
                          tapsAllowed:YES];

self.adLoader = [[GADAdLoader alloc] initWithAdUnitID:"nativeAdUnitID"
                                   rootViewController:self
                                              adTypes:@[ GADAdLoaderAdTypeNative ]
                                              options:@[ swipeGestureOptions ]];
NativeAdOptionsSnippets.m

Warning: If your account is not enabled for custom click gestures, ad requests will return a no-fill.

Listen for swipe gesture events

When a swipe gesture click is recorded, Google Mobile Ads SDK invokes the nativeAdDidRecordSwipeGestureClick: delegate method on GADNativeAdDelegate , in addition to the existing nativeAdDidRecordClick: delegate method.

Swift

// Called when a swipe gesture click is recorded, as configured in
// NativeAdCustomClickGestureOptions.
func nativeAdDidRecordSwipeGestureClick(_ nativeAd: NativeAd) {
  print("A swipe gesture click has occurred.")
}

// Called when a swipe gesture click or a tap click is recorded.
func nativeAdDidRecordClick(_ nativeAd: NativeAd) {
  print("A swipe gesture click or tap click has occurred.")
}
NativeAdOptionsSnippets.swift

Objective-C

// Called when a swipe gesture click is recorded, as configured in
// GADNativeAdCustomClickGestureOptions.
- (void)nativeAdDidRecordSwipeGestureClick:(GADNativeAd *)nativeAd {
  NSLog(@"A swipe gesture click has occurred.");
}

// Called when a swipe gesture click or a tap click is recorded.
- (void)nativeAdDidRecordClick:(GADNativeAd *)nativeAd {
  NSLog(@"A swipe gesture click or tap click has occurred.");
}
NativeAdOptionsSnippets.m

Mediation

Custom click gestures only work on native ads that Google Mobile Ads SDK renders. Ad sources that require third-party SDKs for rendering, don't respond to the custom click directions setting.