Set advanced native features

    • This guide details advanced features for customizing native ads on Android, including asset controls, AdChoices placement, video controls, and custom click gestures.

    • You can specify a preferred aspect ratio for media assets, control image download behavior, and request multiple images for assets that contain a series.

    • AdChoices placement can be set to one of four corners or rendered within a custom view, with custom view access being limited.

    • Video ad playback can be customized by setting the initial mute state and implementing custom playback controls, although custom controls access is limited.

    • Custom click gestures, which allow swipes to be registered as clicks, are disabled by default and access is limited.
    Select platform: AndroidNew 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

    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.

    Call NativeAdOptions.Builder.setMediaAspectRatio() with a NativeAdOptions.MediaAspectRatio value.

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

    Java

      NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 () 
  
 . 
 setMediaAspectRatio 
 ( 
 NativeAdOptions 
 . 
 NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE 
 ) 
  
 . 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 () 
  
 . 
 setMediaAspectRatio 
 ( 
 NativeAdOptions 
 . 
 NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE 
 ) 
  
 . 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    Replace AD_UNIT_ID 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.

    Call NativeAdOptions.Builder.setReturnUrlsForImageAssets() with a boolean 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.

    Java

      NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setReturnUrlsForImageAssets 
 ( 
 true 
 ). 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ) 
  
 . 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ) 
  
 . 
 forNativeAd 
 ( 
  
 nativeAd 
  
 - 
>  
 { 
  
 List<Uri> 
  
 imageUris 
  
 = 
  
 new 
  
 ArrayList 
<> (); 
  
 for 
  
 ( 
 Image 
  
 image 
  
 : 
  
 nativeAd 
 . 
 getImages 
 ()) 
  
 { 
  
 imageUris 
 . 
 add 
 ( 
 image 
 . 
 getUri 
 ()); 
  
 } 
  
 }) 
  
 . 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setReturnUrlsForImageAssets 
 ( 
 true 
 ). 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ) 
  
 . 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ) 
  
 . 
 forNativeAd 
  
 { 
  
 nativeAd 
  
 - 
>  
 val 
  
 imageUris 
  
 = 
  
 nativeAd 
 . 
 images 
 . 
 mapNotNull 
  
 { 
  
 it 
 . 
 uri 
  
 } 
  
 } 
  
 . 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    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.

    Call NativeAdOptions.Builder.setRequestMultipleImages() with a boolean value.

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

    Java

      NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setRequestMultipleImages 
 ( 
 true 
 ). 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setRequestMultipleImages 
 ( 
 true 
 ). 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    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.

    Call NativeAdOptions.Builder.setAdChoicesPlacement() with a NativeAdOption.AdChoicesPlacement 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.

    Java

      NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 () 
  
 . 
 setAdChoicesPlacement 
 ( 
 NativeAdOptions 
 . 
 ADCHOICES_BOTTOM_RIGHT 
 ) 
  
 . 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 () 
  
 . 
 setAdChoicesPlacement 
 ( 
 NativeAdOptions 
 . 
 ADCHOICES_BOTTOM_RIGHT 
 ) 
  
 . 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    AdChoices custom view

    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.

    Call NativeAdView.setAdChoicesView() with a AdChoicesView value.

    The following example demonstrates how to set a custom AdChoices view, with the AdChoices icon rendered inside the AdChoicesView .

    Java

      NativeAdView 
  
 nativeAdView 
  
 = 
  
 new 
  
 NativeAdView 
 ( 
 context 
 ); 
 AdChoicesView 
  
 adChoicesView 
  
 = 
  
 new 
  
 AdChoicesView 
 ( 
 context 
 ); 
 nativeAdView 
 . 
 setAdChoicesView 
 ( 
 adChoicesView 
 ); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 nativeAdView 
  
 = 
  
 NativeAdView 
 ( 
 context 
 ) 
 val 
  
 adChoicesView 
  
 = 
  
 AdChoicesView 
 ( 
 context 
 ) 
 nativeAdView 
 . 
 adChoicesView 
  
 = 
  
 adChoicesView 
     NativeAdOptionsSnippets 

     
     
 . 
 kt

    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.

    Call VideoOptions.Builder.setStartMuted() with a boolean 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.

    Java

      VideoOptions 
  
 videoOptions 
  
 = 
  
 new 
  
 VideoOptions 
 . 
 Builder 
 (). 
 setStartMuted 
 ( 
 false 
 ). 
 build 
 (); 
 NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setVideoOptions 
 ( 
 videoOptions 
 ). 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 videoOptions 
  
 = 
  
 VideoOptions 
 . 
 Builder 
 (). 
 setStartMuted 
 ( 
 false 
 ). 
 build 
 () 
 val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setVideoOptions 
 ( 
 videoOptions 
 ). 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    Custom playback controls

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

    Call VideoOptions.Builder.setCustomControlsRequested() with a boolean value.

    • Custom playback control are disabled by default.

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

    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

    VideoController .

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

    Java

      VideoOptions 
  
 videoOptions 
  
 = 
  
 new 
  
 VideoOptions 
 . 
 Builder 
 (). 
 setCustomControlsRequested 
 ( 
 true 
 ). 
 build 
 (); 
 NativeAdOptions 
  
 nativeAdOptions 
  
 = 
  
 new 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setVideoOptions 
 ( 
 videoOptions 
 ). 
 build 
 (); 
 AdLoader 
  
 loader 
  
 = 
  
 new 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 (); 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 videoOptions 
  
 = 
  
 VideoOptions 
 . 
 Builder 
 (). 
 setCustomControlsRequested 
 ( 
 true 
 ). 
 build 
 () 
 val 
  
 nativeAdOptions 
  
 = 
  
 NativeAdOptions 
 . 
 Builder 
 (). 
 setVideoOptions 
 ( 
 videoOptions 
 ). 
 build 
 () 
 val 
  
 loader 
  
 = 
  
 AdLoader 
 . 
 Builder 
 ( 
 context 
 , 
  
 " AD_UNIT_ID 
" 
 ). 
 withNativeAdOptions 
 ( 
 nativeAdOptions 
 ). 
 build 
 () 
 
      NativeAdOptionsSnippets 
 . 
 kt

    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.

    Java

      MediaContent 
  
 mediaContent 
  
 = 
  
 nativeAd 
 . 
 getMediaContent 
 (); 
 if 
  
 ( 
 mediaContent 
  
 != 
  
 null 
 ) 
  
 { 
  
 VideoController 
  
 videoController 
  
 = 
  
 mediaContent 
 . 
 getVideoController 
 (); 
  
 boolean 
  
 canShowCustomControls 
  
 = 
  
 videoController 
 . 
 isCustomControlsEnabled 
 (); 
 } 
 
      NativeAdOptionsSnippets 
 . 
 java

    Kotlin

      val 
  
 mediaContent 
  
 = 
  
 nativeAd 
 . 
 mediaContent 
 if 
  
 ( 
 mediaContent 
  
 != 
  
 null 
 ) 
  
 { 
  
 val 
  
 videoController 
  
 = 
  
 mediaContent 
 . 
 videoController 
  
 val 
  
 canShowCustomControls 
  
 = 
  
 videoController 
 . 
 isCustomControlsEnabled 
 } 
 
      NativeAdOptionsSnippets 
 . 
 kt

    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.
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: