(ver 5.7.x) BuzzScreen Android 연동 가이드

Owned by Jasmine Lee (Unlicensed)
Last updated: Nov 13, 2024 by Nike MoonVersion comment
15 min read

개요

BuzzScreen Android용 SDK는 모바일 기기의 첫 화면을 광고 인벤토리로 활용할 수 있도록 사용자에게 리워드를 지급하는 보상형 광고, 비보상형 광고, 뉴스 기사 등의 콘텐츠를 게시하여 앱의 수익화를 지원하는 잠금화면 앱 전용 SDK입니다.

BuzzScreen Android용 SDK의 구동 방식은 아래의 다이어그램을 참고하세요.

시작하기 전에

안내 사항

이 가이드는 BuzzScreen Android용 SDK를 앱에 연동하기 위한 정보를 제공합니다. 아래의 안내 사항을 숙지한 후 연동을 진행하세요.

  • 연동 작업 전 버즈빌 BD 매니저와 사전 협의가 완료되어야 합니다.

  • 서비스 출시 전, 연동이 완료된 앱의 apk 파일을 버즈빌 BD 매니저에게 전달하여 승인 절차를 밟으시기를 바랍니다.

반드시 잠금화면을 통한 수익 창출에 대한 구글 정책을 확인한 후 연동을 진행하세요.
특히, 잠금화면 앱은 잠금화면 기능만을 수행해야 합니다. 그러므로 이 외의 목적을 가진 앱에는 BuzzScreen Android용 SDK를 연동할 수 없습니다.

요구 사양

  • Android 4.0.3 Jellybean (API 레벨 15) 이상

  • Android Studio 3.2 이상

  • Gradle 4.0.1 이상

  • compileSdkVersion 31 이상

  • AndroidX

  • JDK 1.11

  • Kotlin 버전 1.5 이상

Lockscreen Activity의 특정한 style 설정이 Android OS 8.0 버전에서 크래시가 발생할 수 있으므로 확인이 필요합니다.

  • 발생 조건: Android API 26의 설정으로 인해 아래 조건을 모두 충족하는 경우

    1. 앱의 targetSdkVersion 이 27 이상인 경우

    2. 사용자 모바일 기기 OS 버전이 8.0(API 26)인 경우

    3. Lockscreen Activity에 적용된 style에 windowTranslucent, windowIsFloating, windowSwipeToDismiss 중 1개 이상이 true로 설정되어 있는 경우

  • 해결 방안

    • styles.xml 에서 windowTranslucent, windowIsFloating,windowSwipeToDismiss 중 true로 세팅된 항목을 제거 또는 false로 변경

<resources> ... <style name="YourLockScreenTheme" parent="@style/AppTheme"> <!-- Items below need to be removed or set to false on specific conditions--> <item name="android:windowIsTranslucent">false</item> <item name="android:windowIsFloating">false</item> <item name="android:windowSwipeToDismiss">false</item> </style> </resources>

준비 사항

항목

설명

비고

항목

설명

비고

1

연동 앱 로그인을 위한 API 서버

BuzzScreen SDK에 사용자 정보를 등록하기 위한 API입니다.

 

2

포인트 적립 요청 수신 API

버즈빌 서버에서 포인트 적립 요청을 보낸 이후, 실제 포인트 지급을 처리할 매체사 API 서버입니다.

매체사 포인트 적립 포스트백 API 연동 가이드 참고

3

연동을 위한 키 값

버즈빌 BD 매니저로부터 발급받은 app_key, unitId 값입니다.

  • app_key : 연동하는 잠금화면 앱의 키 값

  • unitId : 광고 서빙을 위한 Unit ID

 

 

BuzzScreen 연동하기

1 단계. build.gradle , AndroidManifest.xml 설정

1. build.gradle에 아래 코드에 보이는 저장소 및 디펜던시를 추가하세요.

repositories { maven { url "https://dl.buzzvil.com/public/maven" } } dependencies { implementation 'com.buzzvil:buzzscreen:4.41.+' }

2. AndroidManifest.xml에 아래 meta data를 추가하고 000000000000 부분에 app_key를 기입하세요.

<meta-data android:name="com.buzzvil.APP_KEY" android:value="app-pub-000000000000" />

3. 모듈 레벨의 build.gradle 파일에 compileSdkVersion과 targetSdkVersion 을 31로 업데이트하세요.

2 단계. 애드 네트워크 연동

버즈빌 BD 매니저가 애드 네트워크 추가 연동에 대한 안내를 진행합니다. ADN 추가 연동 가이드를 참조하여 모듈 레벨의 AndroidManifest.xml에 해당 AdNetwork의 관련 코드를 추가하세요.

3 단계. 메소드 호출

연동을 위해 초기화, 사용자 정보 설정, 잠금화면 제어 설정을 순서대로 진행하세요.

1) 초기화: init() 및 launch() 호출

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

버즈스크린 초기화
필수

BuzzScreen.init(String unitId, Context context, Class lockerActivityClass, int imageResourceIdOnFail)

  • Application Class 의 onCreate

  • 모든 다른 메소드보다 항상 먼저 호출하세요.

  • Parameters

    • unitId : BuzzScreen SDK 사용을 위한 Unit ID로, 버즈스크린 어드민에서 확인 가능합니다.

    • context : Application context를 this로 입력합니다.

    • lockerActivityClass : 잠금화면 액티비티 클래스.

      • 잠금화면을 커스터마이징하지 않는 경우 SDK 내에서 제공하는 SimpleLockerActivity.class 를 설정합니다.

      • 커스터마이징을 하는 경우 직접 구현한 액티비티 클래스를 설정합니다. 자세한 내용은 UI 커스터마이징의 설명을 참고하세요.

    • imageResourceIdOnFail : 네트워크 에러 발생 시 혹은 일시적으로 잠금화면에 보여줄 광고가 없는 경우 보여주게 되는 이미지를 앱 내 리소스에 포함시켜야 하며, 이 이미지의 리소스 아이디를 설정합니다.

버즈스크린 시작
필수

BuzzScreen.getInstance().launch()

앱 실행 시 처음 실행되는 액티비티에 추가하세요.

-

 

아래의 코드 예제를 참고하세요.

 

2) 사용자 정보 설정

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

사용자 정보 설정을 위한 객체

BuzzScreen.getInstance().getUserProfile()

BuzzScreen.getInstance().activate() 호출 전입니다.

사용자 정보 설정할 수 있는 UserProfile 클래스를 호출합니다.

사용자 식별 값 필수

setUserId(String userId)

userId

  • 사용자에게 적립금을 지급하기 위한 필수적인 설정 값입니다.

  • 매체사에서 사용자를 구분할 수 있는 식별 값입니다.

  • 매체사 포인트 적립 포스트백 API 연동 요청 시에 전달됩니다. 이에 대한 자세한 내용은 매체사 포인트 적립 포스트백 API 연동 가이드를 참고하세요.

사용자 연령 권장

setBirthYear(int birthYear)

사용자의 출생년도를 4자리 숫자로 입력하여 나이를 설정하세요.

사용자 성별 권장

setGender(String gender)

미리 정의된 String을 통해 형식에 맞추어 성별을 설정하세요.

  • UserProfile.USER_GENDER_MALE : 남성

  • UserProfile.USER_GENDER_FEMALE : 여성

사용자 지역 선택

setRegion(String region)

"시/도 + 공백 + 시/군/구" 형식으로 설정하세요.

이 외 선택

커스텀 타게팅 가이드 참고

매체사에서 원하는 사용자 정보로 타겟팅할 수 있습니다.

 

아래의 코드 예제를 참고하세요.

 

3) 잠금화면 제어 설정

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

다른 앱 위에 표시 권한 획득 필수

BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

버즈스크린 활성화 시점

버즈스크린 활성화 필수

BuzzScreen.getInstance().activate()

버즈스크린 활성화 시점

  • activate()를 처음 잠금화면 활성화 시 호출하면, 이후부터 자동으로 잠금화면 사이클이 관리되기 때문에 deactivate()를 호출하기 전에 다시 호출할 필요는 없습니다.

이 함수가 호출된 이후부터 잠금화면에 버즈스크린이 나타납니다.

  • 다른 앱 위에 표시 권한을 획득한 이후에 호출하는 것을 권장합니다. 그렇지 않을 경우에 발생하는 문제에 대해서는 다른 앱 위에 표시 권한 획득하기 토픽을 참고하세요.

버즈스크린 비활성화 필수

BuzzScreen.getInstance().deactivate()

버즈스크린 비활성화 시점

이 함수가 호출되면 더 이상 잠금화면에 버즈스크린이 나타나지 않습니다.

사용자 로그아웃 필수

BuzzScreen.getInstance().logout()

사용자가 로그아웃하는 시점

이 함수는 deactivate()를 호출하며, 버즈스크린에서 사용하는 사용자 정보를 기기에서 삭제합니다.

버즈스크린이 화면에서 사라지는 시간 설정 권장

BuzzScreen.getInstance().setSettings(BuzzScreen.Settings.FINISH_IN_SEC, int set_seconds)

BuzzScreen.init() 이후에 호출

버즈스크린 액티비티가 화면에 뜬 뒤 일정 시간 동안 유저의 활동이 없을 경우 버즈스크린이 화면에서 사라집니다.

  • Parameters

    • set_seconds : 사용자의 활동이 없는 경우 버즈스크린이 화면에서 사라지게 될 시간 (단위: 초)

  • 상세 동작 예

    • 미설정 시: 60초 동안 유저 활동이 없을 경우 동작합니다.

    • set_seconds = 30 : 30초 동안 유저 활동이 없을 경우 동작합니다.

    • set_seconds = 0 : 동작하지 않습니다.

잠금화면을 활성화한 후 실제로 잠금화면이 처음 준비가 된 시점 확인 선택

BuzzScreen.getInstance().activate(OnReadyListener listener)

 

활성화한 후 실제로 잠금화면이 처음 준비가 완료된 시점을 알고 싶을 때, 아래의 interface를 구현하여 activate() 메소드의 파라미터로 넘깁니다.

Notification 커스텀 선택

서비스 노티피케이션 문서 참고

 

버즈스크린을 활성화한 후 알림 패널에 생성된 알림의 icon, text 등을 수정하고자 하는 경우

 

4 단계. 다른 앱 위에 표시 권한 획득하기

Android 10부터 변경된 정책에 따라, 잠금화면을 띄우기 위해서는 다른 앱 위에 표시 권한을 획득해야 합니다. 이에 따라 BuzzScreen Android용 SDK는 사용자에게 해당 권한을 요청하는 메시지를 잠금화면과 인앱(In-App)에 노출해 권한 획득 지원 기능을 제공합니다.

1) 인앱 안내 메시지

  • boolean BuzzScreen#showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

    • 사용자에게 “다른 앱 위에 그리기” 권한 획득을 요청하는 메시지의 팝업 다이얼로그를 띄우는 인터페이스입니다.

    • 앱의 메인 화면이 생성될 때(MainActivity의 OnCreate()) 해당 팝업을 보여주는 것을 권장합니다.

    • 리턴 값은 팝업 다이얼로그가 발생했는지 아닌지를 알려주는 boolean 값입니다.

    • 인자로 주어진 listener를 통해 권한 획득 여부를 알 수 있습니다.

  • 팝업에서 확인 클릭 시 해당 권한을 획득할 수 있는 안드로이드 설정 화면으로 이동하고, 권한 획득시 자동으로 이전 화면으로 전환

  • Android 10 미만이거나 해당 권한이 이미 획득되어 있는 경우에는 팝업을 보여주지 않음

2) 잠금화면 안내 메시지

  • 앱에서 추가 코드를 작성할 필요없이 자동으로 적용

  • Android 10 미만이거나 해당 권한이 이미 획득되어 있는 경우에는 팝업을 보여주지 않음

  • 6시간 간격으로 노출

5 단계. 기본 보안 기능 화면 속성 수정

BuzzScreen.init()된 직후 메소드를 호출하여 보안 기능 화면 속성을 수정하세요.

  • backgroundResourceId(int resourceId): Swipe mode 보안화면에 나오는 배경화면을 지정

  • backgroundImageScaleType(enum ImageView.ScaleType): Swipe mode 보안화면에 지정한 배경화면의 정렬값 설정 (기본값: FIT_XY, 참조 link)

  • backgroundColor(int Color): Swipe mode 보안화면의 배경색 설정 (기본값: Color.WHITE, 참조 link)

  • backgroundDimAlpha(float): Swipe mode 보안화면에는 시계와 액션 안내 텍스트의 가독성을 높이기 위하여 알파값이 적용된 검은색 화면의 알파값을 조절 (기본값: 0.7)

  • showClock(boolean): 시계의 노출/미노출을 세팅 (기본값: true)

  • showDescription(boolean): 유저 액션 안내 텍스트의 노출/미노출을 세팅 (기본값: true)

아래의 코드 예제를 참고하세요.

 

6 단계. 포인트 적립 포스트백 연동(Server-to-Server 연동)

버즈스크린은 포인트 적립이 발생했을 때 직접 사용자들에게 포인트를 지급하는 것이 아닙니다. 버즈스크린 서버에서는 매체사 서버로 포인트 적립 요청을 보낼 뿐이며, 실제 지급은 매체사 서버에서 처리합니다.

포인트 적립 요청 흐름

버즈배너(BuzzBanner)

버즈배너(BuzzBanner)는 BuzzScreen SDK 4.15.x부터 버즈스크린 화면 아래에 비보상 노출형 광고를 노출하는 배너 타입의 지면입니다. 버즈빌에서 기본 UI를 제공하는 SimpleLockerActivity, 자유롭게 UI를 커스터마이징할 수 있는 LockerActivity를 제공합니다.

준비 사항

버즈배너를 연동하려면 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. ID를 발급받으려면 버즈빌 담당자에게 연락하세요.

ID 유형

설명

ID 유형

설명

BuzzBannerAppID

앱을 구분하게 하는 고유 App ID 입니다.

BuzzBannerSecret

앱을 구분하게 하는 고유 App Secret 입니다.

PlacementID

각 광고 지면을 구분하게 하는 고유 ID 입니다. 배너의 사이즈와 PlacementID 가 제대로 매칭되어야 광고 할당 및 노출이 정상적으로 이루어집니다.

BuzzBanner 초기화

BuzzScreen을 초기화한 다음 바로 BuzzBanner를 초기화할 수 있습니다. 다음의 절차를 따르세요. .

  1. 사전에 준비한 ID를 BuzzScreen.getInstance().initBuzzBanner에 설정하세요.

  2. BuzzBannerConfig를 생성하세요.

  3. 생성한 BuzzBannerConfig를 BuzzScreen.getInstance().setDefaultBuzzBannerConfig(buzzBannerConfig)를 통해 설정하세요.

사이즈

Enum

사이즈

Enum

Banner 320 x 50

BuzzBanner.BannerSize.W320XH50

Banner 320 x 100

BuzzBanner.BannerSize.W320XH100

SimpleLockerActivity 사용하기

BuzzBannerConfig 를 설정하면 자동으로 SimpleLockerActivity 아래에 BuzzBanner가 추가됩니다.

커스텀 LockerActivity 사용하기

1. xml 파일의 원하는 위치에 BuzzBannerView 를 추가합니다.

 

 

 

2. Activity에서 onResume, onPause, onDestroy 를 호출하세요.

 

3. 옵션: 배너 광고에 대한 콜백을 받기 위해 BuzzBannerView 에 Load 상태를 따르는 리스너를 등록할 수 있습니다.

ADN 추가 연동

BuzzBanner 의 매출 극대화를 위해 추가 연동 가능한 Ad Network 연동 가이드입니다.

 

ADN

 

버전 정보

maven 저장소

build.gradle(implementation)

 

ADN

 

버전 정보

maven 저장소

build.gradle(implementation)

Adfit(Kakao)

3.12.7

Cauly

3.5.22

Mobon

1.0.0.54

 

Pangle

4.7.1.4

UnityAds

4.3.0

 

Vungle

6.11.0

 

Coupang

1.2.8

 

AppLovin(11.3.3)

1.2.8

 

한줄뉴스(BuzzHeadlineNews)

한줄뉴스(BuzzHeadlineNews)는 BuzzScreen 4.31.x 부터 버즈스크린에 노출되는 비보상 콘텐츠입니다.

SimpleLockerActivity 사용하기

버즈빌에서 제공하는 SimpleLockerActivity, SimpleSlidingLockerActivity 사용 시에는 별도의 연동 과정 없이 자동으로 잠금화면 하단에 한줄뉴스가 나타납니다.

커스텀 LockerActivity 사용하기

커스텀 LockerActivity 에 한줄뉴스를 추가하려면 xml 파일의 원하는 위치에 BuzzHeadlineNewsView 를 추가하세요.

버즈캐시버튼 (BuzzCashButton)

버즈캐시버튼(BuzzCashButton)은 BuzzScreen 5.7.x 부터 버즈스크린에 노출되는 추가 수익 기능입니다.

종속성 추가

프로젝트의 build.gradle 파일

우선 프로젝트의 build.gradle 파일에 버즈캐시버튼을 위한 저장소를 추가해야 합니다.

앱 수준의 build.gradle 파일

다음으로, 앱 수준의 build.gradle 파일에 버즈캐시버튼 종속성을 추가합니다.

 

종속성 추가시 발생할 수 있는 에러

버즈룰렛이나 아바티의 캐시룰렛을 기존에 연동하고 있었던 경우, 같은 이름의 클래스가 중복해서 발견되면서 에러가 발생할 수 있습니다.

Caused by: java.lang.RuntimeException: Duplicate class A found in modules B and C

문제 상황

버즈캐시버튼의 종속성을 추가한 상태에서 빌드할 때, 다음과 유사한 에러 메시지가 다수 발생하면서 빌드에 실패할 수 있습니다.

Caused by: java.lang.RuntimeException: Duplicate class com.mmc.common.AES256Cipher found in modules jetified-archive-ads-mezzomedia-2.0.0.202-runtime (com.avatye.cashbutton:archive-ads-mezzomedia:2.0.0.202) and jetified-cashroulette-plug-archive-aceenter-4.3.0-runtime (com.avatye:cashroulette-plug-archive-aceenter:4.3.0)

해결 방법

앱 수준의 build.gradle 파일에서 다음과 같이 특정 모듈의 종속성을 제외해주면 해결됩니다.

문제 해결하기

버즈캐시버튼을 연동하면서 발생할 수 있는 다양한 문제 상황을 소개하고, 이에 대한 해결 방법을 제시합니다.

'create' overrides nothing

문제 상황

버즈캐시버튼의 종속성을 추가한 상태에서 빌드할 때, 다음과 같은 에러 메시지가 발생하면서 빌드에 실패할 수 있습니다.

'create' overrides nothing

조금 더 구체적으로는 다음과 같은 메시지를 받을 수 있습니다.

Class 'ViewModelFactory' is not abstract and does not implement abstract member public abstract fun <T : ViewModel> create(modelClass: Class<T>): T defined in androidx.lifecycle.ViewModelProvider.Factory

문제 설명

기존에 androidx.lifecycle 모듈을 2.2.0 이하 버전을 사용하면서 코틀린으로 ViewModelProvider.Factory 를 상속한 객체를 구현하고 있었던 경우, 버즈캐시버튼을 연동하면서 버전이 2.4.0 이후 버전으로 올라갔기 때문에 발생합니다.

androidx.lifecycle 모듈은 2.4.0에서 다음과 같은 하위호환성이 깨지는 변화가 있었습니다.

하위호환성이 깨지는 변화: ViewModelProvider 가 코틀린으로 재작성되었습니다.

ViewModelProvider.Factory.create 함수는 더 이상 nullable 제네릭을 허용하지 않습니다.

해결 방법

코드에 다음과 같이 nullable한 타입으로 ViewModelProvider.Factory.create 함수를 사용하는 경우를 찾습니다.

다음과 같이 create 함수가 nullable한 제네릭을 사용하지 않도록 변경합니다. (? 가 제거되었습니다.)

관련 문서

Inheritance from an interface with '@JvmDefault' members is only allowed with -Xjvm-default option

문제 상황

버즈캐시버튼의 종속성을 추가한 상태에서 빌드할 때, 다음과 같은 에러 메시지가 발생하면서 빌드에 실패할 수 있습니다.

Inheritance from an interface with '@JvmDefault' members is only allowed with -Xjvm-default option

문제 설명

기존에 androidx.lifecycle 모듈을 2.5.0 미만의 버전을 사용하면서 코틀린으로 ViewModelProvider.Factory 를 상속한 객체를 구현하고 있었던 경우, 버즈캐시버튼을 연동하면서 버전이 2.5.0 이후 버전으로 올라갔기 때문에 발생합니다.

androidx.lifecycle 모듈은 2.5.0-alpha01 에서 하위호환성이 깨지는 변화가 있었고, 이로 인해 이 문제가 발생한다고 합니다.

해결 방법

다음 두 가지 해결 방법 중 적절한 방법을 골라서 적용합니다.

  1. 앱 수준의 build.gradle 파일에 다음을 추가합니다.

  2. 코틀린 버전을 1.6.20 버전 이상으로 올립니다.

관련 문서