본 연동 가이드는 BuzzAd-Benefit SDK를 Android Application 내에 삽입함으로써 매체사가 원하는 지면에 리워드가 지급되는 광고를 보여주기 위함입니다. 네이티브 광고와 동영상 광고를 지원하며, 커스텀 UI 요소를 통해 광고가 매체사 앱에 자연스럽게 녹아들게 하면서 동시에 매출을 극대화할 수 있습니다.


Index

Getting Started

SDK를 앱에 연동하기 전, 아래 사항을 먼저 준비해야 합니다.

SDK를 연동하면서 증가하는 APK의 용량은 다음 문서를 통해 참고 부탁드립니다. (/wiki/spaces/DEV/pages/997688754)


Installation

다음 샘플 코드를 통해, 실제 구현에 사용된 예제를 참고할 수 있습니다: github sample code (링크)

build.gradle 의 dependencies 부분에 아래 코드 추가

repositories {
    maven { url "https://dl.buzzvil.com/public/maven" }
}

...

dependencies {
    // 예시에 적혀진 버전을 '연동하려는 버전'으로 교체해 주세요. 
    implementation ("com.buzzvil:buzzad-benefit:1.7.+") {
    
        // 현재 Pop 을 연동하고 있지 않다면 아래 코드를 추가해야 합니다.
        exclude group: 'com.buzzvil', module: 'buzzad-benefit-pop'
        // 현재 Notification 을 연동하고 있지 않다면 아래 코드를 추가해야 합니다.
        exclude group: 'com.buzzvil', module: 'buzzad-benefit-notification'
    }
    // 베네핏 1.6.9 버전을 연동하는 경우 아래의 코드를 추가해야 합니다.
    implementation "com.buzzvil:buzzresource:0.0.5"
}

(FAQ)

Warning: com.buzzvil.buzzad.benefit.pop.PopControlService: can't find referenced method 'android.view.DisplayCutout getCutout()' in library class android.view.Display

  1. compileSdkVersion 을 29 이상으로 변경하거나,

  2. proguard rules 에  -dontwarn android.view.Display  를 추가

SDK Initialization

Step 1: Initialize BuzzAdBenefit

Application Class의 onCreate에 아래 코드를 추가할 것을 권장하나, 최초 광고 요청 전에만 불린다면 자유롭게 코드 위치를 결정할 수 있습니다.

public class App extends Application {
    @Override
    public void onCreate() {
        BuzzAdBenefit.init(this, new BuzzAdBenefitConfig.Builder("YOUR_APP_ID").build());
    }
}


Step 2: Set UserProfile of the user

유저가 매체사 앱에 로그인한 시점에 아래와 같이 UserProfile 을 세팅합니다. 설정값 수정 시, 기존 user profile 값을 호출하여 수정 가능합니다.

주의 : User ID와 타게팅 정보 (성별, 연령)는 원활한 서비스 운영을 위해 제공해야 할 필수 항목입니다. 해당 값을 입력하는 setUserProfile 함수가 호출되지 않으면 광고가 제공되지 않습니다.

final UserProfile.Builder builder = new UserProfile.Builder(BuzzAdBenefit.getUserProfile());
final UserProfile userProfile = builder
        .userId("Your_Service_User_ID")
        .gender(UserProfile.Gender.MALE)
        .birthYear(1985)
        .build();
  
BuzzAdBenefit.setUserProfile(userProfile);


추가 사항 : Step 1/2를 통해 세션키 등록이 완료되면 SessionReady Broadcast가 전송됩니다. 세션키는 SDK가 광고를 요청하고 받아오기 위해서 필요한 서버 API Key로서 세션키가 없는 경우 광고 로드가 불가능합니다. Step 2와 광고 요청 시점간 간격이 짧은 경우 아래와 같은 방법으로 SessionReady에 대한 broadcast를 받아 세션키 등록을 확인한 후 광고 요청을 수행할 수 있습니다.

// 1. create a BroadcastReceiver
private BroadcastReceiver sessionReadyReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Session is ready
    }
};

// 2. register the receiver to LocalBroadcastManager
private void registerSessionReadyReceiver() {
    LocalBroadcastManager.getInstance(context).registerReceiver(sessionReadyReceiver, BuzzAdBenefit.getSessionReadyIntentFilter());
}

// 3. unregister the receiver when you're done
private void unregisterSessionReadyReceiver() {
    LocalBroadcastManager.getInstance(context).unregisterReceiver(sessionReadyReceiver);
}


Step 3: Set UserPreferences of the user

유저가 매체사 앱에 로그인한 시점에 UserPreferences를 빌드하여 BuzzAdBenefit SDK에 해당 값을 세팅합니다.

final UserPreferences userPreferences = new UserPreferences.Builder(BuzzAdBenefit.getUserPreferences())
        .autoplayType(AutoplayType.ON_WIFI)
        .build();
BuzzAdBenefit.setUserPreferences(userPreferences);


Step 4. Delete user setting

유저가 매체사 앱에서 로그아웃하는 시점에 UserProfile 및 UserPreferences 설정값을 지워 유저의 사용 정보를 삭제합니다.

BuzzAdBenefit.setUserProfile(null);
BuzzAdBenefit.setUserPreferences(null);


Step 5. Proceed to the next step

BuzzAd Benefit 광고를 노출시킬 공간에 적합한 연동 타입을 선택하여 나머지 연동을 진행합니다.


Advanced Usage

광고 실행 Customization - Custom Launcher 사용

Custom Launcher의 사용은 권장되지 않습니다. Benefit 2.0부터 Cherry-picker 방지, 다양한 리워드 광고 지원을 위하여 SDK가 직접 광고 실행을 컨트롤합니다.

Custom Launcher를 통해 광고 실행을 Customize 할 수 있습니다. 예를 들어, 광고 랜딩 페이지 로드 등을 매체사가 지정하는 Class에서 구현할 수 있습니다.

구현시 주의사항 : Launcher에서 제공하는 클릭 URI는 임의로 Decoding 해서 로드하면 안됩니다. 이 경우 서버에서의 동작이 달라져 광고 관련 통계가 제대로 집계되지 않을 수 있습니다.


  1. Launcher 를 구현합니다.

    public class MyLauncher implements Launcher {
    @Override
    public void launch(Context context, Uri uri, NativeCampaign nativeCampaign) {
        String unitId = "";
        int id = 0;
        String title = "";
        
        if (nativeCampaign instanceof NativeAd) {
            final NativeAd nativeAd = (NativeAd) nativeCampaign;
            unitId = nativeAd.getUnitId();
            id = nativeAd.getAd().getId();
            title = nativeAd.getAd().getTitle();
        } else if (nativeCampaign instanceof NativeArticle) {
            final NativeArticle nativeArticle = (NativeArticle) nativeCampaign;
            unitId = nativeArticle.getUnitId();
            id = nativeArticle.getArticle().getId();
            title = nativeArticle.getArticle().getTitle();
        }
        
        Log.i("MyLauncher", "Unit Id: " + unitId + ", Campaign Id: " + id + ", Title: " + title);
        final Intent intent = new Intent(Intent.ACTION_VIEW, uri); // URI는 Decoding 하면 안 됨
        intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        context.startActivity(intent);
    }
}

  2. BuzzAdBenefit.init 호출 이후에 생성한 Launcher를 세팅합니다.

    BuzzAdBenefit.setLauncher(new MyLauncher());


Custom launcher 사용시 딥링크 광고 처리 가이드

외부 앱으로 랜딩되는 딥링크 광고의 경우 redirect 과정을 거쳐 최종적으로 타겟 앱(또는 플레이스토어)으로 이동하게 됩니다. 이 경우 사용자가 다시 본 앱으로 돌아왔을 때 redirect가 일어났던 인앱 브라우저가 빈 페이지인 상태로 열려있게 됩니다. 따라서 자연스러운 UX를 위하여 외부 앱으로 랜딩되는 광고의 경우 인앱 브라우저를 닫아 사용자가 본 앱으로 돌아왔을 때 빈 화면을 보지 않도록 처리해야 합니다. 이 때 아래 2가지 방법 중 하나를 선택하여 구현합니다.

  1. 인앱 브라우저 내에서 일어나는 redirect를 모니터하여 http/https가 아닌 scheme이 호출된 경우 타겟 앱이 열린 뒤 인앱 브라우저는 자동으로 닫히도록 구현합니다.

  2. Ad 안의 Creative 객체가 가진 isDeeplink 필드(nativeAd.getAd().getCreative().isDeepLink())를 이용하여 사용자가 인앱 브라우저가 열려있는 상태에서 본 앱을 이탈했을 때 인앱 브라우저가 자동으로 닫히도록 구현합니다. 버즈빌에서는 각 광고의 랜딩 타입을 미리 체크하여 딥링크 광고인 경우 isDeeplink를 true로, 일반 웹 랜딩 광고인 경우 isDeeplink를 false로 내려주고 있습니다. 따라서 isDeeplink가 true인 광고가 인앱 브라우저로 열려있는 상태에서 본 앱이 백그라운드로 내려간 경우 타겟 앱으로 이동한 것으로 판단하여 인앱 브라우저를 닫아야 합니다.

Custom launcher 사용시 Article의 sourceUrl 사용법

컨텐츠의 경우 url scheme에 따라 랜딩 방식을 다르게 처리하고 싶다면, 다음과 같은 방법으로 NativeArticle 객체의 sourceUrl을 가져와 분기 처리를 할 수 있습니다. (ex. 앱 안에서 브라우저 오픈 없이 다른 화면으로 이동되는 컨텐츠)

public class MyLauncher implements Launcher {
    @Override
    public void launch(Context context, Uri uri, NativeCampaign nativeCampaign) {
        if (nativeCampaign instanceof NativeArticle) {
            String sourceUrl = 
              ((NativeArticle) nativeCampaign).getArticle().getSourceUrl();
        }
    }
}

액션형 광고에 대한 유저 VOC 페이지

BuzzAd Benefit SDK는 비디오, 앱 인스톨, 페이스북 페이지 좋아요 등 다양한 유저 액션에 리워드를 지급하는 광고를 제공합니다. 그리고 이런 광고의 경우 종종 리워드 미적립을 이유로 유저가 VOC를 보내기도 합니다. 이러한 유저 VOC에 대한 접수 및 처리를 자동화 하기 위해 SDK에서는 미리 만들어 놓은 웹 페이지를 제공하고 있습니다. 아래의 단계를 통해 해당 기능을 사용하실 수 있습니다.


  1. 아래 예시와 같이 VOC 페이지 로드를 위한 유저 진입 Icon/Tab을 디자인 합니다.

    단, Type B - Feed를 사용하시면서 Toolbar를 Customize 하지 않고 Default Toolbar를 사용하시는 경우 예시 중 2번과 같은 아이콘이 이미 디자인에 포함되어 있습니다.

  2. 1번의 Icon/Tab이 클릭될 때 Benefit.getInstance().showInquiryPage(context, unitId)을 호출합니다.

public void showInquiryPage(Context context, @Nullable final String unitId)을 사용하며, 입력한 지면(유닛) 기준으로 조회합니다. 앱 기준으로 조회할 경우 unitId 를 null 로 입력해야 합니다.

이 변경사항은 2.5 버전부터 적용되었으며, BuzzAdBenefit.getInstance().showInquiryPage(context) 에서 변경되었습니다.