리치 팝업 광고

아래 가이드에서는 리치 팝업 광고를 로드하고, 표시하는 방법을 설명합니다.

기본 요건

시작 가이드에 따라 필요한 과정을 완료합니다.

---

테스트 광고 게재위치

Placement Code(게재위치 코드)는 어드민의 인벤토리 > 게재위치 메뉴에서 게재위치를 등록 시 시스템을 통해 자동으로 생성됩니다.

어드민의 인벤토리 > 광고상품 > 광고상품 등록 메뉴에서 리치 팝업 광고의 소재 스펙 및 기본 레이아웃을 설정할 수 있습니다.

---

광고 표시하기

1. 리치 팝업 광고가 표시되기 원하는 화면에서 NestAdsRichPopupAdView를 설정하고 로드합니다.

Kotlin

val richPopupAdView = NestAdsRichPopupAdView(this)

// 게재위치 설정
richPopupAdView.placementCode = "YOUR_PLACEMENT_CODE"

// (선택) 광고 영역의 사이즈를 설정할 수 있습니다. 설정하지 않으면 기본값(FLUID)으로 표기됩니다.
richPopupAdView.setAdSize(NestAdsAdSize.FLUID)

// 광고 리스너를 설정
richPopupAdView.adListener = object : NestAdsAdListener() {
    override fun onAdLoaded() {
        // 광고 로드가 완료되면 팝업을 표시합니다.
        richPopupAdView.show()
    }

    override fun onAdFailedToLoad(error: NestAdsAdError) {
        // 광고 로드가 실패하면 할 행동
    }

    override fun onAdOpened() {
        // 광고가 전체 화면 콘텐츠를 표시할 때 호출
    }

    override fun onAdClosed() {
        // 리치 팝업이 종료 될 때 호출
    }

    override fun onAdClickedWithAdId(adId: Long?) {
        // 광고 클릭 시 호출
    }

    override fun onAdImpressionWithAdId(adId: Long?) {
        // 광고 노출 시 호출
    }
}

// 리치 팝업 전용 리스너 설정
richPopupAdView.setListener(object : NestAdsRichPopupAdListener() {
    override fun onFailedToShow() {
        // 광고 표시 실패 시 호출
    }

    override fun onCtaButtonClicked() {
        // CTA 버튼 클릭 시 호출
    }

    override fun onCountdownFinished() {
        // 카운트다운 완료 시 호출 (카운트다운 광고에서만 호출됨)
    }
})

// (선택) 비디오 광고의 생명주기 콜백 설정
richPopupAdView.setVideoCallback(object : NestAdsVideoController.VideoLifecycleCallbacks() {
    override fun onVideoStart() {
        // 비디오 최초 재생 시작 시 호출
    }

    override fun onVideoPlay() {
        // 비디오 재생 시 호출
    }

    override fun onVideoPause() {
        // 비디오 일시정지 시 호출
    }

    override fun onVideoEnd() {
        // 비디오 종료 시 호출
    }

    override fun onVideoMute(muted: Boolean) {
        // 음소거 상태 변경 시 호출
    }
})

// CTA 버튼 옵션 설정
val buttonOptions = NestAdsButtonOptions.Builder()
    .setBackgroundColor("#000000")
    .setFontColor("#FFFFFF")
    .setOpacity(0.8f)
    .build()

// 비디오 옵션 설정
val videoOptions = NestAdsStandardVideoOptions.Builder()
    .setStartMuted(true)
    .setPlayCondition(NestAdsVideoOptions.NEST_ADS_PLAY_CONDITION_AUTO_START)
    .setProgressBarColor("#FFFFFF")
    .setMuteButtonColor("#FFFFFF")
    .build()

// (선택) 리치 팝업의 스타일 관련 옵션 설정
richPopupAdView.setOptions(
    NestAdsRichPopupOptions.Builder()
        .setBackgroundColor("#000000")
        .setCloseButtonColor("#FFFFFF")
        .setButtonOptions(buttonOptions)
        .setVideoOptions(videoOptions)
        .build()
)

// 광고를 요청합니다.
richPopupAdView.loadAd(NestAdsAdRequest.Builder().build())

---

카운트다운 기능

리치 팝업은 어드민에서 설정한 경우 카운트다운 기능을 지원합니다.

• 카운트다운 활성화: 어드민에서 광고상품 설정 시 카운트다운 옵션을 활성화

• 카운트다운 완료 시: onCountdownFinished() 콜백이 호출됩니다.

• 닫기 버튼: 카운트다운이 완료되기 전까지 닫기 버튼이 비활성화될 수 있습니다.

카운트다운 설정은 어드민의 광고상품 설정에서 관리됩니다. SDK에서는 별도의 카운트다운 설정이 필요하지 않습니다.

---

팝업 닫기

리치 팝업을 코드에서 직접 닫아야 하는 경우 dismiss() 메서드를 사용합니다.

Kotlin

// 팝업 닫기
richPopupAdView.dismiss()

dismiss() 호출 시 내부적으로 destroy()도 함께 호출되어 리소스가 정리됩니다.

---

Public API

NestAdsRichPopupAdView

리치 팝업 광고를 표시하는 뷰입니다.

속성

속성	타입	설명
placementCode	String?	게재위치 코드
adListener	NestAdsAdListener?	광고 이벤트 리스너

메서드

메서드	설명
setAdSize(adSize: NestAdsAdSize)	광고 영역의 크기를 설정합니다.
setOptions(options: NestAdsRichPopupOptions)	리치 팝업의 스타일 및 동작 옵션을 설정합니다.
setListener(listener: NestAdsRichPopupAdListener)	리치 팝업 전용 이벤트 리스너를 설정합니다.
setVideoCallback(callback: NestAdsVideoController.VideoLifecycleCallbacks)	비디오 생명주기 콜백을 설정합니다.
loadAd(nestAdsAdRequest: NestAdsAdRequest)	광고를 요청하고 로드합니다.
show()	리치 팝업 광고를 화면에 표시합니다.
dismiss()	리치 팝업을 닫고 리소스를 해제합니다.
destroy()	광고 뷰의 리소스를 정리합니다.

---

NestAdsRichPopupOptions

리치 팝업 광고의 스타일 및 동작을 커스터마이징하는 옵션입니다.

Builder 메서드

메서드	파라미터	설명
setButtonOptions(buttonOptions: NestAdsButtonOptions)	NestAdsButtonOptions	CTA 버튼의 스타일 옵션을 설정합니다.
setVideoOptions(videoOptions: NestAdsStandardVideoOptions)	NestAdsStandardVideoOptions	비디오 플레이어의 옵션을 설정합니다.
setBackgroundColor(color: String)	HEX 색상 코드 (예: "#000000")	리치 팝업의 배경색을 설정합니다.
setCloseButtonColor(color: String)	HEX 색상 코드 (예: "#FFFFFF")	닫기 버튼의 색상을 설정합니다.

예시

Kotlin

val options = NestAdsRichPopupOptions.Builder()
    .setBackgroundColor("#000000")
    .setCloseButtonColor("#FFFFFF")
    .setButtonOptions(
        NestAdsButtonOptions.Builder()
            .setBackgroundColor("#FF5722")
            .setFontColor("#FFFFFF")
            .build()
    )
    .setVideoOptions(
        NestAdsStandardVideoOptions.Builder()
            .setStartMuted(true)
            .setProgressBarColor("#FFFFFF")
            .build()
    )
    .build()

richPopupAdView.setOptions(options)

---

NestAdsRichPopupAdListener

리치 팝업 광고의 사용자 상호작용 이벤트를 처리하는 리스너입니다.

메서드

메서드	설명
onFailedToShow()	리치 팝업 광고 표시에 실패했을 때 호출됩니다.
onCtaButtonClicked()	CTA(Call-to-Action) 버튼이 클릭되었을 때 호출됩니다.
onCountdownFinished()	카운트다운이 완료되었을 때 호출됩니다. (카운트다운 광고에서만)

---

Reference

• NestAdsRichPopupAdView

• NestAdsRichPopupAdListener

• NestAdsRichPopupOptions

• NestAdsButtonOptions

• NestAdsStandardVideoOptions