docs/buzzbenefit-android/v5/roulette

버즈룰렛(BuzzRoulette)

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

...

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

...

준비 사항​

BuzzRoulette을 연동하기 전, 베네핏허브와 잠금화면 중 하나 이상을 연동한 상태여야 합니다.

• Buzzvil SDK 베네핏허브 연동 또는 팝 베네핏허브 연동 완료

• BuzzScreen SDK 잠금화면 연동 완료

BuzzRoulette 연동하기​

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

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

Buzzvil과 BuzzRoulette을 연동하는 경우​

// 모듈 레벨의 build.gradle
dependencies { 
    def buzzvilBomVersion = 5.17.+

    api platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion")
    implementation "com.buzzvil:buzzvil-sdk"
    implementation "com.buzzvil:buzz-roulette"
}

BuzzScreen과 BuzzRoulette을 연동하는 경우​

// 모듈 레벨의 build.gradle
dependencies { 
    def buzzvilBomVersion = 5.17.+

    api platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion")
    implementation "com.buzzvil:buzzscreen"
    implementation "com.buzzvil:buzz-roulette"
}

Buzzvil, BuzzScreen, BuzzRoulette을 모두 연동하는 경우​

// 모듈 레벨의 build.gradle
dependencies { 
    def buzzvilBomVersion = 5.17.+

    api platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion")
    implementation "com.buzzvil:buzzvil-sdk"
    implementation "com.buzzvil:buzzscreen"
    implementation "com.buzzvil:buzz-roulette"
}

...

2. 버즈빌 담당자(help@buzzvil.com)에게 BuzzRoulette 사용 여부를 알려 주세요.

커스터마이징하기​

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

...

룰렛 테마 변경하기​

버즈룰렛 페이지의 색상을 자유롭게 설정할 수 있습니다.

...

룰렛 아이콘 추가하기​

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

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

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

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

다른 영역에 룰렛 아이콘 추가하기​

룰렛 아이콘을 베네핏허브 기본 위치 이외에도 베네핏허브 내외부의 원하는 위치에 추가할 수 있습니다. Buzzvil SDK는 다음의 API를 통해 이 기능을 제공합니다.

...

private fun checkRouletteAvailability() {
    BuzzAdBenefit.checkRouletteAvailability(
        this,
        object : RouletteAvailabilityListener {
            override fun onAvailable() {
                // 룰렛 사용 가능
                getAvailableRouletteTicketCount() // 룰렛 사용이 가능할 때 받을 수 있는 티켓 수량을 가져옵니다.
            }

            override fun onNotAvailable() {
                // 룰렛 사용 불가
            }
        }
    )
}

private fun getAvailableRouletteTicketCount() {
    BuzzAdBenefit.getAvailableRouletteTicketCount(object : RouletteAvailableTicketCountListener {
        override fun onCountFetched(count: Int) {
            // count: 받을 수 있는 티켓 수량
        }
    })
}

private fun startRoulette() {
    BuzzAdBenefit.startRoulette(this, object : RouletteStartListener {
        override fun onSuccess() {
            // 룰렛 액티비티 실행 성공
        }

        override fun onFailure() {
            // 룰렛 액티비티 실행 실패
        }
    })
}

복사

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

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

...

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

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

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

  Code Block

  // CustomLockerActivity.kt class CustomLockerActivity : BaseLockerActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_custom_locker) val rouletteButton: RouletteButton = findViewById(R.id.rouletteButton) // 룰렛이 정상적으로 초기화되었는지 확인할 수 있는 이벤트 리스너 val rouletteLaunchListener = object: RouletteLaunchListener { override fun onSuccess() { // 룰렛이 정상적으로 초기화 되었을 때 호출됩니다. } override fun onFailure() { // 룰렛 초기화가 실패되었을 때 호출됩니다. } } // 룰렛 버튼을 클릭했을 때 룰렛이 정상적으로 시작되었는지 확인할 수 있는 이벤트 리스너 val rouletteStartListener = object: RouletteStartListener { override fun onSuccess() { // 룰렛이 정상적으로 시작되었을 때 호출됩니다. // TODO: 유저가 룰렛에 진입했다는 이벤트 기록 수집하는 등 기획에 따라 구현합니다. } override fun onFailure() { // 룰렛 시작이 실패되었을 때 호출됩니다. // TODO: 룰렛 시작 실패에 대한 로그 수집 등 기획에 따라 구현합니다. } } bindRouletteButton(rouletteButton, rouletteLaunchListener, rouletteStartListener) // RouletteLaunchListener, RouletteStartListener는 optional이므로 사용하지 않을 경우 null로 전달합니다. // bindRouletteButton(rouletteButton, null, null) } }

  복사

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

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

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

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

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

...

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

...

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

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

...

val isActive = BuzzAdBenefit.getRouletteNotificationStatus()
// true: 포그라운드 서비스 알림 사용
// false: 포그라운드 서비스 알림 사용하지 않음

val useNotification = true
BuzzAdBenefit.setRouletteNotificationStatus(this, useNotification, object: RouletteNotificationStatusListener {
    override fun onStatus(isActive: Boolean, code: Int, reason: String) {
        Log.d("Notification", "is Active: $isActive, code: $code, reason: $reason")
    }
})

class App : Application {
    override fun onCreate() {
        super.onCreate()

        ...
        // Application.onCreate() 단계에서 설정하지 않았을 경우 동작이 정상적으로 이뤄지지 않을 수 있습니다.
        // BuzzAdBenefit.init 함수 호출 이후에 적용해야합니다.
        // 해당하는 함수에서 동작을 정의하는것을 권장합니다.
        
        BuzzAdBenefit.setRouletteNotificationAction(object: RouletteNotificationAction {
            override fun onNotificationClick(activity: Activity): Boolean {
                // Add Your Action
                
                // true로 반환 시 Roulette Noti 커스터마이징 & 기본 동작 실행
                // false로 반환 시 Roulette Noti 커스터마이징한 동작만 실행하고 기본 동작은 실행하지 않음
                return false;
            }
        })
        
        // Action을 null로 설정하게 되면 BuzzAdRoulette의 기본 동작으로 실행되게 됩니다.
        BuzzAdBenefit.setRouletteNotificationAction(null)
        ...
    }
}

복사

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

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

...

✏️  참고
Buzzvil SDK와 Buzzscreen SDK 두 곳에서 룰렛을 사용하는 경우에는 Buzzvil SDK에서 설정하는 것을 권장합니다.

Buzzvil SDK에서 사용 방법​

BuzzvilSdk.initialize() 호출 직후 RouletteNotificationServiceConfig를 설정합니다.

BuzzvilSdk.initialize(context, buzzAdBenefitConfig)
val rouletteNotificationServiceConfig = RouletteNotificationServiceConfig.Builder()
    .channelName("buzzvil-ch")
    .largeIconResourceId(R.drawable.large_app_icon)
    .smallIconResourceId(R.drawable.small_app_icon)
    .title("buzzvil-title")
    .text("buzzvil-text")
    .build()
BuzzAdBenefit.setRouletteNotificationServiceConfig(rouletteNotificationServiceConfig);

복사

Buzzscreen 에서 사용방법​

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

Buzzscreen.init(unitId, context, lockerActivityClass, imageResourceIdOnFail)
val rouletteNotificationServiceConfig = RouletteNotificationServiceConfig.Builder()
    .channelName("buzzvil-ch")
    .largeIconResourceId(R.drawable.large_app_icon)
    .smallIconResourceId(R.drawable.small_app_icon)
    .title("buzzvil-title")
    .text("buzzvil-text")
    .build()
BuzzScreen.setRouletteNotificationServiceConfig(rouletteNotificationServiceConfig)

복사

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

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

...