커스텀형 광고

아래 가이드에서는 커스텀형 광고를 로드하고, 표시하고, 성과 수집 하는 방법을 설명합니다.

기본 요건

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

---

테스트 광고 게재위치

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

테스트 게재위치 목록

placementCode	creativeSpecId	설명
SAMPLE_CUSTOM_EXPANDABLE_BANNER	40000001	단일 광고 요청용 게재위치
SAMPLE_MULTIPLE_IMAGE_BANNER	10000002 10000003 10000004	다중 광고 요청용 게재위치

---

광고 로드하기

커스텀형 광고 형식은 NestAdsAdLoader 클래스를 통해 로드됩니다.

NestAdsAdLoader의 자세한 내용은 NestAdsAdLoader섹션에서 확인해주세요.

Kotlin

val adLoader = NestAdsAdLoader.Builder(this, "SAMPLE_CUSTOM_EXPANDABLE_BANNER")
        .forNativeCustomAd(10000001,
            { nativeCustomAd ->
                // 광고를 표시하고 노출을 기록합니다.
            },
            { nativeCustomAd, mediaSpecId ->
              // 미디어스펙별 클릭 이벤트를 핸들링 합니다.
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

forNativeCustomAd 메서드는 커스텀형 광고 형식을 요청하도록 NestAdsAdLoader 를 구성합니다. 이 메서드에는 세 가지 파라미터가 전달됩니다.

• NestAdsAdLoader 에서 요청해야 하는 소재 스펙의 ID.

• 광고가 로드되면 호출되는 OnCustomAdLoadedListener.

• 광고를 탭하거나 클릭할 때 호출될 OnCustomClickListener (optional). 이 리스너에 대한 자세한 내용은 아래의 성과 수집 섹션을 참조하세요.

한 게재위치에서 두 개 이상의 소재 스펙을 게재하도록 forNativeCustomAd 를 여러 번 호출할 수 있습니다.

Kotlin

val builder = NestAdsAdLoader.Builder(this, ${placementCode})
builder.forNativeCustomAd(${creativeSpecId1},
            { nativeCustomAd ->
                // 광고를 표시하고 노출을 기록합니다.
            })
        forNativeCustomAd(${creativeSpecId2},
            { nativeCustomAd ->
                // 광고를 표시하고 노출을 기록합니다.
            })
...
builder.build()

---

소재 스펙 ID

커스텀형 광고 형식을 식별하는 데 사용되는 소재 스펙 ID는 어드민의 인벤토리 > 소재스펙 메뉴에서 확인할 수 있습니다. 소재 스펙 ID는 소재 스펙 등록 시 시스템을 통해 자동으로 생성됩니다.

소재 스펙 메뉴에서 소재 스펙을 등록 시 미디어 스펙을 자유롭게 구성할 수 있습니다.

미디어 스펙 ID는 커스텀형 광고를 표시할 때 각 미디어 스펙의 데이터를 가져오는 데 사용되는 식별자입니다.

VIDEO 미디어 스펙은 ID가 지정되어 있습니다.

---

NestAdsAdListener 및 NestAdsNativeAdOption 설정하기 (optional)

광고 로더를 초기화 할 때 NestAdsAdListener 및 NestAdsNativeAdOption 을 설정할 수 있습니다.

withAdListener 에서는 광고 요청 결과에 대한 리스너를 등록할 수 있습니다.

withNativeAdOptions 에서는 광고의 표시 옵션들을 설정할 수 있습니다.

자세한 내용은 NestAdsAdListener, NestAdsNativeAdOptions 섹션에서 확인해주세요.

---

광고 요청하기

단일 광고 요청

NestAdsAdLoader가 초기화되면 loadAd 메서드를 호출하여 광고를 요청합니다.

Kotlin

adLoader.loadAd(NestAdsAdRequest.Builder().build())

다중 광고 요청

NestAdsAdLoader가 초기화되면 loadAds 메서드를 호출하여 광고를 요청합니다.

Kotlin

adLoader.loadAds(NestAdsAdRequest.Builder().build(), ${maxNumberOfAds})

NestAdsAdRequest 의 자세한 내용은 NestAdsAdRequest 섹션에서 확인해주세요.

---

광고 표시하기

NestAdsNativeCustomtAd 클래스는 미디어 스펙 ID를 파라미터로 사용하는 getText, getImage 등의 메서드를 제공합니다. NestAdsNativeCustomtAd와 함께 사용하는 전용 광고 뷰 클래스는 없습니다. 따라서 사용자 환경에 적합한 모든 레이아웃을 자유롭게 사용할 수 있습니다.

다음은 NestAdsNativeCustomtAd를 표시하는 함수의 예입니다.

Kotlin

public fun displayAd (parent: ViewGroup, nativeCustomAd: NestAdsNativeCustomAd) {
    val adView = layoutInflater.inflate(R.layout.ad_simple_custom, null)

    // TEXT 타입의 "AdText"란 미디어 스펙 ID 가져와서 세팅
    val myAdTextView = adView.findViewById<TextView>(R.id.adtext)
    myAdTextView.setText(nativeCustomAd.getText("AdText"))

    // IMAGE 타입의 "PreviewImage" 란 미디어 스펙 ID 가져와서 세팅
    val myMainBannerView = adView.findViewById(R.id.main_image)
    myMainBannerView.setImageDrawable(nativeCustomAd.getImage("PreviewImage")?.drawable)

    ...
}

---

동영상 미디어 스펙

소재 스펙을 만들 때 동영상을 추가할 수 있습니다.

NestAdsOnCustomAdLoadedListener를 통해 nativeCustomAd 가 들어오면 nativeCustomAd.mediaContent 를 사용하여 미디어 콘텐츠를 가져올 수 있습니다.

그런 다음 NestAdsMediaView를 생성하고, mediaContent에 그 값을 설정합니다. 응답 받은 광고에 동영상이 없는 경우엔 그에 대처하여 코드를 작성해야 합니다.

Kotlin

NestAdsNativeCustomAd.OnCustomAdLoadedListener { ad ->
    val mediaContent = nativeCustomAd.mediaContent
    if (mediaContent != null && mediaContent.hasVideoContent()) {
        val mediaView = NestAdsMediaView(this)
        mediaView.mediaContent = mediaContent

        val videoController = mediaContent.videoController
        if (videoController != null) {
             videoController.videoLifecycleCallbacks =
                  object : NestAdsVideoController.VideoLifecycleCallbacks() {
                       override fun onVideoEnd() {
                            super.onVideoEnd()
                       }
                  }
        }

        binding.customMediaPlaceholder.addView(mediaView)
    } else {
        // 동영상 없을시 대체 이미지
    }
}

동영상 광고의 라이프 사이클에 따라 콜백 함수를 등록할 수 있습니다. 자세한 내용은 VideoLifecycleCallbacks 섹션을 참조하세요.

---

성과 수집

어드민에서 각 성과와 미디어 스펙을 매핑할 수 있습니다. 해당 미디어 스펙의 뷰가 노출되거나 클릭되면 SDK로 성과를 전달해야 합니다.

노출수

성과필드 매핑 > 노출수와 매핑된 미디어 스펙의 뷰가 노출되면 NestAdsNativeCustomAd 에서 recordImpression 메서드를 호출합니다.

Kotlin

nativeCustomAd.recordImpression();

클릭수 및 행동유도 클릭수

성과필드 매핑 > 클릭수/행동유도 클릭수와 매핑된 미디어 스펙의 뷰가 클릭되면 NestAdsNativeCustomAd 에서 performClick 메서드를 호출하고 클릭한 미디어 스펙의 ID를 전달합니다.

예를 들어 'MainImage'라는 미디어 스펙이 있고 이 미디어 스펙에 해당하는 ImageView의 클릭을 보고하려는 경우 코드는 다음과 같습니다.

Kotlin

public fun displayAd (parent: ViewGroup, nativeCustomAd: NestAdsNativeCustomAd) {
    ...
    // IMAGE 타입의 "PreviewImage" 란 미디어 스펙 ID 가져와서 세팅
    val myMainBannerView = adView.findViewById(R.id.main_image)
    myMainBannerView.setImageDrawable(nativeCustomAd.getImage("PreviewImage").drawable)

    //Mainimage의 클릭 리스너에서 .performClick 수행
    myMainBannerView.setOnClickListener {
        nativeCustomAd.performClick("PreviewImage")
    }

    ...
}

performClick을 호출하면 다음의 일을 수행합니다.

1. 해당 미디어 스펙의 클릭 성과 수집

2. forNativeCustomAd 의 세 번째 파라미터인 OnCustomClickListener을 등록한 경우 해당 함수 호출

3. OnCustomClickListener을 등록하지 않은 경우, 해당 미디어 스펙에 랜딩 URL 이 등록되어 있으면 해당 URL 오픈

각 성과 수집에는 NestAds 자체 트래킹 및 외부 트래킹 내용이 모두 포함되어 있습니다.