BuzzAd-Benefit Android SDK 연동 가이드

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

Index

1 Getting Started
2 Installation
- 2.1 build.gradle 의 dependencies 부분에 아래 코드 추가
3 SDK Initialization
4 Advanced Usage
- 4.1 광고 실행 Customization - Custom Launcher 사용
  - 4.1.1 Custom launcher 사용시 딥링크 광고 처리 가이드
  - 4.1.2 Custom launcher 사용시 Article의 sourceUrl 사용법
- 4.2 액션형 광고에 대한 유저 VOC 페이지

Getting Started

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

Buzzvil의 BD 매니저를 통해 전달받은 app_id
BD 매니저를 통해 전달받은 unit_id (원하는 Type 에 맞는 unit_id 수령)
- Type A - Native Ads 적용 시 NATIVE AD UNIT_ID 준비
- Type B - Feed 적용 시 FEED UNIT_ID 준비
- Type C - Interstitial 적용 시 INTERSTITIAL UNIT_ID 준비
- Type D - Pop 적용 시
  - 기존에 Benefit SDK 가 연동되어 있는 경우, POP UNIT_ID 준비
  - 처음 Benefit SDK 를 연동하며 Pop 을 단독으로 연동하는 경우, BuzzAdPop 링크로 이동
Buzzvil 서버로부터 포인트 적립 요청을 받을 수 있는 매체사 API 서버 - 포인트 postback API 연동문서
- Postback 수신 url 세팅 후 Buzzvil BD 매니저에게 전달

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

Installation

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

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

“com.buzzvil:buzzad-benefit:연동하려는 버전”을 입력해 주세요.
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" 부분을 추가해 주세요.

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

compileSdkVersion 을 29 이상으로 변경하거나,
proguard rules 에 -dontwarn android.view.Display 를 추가

SDK Initialization

Step 1: Initialize `BuzzAdBenefit`

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

YOUR_APP_ID 부분에 위 단계에서 준비한 app_id 삽입

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 함수가 호출되지 않으면 광고가 제공되지 않습니다.

userId : 매체사 서비스 유저를 unique 하게 구분할 수 있는 식별값
- 매체사 서비스에서 유니크하다고 판단되는 유저에 대하여, userId 값이 복수 개 연동되거나 변경될 가능성이 있을 경우 사전에 BD 매니저와 논의해야 합니다.
- 예: 매체사 앱 삭제 후 재설치 시 userId 값이 변경되는 경우
gender
- UserProfile.Gender.MALE: 남성
- UserProfile.Gender.FEMALE: 여성
birthYear: 출생년도

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를 받아 세션키 등록을 확인한 후 광고 요청을 수행할 수 있습니다.

Step 3: Set `UserPreferences` of the user

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

autoplayType(AutoplayType autoplayType): 동영상 광고에 대한 자동재생 옵션을 설정합니다. AutoplayType 의 설정값은 아래와 같습니다. 미설정시 기본값은 AutoplayType.ON_WIFI로 적용됩니다.
- AutoplayType.ENABLED: 동영상 광고가 Wifi, LTE 환경 모두에서 항상 자동재생됨
- AutoplayType.ON_WIFI: 동영상 광고가 Wifi 네트워크 환경에서만 자동재생됨
- AutoplayType.DISABLED: 동영상 광고가 자동재생되지 않음

Step 4. Delete user setting

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

Step 5. Proceed to the next step

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

Type A - Native Ads : 인앱 디자인과 자연스럽게 어우러지도록 광고를 노출시키고자 하는 경우
Type B - Feed : 버튼 등 별도의 진입 경로를 통해 광고 목록을 노출시키고자 하는 경우
Type C - Interstitial : 버즈빌이 사전에 만들어 놓은 레이아웃을 활용하여 Dialog 또는 BottomSheet 형태로 전면 광고를 노출하고자 하는 경우
Type D - Pop : 앱 외부 홈스크린과 다른 앱 최상단에 띄우는 챗헤드를 통해 광고 목록을 노출하고자 하는 경우

Advanced Usage

광고 실행 Customization - Custom Launcher 사용

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

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

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

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

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

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

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

Custom launcher 사용시 Article의 sourceUrl 사용법

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

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

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

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

단, Type B - Feed를 사용하시면서 Toolbar를 Customize 하지 않고 Default Toolbar를 사용하시는 경우 예시 중 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) 에서 변경되었습니다.