Native Video Ads

GFP SDK version 6.5.0 and above supports native video ads. The implementation method is the same as the existing native ad integration method. For cases that require specialized handling for native video ads, please refer to the guide below.

1. Basic Setup

GfpAdLoader Build

This is how to configure GfpAdLoader for loading native video ads.

Kotlin

// 1. Create AdParam
val adParam = AdParam.Builder()
    .setAdUnitId("YOUR_AD_UNIT_ID")
    .build()

// 2. Configure native video options
val nativeVideoOptions = GfpNativeVideoOptions.Builder()
    .autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)
    .backBufferDurationMillis(90_000)
    .build()

// 3. Configure native ad options
val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setEnableMediaBackgroundBlur(true)
    .setHasMediaView(true)
    .setTheme(LazyTheme { ResolvedTheme.DARK })
    .setVideoOptions(nativeVideoOptions)
    .build()

// 4. Create GfpAdLoader
val adLoader = GfpAdLoader.Builder(this, adParam)
    .withAdListener(object : AdEventListener() {
        override fun onError(error: GfpError, responseInfo: GfpResponseInfo) {
            // Error handling
        }
    })
    .withNativeAd(nativeAdOptions) { nativeAd ->
        // Ad rendering
        inflateNativeAd(nativeAd)
    }
    .build()

Java

// 1. Create AdParam
AdParam adParam = new AdParam.Builder()
        .setAdUnitId("YOUR_AD_UNIT_ID")
        .build();

// 2. Configure native video options
GfpNativeVideoOptions nativeVideoOptions = new GfpNativeVideoOptions.Builder()
        .autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)
        .backBufferDurationMillis(90_000)
        .build();

// 3. Configure native ad options
GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
        .setEnableMediaBackgroundBlur(true)
        .setHasMediaView(true)
        .setTheme(new LazyTheme() {
            @Override
            public ResolvedTheme getTheme() {
                return ResolvedTheme.DARK;
            }
        })
        .setVideoOptions(nativeVideoOptions)
        .build();

// 4. Create GfpAdLoader
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
        .withAdListener(new AdEventListener() {
            @Override
            public void onError(GfpError error, GfpResponseInfo responseInfo) {
                // Error handling
            }
        })
        .withNativeAd(nativeAdOptions, nativeAd -> {
            // Ad rendering
            inflateNativeAd(nativeAd);
        })
        .build();

2. Option Configuration

GfpNativeVideoOptions

These are the core options that control the behavior of native video ads.

Auto-play Configuration

Kotlin

.autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)

Java

.autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)

• Required setting: When custom auto-play logic is needed, such as in Naver Shorts
• Used when implementing rules like auto-play at 50% visibility directly
• Must be set to GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None

Buffering Configuration

Kotlin

.backBufferDurationMillis(90_000)

Java

.backBufferDurationMillis(90_000)

• Configure to avoid re-downloading when video is played repeatedly
• Recommended to set to 90_000ms to match Naver Shorts maximum length of 90 seconds

Player Control Customization

Kotlin

.adOverlayViewFactory(CustomControlView.Factory())

Java

.adOverlayViewFactory(new CustomControlView.Factory())

• Customize player UI (play/pause/mute buttons, timeline)
• Configure a class that inherits from ResolvedAdViewGroup.Factory
• Required setting for Naver Shorts

Bitrate Limitation

Kotlin

.maxBitrateKbps(800)

Java

.maxBitrateKbps(800)

• Control video quality (default: 800kbps)
• Can be adjusted according to network environment

GfpNativeAdOptions

These are the basic options related to media rendering.

Background Blur Effect

Kotlin

.setEnableMediaBackgroundBlur(true)

Java

.setEnableMediaBackgroundBlur(true)

• Required setting: Apply blur effect to the margins of GfpMediaView where media is rendered
• If set to false, a black background will be displayed

Video Options Connection

Kotlin

.setVideoOptions(nativeVideoOptions)

Java

.setVideoOptions(nativeVideoOptions)

• Apply the GfpNativeVideoOptions configured above

3. Ad Loading

Once the configuration for GfpAdLoader is complete, you can load ads as follows.

Kotlin

adLoader.loadAd()

Java

adLoader.loadAd();

4. Ad Rendering

When a native ad is loaded, the GFP SDK notifies you of the ad load through the GfpNativeAd.OnNativeAdLoadedListener listener of the withNativeAd() method that was configured through GfpAdLoader.Builder.

Kotlin

val adLoader = GfpAdLoader.Builder(this, adParam)
    // . . .
    .withNativeAd(nativeAdOptions) { nativeAd ->
        // Assuming we have adContainer as a ViewGroup that will serve as a placeholder for the ad
        inflateNativeAd(adContainer, nativeAd)
    }
    .build()

Java

GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    // . . .
    .withNativeAd(nativeAdOptions, nativeAd -> {
        // Assuming we have adContainer as a ViewGroup that will serve as a placeholder for the ad
        inflateNativeAd(adContainer, nativeAd);
    })
    .build();

Here's an example of filling the GfpNativeAd object passed through the listener into the GfpNativeAdView where the ad will be drawn:

Kotlin

fun inflateNativeAd(parent: ViewGroup, nativeAd: GfpNativeAd) {
    // Inflate GfpNativeAdView and add it to the parent ViewGroup
    val inflater = parent.context.getSystemService(Context.LAYOUT_INFLATER_SERVICE) as LayoutInflater
    val adView = inflater.inflate(R.layout.ad_layout_file, parent) as GfpNativeAdView

    // Find the view to display the title, set the text, then register it using the titleView property of GfpNativeAdView
    val titleView = adView.findViewById<TextView>(R.id.ad_title)
    titleView.text = nativeAd.title
    adView.titleView = titleView

    // Repeat the above process to set up additional View objects

    val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
    adView.mediaView = mediaView

    // Register the GfpNativeAd object through setNativeAd of GfpNativeAdView
    adView.setNativeAd(nativeAd)

    // Remove the process as GfpNativeAdView may be included in the parent ViewGroup
    parent.removeAllViews()

    // Position GfpNativeAdView in the parent ViewGroup
    parent.addView(adView)
}

Java

void inflateNativeAd(ViewGroup parent, GfpNativeAd nativeAd) {
    // Inflate GfpNativeAdView and add it to the parent ViewGroup
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
        .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.ad_layout_file, parent);

    // Find the view to display the title, set the text, then register it using the titleView property of GfpNativeAdView
    TextView titleView = adView.findViewById(R.id.ad_title);
    titleView.setText(nativeAd.getTitle());
    ((GfpNativeAdView) adView).setTitleView(titleView);

    // Repeat the above process to set up additional View objects

    MediaView mediaView = adView.findViewById(R.id.ad_media);
    ((GfpNativeAdView) adView).setMediaView(mediaView);

    // Register the GfpNativeAd object through setNativeAd of GfpNativeAdView
    ((GfpNativeAdView) adView).setNativeAd(nativeAd);

    // Remove the process as GfpNativeAdView may be included in the parent ViewGroup
    parent.removeAllViews();

    // Position GfpNativeAdView in the parent ViewGroup
    parent.addView(adView);
}

5. Media Information and Video Control

GfpMediaData

GfpMediaView is a View designed to draw images, videos, and richer Views, and from GFP SDK version 6.2.0, information about media to be drawn in GfpMediaView is delivered through the GfpMediaData object via the GfpNativeAd.getMediaData() method.

The information delivered by GfpMediaData is as follows:

Field	Description
mediaType	Returns one of the values: IMAGE, VIDEO, RICH_MEDIA, UNKNOWN.
aspectRatio	Returns the aspect ratio value of the media when mediaType is IMAGE or VIDEO.
videoController	Only returned when mediaType is VIDEO. Returns null for other mediaType values.

GfpNativeVideoController

This is an object that can be usefully used when you want to control native video ads and check the current state of video ads.

info

You must set autoPlayBehaviorProvider of GfpNativeVideoOptions to GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None to safely use the methods provided by GfpNativeVideoController.

The methods provided by GfpNativeVideoController are as follows:

Method	Description
play()	Plays the video ad. If the video ad is in a completed state, calling play() will restart the video from the beginning.
pause()	Pauses the video ad.
stop()	Stops the video ad and releases the player.
seekTo(positionMillis: Long)	Moves the video ad to the given positionMillis.
mute(muted: Boolean)	Sets the mute state of the video ad.
dispatchUserActivationPlayerEvent(muted: Boolean)	Allows you to handle tracking processes that the SDK was handling by itself when playing video ads through this method. Please contact the GFP SDK development team when using this method.
isMuted()	Returns true if the audio of the video ad is muted, otherwise returns false.
isPlaying()	Returns true if the video ad is playing, otherwise returns false.
getAdProgress(): VideoProgressUpdate	Returns the current playback progress information of the video ad.
setCallback(callbacks: VideoLifecycleCallbacks)	Sets a callback to receive events from the video ad.

Event Callback Configuration

Kotlin

videoController.setCallback(object : VideoLifecycleCallbacks {
    // Handle video events
})

Java

videoController.setCallback(new VideoLifecycleCallbacks() {
    // Handle video events
});

6. Additional Configuration

Cache Configuration

You can set the caching size for outstream videos. The unit is MB, and enter -1 to disable caching.

Kotlin

GfpSdk.setSdkProperties(
    GfpSdk.getSdkProperties().buildUpon()
        .addProviderOptions(
            NdaProviderOptions.Builder()
                .setOutStreamVideoCacheSizeMb(50) // Cache size (MB), enter -1 to disable
                .build()
        )
        .build()
)

Java

GfpSdk.setSdkProperties(
    GfpSdk.getSdkProperties().buildUpon()
        .addProviderOptions(
            new NdaProviderOptions.Builder()
                .setOutStreamVideoCacheSizeMb(50) // Cache size (MB), enter -1 to disable
                .build()
        )
        .build()
);

Control View Type

From GFP SDK version 7.4.0, you can set a clickable outstream control view type that can land on the advertiser's URL when clicking on the video area.

The control view types currently supported are as follows:

Control View Type	Description	Factory Class
Default	Shows playback control button when video is clicked	DefaultOutStreamVideoControlView.Factory()
Clickable	Lands on advertiser's site when video is clicked	ClickableOutStreamVideoControlView.Factory()

You can implement clickable outstream UI through the existing GfpNativeVideoOptions.adOverlayViewFactory() as follows:

Kotlin

val nativeVideoOptions = GfpNativeVideoOptions.Builder()
    .adOverlayViewFactory(ClickableOutStreamVideoControlView.Factory()) // clickable outstream ui
    // ...
    .build()

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setVideoOptions(nativeVideoOptions)
    // ...
    .build()

val adLoader = GfpAdLoader.Builder(this, adParam)
    .withNativeAd(nativeAdOptions) { nativeAd -> /* . . . */ }
    // ...
    .build()

Java

GfpNativeVideoOptions nativeVideoOptions = new GfpNativeVideoOptions.Builder()
    .adOverlayViewFactory(new ClickableOutStreamVideoControlView.Factory()) // clickable outstream ui
    // ...
    .build();

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setVideoOptions(nativeVideoOptions)
    // ...
    .build();

GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    .withNativeAd(nativeAdOptions, nativeAd -> { /* . . . */ })
    // ...
    .build();