해당 문서는 BuzzAd Ext.point SDK의 광고 지면 타입 중 하나인, Native Type 을 연동하는 문서입니다. Native Type 은 별도의 지면을 구성하지 않고, 기존의 지면에 자연스럽게 광고를 노출할 수 있습니다. 구성하는 방식에 따라, 단일 광고 아이템 노출 외에도 좌우 스크롤 형식으로 여러 개의 광고 아이템을 보여줄 수 있습니다.

다음 과정이 완료 되었는지 확인이 필요합니다.

Android X 환경이 준비 완료 되었는지 (링크)

공통 적용 항목 연동이 완료 되었는지 (링크)

위의 과정 중 완료되지 않은 항목이 있다면, 이전 단계의 연동을 먼저 완료해야 합니다.

다음 항목에 대한 확인이 필요합니다.

Native Type 광고가 노출될 지면이 Activity 또는 Fragment 로 구현되어 있는지

만약 위와 다른 지면에서 구현을 할 경우, 버즈빌의 기술지원 매니저에게 문의 바랍니다.

연동하기

1. 기본 설정을 적용하여 구현하기

광고 요청을 위한 NativeAdLoader 설정하기

[1] NativeAdLoader객체를 생성한 뒤, 발급받은 Unit Id 를 설정합니다. loadAd() 를 호출하여 광고 정보를 받아옵니다.

final String TAG = YourActivity.class.getSimpleName();

// 예시에 적힌 "Native_Unit_Id" 를 '버즈빌에서 발급한 Unit Id'로 교체해 주세요.
final NativeAdLoader loader = new NativeAdLoader("Native_Unit_Id");

// loadAd 로 버즈빌 서버에서 광고 정보를 받아옵니다.
//// 광고 로드 개수에 따라 다음을 적용합니다.
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) {
    	// NativeAd 를 이용하여 광고 View 를 그립니다.
        populateAd(nativeAd);
    }
});

[2] 받아온 정보와 nativeAd 를 이용하여 광고 뷰를 그립니다. (광고 레이아웃에 대한 내용은 아래서 확인 가능합니다.)

광고 레이아웃 생성

앱 내에 레이아웃을 생성하고, 광고 구성 항목들을 뷰에 연결합니다.

[1] 광고 레이아웃의 Root 는 com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView 으로 설정해야 합니다.

[2] NativeAdView 클래스는 하나의 광고에 대응되는 ViewGroup 의 일종으로, 광고를 표시하기 위한 하위 구성 항목이 반드시 이 오브젝트의 child 로 등록되어야 합니다. 하위 구성 항목은 다음과 같습니다.

	Component	Description	Size	Requirements	Required

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

[3] NativeAdView 는 다음과 같은 방식으로 적용합니다.

<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/textTitle"
            ... />
        <TextView
            android:id="@+id/textDescription"
            ... />
        <ImageView
            android:id="@+id/imageIcon"
            ... />
        <com.buzzvil.buzzad.benefit.presentation.media.CtaView
            android:id="@+id/ctaView"
            .../>
    ...
    </LinearLayout>
    ...
</com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView>

[4] 광고 소재를 보여주는 뷰에는 com.buzzvil.buzzad.benefit.presentation.media.MediaView가 반드시 포함되어야 합니다.

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

[광고 요청을 위한 NativeAdLoader 설정하기] 의 onAdLoaded 에서 받은 NativeAd 오브젝트를 이용하여 광고 뷰를 그립니다. 다음과 같은 순서로 구성합니다.

[1] [광고 레이아웃 생성]에서 생성한 광고 뷰에 NativeAd.getAd() 를 통해 가져온 Ad 의 각 요소를 설정합니다.

[2] clickableViews List<View> 를 생성하여 광고 클릭이 가능한 영역을 지정합니다. 해당 뷰 영역을 클릭 할 경우, 광고 랜딩 페이지로 이동하게 됩니다.

[3] NativeAdView 에 clickableViews, MediaView, NativeAd 를 설정합니다.

[4] 광고 참여 완료 후 UI 변경을 위해 NativeAdView 에 OnNativeAdEventListener 를 등록하고, onParticipated 콜백에서 해당 광고에 참여하였음을 표시합니다.

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) Ad 의 각 요소를 세팅합니다.
    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) 광고 클릭이 가능한 영역을 지정합니다.
    final List<View> clickableViews = new ArrayList<>();
    clickableViews.add(ctaView);
    clickableViews.add(mediaView);
    clickableViews.add(titleTextView);
    clickableViews.add(descriptionTextView);

    // (3) NativeAdView 에 다음의 항목을 추가합니다.
    nativeAdView.setClickableViews(clickableViews);
    nativeAdView.setMediaView(mediaView);
    nativeAdView.setNativeAd(nativeAd);

    // Advanced : 광고 View를 Scale 해서 사용하는 경우에 한하여 적용
    // nativeAdView.setScaleValue(SCALE_X_VALUE, SCALE_Y_VALUE);

    // (4) 광고 참여 완료 후 UI 변경을 위해 OnNativeAdEventListener 를 등록합니다.
    nativeAdView.addOnNativeAdEventListener(new NativeAdView.OnNativeAdEventListener() {
        @Override
        public void onImpressed(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {

        }

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

        }

        @Override
        public void onRewardRequested(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {
            // 퍼블리셔 기획에 따라 리워드 로딩 이미지를 보여주는 등의 처리
        }

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

        @Override
        public void onParticipated(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) {
            // 퍼블리셔 기획에 따라 UI 처리
            ctaPresenter.bind(nativeAd);
        }
    });
}

광고의 상태별 콜백에 대해 다양한 커스터마이즈를 원하는 경우, 콜백의 정의 및 동작을 광고 노출/클릭/참여와 관련한 콜백 변화 문서를 참고하여 확인할 수 있습니다.

연동하기

2. 추가 설정, 기능을 적용하기

다음 항목에 대한 확인이 필요합니다.

연동하기 - [1. 기본 설정을 적용하여 구현하기] 를 통해 기본 값으로 구현을 완료한 광고 지면에서 정상적으로 광고를 확인하고 참여할 수 있는지 확인

디자인 커스터마이즈 - CtaView (버튼) Customization

CtaView를 기본 값으로 제공되는 View가 아닌 다른 모양의 View로 변경할 경우, CustomCtaView 를 생성하여 다음과 같이 적용하면 됩니다.

여러 개의 Native 광고 로드하기

NativeAdLoader 의 loadAds(NativeAdLoader.OnAdsLoadedListener listener, int count)를 사용하여 여러 개의 Native 광고를 로드할 수 있습니다. 동일한 크기의 지면에서 좌우 스크롤 방식으로 여러개의 광고를 확인할 수 있습니다.

비디오 에러에 대한 리스너 등록

MediaView에서 발생하는 비디오 이벤트에 대한 리스너를 등록할 수 있습니다.

광고 참여 상태에 따른 CTA 등 소재 표시 분기 처리 방법

버즈빌에서 내려가는 광고는 기본적으로 모두 리워드가 할당되어 있습니다. 광고마다 리워드 적립 주기(기본 2시간)가 설정되어 있고, 사용자가 리워드 적립 주기 내에 동일 광고를 다시 참여하는 경우 리워드는 적립되지 않습니다. 따라서 광고 렌더링시 다음과 같은 방법으로 분기 처리를 하여 기획 의도에 맞는 UI를 사용자에게 보여주어야 합니다.

예를 들어 어떤 광고가 IPU(시간당 노출 제한)이 없이, 리워드 적립 주기는 1시간인 경우, 최초 참여시에는 리워드가 지급 되고 이후 1시간 내에 동일 광고가 노출 되었을 때, 이 광고는 리워드 지급이 되지 않는 상태이므로 CTA 등 UI를 "참여완료" 또는 "0P" 등으로 변경하여 사용자에게 리워드가 지급되지 않는 광고임을 알려주어야 합니다.

분기 처리시 사용되는 필드

[1] Ad 객체의 reward_status: 버즈빌 서버에서 광고를 할당할 때 해당 광고에 대하여 리워드 적립 주기 내에 현재 사용자의 적립 내역이 존재하면 "received" 값을 넣어줍니다.
(주의 사항 - reward_status가 "received"여도 reward의 값은 원래 리워드 금액이 그대로 기록되어 있습니다.)

[2] Ad 객체의 is_participated: 현재 할당 받은 광고들의 참여 상태를 sync하기 위한 값입니다. 광고 참여가 일어나면 해당 광고 및 메모리 상의 동일 광고들의 is_participated값이 true로 바뀌며 onParticipate 콜백이 호출됩니다.
(주의 사항 - 버즈빌 서버에서 광고의 reward_status가 "received"로 내려온 경우에도 이번 할당에서 참여를 다시 하기 전까지 is_participated는 "false"로 설정되어 있습니다.)

분기 처리 예시 pseudo code

Image 타입의 광고 서포트

할당받는 광고의 수를 극대화 하기 위해, 기존에 버즈스크린 잠금화면에 사용하는 Full Screen 광고를 이미지의 일부를 Cropping 한 후 사용 (이하 "Image 타입의 광고")하실 수 있습니다. (자세한 구현 사항은 아래 그림 참조)

Image 타입의 광고의 경우 기존 광고들과 다르게 icon, title, description 의 내용이 없습니다. 더불어 광고 영역 전체의 상하의 길이가 깁니다. 이런 상황에서 레이아웃을 알맞게 그리기 위한 추가 작업을 한 후 해당 광고 타입을 받을 수 있는 NativeAdLoader 의 새로운 메소드를 사용해야 합니다.

View의 Height 조정:
Image 타입의 광고는 기존의 mediaView 보다 상하 길이가 길기 때문에, 모든 광고 view의 height를 wrap_content로 적용하고 기타 height를 고정하는 로직을 제거해야 합니다.
View의 레이아웃 조정:
NativeAd 를 이용해서 광고 뷰를 그리는 과정에서 현재 타입이 Image 인지 확인하여 title, description 을 위한 layout 을 없앱니다. 혹시 광고주 icon에 대해서도 개별적인 layout으로 구현하신 경우에는 이 부분도 없애야 합니다.
광고 로드:
NativeAdLoader 사용 시 다음 예시와 같이 imageTypeEnabled 파라미터를 true 로 설정해서 광고를 로드하면 Image type 의 광고도 받을 수 있습니다.

Buzzvil Developer Guides

[Ext.point] Native Type

다음 과정이 완료 되었는지 확인이 필요합니다.

다음 항목에 대한 확인이 필요합니다.

연동하기

1. 기본 설정을 적용하여 구현하기

광고 요청을 위한 NativeAdLoader 설정하기

광고 레이아웃 생성

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

연동하기

2. 추가 설정, 기능을 적용하기

다음 항목에 대한 확인이 필요합니다.

디자인 커스터마이즈 - CtaView (버튼) Customization

여러 개의 Native 광고 로드하기

비디오 에러에 대한 리스너 등록

광고 참여 상태에 따른 CTA 등 소재 표시 분기 처리 방법

Image 타입의 광고 서포트