(ver 4.45.x)(ver 5.3.x) BuzzScreen Android 연동 가이드
개요
BuzzScreen Android용 SDK는 모바일 기기의 첫 화면을 광고 인벤토리로 활용할 수 있도록 사용자에게 리워드를 지급하는 보상형 광고, 비보상형 광고, 뉴스 기사 등의 콘텐츠를 게시하여 앱의 수익화를 지원하는 잠금화면 앱 전용 SDK입니다.
BuzzScreen Android용 SDK의 구동 방식은 아래의 다이어그램을 참고하세요.
시작하기 전에
안내 사항
이 가이드는 BuzzScreen Android용 SDK를 앱에 연동하기 위한 정보를 제공합니다. 아래의 안내 사항을 숙지한 후 연동을 진행하세요.
연동 작업 전 버즈빌 BD 매니저와 사전 협의가 완료되어야 합니다.
서비스 출시 전, 연동이 완료된 앱의 apk 파일을 버즈빌 BD 매니저에게 전달하여 승인 절차를 밟으시기를 바랍니다.
반드시 잠금화면을 통한 수익 창출에 대한 구글 정책을 확인한 후 연동을 진행하세요.
특히, 잠금화면 앱은 잠금화면 기능만을 수행해야 합니다. 그러므로 이 외의 목적을 가진 앱에는 BuzzScreen Android용 SDK를 연동할 수 없습니다.
버즈스크린의 UI 및 동작을 커스터마이징하고 싶다면 고급 설정을 참고하여 구현하세요.
사용자가 룰렛을 돌려 리워드를 획득할 수 있는 버즈룰렛(BuzzRoulette)을 추가할 수 있습니다. 고수익성의 광고를 제공하고 사용자의 광고 참여 유도에 효과적인 버즈룰렛을 추가하려면 BuzzRoulette 연동 가이드를 참고하세요.
요구 사양
Android 4.0.3 Jellybean (API 레벨 15) 이상
Android Studio 3.2 이상
Gradle 4.0.1 이상
compileSdkVersion 31 이상
AndroidX
JDK 1.11
Kotlin 버전 1.5 이상
준비 사항
항목 | 설명 | 비고 | |
---|---|---|---|
1 | 연동 앱 로그인을 위한 API 서버 | BuzzScreen SDK에 사용자 정보를 등록하기 위한 API입니다. |
|
2 | 포인트 적립 요청 수신 API | 버즈빌 서버에서 포인트 적립 요청을 보낸 이후, 실제 포인트 지급을 처리할 매체사 API 서버입니다. | |
3 | 연동을 위한 키 값 | 버즈빌 BD 매니저로부터 발급받은
|
|
BuzzScreen 연동하기
1 단계. build.gradle
, AndroidManifest.xml
설정
1. build.gradle
에 아래 코드에 보이는 저장소 및 디펜던시를 추가하세요.
repositories {
maven { url "https://dl.buzzvil.com/public/maven" }
}
dependencies {
implementation 'com.buzzvil:buzzscreen:4.45.+'
}
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()
호출
항목 | 코드 | 호출 위치 | 설명 |
---|---|---|---|
버즈스크린 초기화 |
|
|
|
버즈스크린 시작 |
| 앱 실행 시 처음 실행되는 액티비티에 추가하세요. | - |
아래의 코드 예제를 참고하세요.
2) 사용자 정보 설정
항목 | 코드 | 호출 위치 | 설명 |
---|---|---|---|
사용자 정보 설정을 위한 객체 |
|
| 사용자 정보 설정할 수 있는 |
사용자 식별 값 필수 |
|
| |
사용자 연령 권장 |
| 사용자의 출생년도를 4자리 숫자로 입력하여 나이를 설정하세요. | |
사용자 성별 권장 |
| 미리 정의된 String을 통해 형식에 맞추어 성별을 설정하세요.
| |
사용자 지역 선택 |
| "시/도 + 공백 + 시/군/구" 형식으로 설정하세요.
| |
이 외 선택 | 커스텀 타게팅 가이드 참고 | 매체사에서 원하는 사용자 정보로 타겟팅할 수 있습니다. |
아래의 코드 예제를 참고하세요.
3) 잠금화면 제어 설정
항목 | 코드 | 호출 위치 | 설명 |
---|---|---|---|
다른 앱 위에 표시 권한 획득 필수 |
| 버즈스크린 활성화 시점 |
|
버즈스크린 활성화 필수 |
| 버즈스크린 활성화 시점
| 이 함수가 호출된 이후부터 잠금화면에 버즈스크린이 나타납니다.
|
버즈스크린 비활성화 필수 |
| 버즈스크린 비활성화 시점 | 이 함수가 호출되면 더 이상 잠금화면에 버즈스크린이 나타나지 않습니다. |
사용자 로그아웃 필수 |
| 사용자가 로그아웃하는 시점 | 이 함수는 |
버즈스크린이 화면에서 사라지는 시간 설정 권장 |
|
| 버즈스크린 액티비티가 화면에 뜬 뒤 일정 시간 동안 유저의 활동이 없을 경우 버즈스크린이 화면에서 사라집니다.
|
잠금화면을 활성화한 후 실제로 잠금화면이 처음 준비가 된 시점 확인 선택 |
|
| 활성화한 후 실제로 잠금화면이 처음 준비가 완료된 시점을 알고 싶을 때, 아래의 interface를 구현하여 |
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 연동)
버즈스크린은 포인트 적립이 발생했을 때 직접 사용자들에게 포인트를 지급하는 것이 아닙니다. 버즈스크린 서버에서는 매체사 서버로 포인트 적립 요청을 보낼 뿐이며, 실제 지급은 매체사 서버에서 처리합니다.
프로세스
매체사 포인트 적립 포스트백 API 연동 가이드를 참고하여 포스트백 수신 서버 구축하세요.
Endpoint url을 버즈빌 BD 매니저에게 전달하세요.
포인트 적립 요청 흐름
버즈배너(BuzzBanner)
버즈배너(BuzzBanner)는 BuzzScreen SDK 4.15.x부터 버즈스크린 화면 아래에 비보상 노출형 광고를 노출하는 배너 타입의 지면입니다. 버즈빌에서 기본 UI를 제공하는 SimpleLockerActivity
, 자유롭게 UI를 커스터마이징할 수 있는 LockerActivity
를 제공합니다.
준비 사항
버즈배너를 연동하려면 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. ID를 발급받으려면 버즈빌 담당자에게 연락하세요.
ID 유형 | 설명 |
---|---|
BuzzBannerAppID | 앱을 구분하게 하는 고유 App ID 입니다. |
BuzzBannerSecret | 앱을 구분하게 하는 고유 App Secret 입니다. |
PlacementID | 각 광고 지면을 구분하게 하는 고유 ID 입니다. 배너의 사이즈와 PlacementID 가 제대로 매칭되어야 광고 할당 및 노출이 정상적으로 이루어집니다. |
BuzzBanner 초기화
BuzzScreen을 초기화한 다음 바로 BuzzBanner를 초기화할 수 있습니다. 다음의 절차를 따르세요. .
사전에 준비한 ID를
BuzzScreen.getInstance().initBuzzBanner
에 설정하세요.BuzzBannerConfig
를 생성하세요.생성한
BuzzBannerConfig
를BuzzScreen.getInstance().setDefaultBuzzBannerConfig(buzzBannerConfig)
를 통해 설정하세요.
사이즈 | Enum |
---|---|
Banner 320 x 50 |
|
Banner 320 x 100 |
|
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) |
---|---|---|---|
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
를 추가하세요.