고급 설정

이 페이지에서는 네이티브 2.0에서 구현할 수 있는 기능을 확인할 수 있습니다.

CTA 버튼 자체 구현하기

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

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

뷰 레이아웃(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>

CtaView 클래스를 상속하는 서브클래스인 CustomCtaView를 생성하세요.
CtaView 클래스에서 사용하던 CTA View 레이아웃을 inflate하도록 구현하세요.
사용자의 광고 참여 상태에 따라 호출되는 아래의 오버라이딩 메소드에서 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);
    }
}

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

<com.buzzvil.buzzad.benefit.nativead2.api.NativeAd2View
    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.nativead2.api.NativeAd2View>

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

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

ii. NativeAd2ViewBinder의 ctaView 속성을 customCtaView로 설정하세요.

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

final NativeAd2View nativeAd2View = findViewById(R.id.nativeAd2View);
final MediaView mediaView = findViewById(R.id.mediaView);
final TextView titleTextView = findViewById(R.id.textTitle);
final TextView descriptionTextView = findViewById(R.id.textDescription);
final ImageView iconImageView = findViewById(R.id.imageIcon);

// Native 광고 레이아웃에서 CustomCtaView 를 가져옵니다.
final CustomCtaView customCtaView = nativeAdView.findViewById(R.id.customCtaView);

NativeAd2ViewBinder binder = new NativeAd2ViewBinder.Builder()
        .nativeAd2View(nativeAd2View)
        .mediaView(mediaView)
        .titleTextView(titleTextView)
        .descriptionTextView(descriptionTextView)
        .iconImageView(iconImageView)
        // ctaView에 CustomCtaView를 설정합니다.
        .ctaView(customCtaView)
        .build("YOUR_NATIVE_UNIT_ID");

binder.addNativeAd2StateChangedListener(new NativeAd2StateChangedListener() {
    @Override
    public void onRequested() {
    }
    
    @Override
    public void onNext(NativeAd2 nativeAd2) {
    }

    @Override
    public void onComplete() {
    }

    @Override
    public void onError(@NonNull AdError adError) {
    }
});

binder.bind();

✏️ 참고
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 단계. 광고 할당 및 표시하기 토픽을 참고하세요.

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

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

다음은 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() {
    // 동영상 광고 랜딩 시 필요한 처리
  }
});

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

✏️ 참고
광고 참여 상태에 따라 CTA View를 변경하기 위해 이벤트 리스너를 사용했다면, 더 이상 사용할 필요 없습니다.
리워드 적립 결과(RewardResult) 종류는 리워드 적립 결과(RewardResult) 종류를 참고하세요.

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

❗️ 주의
광고 이벤트 리스너로 피드 진입 슬라이드의 노출 또는 클릭 이벤트를 수신할 수는 없습니다.
로그 기록, 단순 알림 외에 다른 동작을 추가하는 것을 권장하지 않습니다. 직접 구현한 동작이 네이티브에서 제공하는 기능(광고 자동 갱신 등)과 충돌할 수 있습니다.

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

NativeAd2ViewBinder binder = new NativeAd2ViewBinder.Builder()
        .nativeAd2View(nativeAd2View)
        .mediaView(mediaView)
        .titleTextView(titleTextView)
        .descriptionTextView(descriptionTextView)
        .iconImageView(iconImageView)
        .ctaView(ctaView)
        .build("YOUR_NATIVE_UNIT_ID");

binder.addNativeAd2StateChangedListener(new NativeAd2StateChangedListener() {
    @Override
    public void onRequested() {
    }
    
    @Override
    public void onNext(NativeAd2 nativeAd2) {
    }

    // ...중략
});

// 광고 이벤트 리스너를 등록합니다.
// 로그 기록, 단순 알림 외에 다른 동작을 추가하는 것을 권장하지 않습니다. 자동 갱신 등 네이티브 2.0의 기능과 직접 구현한 동작이 충돌할 수 있습니다.
binder.addNativeAd2EventListener(new NativeAd2EventListener() {
    @Override
    public void onImpressed(@NonNull NativeAd2 nativeAd2) {
        // Native 광고가 유저에게 노출되었을 때 호출됩니다.
    }

    @Override
    public void onClicked(@NonNull NativeAd2 nativeAd2) {
        // 유저가 Native 광고를 클릭했을 때 호출됩니다.
    }

    @Override
    public void onRewardRequested(@NonNull NativeAd2 nativeAd2) {
        // 리워드 적립을 요청했을 때 호출됩니다.
    }

    @Override
    public void onRewarded(@NonNull NativeAd2 nativeAd2, @NonNull RewardResult rewardResult) {
        // 리워드가 적립되었을 때 호출됩니다.
    }

    @Override
    public void onParticipated(@NonNull NativeAd2 nativeAd2) {
        // 유저가 광고 참여를 완료하였을 때 호출됩니다.
    }
});

binder.bind();

리워드 적립 결과(`RewardResult`) 종류

RewardResult	결과	설명
`SUCCESS`	적립성공	적립에 성공했습니다.
`ALREADY_PARTICIPATED`	적립 실패	이미 적립된 광고입니다.
`MISSING_REWARD`	적립 실패	리워드가 없는 광고입니다.
`TOO_SHORT_TO_PARTICIPATE`	적립 실패	광고 랜딩 페이지에서 너무 빨리 돌아왔습니다.
`NETWORK_TIMEOUT`	적립 실패	네트워크 타임 아웃이 발생했습니다.
`NETWORK_TIMEOUT_IN_POWER_SAVE_MODE`	적립 실패	단말의 `절전모드`로 인해 네트워크 타임아웃이 발생했습니다.
`BROWSER_NOT_LAUNCHED`	적립 실패	광고 랜딩 페이지를 보기위한 브라우저가 실행되지 않았습니다.
`REQUEST_ERROR`	적립 실패	잘못된 요청입니다.
`UNKNOWN_NETWORK_ERROR`	적립 실패	알 수 없는 네트워크 오류가 발생했습니다.
`UNKNOWN_SERVER_ERROR`	적립 실패	알 수 없는 서버 오류가 발생했습니다.
`UNKNOWN_CLIENT_ERROR`	적립 실패	알 수 없는 클라이언트 오류가 발생했습니다.
`UNKNOWN_ERROR`	적립 실패	알 수 없는 오류가 발생했습니다.

유저가 단말의 절전모드를 활성화하면 백그라운드 실행 제한으로 인해 클릭형 광고(CPC, CPM)의 적립이 높은 확률로 실패합니다. RewardResult.NETWORK_TIMEOUT_IN_POWER_SAVE_MODE 를 활용하면 절전모드를 활성화 한 유저에게 적립 실패 사유를 안내를 할 수 있습니다.

고급 설정

CTA 버튼 자체 구현하기​

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

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

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

리워드 적립 결과(RewardResult) 종류​

CTA 버튼 자체 구현하기

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

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

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

리워드 적립 결과(`RewardResult`) 종류