개요

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

Step1. 광고 요청

YOUR_NATIVE_AD_UNIT_ID 세팅 후 NativeAdLoader 객체를 인스턴스화하고, loadAd() 를 호출 합니다.

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 으로 설정되어야 합니다.

• Layout에 NativeAdView를 추가하고, 다음과 같은 component를 추가합니다.

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>

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

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

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

2. clickableViews list를 생성하여 광고 클릭이 가능하도록 설정할 영역을 지정합니다. 해당 뷰 영역을 클릭 시 광고 랜딩 페이지로 이동하게 됩니다.

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) 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.
       nativeAdView.setClickableViews(clickableViews);
       nativeAdView.setMediaView(mediaView);
       nativeAdView.setNativeAd(nativeAd);
   
       // Advanced : 광고 View를 Scale 해서 사용하는 경우에 한하여 적용
       // nativeAdView.setScaleValue(SCALE_X_VALUE, SCALE_Y_VALUE);
   
       // 4) Add OnNativeAdEventListener to NativeAdView and implement participated UI.
       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) {
               // Action형 광고에 대한 CTA 처리
               ctaPresenter.bind(nativeAd);
           }
   
           @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) {
               // 퍼블리셔 기획에 따라 UI 처리
               ctaPresenter.bind(nativeAd);
           }
       });
   }

5. (Optional) 광고의 상태별 콜백에 대해 다양한 커스터마이즈를 원하는 경우 콜백의 정의 및 동작은 광고 노출/클릭/참여와 관련한 콜백 변화 문서 참고

6. (Optional) 광고의 디자인 커스터마이즈를 원하는 경우 하단의 디자인 커스터마이징을 참고