고급 설정

이 페이지에서는 BuzzAd Android용 SDK의 네이티브 지면애서 구현할 수 있는 기능을 확인할 수 있습니다.

CTA 버튼 자체 구현하기

BuzzAd Android용 SDK에서 기본으로 제공하는 UI를 사용하지 않고 CTA 버튼을 직접 구현할 수 있습니다.

CTA 버튼을 직접 구현하려면 다음의 절차를 따르세요.

1. 뷰 레이아웃(view_customized_cta.xml)을 구현하세요.
   다음은 레이아웃 리소스로 뷰 레이아웃을 구현한 예시입니다.

   <!-- view_customized_cta.xml -->
   
   <LinearLayout
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:background="@color/colorPrimaryDark">
       <!-- CTA 버튼의 텍스트 -->    
       <TextView
           android:id="@+id/textCta"/>
           
       <!-- CTA 버튼의 아이콘 이미지 -->
       <ImageView
           android:id="@+id/imageReward"
           android:layout_width="24dp"
           android:layout_height="24dp"
           android:src="아이콘 이미지 리소스"/>
   
       <!-- CTA 버튼의 리워드 텍스트 -->
       <TextView
           android:id="@+id/textReward"/>
   </LinearLayout>

2. CtaView 클래스를 상속하는 서브클래스인 CustomCtaView를 생성하세요.

3. CtaView 클래스에서 사용하던 CTA View 레이아웃을 inflate하도록 구현하세요.

4. 사용자의 광고 참여 상태에 따라 호출되는 아래의 오버라이딩 메소드에서 CTA 버튼의 아이콘 이미지, 텍스트, 리워드 값을 구현하세요.

• renderViewParticipatingState : 사용자가 광고에 참여 중인 상태 (예: 액션형 광고의 랜딩 페이지에 진입한 상태)

• renderViewParticipatedState : 사용자가 광고 참여를 완료한 상태

• renderViewRewardAvailableState : 사용자가 아직 광고에 참여하지 않은 상태

• renderViewRewardNotAvailableState : 사용자가 획득할 리워드가 없는 광고

  public class CustomCtaView extends CtaView {
      private final ImageView rewardImageView;
      private final TextView rewardTextView;
      private final TextView ctaTextView;
          
      public CustomCtaView(@NonNull Context context) {
          this(context, null);
      }
  
      public CustomCtaView(@NonNull Context context, @Nullable AttributeSet attrs) {
          this(context, attrs, 0);
      }
  
      public CustomCtaView(@NonNull Context context, @Nullable AttributeSet attrs, int defStyleAttr) {
          super(context, attrs, defStyleAttr);
          // TODO:  기존에 사용하던 CTA View 레이아웃을 inflate 하도록 구현하세요.
          inflate(getContext(), R.layout.view_customized_cta, this);
          this.rewardImageView = findViewById(R.id.imageReward);
          this.rewardTextView = findViewById(R.id.textReward);
          this.ctaTextView = findViewById(R.id.textCta);        
      }
  
      // CTA 텍스트 설정
      public void setCtaText(String ctaText) {
          ctaTextView.setText(ctaText);
      }
      // CTA 리워드 값 설정
      public void setRewardText(String rewardText) {
          rewardTextView.setText(rewardText);
      }
      // CTA 아이콘 설정
      public void setRewardIcon(@DrawableRes int iconResId) {
          rewardImageView.setImageResource(iconResId);
          rewardImageView.setVisibility(View.VISIBLE);
      }
      // CTA 아이콘 숨기기 처리
      public void hideRewardIcon() {
          rewardImageView.setVisibility(View.GONE);
      }   
          
      // 사용자가 광고에 참여 중인 상태
      @Override
      public void renderViewParticipatingState(@NonNull String callToAction) {
          setCtaText("참여 확인 중");
          hideRewardIcon();
          setRewardText("");
      }
      // 사용자가 광고 참여를 완료한 상태
      @Override
      public void renderViewParticipatedState(@NonNull String callToAction) {
          setRewardIcon(R.drawable.my_participated_icon);
          setRewardText("");
          setCtaText("참여 완료");
      }
      // 사용자가 아직 광고에 참여하지 않은 상태
      @Override
      public void renderViewRewardAvailableState(@NonNull String callToAction, int reward) {
          setRewardIcon(R.drawable.my_reward_icon);
          setRewardText(String.format(Locale.US, "+%,d", reward));
          setCtaText(callToAction);
      }
      // 사용자가 획득할 리워드가 없는 광고
      @Override
      public void renderViewRewardNotAvailableState(@NonNull String callToAction) {
          hideRewardIcon();
          setRewardText("");
          setCtaText(callToAction);
      }
  }

5. 새로 생성한 CustomCtaView 클래스의 경로를 네이티브 광고 레이아웃에 설정하세요. 다음은 네이티브 광고의 레이아웃 예시입니다.

   <com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView
       android:id="@+id/native_ad_view">
       <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"/>        
       <!-- TODO: 새로 생성한 CustomCtaView 클래스 경로를 설정합니다. -->
       <com.your.packagename.CustomCtaView
           android:id="@+id/customCtaView"/>
   </com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView>

6. 다음 순서에 따라 직접 구현한 CTA 버튼을 네이티브 광고에 반영하세요.

   i. 네이티브 광고 레이아웃에서 NativeAdView와 커스텀 CTA 버튼인 CustomCtaView를 가져오세요.

   ii. loadAd()메소드를 호출한 후 네이티브 광고가 성공적으로 할당되어 onAdLoaded 콜백 메소드가 호출되면, NativeAdViewBinder의 ctaView 속성을 customCtaView로 설정하세요.

   iii. bind()를 호출하여 광고 레이아웃에 광고 데이터를 바인딩하세요.

   final NativeAdView nativeAdView = findViewById(R.id.native_ad_view);
   final MediaView mediaView = nativeAdView.findViewById(R.id.mediaView);
   final TextView titleTextView = nativeAdView.findViewById(R.id.textTitle);
   final ImageView iconImageView = nativeAdView.findViewById(R.id.imageIcon);
   final TextView descriptionTextView = nativeAdView.findViewById(R.id.textDescription);
   
   // Native 광고 레이아웃에서 CustomCtaView 를 가져옵니다.
   final CustomCtaView customCtaView = nativeAdView.findViewById(R.id.customCtaView);
   
   final NativeAdRequest nativeAdRequest = new NativeAdRequest.Builder().build();
   final BuzzAdNative buzzAdNative = new BuzzAdNative("YOUR_NATIVE_UNIT_ID");
       
   buzzAdNative.loadAd(nativeAdRequest, new BuzzAdNative.AdLoadListener() {
       @Override
       public void onAdLoaded(@NotNull NativeAd nativeAd) {
           // 할당된 광고가 있으면 호출됩니다.
           // 광고 데이터를 바인딩합니다.
           final NativeAdViewBinder viewBinder = new NativeAdViewBinder.Builder(nativeAdView, mediaView)
               .titleTextView(titleTextView)
               .descriptionTextView(descriptionTextView)
               .iconImageView(iconImageView)
               .ctaView(customCtaView)
               .build();
           viewBinder.bind(nativeAd);
       }
   
       @Override
       public void onLoadFailed(@NotNull AdError adError) {
           // 할당된 광고가 없으면 호출됩니다.
           Log.e(TAG, "Failed to load a native ad.", adError);
       }
   });

✏️  참고
SDK에서 제공하는 DefaultCtaView로 구현한 CTA 버튼의 디자인을 변경하려면 CTA 버튼 커스터마이징하기 토픽을 참고하세요.

⚠️ 주의
CustomCtaView 클래스는 난독화 되지 않도록 Proguard 설정에서 제외해야 합니다. Proguard 설정 파일에 다음 라인을 추가하세요.

-keep class com.your.packagename.CustomCtaView { *; }

네이티브 오버레이 추가하기

사용자가 네이티브 광고에 참여한 후 앱으로 되돌아오면 참여 완료 광고 위에 피드 진입을 유도하는 텍스트와 아이콘이 오버레이되도록 설정할 수 있습니다. 텍스트와 아이콘으로 구성되는 이 UI는 최소 1분의 간격을 두고 표시됩니다. 예를 들어, 네이티브 오버레이가 표시된 이후에 1분 동안은 광고 참여 후에 네이티브 오버레이가 표시되지 않습니다.

네이티브 오버레이를 사용하려면 Native 지면의 기본 설정 시 enableNativeToFeedOverlay()를 추가하세요.

✏️  참고
Native 지면의 기본 설정에 대한 자세한 내용은 네이티브 지면 기본 설정 토픽을 참고하세요.

viewBinder.bind(nativeAd);

nativeAdView.enableNativeToFeedOverlay(); // Native Overlay 기능 활성화

onResume에서 Native 광고 할당 요청을 수행하면 앱으로 되돌아온 후에 광고가 재할당되어 네이티브 오버레이가 표시되지 않습니다. 네이티브 광고 할당에 대한 자세한 내용은 3 단계. 광고 할당 및 표시하기 토픽을 참고하세요.

한 번에 여러 개의 광고 로드하기

한 번의 광고 요청으로 여러 개의 광고를 할당받을 수 있습니다. 최대 10개까지 가능하며, 추가로 광고를 할당받으려면 버즈빌 담당자에게 문의하세요.

다음은 NATIVE_ADS_COUNT를 지정하여 여러 개의 광고를 할당받는 예시입니다.

final NativeAdsRequest nativeAdsRequest = new NativeAdsRequest.Builder()
    .adCount(NATIVE_ADS_COUNT) // 한 번에 로드할 광고 개수를 설정합니다. 
    .build();
final BuzzAdNative buzzAdNative = new BuzzAdNative("YOUR_NATIVE_AD_UNIT_ID");

buzzAdNative.loadAds(nativeAdsRequest, new BuzzAdNative.AdsLoadListener() {
    @Override
    public void onAdsLoaded(@NonNull List<NativeAd> ads) {
        // 광고 할당이 성공하면 호출됩니다.
        // TODO: 광고 표시 단락을 참고하여 구현합니다. 
    }

    @Override
    public void onLoadFailed(@NonNull AdError error) {
        // 할당된 광고가 없으면 호출됩니다.
        Log.e(TAG, "Failed to load a native ad.", error);
    }
});

광고 객체 재사용하기

광고 객체 재사용을 위해 광고와 뷰를 연결을 해제하는 인터페이스가 BuzzAd Android용 SDK v3.5.x부터 추가되었습니다. 자체적으로 피드 지면 또는 그리드 형식으로 UI를 구현하는 등 광고 객체를 재사용하는 경우, 광고와 뷰를 연결하는 과정 외에도 뷰가 필요 없어졌을 때 둘의 연결을 해제하는 필요합니다. 광고와 뷰의 연결을 해제하면 광고를 새로운 뷰와 연결하거나 뷰를 새로운 광고와 연결할 수 있습니다.

이를 위해 BuzzAd Android용 SDK에서는 광고와 뷰의 연결을 해제하는 방법으로 NativeAdViewBinder.unbind()를 제시합니다. 다음의 예시를 참고하세요.

✅  중요
이 기능은 BuzzAd Android용 SDK v3.5.x부터 추가할 수 있습니다. v3.5.x 미만의 버전을 연동한 경우 이 기능을 탑재하려면 v3.5.x 이상으로 업데이트하세요.

1. RecyclerView의 Adapter에서 코드 예제와 같이 구현하세요.

   class MyAdapter extends .... {
       ....
       @Override
       public void onViewRecycled(final ViewHolder holder) {
           super.onViewRecycled(holder);
           // unbind를 반드시 호출하여 재사용할 때 문제가 발생하지 않게 합니다.
           holder.unbind();
       }
   }

2. RecyclerView의 ViewHolder는 NativeAd와 View를 bind할 때 사용한 NativeAdViewBinder 객체를 버리지 않고 들고 있습니다. unbind 에서 광고와 뷰의 관계를 해제하세요.

   class MyAdapter extends .... {
       protected static class ViewHolder extends RecyclerView.ViewHolder {
   
           private final NativeAdViewBinder nativeAdViewBinder;
   
           public ViewHolder(final ViewItemBinding binding) {
               super(binding.getRoot());
   
               nativeAdViewBinder = new NativeAdViewBinder.Builder(
                       binding.getRoot(),
                       binding.mediaView
               )
                       ....
                       .build();
           }
           void bind(final NativeAd nativeAd) {
               nativeAdViewBinder.bind(nativeAd);
           }
       }
   
       public void bind(NativeAd nativeAd) {
           final MediaView mediaView = nativeAdView.findViewById(R.id.mediaView);
           final TextView titleTextView = nativeAdView.findViewById(R.id.textTitle);
           final ImageView iconImageView = nativeAdView.findViewById(R.id.imageIcon);
           final TextView descriptionTextView = nativeAdView.findViewById(R.id.textDescription);
           final DefaultCtaView ctaView = nativeAdView.findViewById(R.id.ctaView);

   protected static class ViewHolder extends RecyclerView.ViewHolder {
       ....
       void unbind() {
           this.nativeAdViewBinder.unbind();
       }
   }

광고 이벤트 리스너 등록하기

✏️  참고
광고 참여 상태에 따라 CTA View를 변경하기 위해 이벤트 리스너를 사용했다면, 더 이상 사용할 필요 없습니다.
>

✏️  참고
리워드 적립 결과(RewardResult) 종류는 리워드 적립 결과(RewardResult) 종류를 참고하세요.

NativeAdEventListener 를 통해 광고 콜백 이벤트를 수신할 수 있습니다. 광고 콜백 이벤트를 수신하려면 NativeAdViewBinder.bind() 함수를 호출한 이후에 리스너를 등록해야 합니다.

다음은 NativeAd에 광고 이벤트 리스너를 등록하는 예시입니다.

// Native 지면의 UNIT ID로 BuzzAdNative 객체를 생성합니다. 
final BuzzAdNative buzzAdNative = new BuzzAdNative("YOUR_NATIVE_UNIT_ID");

buzzAdNative.loadAd(nativeAdRequest, new BuzzAdNative.AdLoadListener() {
    @Override
    public void onAdLoaded(@NonNull NativeAd nativeAd) {
        // 할당된 광고가 있으면 호출됩니다.             
        // NativeAdViewBinder에 Native 광고 컴포넌트를 등록합니다.
        final NativeAdViewBinder viewBinder = new NativeAdViewBinder.Builder(nativeAdView, mediaView)
            .titleTextView(titleTextView)
            .descriptionTextView(descriptionTextView)
            .iconImageView(iconImageView)
            .ctaView(ctaView)
            .build();
        viewBinder.bind(nativeAd); // 광고 데이터를 바인딩합니다. 
        
        // Optional: Native 광고의 리스너 등록하고 각 이벤트에 따라 필요한 기능을 구현합니다.
        // 자세한 내용은 아래 광고 이벤트 등록 단락을 참고하세요. 
        // 주의: 반드시 NativeAdViewBinder.bind() 함수를 호출한 이후에 리스너 등록을 해야합니다.
        handleNativeCallbackListener(nativeAd);
    }
    // ...생략
});

public void handleNativeCallbackListener(final NativeAd nativeAd){
    // 광고 콜백 이벤트를 수신할 수 있습니다.
    // 중복하여 호출하면 2개 이상의 리스너가 등록됩니다.
    nativeAd.addNativeAdEventListener(new NativeAdEventListener() {
        @Override
        public void onImpressed(@NonNull NativeAd nativeAd) {
            // Native 광고가 유저에게 노출되었을 때
        }

        @Override
        public void onClicked(@NonNull NativeAd nativeAd) {
            // 유저가 Native 광고를 클릭했을 때
            // TODO: 기획에 따른 추가적인 UI 처리
        }

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

        @Override
        public void onRewarded(@NonNull NativeAd nativeAd, @Nullable RewardResult rewardResult) {
            // 리워드 적립 결과(RewardResult) 종류는 '리워드 적립 결과(RewardResult) 종류' 항목을 참고하세요.
            // 리워드 적립 결과 (RewardResult): SUCCESS, ALREADY_PARTICIPATED, MISSING_REWARD 
            // TODO: 리워드 적립 결과에 따라 적절한 유저 커뮤니케이션 처리
        }

        @Override
        public void onParticipated(@NonNull NativeAd nativeAd) {
            // TODO: 기획에 따른 추가적인 UI 처리
        }
    });
}

동영상 광고 리스너 등록하기

동영상 광고에서 발생하는 콜백 이벤트를 수신할 수 있습니다.

다음은 MediaView에 동영상 광고 이벤트 리스너를 등록하는 예시입니다.

mediaView.setVideoEventListener(new com.buzzvil.buzzad.benefit.presentation.video.VideoEventListener() {
  @Override
  public void onVideoStarted() {
  }

  @Override
  public void onError(@NonNull VideoErrorStatus videoErrorStatus, @Nullable String errorMessage) {
    if (errorMessage != null) {
        Toast.makeText(mediaView.getContext(), errorMessage, Toast.LENGTH_SHORT).show();
    }
  }

  @Override
  public void onResume() {
  }

  @Override
  public void onPause() {
  }

  @Override
  public void onReplay() {
  }

  @Override
  public void onVideoEnded() {
    // 동영상 재생 완료 시 필요한 처리
  }

  @Override
  public void onLanding() {
    // 동영상 광고 랜딩 시 필요한 처리
  }
});

광고 타입 확인하기

BuzzAd Android용 SDK는 노출형, 액션형 등 다양한 광고 유형별로 차별화된 리워드 제공 등 다양한 기획을 지원하기 위해 광고 유형을 확인할 수 있는 API를 제공합니다. API에 대한 자세한 내용은 자주 하는 질문의 광고 타입 확인하기를 참고하세요.