BuzzRoulette 연동가이드: Android SDK v3

Owned by Lia Lee (Unlicensed)
Last updated: Aug 19, 2024
17 min read

버즈룰렛(BuzzRoulette)

BuzzRoulette은 사용자에게 포인트를 무료로 적립할 수 있는 리워드 룰렛과 광고에 참여할 때마다 룰렛을 돌리기 위해 필요한 티켓을 제공하는 기능입니다. BuzzRoulette을 통해 룰렛 게임의 재미를 제공하여 티켓을 획득하기 위한 사용자의 광고 참여를 자연스럽게 유도할 수 있습니다. 이로써 광고 노출 비율을 높이고 BuzzAd 또는 BuzzScreen SDK를 연동한 앱의 매출을 대폭 끌어올릴 수 있습니다.

BuzzRoulette은 Android용 BuzzAd SDK v3.1.x와 BuzzScreen SDK v4.0.x 이상부터 지원합니다. BuzzRoulette 연동을 완료하려면 버즈빌이 필요한 서버 구성을 설정해야 합니다. BuzzRoulette 연동을 완료하면 BuzzAd는 피드 지면, BuzzScreen은 잠금화면 우측 상단에 기능을 실행할 수 있는 룰렛 아이콘이 생성됩니다.

아이콘을 눌러 룰렛 화면에 진입한 사용자가 터치해서 티켓얻기를 눌러 광고에 참여하거나 영상보고 티켓얻기를 눌러 광고 영상을 시청하면 룰렛을 돌리기 위한 티켓을 얻을 수 있습니다.

✏️  참고

  • BuzzAd에서는 사용자가 개인정보 수집에 동의하지 않으면 룰렛 기능을 실행할 수 없습니다.

  • BuzzRoulette을 사용하려면 BuzzRoulette을 라이브러리를 직접 추가해야 합니다.

 

BuzzAd 피드에서 룰렛 아이콘을 통해 실행되는 BuzzRoulette

BuzzScreen 잠금화면에서 룰렛 아이콘을 통해 실행되는 BuzzRoulette

준비 사항​

BuzzRoulette을 연동하기 전, BuzzAd와 BuzzScreen 중 하나 이상을 연동한 상태여야 합니다.

BuzzRoulette 연동을 위한 조합​

BuzzRoulette은 BuzzAd와 BuzzScreen을 지원합니다. 세 개의 라이브러리는 다음과 같이 조합할 수 있습니다.

  • BuzzAd + BuzzRoulette

  • BuzzScreen + BuzzRoulette

  • BuzzAd + BuzzScreen + BuzzRoulette

BuzzRoulette을 BuzzAd, BuzzScreen에 연동할 때에는 안정적인 기능 구현을 위해 아래 표에 명시된 버전끼리 조합하세요.

BuzzRoulette

       BuzzAd      

     BuzzScreen    

BuzzRoulette

       BuzzAd      

     BuzzScreen    

2.2.+

3.1.+

3.37.+

2.4.+

3.3.+

3.39.+

2.7.+

3.5.+

4.0.+

2.8.+

3.7.+

4.1.+

2.9.+

3.9.+

4.3.+

2.11.+

3.11.+

4.5.+

2.13.+

3.13.+

4.7.+

2.15.+

3.15.+

4.9.+

2.17.+

3.17.+

4.11.+

2.19.+

3.19.+

4.13.+

2.21.+

3.21.+

4.15.+

2.23.+

3.23.+

4.17.+

2.25.+

3.25.+

4.19.+

2.27.+

3.27.+

4.21.+

2.29.+

3.29.+

4.23.+

2.31.+

3.31.+

4.25.+

2.34.+

3.35.+

4.29.+

2.36.+

3.37.+

4.31.+

2.38.+

3.39.+

4.33.+

2.39.+

3.41.+

4.35.+

2.41.+

3.43.+

4.37.+

2.42.+

3.45.+

4.39.+

2.42.+

3.47.+

4.41.+

✏️  참고

  • BuzzAd 3.3.+와 BuzzRoulette 2.2.+를 연동 중인 경우, BuzzRoulette 2.4.+로 마이그레이션해야 합니다. 마이그레이션에 대한 자세한 내용은 BuzzRoulette 마이그레이션 가이드를 참고하세요.

  • BuzzAd 3.15.+(BuzzRoulette 2.15.+)에서 BuzzAd 3.17.+(BuzzRoulette 2.17.+) 이상 버전으로 업데이트하는 경우 BuzzAd Android v3.17.x 마이그레이션 가이드를 참고하여 업데이트를 진행하세요

  • BuzzAd와 BuzzScreen을 모두 연동한 상태에서 한쪽에서만 활성화하고 싶은 경우, help@buzzvil.com에 연락하세요.

 

BuzzRoulette 연동하기​

✅  중요
BuzzRoulette, BuzzAd, BuzzScreen의 라이브러리 버전 조합에 대한 정보는 BuzzRoulette 연동을 위한 버전 조합 을 참고하세요.

BuzzRoulette을 연동하려면 다음의 절차를 따르세요.

  1. 프로젝트 레벨의 build.gradle 파일에 jitpack과 Pangle ADN repository를 추가하세요.

    // 프로젝트 레벨의 build.gradle allprojects { repositories { maven { url 'https://jitpack.io' }  // jitpack 추가 maven { url 'https://artifact.bytedance.com/repository/pangle' } // Pangle ADN 저장소 추가 maven { url 'https://dl.cloudsmith.io/public/avatye/Android-SDK/maven/' } // Avatye 저장소 추가 } }

    복사

  2. 모듈 레벨의 build.gradle 파일에서 dependencies 블록에 implementation 원격 바이너리 종속 항목의 구성을 지정하세요.

BuzzAd와 BuzzRoulette을 연동하는 경우 - BuzzAd 3.1.+, BuzzRoulette 2.2.+ 연동 예시​
// 모듈 레벨의 build.gradle dependencies { implementation 'com.buzzvil:buzzad-benefit:3.1.+' implementation 'com.buzzvil:buzz-roulette:2.2.+' }

복사

BuzzScreen과 BuzzRoulette을 연동하는 경우 - BuzzScreen 3.37.+, BuzzRoulette 2.2.+ 연동 예시​
// 모듈 레벨의 build.gradle dependencies { implementation 'com.buzzvil:buzzscreen:3.37.+' implementation 'com.buzzvil:buzz-roulette:2.2.+' }

복사

BuzzAd, BuzzScreen, BuzzRoulette을 모두 연동하는 경우 - BuzzAd 3.1.+, BuzzScreen 3.37.+, BuzzRoulette 2.2.+ 연동 예시​

복사

❌  오류
위의 dependency를 추가할 때 다음과 같은 오류가 발생할 수 있습니다. 이는 gradle.properties에 android.enableJetifier=true를 추가하여 해결할 수 있습니다.

오류 메시지

  1. 버즈빌 담당자에게 BuzzRoulette 사용 여부를 알려 주세요.

커스터마이징하기​

BuzzRoulette의 화면 타이틀과 적립 리워드 단위를 표시하는 텍스트를 변경할 수 있습니다. 화면 상단의 타이틀을 최대 10자까지, 적립 리워드 단위(예: 캐시, 머니 등)를 최대 5자까지 변경할 수 있습니다. 변경이 필요한 경우 버즈빌 담당자에게 연락하세요.

룰렛 아이콘 추가하기​

프로젝트를 빌드하여 앱을 실행하면 BuzzAd 피드 또는 팝 피드, 그리고 BuzzScreen 잠금화면에 룰렛 버튼이 자동으로 추가됩니다. 단, 지면을 커스텀한 경우에는 직접 코드를 설정해야 합니다.

  • 룰렛 아이콘을 표시하거나 제거하려면 반드시 버즈빌의 서버 설정이 병행되어야 합니다.

  • 버즈빌이 서버에서 BuzzRoulette을 비활성화한 앱에는 룰렛 아이콘이 표시되지 않습니다.

  • 버즈빌 서버에서 변경된 설정이 적용되기까지 최대 6시간이 소요될 수 있습니다.

BuzzAd 피드 커스텀 툴바에 룰렛 아이콘 추가하기​

BuzzAd Android용 SDK에서 제공하는 기본 UI를 수정하여 툴바를 커스텀하는 경우, 직접 코드를 설정하여 룰렛 아이콘을 추가할 수 있습니다.

⚠️  주의
BuzzAd를 연동한 경우에 해당하는 내용입니다. BuzzSceen만 연동한 경우에는 해당하지 않습니다.

FeedToolbar에 룰렛 아이콘 추가하기​

BuzzAd Android용 SDK에서 제공하는 FeedToolbar 기본 UI를 수정한 후 룰렛 아이콘을 추가하려면 addRouletteMenuItemView를 호출하세요.

복사

PopToolbar에 룰렛 아이콘 추가하기​

BuzzAd Android용 SDK에서 제공하는 PopToolbar 기본 UI를 수정한 후 룰렛 아이콘을 추가하려면 addRouletteMenuItemView를 호출하세요.

복사

직접 구현한 커스텀 툴바에 룰렛 아이콘 추가하기​

✅  중요
이 기능은 BuzzAd Android용 SDK v3.9.0부터 추가할 수 있습니다. v3.9.0 미만의 버전을 연동한 경우 이 기능을 탑재하려면 v3.9.0 이상으로 업데이트하세요. 직접 구현한 Custom View 사용하기를 통해 툴바의 레이아웃을 구성한 경우 checkRouletteAvailability, getRouletteTicketCount, showRoulette을 통해 툴바에 룰렛 아이콘을 추가할 수 있습니다.

  • checkRouletteAvailability: 룰렛 기능을 추가할 수 있는지 판단합니다.

    • 추가할 수 있으면 RouletteAvailabilityListener.onAvailable이 호출됩니다.

    • 추가할 수 없다면 RouletteAvailabilityListener.onNotAvailable이 호출됩니다.

  • getRouletteTicketCount: 획득 가능한 룰렛 티켓 수량을 가져옵니다.

    • checkRouletteAvailability에서 RouletteAvailabilityListener.onAvailable 호출되어야 사용할 수 있습니다.

    • RouletteAvailableTicketCountListener.onCountFetched(int count)를 통해 획득 가능한 룰렛 티켓 수량을 가져옵니다.

  • showRoulette: 룰렛 액티비티를 실행합니다.

Custom View를 사용하는 FeedToolbar에 룰렛 아이콘 추가하기​

복사

Custom View를 사용하는 PopToolbar에 룰렛 아이콘 추가하기​

복사

BuzzAd 피드 툴바 이외의 영역에 룰렛 아이콘 추가하기​

룰렛 아이콘을 피드 툴바 이외에도 원하는 임의의 영역에 추가할 수 있습니다. BuzzAd Android용 SDK는 다음의 API를 통해 이 기능을 제공합니다.

✅  중요
이 기능은 BuzzAd Android용 SDK v3.11.x부터 사용할 수 있습니다. v3.11.x 미만의 버전을 연동한 경우 이 기능을 사용하려면 v3.11.x 이상으로 업데이트하세요.

API

설명

API

설명

BuzzAdBenefit.checkRouletteAvailability()

룰렛의 사용 가능 여부를 확인합니다.

  • Context: Android 컨텍스트

  • RouletteAvailabilityListener: 룰렛의 사용 가능 여부를 호출하는 리스너

    • onAvailable(): 사용 가능

    • onNotAvailable(): 사용 불가

BuzzAdBenefit.getAvailableRouletteTicketCount()

룰렛에서 받을 수 있는 티켓 수량을 가져옵니다.

  • RouletteAvailableTicketCountListener: 받을 수 있는 티켓 수량을 가져오는 리스너

    • onCountFetched(int count): 카운트(count)받을 수 있는 티켓 수량

BuzzAdBenefit.startRoulette()

룰렛을 시작합니다.

  • Activity: 룰렛 버튼이 추가되는 액티비티

  • RouletteStartListener: 룰렛 시작 결과가 호출되는 리스너

    • onSuccess: 룰렛을 사용할 수 있어 룰렛 아이콘이 액티비티에 표시되고 기능을 사용할 수 있습니다.

    • onFailure: 룰렛을 사용할 수 없습니다. “죄송합니다! 지금은 사용할 수 없습니다.“ 토스트가 표시됩니다.)

피드 툴바 이외의 영역에 룰렛 아이콘을 추가하려면 다음의 절차를 따르세요.

  1. 액티비티가 시작되는 시점에 checkRouletteAvailability를 사용해 룰렛의 사용 가능 여부를 확인하세요.

  • checkRouletteAvailability에서 RouletteAvailabilityListener를 통해 onAvailable()이 호출되면 룰렛을 사용할 수 있습니다.

✅  중요

  • checkRouletteAvailability를 사용하는 시점은 원하는 대로 구현할 수 있습니다. 단, 사용자의 원활한 룰렛 사용을 위해 버즈빌은 실제 룰렛 사용 시점과 룰렛 사용 가능 여부의 확인 시점을 가까운 최대한 가깝게 구현하는 것을 권장합니다.

  • 룰렛 사용이 가능해야 다음 절차를 수행할 수 있습니다.

 

  1. 만약 획득 가능한 룰렛 티켓 수량을 가져와서 표시하려면, RouletteAvailabilityListener.onAvailable에서 getAvailableRouletteTicketCount를 호출하세요.

  • RouletteAvailableTicketCountListener의 onCountFetched(int count)를 통해 받을 수 있는 티켓 수량을 가져올 수 있습니다.

✏️  참고
2번 단계는 사용자의 룰렛 사용을 유도하기 위한 선택적인 절차입니다.

  1. 룰렛 아이콘을 눌렀을 때 룰렛 기능이 시작되도록 startRoulette을 사용하세요.

  • 성공 시 룰렛 액티비티가 실행됩니다.

  • 실패 시 "죄송합니다! 지금은 사용할 수 없습니다." 토스트가 표시됩니다.

복사

BuzzScreen 커스텀 잠금화면에 룰렛 아이콘 추가하기​

자체적으로 구현한 잠금화면을 사용하는 경우에는 아래 내용을 참고하여 룰렛 아이콘을 추가하세요.

⚠️  주의
BuzzScreen을 연동한 경우에 해당하는 내용입니다. BuzzAd만 연동하는 경우에는 해당하지 않습니다.

  1. BaseLockerActivity를 상속받은 커스텀 액티비티 XML 파일 내 원하는 위치에 RouletteButton을 추가하거나 코드로 레이아웃을 작성하여 추가하세요.

    다음은 XML 파일로 추가하는 예시입니다.

    ⚠️  주의

    • bindRouletteButton에서 roulette launch에 실패하면 자동으로 RouletteButton의 visibility가 GONE으로 설정됩니다.
      RouletteButton의 visibility가 GONE으로 변경돼도 문제 없도록 레이아웃을 작성하세요.
      RouletteButton의 visibility를 직접 변경하면 안 됩니다.

    • RouletteButton의 android:layout_width, android:layout_height는 코드 예제와 같이 모두 wrap_content로 설정해야 합니다. 크기를 임의로 변경하는 경우, 룰렛 버튼의 레이아웃이나 정렬이 틀어질 수 있습니다.

     

    복사

  2. BaseLockerActivity를 상속받은 CustomLockerActivity의 onCreate()에서 bindRouletteButton(RouletteButton, @Nullable RouletteStartListener, @Nullable RouletteLaunchListener)를 호출하여 RouletteButton를 바인드하세요.

  • 룰렛 초기화와 룰렛 시작의 성공/실패 여부에 따라 추가 작업(로그 기록 등)을 하려면 리스너를 추가하고, 리스너를 사용하지 않으려면 null로 전달하세요. 각각의 리스너 역할은 다음과 같습니다.

    • RouletteLaunchListener : 룰렛이 정상적으로 초기화되었는지 확인할 수 있는 이벤트 리스너

    • RouletteStartListener : 룰렛 버튼을 클릭했을 때 룰렛이 정상적으로 시작되었는지 확인할 수 있는 이벤트 리스너

    복사

티켓박스 포그라운드 서비스 알림 사용하기​

티켓박스 포그라운드 서비스 알림이란?​

티켓박스 포그라운드 서비스 알림은 사용자에게 획득할 수 있는 티켓 또는 티켓박스가 있음을 알리는 기능입니다. 티켓박스는 사용자가 광고에 참여하지 않아도 룰렛용 티켓을 하루에 한 번 획득할 수 있는 기능으로, 룰렛 화면에 진입하는 비율을 효과적으로 높이는 기능을 수행합니다.

티켓박스 포그라운드 서비스 알림 배너란?​

티켓박스 포그라운드 서비스 알림을 활성화하기 위한 배너는 '티켓박스가 도착했습니다'라는 메시지와 바로 확인하기 버튼으로 구성되며, 룰렛 화면에 기본적으로 나타납니다. 사용자가 이 배너를 누르면 티켓박스에 대한 설명을 확인하고 알림 기능을 활성화할 수 있으며, 티켓박스를 획득한 사용자의 룰렛 화면에서는 배너가 사라졌다가 다음날 다시 나타납니다.

티켓박스 포그라운드 서비스 알림 배너를 룰렛 화면에서 제거하거나 다시 표시하려면 버즈빌 담당자에게 연락하세요.

✏️  참고
사용자는 룰렛 화면 우측 상단의 메뉴 아이콘을 통해 티켓박스 포그라운드 서비스 알림을 끌 수 있습니다.

배너와 알림 창에 나타나는 티켓박스 포그라운드 서비스 알림

티켓박스 포그라운드 서비스 커스터마이징 API 사용하기​

다음의 API를 사용하여 티켓박스 포그라운드 서비스 알림을 사용하고 있는지 확인하거나 원하는 컴포넌트로 자체 구현한 UI를 적용할 수 있습니다. 또는 포그라운드 서비스 알림을 통해 실행하는 동작을 직접 구현할 수 있습니다.

API

설명

API

설명

BuzzAdBenefit.getRouletteNotificationStatus()

티켓박스 포그라운드 서비스 알림의 사용 여부를 확인합니다.

  • true: 포그라운드 서비스 알림 사용

  • false: 포그라운드 서비스 알림 사용하지 않음

 

✅  중요 이 기능은 BuzzAd Android용 SDK v3.17.0부터 추가할 수 있습니다.

BuzzAdBenefit.setRouletteNotificationStatus()

커스터마이징한 티켓박스 포그라운드 서비스 알림의 사용 여부를 설정합니다.

  • context: Android 컨텍스트

  • useNotification: 알림 활성화/비활성화

  • RouletteNotificationStatusListener: 포그라운드 서비스 알림 활성화/비활성화 호출되는 리스너

    • onStatus(boolean isActive, int code, @NonNull String reason): 포그라운드 서비스 알림이 성공적으로 활성화/비활성화되었는지 알림

      • isActive: 활성화 상태

      • code: 상태 코드 (0: 성공)

      • reason: 설정 실패 이유

 

✅  중요 이 기능은 BuzzAd Android용 SDK v3.17.0부터 추가할 수 있습니다.

BuzzAdBenefit.setRouletteNotificationAction

포그라운드 서비스 알림을 통해 실행하는 동작을 커스터마이징합니다.
커스터마이징하지 않으면 기본적으로 앱이 실행됩니다.

  • RouletteNotificationAction : Notification 의 주황색 버튼 클릭 시 원하는 동작 정의

    • onNotificationClick(Activity activity)

      • Activity : Android Activity

      • true 반환 시: 커스터마이징 및 기본 동작 실행

      • false 반환 시: 커스터마이징 동작만 실행

 

✅  중요 이 기능은 BuzzAd Android용 SDK v3.19.0부터 추가할 수 있습니다.

복사

티켓박스 포그라운드 서비스 알림 디자인 커스터마이징​

RouletteNotificationServiceConfig 를 통해 티켓박스 포그라운드 서비스의 알림 채널 이름, 아이콘, 텍스트를 변경할 수 있습니다.

아이콘과 Title, Text 가 변경 된 포그라운드 서비스 알림

✅  중요
이 기능은 BuzzAd Android용 SDK v3.17.x부터 사용할 수 있습니다. 이 기능을 사용하려면 v3.17.x 이상으로 업데이트하세요.

RouletteNotificationServiceConfig 으로 설정할 수 있는 값은 다음과 같습니다.

API

설명

API

설명

RouletteNotificationServiceConfig.channelName

디바이스 설정에 표시되는 채널명을 설정 합니다. 기본값은 '앱명 + 알림창 상태바'로 표시됩니다.

RouletteNotificationServiceConfig.largeIconResourceId

'티켓박스 포그라운드 서비스 알림'에 표시되는 아이콘을 설정합니다.(resource id)

RouletteNotificationServiceConfig.smallIconResourceId

디바이스 상단 알림창에 표시되는 아이콘을 설정합니다.(resource id)

RouletteNotificationServiceConfig.title

'티켓박스 포그라운드 서비스 알림'에 표시되는 앱명을 설정 합니다. 기본값은 담당 매니저를 통해 전달된 앱명을 사용합니다.

RouletteNotificationServiceConfig.text

'티켓박스 포그라운드 서비스 알림'에 표시되는 게임명을 설정 합니다. 기본값은 담당 매니저를 통해 전달된 게임명을 사용합니다. 전달된 값이 없다면, '캐시룰렛'이 설정 됩니다.

BuzzAdBenefit 에서 사용방법​

BuzzAdBenefit.init() 호출 직후 RouletteNotificationServiceConfig 를 설정합니다.

복사

Buzzscreen 에서 사용방법​

Buzzscreen.init() 호출 직후 RouletteNotificationServiceConfig 를 설정합니다.

복사

✅ BuzzAdBenefit 과 Buzzscreen 두 곳에서 룰렛을 사용하는 경우에는 한 곳에서만 설정합니다. BuzzAdBenefit 에서 설정하는 것을 권장합니다.

부록: BuzzRoulette 광고 라이브러리​

다음은 BuzzRoulette에서 참조하는 광고 라이브러리입니다.

  • AdPopcorn SDK : v3.1.0

  • UnityAds SDK : V4.3.0

  • Mobon SDK : v1.0.0.54

  • AppLovin SDK : v11.3.3

  • Pangle SDK : v4.5.0.6

❌   오류
앱에서 이미 AppLovin SDK를 연동하고 있는 경우 BuzzRoulette을 연동하면 BuzzRoulette에서 참조하는 AppLovin SDK와 충돌이 발생하여 앱 빌드에 실패할 수 있습니다. 문제를 해결하려면 AppLovin SDK 충돌이 발생합니다 토픽을 참고하세요.