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

개요

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

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

시작하기 전에

안내 사항

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

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

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

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

  • 버즈스크린의 UI 및 동작을 커스터마이징하고 싶다면 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/385253519을 참고하여 구현하세요.

  • 사용자가 룰렛을 돌려 리워드를 획득할 수 있는 버즈룰렛(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 이상

Lockscreen Activity의 style에 windowTranslucent, windowIsFloating, windowSwipeToDismiss 중 1개 이상이 true로 설정되어 있을 경우 Android OS 8.0 버전에서 크래시가 발생할 수 있습니다. 그러므로 연동하는 앱이 Android OS 8.0 버전을 지원하는 경우 아래 내용을 확인하세요.

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,windowSwipeToDismisstrue로 세팅된 항목을 제거 또는 false로 변경

1 2 3 4 5 6 7 8 9 <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에 아래 코드에 보이는 저장소 및 디펜던시를 추가하세요.

1 2 3 4 5 6 7 repositories { maven { url "https://dl.buzzvil.com/public/maven" } } dependencies { implementation 'com.buzzvil:buzzscreen:4.1.+' }

BuzzAd Android용 SDK도 연동하고 있는 경우, 빌드 시 com.android.tools.r8.errors.CompilationError: Program type already present: com.buzzvil.buzzresource.BuildConfig 오류가 발생할 수 있습니다. 이는 BuzzAd Benefit SDK 3.5.+를 연동하면 해결됩니다.

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

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

3. 모듈 레벨의 build.gradle 파일에 compileSdkVersiontargetSdkVersion31로 업데이트하세요.

1 2 3 4 5 6 7 android {     compileSdkVersion 31     defaultConfig {         targetSdkVersion 31     } } 

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

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

3 단계. 메소드 호출

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

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

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

버즈스크린 초기화
필수

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

  • Application ClassonCreate

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

기존에 사용하던 Application Class가 없이 BuzzScreen 연동을 위해 처음으로 Application Class를 생성할 경우 반드시 AndroidManifest.xml에 해당 Application Class를 등록해야 합니다.

  • Parameters

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

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

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

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

      • 커스터마이징을 하는 경우 직접 구현한 액티비티 클래스를 설정합니다. 자세한 내용은 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/386236524의 설명을 참고하세요.

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

버즈스크린 시작
필수

BuzzScreen.getInstance().launch()

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

-

 

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 public class App extends Application { @Override public void onCreate() { super.onCreate(); // BuzzScreen 초기화 BuzzScreen.init("Unit ID", this, SimpleLockerActivity.class, R.drawable.image_on_fail); } } public class MainActivity extends Activity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 앱 실행시 처음 실행되는 액티비티에 추가합니다. BuzzScreen.getInstance().launch(); } }

 

2) 사용자 정보 설정

연령, 성별, 지역 등 사용자 정보를 설정하지 않는 경우 타겟팅이 설정된 광고가 보이지 않으므로, 사용자가 볼 수 있는 전체 광고의 수량이 줄어들게 됩니다. 사용자 정보 설정이 불가능한 경우 BD 매니저와 사전에 논의하시기 바랍니다.

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

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

BuzzScreen.getInstance().getUserProfile()

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

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

사용자 식별 값 필수

setUserId(String userId)

userId

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

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

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

앱 재설치 또는 일정 주기에 따라 userId 가 변화할 경우, 반드시 미리 BD 매니저와 논의하시기 바랍니다.

사용자 연령 권장

setBirthYear(int birthYear)

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

사용자 성별 권장

setGender(String gender)

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

  • UserProfile.USER_GENDER_MALE : 남성

  • UserProfile.USER_GENDER_FEMALE : 여성

사용자 지역 선택

setRegion(String region)

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

이 외 선택

https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/385417457 가이드 참고

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

 

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

1 2 3 4 5 6 // 사용자 정보를 등록하는 코드입니다. com.buzzvil.buzzscreen.sdk.UserProfile userProfile = BuzzScreen.getInstance().getUserProfile(); userProfile.setUserId("USER_ID"); userProfile.setBirthYear(1985); userProfile.setGender(UserProfile.USER_GENDER_MALE); userProfile.setRegion("서울특별시 관악구");

 

3) 잠금화면 제어 설정

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

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

BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

버즈스크린 활성화 시점

버즈스크린 활성화 필수

BuzzScreen.getInstance().activate()

버즈스크린 활성화 시점

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

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

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

버즈스크린 비활성화 필수

BuzzScreen.getInstance().deactivate()

버즈스크린 비활성화 시점

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

사용자 로그아웃 필수

BuzzScreen.getInstance().logout()

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

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

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

BuzzScreen Android용 SDK v1.9.2.3 이상에서만 설정할 수 있습니다.

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() 메소드의 파라미터로 넘깁니다.

1 2 3 public interface OnReadyListener { void onReady();// This will be called when the first lockscreen is ready to be shown. }

Notification 커스텀 선택

https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/385744942 문서 참고

 

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

 

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

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

Android 12부터는 다른 앱 위에 표시 권한을 획득하지 않으면 아래의 문제가 발생할 수 있습니다.

  • 일부 모바일 기기에서 잠금화면을 실행할 때 잠금화면 기능이 정상적으로 작동하지 않을 수 있습니다.다.

  • 기본 보안 기능 화면 속성 수정 토픽에 안내된 기본 보안 기능 화면이 나타나지 않습니다. 이는 특히 Google Play 정책에 따라 앱 등록 거부를 초래할 수 있으므로 반드시 다른 앱 위에 표시 권한을 요청하는 기능을 추가하세요.

1) 인앱 안내 메시지

  • boolean BuzzScreen#showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

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

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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 public class MainActivity extends AppCompatActivity { private BuzzScreenClient buzzScreenClient = new BuzzScreenClient(); @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 본 예제에서는 MainActivity를 시작 Activity라고 가정하고 launch 메소드를 추가함 BuzzScreen.getInstance().launch(); } @Override protected void onResume() { super.onResume(); buzzScreenClient.checkAvailability(new BuzzScreenClient.OnCheckAvailabilityListener() { @Override public void onAvailable() { // 버즈스크린을 활성화 할 수 있는 경우 호출됩니다. // 잠금화면 활성화에 필요한 흐름을 구성합니다. // 최종 잠금화면 활성화는 BuzzScreen.getInstance().activate()를 통해 동작합니다. checkShowOverPermission(); } @Override public void onError(BuzzScreenClient.CheckAvailabilityError error) { switch (error) { case HOST_APP_NOT_INSTALLED: sendToPlayStore("앱이 설치되어 있지 않습니다.\n설치 링크로 이동합니다."); break; case HOST_NOT_SUPPORTED_VERSION: sendToPlayStore("앱이 최신 버전이 아닙니다.\n설치 링크로 이동합니다."); break; case NOT_ENOUGH_USER_INFO: // M App 을 통해 유저 정보를 받을 수 있도록 합니다. sendToMain(); break; case UNKNOWN_ERROR: Toast.makeText(MainActivity.this, "에러가 발생했습니다. 다시 시도해주세요.", Toast.LENGTH_SHORT).show(); break; } } }); } @Override public void onPause() { super.onPause(); // checkAvailability 를 중단하기위해 호출합니다. // 여기서 중단하지 않으면 onAvailable or onError 가 호출됩니다. buzzScreenClient.pause(); } private fun checkShowOverPermission() { BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(new BuzzScreen.OverlayPermissionListener() { @Override public void onGranted() { // 권한 획득 성공 // 권한이 있으므로, 잠금화면 활성화 가능합니다. BuzzScreen.getInstance().activate(); } @Override public void onFailed(Throwable throwable) { // 권한 획득 실패 // 권한이 없으므로, 잠금화면을 비활성화 합니다. if (BuzzScreen.getInstance().isActivated()) { BuzzScreen.getInstance().deactivate(); } ) }); } }
  • 팝업에서 확인 클릭 시 해당 권한을 획득할 수 있는 안드로이드 설정 화면으로 이동하고, 권한 획득시 자동으로 이전 화면으로 전환

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

2) 잠금화면 안내 메시지

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

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

  • 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)

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

1 2 3 4 5 6 7 8 9 10 11 BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail, Constants.useGDPR ? BuzzScreen.PrivacyPolicy.GDPR : BuzzScreen.PrivacyPolicy.NONE); BuzzScreen.getInstance().setSecurityConfiguration( new SecurityConfiguration.Builder(). backgroundResourceId(R.drawable.your_drawable). backgroundImageScaleType(ImageView.ScaleType.FIT_CENTER). backgroundColor(Color.WHITE). backgroundDimAlpha(0.7f). showClock(true). showDescription(true). build());

 

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

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

포인트 적립 알림 푸시를 사용자에게 보내고 싶은 경우에는 포인트 적립 요청을 받고 매체사에서 직접 푸시를 전송합니다.

포인트 적립 요청 흐름