Table of Contents

exclude	.*(BuzzAd-Benefit

SDK: Type A - Native Ads|주의사항)

개요

본 가이드는 BuzzAd -Benefit SDK의 네이티브 Native 타입 광고를 연동하는 방법을 다루는 문서입니다.

...

Note
Native

...

타입을 연동하기 전,

...

시작하기의 연동 사항을 모두 적용했는지

...

확인해주세요.

...

Native 타입 광고가 노출될 지면이 Activity 또는 Fragment로 구현되어 있어야 합니다. 만일 이와 다르게 구현되어있다면 버즈빌 측에 사전 문의 부탁드립니다.

Index

Table of Contents

exclude	.*(BuzzAd-Benefit SDK: Type A - Native Ads\|주의사항)

Step 1: `NativeAdLoader` 로 광고 요청

NativeAdLoader 객체를 인스턴스화
- YOUR_NATIVE_AD_UNIT_ID 세팅
loadAd() 호출

Step1. 광고 요청

YOUR_NATIVE_UNIT_ID 세팅 후 NativeAdLoader인스턴스를 생성하고, loadAd() 를 호출합니다.

Code Block

language	java

final String TAG = YourActivity.class.getSimpleName();
final NativeAdLoader loader = new NativeAdLoader("YOUR_NATIVE_AD_UNIT_ID");
loader.loadAd(new NativeAdLoader.OnAdLoadedListener() {
    @Override
    public void onLoadError(@NonNull AdError adError) {
        Log.e(TAG, "Failed to load a native ad.", adError);
    }

    @Override
    public void onAdLoaded(@NonNull NativeAd nativeAd) {
    	populateAd(nativeAd); // Step 3 참고
    }
});

...

Step2. 광고 레이아웃 생성

...

Benefit 2.5.X 버전 이후로 버즈빌의 광고는, 일반 광고와 쇼핑 광고를 구분하여 보여주고 있습니다. 기존에 연동 중인 경우, 기존 사용하던 광고를 일반 광고로 구분합니다.

다음은 일반 광고를 매체사 앱 내에 레이아웃을 생성하고 광고 컴포넌트들을 관련 뷰에 연결합니다.

BuzzAd Benefit 광고 레이아웃의 Root 는 com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView 으로 설정되어야 합니다.
- NativeAdView 클래스는 하나의 광고에 대응되는 ViewGroup 의 일종으로, 광고를 표시하기 위한 하위 컴포넌트들은 반드시 이 오브젝트의 child 로 등록되어야 합니다.
광고 소재를 보여주는 뷰에는 com.buzzvil.buzzad.benefit.presentation.media.MediaView가 반드시 포함되어야 합니다.

하위 컴포넌트

...

Component

...

Description

...

Size

...

Requirements

...

Required

...

Media view

...

이미지, 동영상 등 광고 소재

...

Activity 또는 Fragment 레이아웃 내에 아래 구조에 맞게 `NativeAdView` 레이아웃을 추가합니다.
Component
Description
Size
Requirements
Required
Media view
이미지, 동영상 등 광고 소재
1200x627 px
Aspect ratio 유지 권장
이미지 주위에 패딩 추가 가능
Y
Title view
광고의 제목
최대 25자10자
생략 부호로 일정 길이 이상은 생략 가능
Y
Description view
광고에 대한 상세 설명
최대 100자40자
생략 부호로 일정 길이 이상은 생략 가능
Y
CTA view
Reward text view: 액션 시 지급되는 포인트 금액
CTA text view: 광고의 액션을 유도하는 문구
최대 15자7자
생략 부호로 일정 길이 이상은 생략 가능
Y
Icon image view
광고주 아이콘 이미지
80x80 px
Aspect ratio 유지 권장
Y
Sponsored
image/ text view
광고임을 나타내는 텍스트 또는 이미지
-
광고, ad, 스폰서, Sponsored 등의 문구를 노출
N
...

NativeAdView의 레이아웃 예시

위에서 설명한 UI 컴포넌트 (예. MediaView) 는 NativeAdView 의 하위 컴포넌트로 구현해야합니다.
그 이외 구조는 기획에 맞게 변경할 수 있습니다.

Code Block

language	java

<com.buzzvil.buzzad.benefit.presentation.nativead

...

Step 2-2: 광고 레이아웃 생성 - 쇼핑 광고

다음은 쇼핑 광고를 매체사 앱 내에 레이아웃을 생성하고 광고 컴포넌트들을 관련 뷰에 연결합니다. 일반 광고와 다르게, 원가 (price) + 할인율 (discountPercentageText) + 할인된 가격 (discountedPrice) + 상품 카테고리 (category) 가 추가 되었습니다.

...

Layout에 com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView를 추가하고, 다음과 같은 component를 추가합니다.

...

Component

...

Description

...

Size

...

Requirements

...

Required

...

Media view

...

이미지, 동영상 등 광고 소재

...

1200x627 px

...

Aspect ratio 유지 권장
이미지 주위에 패딩 추가 가능

...

Y

...

Description view

...

광고에 대한 상세 설명

...

최대 100자

...

생략 부호로 일정 길이 이상은 생략 가능

...

Y

...

Price view

...

상품의 가격 정보

...

-

...

Y

...

Original price View

...

할인이 있을 경우, 원래 가격 정보

...

-

...

Y

...

Category view

...

상품의 카테고리 정보

...

-

...

N

...

CTA view

...

Reward text view: 액션 시 지급되는 포인트 금액
CTA text view: 광고의 액션을 유도하는 문구

...

최대 15자

...

생략 부호로 일정 길이 이상은 생략 가능

...

Y

...

Sponsored
image/ text view

...

광고임을 나타내는 텍스트 또는 이미지

...

-

...

광고, ad, 스폰서, Sponsored 등의 문구를 노출

...

N

Code Block

language	xml

<?xml version="1.0" encoding="utf-8"?>
<com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView
    android:id="@+id/native_ad_view"
    ...>
    <LinearLayout
        ...>
        <com.buzzvil.buzzad.benefit.presentation.media.MediaView
            android:id="@+id/mediaView"
            ... />
        <TextView
            android:id="@+id/textDescription"
            ... />
        <TextView
            android:id="@+id/priceText"
            ... />
        <TextView
            android:id="@+id/originalPriceText"
            ... />
        <TextView
            android:id="@+id/discountPercentageText"
            ... />
        <TextView
            android:id="@+id/categoryText"
            ... />
        <com.buzzvil.buzzad.benefit.presentation.media.CtaView
            android:id="@+id/ctaView"
            ... />
    ...
    </LinearLayout>
    ...
</com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView>

쇼핑 광고 적용하기

쇼핑 광고와 일반 광고 구분 - Step 1: NativeAdLoader 로 광고 요청할 때, CPS 광고를 확인할 수 있습니다.

Expand

title	NativeAdLoader 로 광고 요청할 때, CPS 광고를 확인

Code Block

language	java

final String TAG = YourActivity.class.getSimpleName();
final NativeAdLoader loader = new NativeAdLoader("YOUR_NATIVE_AD_UNIT_ID");
loader.loadAd(new NativeAdLoader.OnAdLoadedListener() {
    @Override
    public void onLoadError(@NonNull AdError adError) {
        Log.e(TAG, "Failed to load a native ad.", adError);
    }

    @Override
    public void onAdLoaded(@NonNull NativeAd nativeAd) {
    	final AdRevenueType revenueType = AdRevenueType.getAdRevenueTypeFromName(ad.getRevenueType());
        if (AdRevenueType.CPS.equals(revenueType)) {
            // CPS 광고
            populateCPSAd(nativeAd);
        } else {
            // 다른 타입의 광고
            populateAd(nativeAd);
        }
    }
});

CPS 광고에 제공되는 추가정보는 다음과 같이 가져올 수 있습니다.

Expand

title	CPS 광고에 제공되는 추가정보

Code Block

language	java

private void populateCPSAd(final NativeAd nativeAd) {
    final Ad ad = nativeAd.getAd();
    final Product product = ad.getProduct();
    if (product != null) {
        if (product.getDiscountedPrice() != null) {
            // 할인된 가격 정보. 할인중인 상품이 아닌경우, null 값이 반환됨
        }
        long originalPrice = product.getPrice();
        String category = product.getCategory();
    } 
}

(중요) 사용 예시

private void populateCPSAds(final NativeAd nativeAd) { final Ad ad = nativeAd.getAd(); final Product product = ad.getProduct(); if (product != null) { if (product.getDiscountedPrice() != null) { // 할인이 있는 쇼핑 광고 originalPriceText.setPaintFlags(originalPriceText.getPaintFlags() | Paint.STRIKE_THRU_TEXT_FLAG); int percentage = 0; // 할인된 가격 정보로 할인율을 계산하여 보여줄 수 있습니다 if (product.getPrice() > product.getDiscountedPrice()) { percentage = Math.round(((product.getPrice() - product.getDiscountedPrice()) / product.getPrice() * 100)); } if (percentage > 0) { // 할인이 있는 쇼핑 광고의 경우 원래 가격, 할인 가격, 할인율을 아래와 같이 표기할 수 있습니다 priceText.setText(getCommaSeparatedPrice(product.getDiscountedPrice().longValue())); originalPriceText.setText(getCommaSeparatedPrice((long) product.getPrice())); discountPercentageText.setText(String.format(Locale.ROOT, "%d%%", percentage)); discountPercentageText.setVisibility(View.VISIBLE); } else { // 할인 가격이 있지만 원래 가격과 차이가 없는 경우, 아래와 같이 원래의 가격만 노출합니다 priceText.setText(getCommaSeparatedPrice((long) product.getPrice())); originalPriceText.setText(""); discountPercentageText.setVisibility(View.GONE); } } else { // 할인이 없는 쇼핑 광고의 경우 원래의 가격만 노출합니다 priceText.setText(getCommaSeparatedPrice((long) product.getPrice()));

.NativeAdView
    android:id="@+id/native_ad_view"
    ...생략... >
  
    <com.buzzvil.buzzad.benefit.presentation.media.MediaView
        android:id="@+id/mediaView"

originalPriceText.setText("");

...생략... />
    <TextView

discountPercentageText.setVisibility(View.GONE);

 android:id="@+id/textTitle"

}

...생략... />
    <TextView

//

카테고리가

있는

경우

아래와

같이 노출 할 수 있습니다.

 android:id="@+id/textDescription"

categoryText.setText(product.getCategory());

...생략... />
    <ImageView

if

(!TextUtils.isEmpty(product.getCategory()))

{

    android:id="@+id/imageIcon"

categoryText.setVisibility(View.VISIBLE);

...생략... />

}

<com.buzzvil.buzzad.benefit.presentation.media.CtaView

}

// 아래와 같이 가격 정보를 format하여 UI 가독성을 높일 수 있습니다 private String getCommaSeparatedPrice (long price) { return String.format(Locale.getDefault(), "₩%,d", price); }

Expand

title	사용 예시

Code Block

language	java

Step 3: `NativeAd` 오브젝트로 레이아웃 구성

Step 1 의 onAdLoaded 에서 받은 NativeAd 오브젝트를 이용하여 광고 뷰를 그립니다.

...

위 Step 2에서 생성한 광고 컴포넌트 뷰에 NativeAd.getAd() 를 통해 가져온 Ad 의 각 요소를 세팅합니다.

...

android:id="@+id/ctaView"
        ...생략... />

    ...생략...
</com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView>

Step3. NativeAd 레이아웃에 데이터를 바인딩

할당 받은 광고 데이터를 NativeAdView에 바인딩 합니다.

clickableViews 리스트에 광고 컴포넌트를 추가하여, 클릭 이벤트를 수신할 컴포넌트를 설정합니다.
clickableViews에 추가된 광고 컴포넌트를 클릭 시 광고 페이지로 이동하게 됩니다.
NativeAdView 에 clickableViews, MediaView, NativeAd 를

...

설정해야합니다.
CTA 버튼은 CtaPresenter 를 이용하여 상황에 맞는 적절한 문구로 변경됩니다.

...

OnNativeAdEventListener 를 통해 광고 콜백 이벤트를 수신할 수 있습니다.
기획에 따라 추가로 UI 등을 추가할 수 있습니다.

Code Block

language	java

public void populateAd(final NativeAd nativeAd) {
    final NativeAdView view = findViewById(R.id.native_ad_view);

    final Ad ad = nativeAd.getAd();
    final Creative.Type creativeType = ad.getCreative() == null ? null : ad.getCreative().getType();
    
    final MediaView mediaView = view.findViewById(R.id.mediaView);
    final TextView titleTextView = view.findViewById(R.id.textTitle);
    final ImageView iconView = view.findViewById(R.id.imageIcon);
    final TextView descriptionTextView = view.findViewById(R.id.textDescription);
    final CtaView ctaView = view.findViewById(R.id.ctaView);
    final CtaPresenter ctaPresenter = new CtaPresenter(ctaView); // CtaView should not be null
    ctaPresenter.bind(nativeAd);

    // 1) Assign Ad Properties.
    if (mediaView != null) {
        mediaView.setCreative(ad.getCreative());
        mediaView.setVideoEventListener(new VideoEventListener() {
            // Override

...

 and implement methods
            // 고급 설정 참조
        });
    }

    if (titleTextView != null) {
        titleTextView.setText(ad.getTitle());
    }

    if (iconView != null) {
        ImageLoader.getInstance().displayImage(ad.getIconUrl(), iconView);
    }

    if (descriptionTextView != null) {
        descriptionTextView.setText(ad.getDescription());
    }

    // 2) Create a list of clickable views.
    final List<View> clickableViews = new ArrayList<>();
    clickableViews.add(ctaView);
    clickableViews.add(mediaView);
    clickableViews.add(titleTextView);
    clickableViews.add(descriptionTextView);

    // 3) Register ClickableViews, MediaView and NativeAd to NativeAdView.

...

view.setClickableViews(clickableViews);

...

view.setMediaView(mediaView);

...

view.setNativeAd(nativeAd);

    // Advanced : 광고 View를 Scale 해서 사용하는 경우에 한하여 적용
    //

...

view.setScaleValue(SCALE_X_VALUE, SCALE_Y_VALUE);

    // 4) Add OnNativeAdEventListener to NativeAdView and implement participated UI.

...

view.addOnNativeAdEventListener(new NativeAdView.OnNativeAdEventListener() {
        @Override
        public void onImpressed(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {
  
        }

        @Override
        public void onClicked(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {

...

ctaPresenter.bind(nativeAd);
            // 기획에 따른 추가적인

...

UI 처리
        }

        @Override
        public void onRewardRequested(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {
            //

...

 기획에 따라 리워드 로딩 이미지를 보여주는 등의 처리
        }

        @Override
        public void onRewarded(@NonNull NativeAdView view, @NonNull NativeAd nativeAd, @Nullable RewardResult rewardResult) {
            // 리워드 적립의 결과 (RewardResult) SUCCESS, ALREADY_PARTICIPATED, MISSING_REWARD 등에 따라서 적절한 유저 커뮤니케이션 처리
        }

        @Override
        public void onParticipated(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {

...

ctaPresenter.bind(nativeAd);
            // 기획에 따른 추가적인

...

UI 처리
        }
    });
}

...

광고의 상태별 콜백에 대해

...

커스터마이즈를

...

하는 경우에 광고 노출/클릭/참여와 관련한 콜백 변화 문서

...

참고하여 콜백의 정의 및 동작을 파악할 수 있습니다.
CtaView (버튼)를 추가적으로 커스터마이징하는 경우는 디자인 커스터마이징을 참고

Versions Compared

Old Version 3

New Version Current

Key

개요

Step 1: `NativeAdLoader` 로 광고 요청

Step1. 광고 요청

Step2. 광고 레이아웃 생성

NativeAdView의 레이아웃 예시

Step 2-2: 광고 레이아웃 생성 - 쇼핑 광고

Step 3: `NativeAd` 오브젝트로 레이아웃 구성

Step3. NativeAd 레이아웃에 데이터를 바인딩

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

개요

Step 1: NativeAdLoader 로 광고 요청

Step1. 광고 요청

Step2. 광고 레이아웃 생성

NativeAdView의 레이아웃 예시

Step 2-2: 광고 레이아웃 생성 - 쇼핑 광고

Step 3: NativeAd 오브젝트로 레이아웃 구성

Step3. NativeAd 레이아웃에 데이터를 바인딩

Step 1: `NativeAdLoader` 로 광고 요청

Step 3: `NativeAd` 오브젝트로 레이아웃 구성