네이티브 동영상 광고

GFP SDK 6.5.0 버전부터 네이티브 동영상 광고를 지원합니다. 구현 방식은 기존 네이티브 광고 연동 방식과 동일하며, 네이티브 동영상 광고에 특화된 처리가 필요한 경우 아래 가이드를 참고하세요.

1. 기본 설정

GfpAdLoader 빌드

네이티브 동영상 광고를 로드하기 위한 GfpAdLoader 설정 방법입니다.

Kotlin

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

// 2. 네이티브 동영상 옵션 설정
val nativeVideoOptions = GfpNativeVideoOptions.Builder()
    .autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)
    .backBufferDurationMillis(90_000)
    .build()

// 3. 네이티브 광고 옵션 설정
val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setEnableMediaBackgroundBlur(true)
    .setHasMediaView(true)
    .setTheme(LazyTheme { ResolvedTheme.DARK })
    .setVideoOptions(nativeVideoOptions)
    .build()

// 4. GfpAdLoader 생성
val adLoader = GfpAdLoader.Builder(this, adParam)
    .withAdListener(object : AdEventListener() {
        override fun onError(error: GfpError, responseInfo: GfpResponseInfo) {
            // 에러 처리
        }
    })
    .withNativeAd(nativeAdOptions) { nativeAd ->
        // 광고 렌더링
        inflateNativeAd(nativeAd)
    }
    .build()

Java

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

// 2. 네이티브 동영상 옵션 설정
GfpNativeVideoOptions nativeVideoOptions = new GfpNativeVideoOptions.Builder()
        .autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)
        .backBufferDurationMillis(90_000)
        .build();

// 3. 네이티브 광고 옵션 설정
GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
        .setEnableMediaBackgroundBlur(true)
        .setHasMediaView(true)
        .setTheme(new LazyTheme() {
            @Override
            public ResolvedTheme getTheme() {
                return ResolvedTheme.DARK;
            }
        })
        .setVideoOptions(nativeVideoOptions)
        .build();

// 4. GfpAdLoader 생성
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
        .withAdListener(new AdEventListener() {
            @Override
            public void onError(GfpError error, GfpResponseInfo responseInfo) {
                // 에러 처리
            }
        })
        .withNativeAd(nativeAdOptions, nativeAd -> {
            // 광고 렌더링
            inflateNativeAd(nativeAd);
        })
        .build();

2. 옵션 설정

GfpNativeVideoOptions

네이티브 동영상 광고의 동작을 제어하는 핵심 옵션들입니다.

자동재생 설정

Kotlin

.autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)

Java

.autoPlayBehaviorProvider(GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None)

• 필수 설정: 네앱 숏폼과 같이 커스텀 자동재생 로직이 필요한 경우
• 50% 노출 시 자동재생 등의 규칙을 직접 구현할 때 사용
• GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None 으로 설정 필요

버퍼링 설정

Kotlin

.backBufferDurationMillis(90_000)

Java

.backBufferDurationMillis(90_000)

• 동영상 반복 재생 시 다시 다운로드하지 않도록 설정
• 네앱 숏폼 최대 길이 90초에 맞춰 90_000ms 설정 권장

플레이어 컨트롤 커스터마이징

Kotlin

.adOverlayViewFactory(CustomControlView.Factory())

Java

.adOverlayViewFactory(new CustomControlView.Factory())

• 플레이어 UI (재생/일시정지/음소거 버튼, 타임바) 커스터마이징
• ResolvedAdViewGroup.Factory 를 상속하는 클래스 구성
• 네앱 숏폼의 경우 필수 설정

비트레이트 제한

Kotlin

.maxBitrateKbps(800)

Java

.maxBitrateKbps(800)

• 영상 품질 제어 (기본값: 800kbps)
• 네트워크 환경에 따라 조정 가능

GfpNativeAdOptions

미디어 렌더링과 관련된 기본 옵션들입니다.

배경 블러 효과

Kotlin

.setEnableMediaBackgroundBlur(true)

Java

.setEnableMediaBackgroundBlur(true)

• 필수 설정: 미디어가 렌더링되는 GfpMediaView 여백에 블러 효과 적용
• false 로 설정 시 검은 배경이 표시됨

동영상 옵션 연결

Kotlin

.setVideoOptions(nativeVideoOptions)

Java

.setVideoOptions(nativeVideoOptions)

• 위에서 설정한 GfpNativeVideoOptions 적용

3. 광고 로드

GfpAdLoader 에 대한 설정이 완료되면 다음과 같이 광고를 로드할 수 있습니다.

Kotlin

adLoader.loadAd()

Java

adLoader.loadAd();

4. 광고 렌더링

네이티브 광고가 로드되면 GFP SDK가 GfpAdLoader.Builder 를 통해서 설정했던 withNativeAd() 메서드의 GfpNativeAd.OnNativeAdLoadedListener 리스너를 통해 광고 로드를 알려줍니다.

Kotlin

val adLoader = GfpAdLoader.Builder(this, adParam)
    // . . .
    .withNativeAd(nativeAdOptions) { nativeAd ->
        // 광고가 게재될 placeholder 의 ViewGroup 으로써 adContainer 를 가지고 있다고 가정합니다.
        inflateNativeAd(adContainer, nativeAd)
    }
    .build()

Java

GfpAdLoader adLoader = GfpAdLoader.Builder(this, adParam)
    // . . .
    .withNativeAd(nativeAdOptions, nativeAd -> {
        // 광고가 게재될 placeholder 의 ViewGroup 으로써 adContainer 를 가지고 있다고 가정합니다.
        inflateNativeAd(adContainer, nativeAd);
    })
    .build();

광고가 그려지게 되는 GfpNativeAdView 에 해당 리스너로 전달되는 GfpNativeAd 객체를 채우는 예시는 다음과 같습니다.

Kotlin

fun inflateNativeAd(parent: ViewGroup, nativeAd: GfpNativeAd) {
    // GfpNativeAdView 를 inflate 하여 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

    // Title 을 표시할 뷰를 찾아 텍스트를 설정한 다음 GfpNativeAdView 의 titleView 속성을 사용하여 등록합니다.
    val titleView = adView.findViewById<TextView>(R.id.ad_title)
    titleView.text = nativeAd.title
    adView.titleView = titleView

    // 위와 같은 처리를 반복하여 추가 View 객체들을 설정합니다.

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

    // GfpNativeAdView 의 setNativeAd 를 통해 GfpNativeAd 객체를 등록합니다.
    adView.setNativeAd(nativeAd)

    // 부모 ViewGroup 에 GfpNativeAdView 가 포함되었을 수 있으니 제거하는 과정을 거칩니다.
    parent.removeAllViews()

    // 부모 ViewGroup 에 GfpNativeAdView 를 위치시킵니다.
    parent.addView(adView)
}

Java

void inflateNativeAd(ViewGroup parent, GfpNativeAd nativeAd) {
    // GfpNativeAdView를 inflate하여 parent ViewGroup에 추가합니다.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
        .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.ad_layout_file, parent);

    // Title을 표시할 뷰를 찾아 텍스트를 설정한 다음 GfpNativeAdView의 titleView 속성을 사용하여 등록합니다.
    TextView titleView = adView.findViewById(R.id.ad_title);
    titleView.setText(nativeAd.getTitle());
    ((GfpNativeAdView) adView).setTitleView(titleView);

    // 위와 같은 처리를 반복하여 추가 View 객체들을 설정합니다.

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

    // GfpNativeAdView의 setNativeAd를 통해 GfpNativeAd 객체를 등록합니다.
    ((GfpNativeAdView) adView).setNativeAd(nativeAd);

    // 부모 ViewGroup에 GfpNativeAdView가 포함되었을 수 있으니 제거하는 과정을 거칩니다.
    parent.removeAllViews();

    // 부모 ViewGroup에 GfpNativeAdView를 위치시킵니다.
    parent.addView(adView);
}

5. 미디어 정보 및 동영상 제어

GfpMediaData

GfpMediaView 는 이미지 및 동영상 그리고 좀 더 리치한 View 들을 그릴 수 있도록 설계된 View 이고 GFP SDK 6.2.0 버전 부터는 GfpNativeAd.getMediaData() 메서드를 통해서 GfpMediaView 에 그려질 미디어 들에 대한 정보를 GfpMediaData 객체를 통해서 전달합니다.

GfpMediaData 가 전달하는 정보들은 아래와 같습니다:

Field	Description
mediaType	IMAGE, VIDEO, RICH_MEDIA, UNKNOWN 중 하나의 값을 반환합니다.
aspectRatio	mediaType 이 IMAGE 또는 VIDEO 일 경우 미디어의 비율값을 반환합니다.
videoController	mediaType 이 VIDEO 일 경우에만 반환됩니다. 다른 mediaType 의 경우 null 로 반환됩니다.

GfpNativeVideoController

네이티브 동영상 광고를 컨트롤하고 동영상 광고의 현재 상태를 확인하고자 할 때 유용하게 사용될 수 있는 객체입니다.

정보

GfpNativeVideoOptions 의 autoPlayBehaviorProvider 를 GfpNativeVideoOptions.ResolvedAutoPlayBehavior.None 으로 설정하셔야만 GfpNativeVideoController 가 제공하는 메서드들을 안전하게 사용하실 수 있습니다.

GfpNativeVideoController 가 제공하는 메서드들은 아래와 같습니다:

Method	Description
play()	동영상 광고를 play 합니다. 만약 동영상 광고가 완료된 상태일 경우 play() 를 호출할 경우, 영상은 처음부터 다시 재생이 됩니다.
pause()	동영상 광고를 pause 합니다.
stop()	동영상 광고를 멈추고 플레이어를 해제합니다.
seekTo(positionMillis: Long)	동영상 광고를 주어진 positionMillis 로 이동시킵니다.
mute(muted: Boolean)	동영상 광고의 mute 상태를 설정합니다.
dispatchUserActivationPlayerEvent(muted: Boolean)	동영상 광고를 재생할 때에 SDK 가 스스로 처리하던 Tracking 처리들을 해당 메서드로 처리할 수 있게 됩니다. 이 메서드를 사용할 때에는 GFP SDK 개발팀에게 반드시 문의 주시기 바랍니다.
isMuted()	동영상 광고의 오디오가 mute 상태일 경우에는 true 를 아닌 경우에는 false 를 return 합니다.
isPlaying()	동영상 광고의 재생중인 경우 true 를 아닌 경우에는 false 를 return 합니다.
getAdProgress(): VideoProgressUpdate	동영상 광고의 현재 재생 progress 정보를 반환합니다.
setCallback(callbacks: VideoLifecycleCallbacks)	동영상 광고의 이벤트들을 받는 Callback 을 설정합니다.

이벤트 콜백 설정

Kotlin

videoController.setCallback(object : VideoLifecycleCallbacks {
    // 동영상 이벤트 처리
})

Java

videoController.setCallback(new VideoLifecycleCallbacks() {
    // 동영상 이벤트 처리
});

6. 추가 설정

캐시 설정

아웃스트림 비디오의 캐싱 사이즈를 설정할 수 있습니다. 단위는 MB 이며 캐싱을 비활성화하려면 -1을 입력합니다.

Kotlin

GfpSdk.setSdkProperties(
    GfpSdk.getSdkProperties().buildUpon()
        .addProviderOptions(
            NdaProviderOptions.Builder()
                .setOutStreamVideoCacheSizeMb(50) // 캐시 사이즈(MB), 비활성화하려면 -1 입력
                .build()
        )
        .build()
)

Java

GfpSdk.setSdkProperties(
    GfpSdk.getSdkProperties().buildUpon()
        .addProviderOptions(
            new NdaProviderOptions.Builder()
                .setOutStreamVideoCacheSizeMb(50) // 캐시 사이즈(MB), 비활성화하려면 -1 입력
                .build()
        )
        .build()
);

Control View Type

GFP SDK 7.4.0 버전부터 영상 영역 클릭 시 광고주 url로 랜딩할 수 있는 clickable 아웃스트림용 control view type 을 설정할 수 있습니다.

현재 지원하고 있는 control view type은 다음과 같습니다:

Control View Type	Description	Factory Class
Default	영상 클릭 시 playback control 버튼 노출	DefaultOutStreamVideoControlView.Factory()
Clickable	영상 클릭 시 광고주 사이트로 랜딩	ClickableOutStreamVideoControlView.Factory()

다음과 같이 기존의 GfpNativeVideoOptions.adOverlayViewFactory() 를 통해 clickable 아웃스트림 UI 를 구현할 수 있습니다.

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();