카드형 배너 광고

아래 가이드에서는 카드 배너 광고를 로드하고, 표시하는 방법을 설명합니다.

기본 요건

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

---

테스트 광고 게재위치

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

테스트 게재위치 목록

placementCode	설명
SAMPLE_MULTIPLE_IMAGE_BANNER_CARD_APP	복수개의 이미지 배너 카드 자동 캐러셀 지원 인디케이터 및 리스트 뷰 지원

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

---

광고 표시하기

1. 카드 배너 광고가 표시되기 원하는 화면에서 NestAdsCardBannerAdView 를 설정하고 로드합니다.

Kotlin

val cardBannerAdView = NestAdsCardBannerAdView(this)

// 게재위치 설정
cardBannerAdView.placementCode = "SAMPLE_MULTIPLE_IMAGE_BANNER_CARD_APP"

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

// (선택) 복수개의 광고 제공이 필요할 경우 설정할 수 있습니다.
cardBannerAdView.setMaxNumberOfAds(5)

// 광고 리스너를 설정
cardBannerAdView.adListener = object : NestAdsAdListener() {
    override fun onAdLoaded() {
    // 광고 로드가 완료되면 할 행동
    }

    override fun onAdFailedToLoad(error: NestAdsAdError) {
        // 복수개 광고 제공이 필요할 경우 setMaxNumberOfAds 에서 요청한 광고 개수보다
        // 적은 수의 광고가 도착할 경우를 대비하여 추가해 줍니다.
        if (error.code == 3001) {
            onAdLoaded()
            return
        }
        // 광고 로드가 실패하면 할 행동
    }

    override fun onAdOpened() {
        // 광고가 전체 화면 콘텐츠를 표시할 때 호출
    }
    
    override fun onAdClickedWithAdId(adId: Long) {
        // 광고 클릭 시 호출
    }
    
    override fun onAdImpressionWithAdId(adId: Long) {
        // 광고 노출 시 호출
    }
}

// 카드 배너 전용 리스너 설정
// onIndicatorClicked는 
// NestAdsCardBannerOptions.adList.useCustomClickAction = true로 설정되어 있어야 호출됩니다.
cardBannerAdView.setCardBannerAdListener(object : NestAdsCardBannerAdListener() {
    override fun onIndicatorClicked(response: List<NestAdsCardBannerAdResponse>) {
        // 인디케이터를 클릭하면 할 행동  
    }

    override fun onListPopupOpened() {
        // 리스트 팝업이 열리면 할 행동 
    }

    override fun onListPopupClosed() {
        // 리스트 팝업이 닫히면 할 행동
    }
})
// 인디케이터 설정
val indicatorOption = NestAdsIndicatorOption.Builder()
    .setOpacity(100f)
    .setSize(NestAdsIndicatorSize.MEDIUM)
    .build()

val carouselOption = NestAdsCarouselOption.Builder()
    .setTransitionDuration(500) // 배너 전환 시간 (ms)
    .setDisplayDuration(3000) // 배너 대기 시간 (ms)
    .setIndicatorOption(indicatorOption)
    .build()

val adListOption = NestAdsAdListOptions.Builder()
    .setUseCustomClickAction(false) // 커스텀 클릭 동작 사용 여부
    .build()

// (선택) 카드 배너의 스타일 관련 옵션 설정
cardBannerAdView.setCardBannerOption(
    NestAdsCardBannerOptions.Builder()
        .setBackgroundColor("#FFFFFF") // 배경색 설정
        .setCardBannerRadius(8) // 모서리 둥근 정도 (dp)
        .setOpacity(1.0f) // 투명도 (0.0 ~ 1.0)
        .setCarouselOptions(carouselOption)
        .setAdListOptions(adListOption)
        .build()
)

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

---

자동 스크롤

카드 배너는 복수의 광고가 있을 경우 자동으로 스크롤됩니다.

• 자동 스크롤 조건: 광고가 화면에 조금이라도 노출되면 동작 (0% 초과)

• 일시정지: 화면에 0% 노출 시 자동 스크롤 일시정지

• 재개: 다시 화면에 노출되면 자동 스크롤 재개

50% 가시성 기준은 노출(Impression) 로그 전송에만 적용됩니다. 자동 스크롤은 0% 가시성일 때만 일시정지됩니다.

---

Public API

NestAdsCardBannerAdView

카드 배너 광고를 표시하는 뷰입니다.

속성

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

메서드

메서드	설명
setAdSize(adSize: NestAdsAdSize)	광고 영역의 크기를 설정합니다.
setMaxNumberOfAds(maxNumberOfAds: Int)	요청할 최대 광고 개수를 설정합니다. (1~99)
setCardBannerOption(options: NestAdsCardBannerOptions)	카드 배너의 스타일 및 동작 옵션을 설정합니다.
setCardBannerAdListener(listener: NestAdsCardBannerAdListener)	카드 배너 전용 이벤트 리스너를 설정합니다.
loadAd(nestAdsAdRequest: NestAdsAdRequest)	광고를 요청하고 로드합니다.
destroy()	광고 뷰의 리소스를 정리합니다.

---

NestAdsCardBannerOptions

카드 배너 광고의 스타일 및 동작을 커스터마이징하는 옵션입니다.

Builder 메서드

메서드	파라미터	설명
setBackgroundColor(backgroundColor: String?)	HEX 색상 코드 (예: "#FFFFFF")	카드 배너의 배경색을 설정합니다.
setCardBannerRadius(radius: Int)	0 이상의 정수 (dp)	카드 배너의 모서리 둥근 정도를 설정합니다.
setOpacity(opacity: Float)	0.0 ~ 1.0	카드 배너의 투명도를 설정합니다.
setCarouselOptions(carousel: NestAdsCarouselOption)	NestAdsCarouselOption	캐러셀 관련 옵션을 설정합니다.
setAdListOptions(adList: NestAdsAdListOptions)	NestAdsAdListOptions	광고 리스트 관련 옵션을 설정합니다.

예시

Kotlin

val options = NestAdsCardBannerOptions.Builder()
    .setBackgroundColor("#F5F5F5")
    .setCardBannerRadius(12)
    .setOpacity(0.95f)
    .setCarouselOptions(
        NestAdsCarouselOption.Builder()
        .setAutoScroll(true)
        .setAutoScrollInterval(4000L)
        .build()
    )
    .build()

cardBannerAdView.setCardBannerOption(options)

---

NestAdsCardBannerAdListener

카드 배너 광고의 사용자 상호작용 이벤트를 처리하는 리스너입니다.

메서드

메서드	파라미터	설명
onIndicatorClicked(response: List)	광고 응답 리스트	인디케이터(광고 개수 표시)를 클릭했을 때 호출됩니다.
onListPopupOpened()	-	광고 리스트 팝업이 열렸을 때 호출됩니다.
onListPopupClosed()	-	광고 리스트 팝업이 닫혔을 때 호출됩니다.

---

Reference

• NestAdsCardBannerAdView

• NestAdsCardAdListener

• NestAdsCardBannerOptions