Native ads provides the following advanced features that let you customize your ad integration:
- Video playback controls: Customize video playback behavior and listen to video lifecycle events.
- AdChoices icon placement: Customize the placement of the AdChoices icon.
- Custom click gestures: Configure swipe gestures as click actions.
This guide shows you how to use the advanced features of native ads with Google Mobile Ads SDK for React Native.
Prerequisites
Before you continue, do the following:
Manage video playback and events
When requesting native ads that contain video assets, customize video playback startup options, listen to video lifecycle events, and control video playback.
Configure video request options
To customize initial video behavior, set the
videoOptions property on the
NativeAdRequest object using a
VideoOptions object.
The following example sets the video to start muted when playback begins:
export async function loadNativeVideoAd(
adUnitId: string,
): Promise<NativeAd | null> {
try {
const ad = await NativeAd.load({
adUnitId,
videoOptions: {
// Autoplay video with sound muted.
startMuted: true,
},
});
// Inspect video metadata if the ad contains video content.
if (ad.mediaContent.hasVideoContent) {
console.log('Video duration in seconds:', ad.mediaContent.duration);
console.log('Video aspect ratio:', ad.mediaContent.aspectRatio);
}
return ad;
} catch (error) {
const loadError = error as LoadAdError;
console.error('Failed to load native video ad:', loadError.message);
return null;
}
}
After the ad loads, this example also checks if the ad contains a video asset, logs the video metadata, and returns the loaded ad. On failure, the example logs an error message.
For more information about video metadata properties, such as aspect ratio,
current time, and duration, see MediaContent.
Listen to video events
To listen for video lifecycle events, such as when a video starts or ends,
pass event callbacks from the
VideoControllerEventProps interface to
the NativeAdMediaView component.
The following example passes callbacks to log video lifecycle events and renders custom buttons to control video playback:
export function NativeAdWithVideoControls({ad}: {ad: NativeAd}) {
const mediaViewRef = useRef<NativeAdMediaViewMethods>(null);
return (
<NativeAdView ad={ad}>
{/* Video lifecycle callbacks */}
<NativeAdMediaView
ref={mediaViewRef}
// Called when video playback starts.
onVideoStart={() => {
console.log('Video playback started.');
}}
// Called when video playback resumes or plays.
onVideoPlay={() => {
console.log('Video is playing.');
}}
// Called when video playback pauses.
onVideoPause={() => {
console.log('Video playback paused.');
}}
// Called when video playback completes.
onVideoEnd={() => {
console.log('Video playback finished.');
}}
// Called when the video mute state changes.
onVideoMute={(isMuted: boolean) => {
console.log(`Video mute state changed: ${isMuted}`);
}}
/>
{/* Custom playback controls (Ad Manager customControlsRequested only) */}
<View>
{/* Plays or resumes the video. */}
<Button
title="Play"
onPress={() => mediaViewRef.current?.playVideo()}
/>
{/* Pauses video playback. */}
<Button
title="Pause"
onPress={() => mediaViewRef.current?.pauseVideo()}
/>
{/* Stops video playback and resets the playback position to the beginning. */}
<Button
title="Stop"
onPress={() => mediaViewRef.current?.stopVideo()}
/>
{/* Mutes or unmutes audio. */}
<Button
title="Mute"
onPress={() => mediaViewRef.current?.setVideoMuted(true)}
/>
<Button
title="Unmute"
onPress={() => mediaViewRef.current?.setVideoMuted(false)}
/>
</View>
</NativeAdView>
);
}
When you enable custom controls, control video playback by
attaching the ref property of the
NativeAdMediaViewMethods type to the
NativeAdMediaView component. The
NativeAdMediaViewMethods type aliases the
VideoControllerMethods interface, which
exposes the playVideo, pauseVideo, stopVideo, and
setVideoMuted methods on the ref object.
Configure AdChoices placement
To customize the placement of the AdChoices icon, specify the
adChoicesPlacement property on the
NativeAdRequest object using the
AdChoicesPlacement object.
The following example configures the AdChoices icon placement in the top-left corner on the ad request:
export async function loadNativeAdWithAdChoicesPlacement(
adUnitId: string,
): Promise<NativeAd | null> {
try {
const ad = await NativeAd.load({
adUnitId,
// Render the AdChoices icon in the top-left corner.
adChoicesPlacement: AdChoicesPlacement.TOP_LEFT,
});
return ad;
} catch (error) {
const loadError = error as LoadAdError;
console.error('Failed to load native ad:', loadError.message);
return null;
}
}
This example also returns the loaded ad on success and logs an error message on failure.
Configure custom click gestures
Configure swipe gestures as click actions on native ads using the
customClickGestureDirection
and
customClickGestureAllowTaps
properties on the NativeAdRequest object.
The following example configures the gesture direction as a right swipe and allows taps when loading an ad:
export async function loadNativeAdWithCustomClick(
adUnitId: string,
): Promise<NativeAd | null> {
try {
const ad = await NativeAd.load({
adUnitId,
// Require a right swipe gesture for clicks while allowing standard taps.
customClickGestureDirection: SwipeGestureDirection.RIGHT,
customClickGestureAllowTaps: true,
});
if (ad.isCustomClickGestureEnabled) {
console.log('Custom click gestures are enabled for this ad.');
}
return ad;
} catch (error) {
const loadError = error as LoadAdError;
console.error('Failed to load native ad:', loadError.message);
return null;
}
}
This example also checks if custom click gestures are enabled, returns the loaded ad on success, and logs an error on failure.
After loading the ad, check the
ad.isCustomClickGestureEnabled
property to verify whether custom click gestures are active for that ad.
Next steps
After you've configured your native ads advanced features, you can learn about the following: