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.
Call NativeAdRequest.Builder.setMediaAspectRatio()
with a NativeAd.NativeMediaAspectRatio
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.
Kotlin
val
adRequest
=
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setMediaAspectRatio
(
NativeAd
.
NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE
)
.
build
()
Java
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setMediaAspectRatio
(
NativeAd
.
NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE
)
.
build
();
Image download control
Image download control lets you decide if image assets or only URIs are returned by the SDK.
Call NativeAdRequest.Builder.disableImageDownloading()
.
-
Image download control are disabled by default.
-
When disabled, GMA Next-Gen 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.
Kotlin
val
adRequest
=
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setMediaAspectRatio
(
NativeAd
.
NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE
)
.
disableImageDownloading
()
.
build
()
val
adCallback
:
NativeAdLoaderCallback
=
object
:
NativeAdLoaderCallback
{
override
fun
onNativeAdLoaded
(
nativeAd
:
NativeAd
)
{
// Get the image uri.
val
imageUri
=
nativeAd
.
image
?.
uri
}
};
// Load the native ad with the ad request and callback.
NativeAdLoader
.
load
(
adRequest
,
adLoaderCallback
);
Java
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
disableImageDownloading
()
.
build
();
NativeAdLoaderCallback
adLoaderCallback
=
new
NativeAdLoaderCallback
()
{
@Override
public
void
onNativeAdLoaded
(
@NonNull
NativeAd
nativeAd
)
{
// Get the image uri.
Uri
imageUri
=
nativeAd
.
getImage
().
getUri
();
}
};
// Load the native ad with the ad request and callback.
NativeAdLoader
.
load
(
adRequest
,
adLoaderCallback
);
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.
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 NativeAdRequest.Builder.setAdChoicesPlacement()
with a NativeAdRequest.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.
Kotlin
val
adRequest
=
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setAdChoicesPlacement
(
NativeAdOptions
.
ADCHOICES_BOTTOM_RIGHT
)
.
build
()
Java
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setAdChoicesPlacement
(
NativeAdOptions
.
ADCHOICES_BOTTOM_RIGHT
)
.
build
();
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
.
Kotlin
override
fun
onNativeAdLoaded
(
nativeAd
:
NativeAd
)
{
val
nativeAdView
=
NativeAdView
(
applicationContext
)
val
adChoicesView
=
AdChoicesView
(
this
)
nativeAdView
.
adChoicesView
=
adChoicesView
}
Java
public
void
onNativeAdLoaded
(
@NonNull
NativeAd
nativeAd
)
{
NativeAdView
nativeAdView
=
new
NativeAdView
(
getApplicationContext
());
AdChoicesView
adChoicesView
=
new
AdChoicesView
(
this
);
nativeAdView
.
setAdChoicesView
(
adChoicesView
);
}
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 and call NativeAdOptions.Builder.setVideoOptions()
.
-
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.
Kotlin
val
videoOptions
=
VideoOptions
.
Builder
()
.
setStartMuted
(
false
)
.
build
()
val
adRequest
=
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setVideoOptions
(
videoOptions
)
.
build
()
Java
VideoOptions
videoOptions
=
VideoOptions
.
Builder
()
.
setStartMuted
(
false
)
.
build
()
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setVideoOptions
(
videoOptions
)
.
build
()
Custom playback controls
This lets you request custom video input controls to play, pause, or mute the video.
To set the ads starting mute state, call VideoOptions.Builder.setCustomControlsRequested()
.
-
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
VideoOptions.Builder.setCustomControlsRequested()
.
The following example shows how request a video with custom playback controls.
Kotlin
val
videoOptions
:
VideoOptions
.
Builder
()
.
setCustomControlsRequested
(
true
)
.
build
()
val
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setVideoOptions
(
videoOptions
)
.
build
()
Java
VideoOptions
VideoOptions
=
VideoOptions
.
Builder
()
.
setCustomControlsRequested
(
true
)
.
build
()
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
setVideoOptions
(
videoOptions
)
.
build
()
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.
Kotlin
val
adCallback
:
NativeAdLoaderCallback
=
object
:
NativeAdLoaderCallback
{
override
fun
onNativeAdLoaded
(
nativeAd
:
NativeAd
)
{
val
mediaContent
=
nativeAd
.
mediaContent
;
if
(
mediaContent
!=
null
)
{
val
videoController
=
mediaContent
.
videoController
;
val
canShowCustomControls
=
videoController
?.
isCustomControlsEnabled
();
}
}
};
Java
NativeAdLoaderCallback
adCallback
=
new
NativeAdLoaderCallback
()
{
@Override
public
void
onNativeAdLoaded
(
@NonNull
NativeAd
nativeAd
)
{
MediaContent
mediaContent
=
nativeAd
.
getMediaContent
();
if
(
mediaContent
!=
null
)
{
VideoController
videoController
=
mediaContent
.
getVideoController
();
if
(
videoController
!=
null
)
{
boolean
canShowCustomControls
=
videoController
.
isCustomControlsEnabled
();
}
}
}
};
Render custom video controls
Render custom video controls using the following best practices:
- 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.
- 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.
Custom click gestures
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.
Call NativeAdRequest.Builder.enableCustomClickGestureDirection()
with a NativeAd.SwipeGestureDirection
and a boolean
value.
The following example implements a custom swipe gesture to the right and preserves normal tab behavior.
-
Custom click gestures is disabled by default.
-
When disabled, your app will support normal clicking behaviour.
-
When enabled, your app will support custom swipe gestures.
The following example implements a custom swipe gesture to the right and preserves normal tab behavior.
Kotlin
val
adOptions
=
NativeAdOptions
.
Builder
()
.
enableCustomClickGestureDirection
(
/* swipeDirection */
NativeAdOptions
.
SWIPE_GESTURE_DIRECTION_RIGHT
,
/* tapsAllowed= */
true
)
.
build
();
// The following sample ad unit ID has been enabled for custom click gestures
// and can be used for testing.
val
adRequest
=
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
listOf
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
withNativeAdOptions
(
adOptions
)
.
build
();
Java
NativeAdOptions
adOptions
=
new
NativeAdOptions
.
Builder
()
.
enableCustomClickGestureDirection
(
/* swipeDirection */
NativeAdOptions
.
SWIPE_GESTURE_DIRECTION_RIGHT
,
/* tapsAllowed= */
true
)
.
build
();
// The following sample ad unit ID has been enabled for custom click gestures
// and can be used for testing.
NativeAdRequest
adRequest
=
new
NativeAdRequest
.
Builder
(
"ca-app-pub-3940256099942544/2247696110"
,
List
.
of
(
NativeAd
.
NativeAdType
.
NATIVE
))
.
withNativeAdOptions
(
adOptions
)
.
build
();
Listen for swipe gesture events
To listen to swipe gesture events, call NativeAd.setAdEventCallback()
with a NativeAdEventCallback
and
implement the onAdSwipeGestureClicked()
method.
Kotlin
val
adCallback
:
NativeAdLoaderCallback
=
object
:
NativeAdLoaderCallback
{
override
fun
onNativeAdLoaded
(
nativeAd
:
NativeAd
)
{
// Implement the onAdSwipeGestureClicked() method.
val
nativeAdCallback
:
NativeAdEventCallback
=
object
:
NativeAdEventCallback
{
override
fun
onAdSwipeGestureClicked
()
{
// A swipe gesture click has occurred.
}
}
}
}
// Load the native ad with the ad request and callback.
NativeAdLoader
.
load
(
adRequest
,
adCallback
)
Java
NativeAdLoaderCallback
adCallback
=
new
NativeAdLoaderCallback
()
{
@Override
public
void
onNativeAdLoaded
(
@NonNull
NativeAd
nativeAd
)
{
// Implement the onAdSwipeGestureClicked() method.
NativeAdEventCallback
nativeAdCallback
=
new
NativeAdEventCallback
()
{
@Override
public
void
onAdSwipeGestureClicked
()
{
// A swipe gesture click has occurred.
}
};
}
};
// Load the native ad with the ad request and callback.
NativeAdLoader
.
load
(
adRequest
,
adCallback
);
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.
