본문으로 건너뛰기

팝(Pop)

팝을 추가하고 기능을 구현하는 방법과 아이콘 이미지 등의 디자인을 변경하는 방법을 알아보세요.

 중요

  • Buzzvil SDK 5.13.x 부터는 Android 14 대응을 위해 팝 모듈을 코드로 추가하는 옵트인 방식으로 제공하게 되었습니다.
  • Android 14 대응 관련 변경 사항은 릴리스 뉴스에서 확인하실 수 있습니다.

주요 특징

팝은 앱 외부에서 유저를 버즈베네핏으로 유도하는 원형 버튼입니다. 유저가 모바일 화면의 잠금을 해제할 때마다 나타나며 드래그해 원하는 위치로 옮길 수 있습니다. 또한 기본형 팝 버튼에는 투명도가 적용되어 Android 12에 적용되는 오버레이의 터치 이벤트 차단을 대응하고 안정적인 앱 동작을 지원합니다.

연동

팝을 추가하는 방법을 확인해 보세요.

1 단계. 준비하기

2 단계. 팝 버즈베네핏 추가하기

팝 사용을 위한 의존성을 gradle 파일에 추가하세요.

// 모듈 레벨의 build.gradle

dependencies {
    val buzzvilBomVersion = 6.0.+

    api(platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion"))
    implementation("com.buzzvil:buzzvil-sdk")
    implementation("com.buzzvil:buzzad-benefit-pop")
}

3 단계. 팝 활성화하기

팝을 활성화하여 유저에게 제공하려면 다음의 절차를 따르세요.

  1. BuzzPop.activate()를 호출해 팝을 활성화하세요.
  • Android 정책에 따라 Android 6.0 Marshmallow 이상 버전에서는 다른 앱 위에 그리기 권한을 받아야 합니다. BuzzPop.activate()를 호출할 경우에 필요에 따라 다른 앱 위에 그리기 권한을 유도하세요.
  1. BuzzPop.show()를 호출하여 팝 버튼을 표시하세요.
import com.buzzvil.buzzbenefit.pop.BuzzPop
import com.buzzvil.buzzbenefit.pop.BuzzPopActivateListener

BuzzPop.activate(object : BuzzPopActivateListener {
override fun onActivated() {
// 정상적으로 Pop이 활성화 되었을 때 호출됩니다.

// 유저 화면에 Pop을 표시합니다.
BuzzPop.show()
}

override fun onActivationFailed(error: Throwable) {
// Pop 활성화에 실패하였을 때 호출됩니다.
}
})

✏️  참고
팝을 활성화하면 포그라운드 서비스 알림이 활성화됩니다.

팝 비활성화하기

팝을 비활성화하려면 BuzzPop.deactivate()를 호출하세요. 팝을 비활성화하면 포그라운드 서비스 알림도 사라집니다.

다음은 팝을 비활성화하는 예시입니다.

import com.buzzvil.buzzbenefit.pop.BuzzPop

BuzzPop.deactivate()

팝 활성화 상태 확인하기

팝의 활성화 상태를 확인하려면 BuzzPop.isActivated를 사용하세요.

다음은 팝의 활성화 상태에 따라 팝을 켜고 끄는 예시입니다.

import com.buzzvil.buzzbenefit.pop.BuzzPop
import com.buzzvil.buzzbenefit.pop.BuzzPopActivateListener

fun togglePop() {
if (BuzzPop.isActivated) {
BuzzPop.deactivate()
} else {
BuzzPop.activate(object : BuzzPopActivateListener {
override fun onActivated() {
// 정상적으로 Pop이 활성화 되었을 때 호출됩니다.

// 유저 화면에 Pop을 표시합니다.
BuzzPop.show()
}

override fun onActivationFailed(error: Throwable) {
// Pop 활성화에 실패하였을 때 호출됩니다.
}
})
}
}

디자인 커스터마이징

Buzzvil SDK에서 제공하는 팝 버튼의 디자인을 변경하기 위한 방법을 확인할 수 있습니다. 팝 버튼 디자인 규격에 대한 자세한 지침은 팝 디자인 가이드 문서를 확인하세요.

✏️  참고
팝 설정은 SDK 초기화 전에 이루어져야 합니다.

팝 버튼 색상

팝 버튼 색상은 주요 UI의 색상(Primary color)을 따릅니다. 자세한 내용은 전체 테마 토픽을 참고하세요.

팝 버튼 아이콘

Application.onCreate에서 BuzzAdPopTheme을 설정하여 팝 버튼의 평상시 아이콘, 리워드 아이콘을 변경할 수 있습니다.

아이콘 유형코드설명권장 사이즈
평상시 아이콘iconResIdPop 버튼의 기본 아이콘입니다.
  • 56 x 56 dp (mdpi 기준)
  • 224 x 224 px (xxxhdpi까지 지원, 픽셀 기준 최대 4배)
리워드 아이콘rewardReadyIconResId적립할 수 있는 포인트가 있을 때, 표시됩니다.
  • 56 x 56 dp (mdpi 기준)
  • 224 x 224 px (xxxhdpi까지 지원, 픽셀 기준 최대 4배)

다음의 팝 아이콘을 변경하는 예시입니다.

import com.buzzvil.buzzbenefit.pop.BuzzPopTheme

// SDK 초기화 전에 호출합니다.
BuzzPopTheme.iconResId = R.drawable.your_pop_icon
BuzzPopTheme.rewardReadyIconResId = R.drawable.your_pop_icon_reward_ready

...

BuzzvilSdk.initialize( ... )

팝 버튼 아이콘 리소스 구성하기

팝 버튼 아이콘의 리소스는 각각 다음과 같이 구성할 수 있습니다.

  • iconResId: 평상시 아이콘과 종료 아이콘을 지정하세요.
<!-- your_pop_icon.xml -->
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<!-- 종료 아이콘 -->
<item android:drawable="@drawable/icon_pop_selected" android:state_selected="true" />
<!-- 평상시 팝 아이콘 -->
<item android:drawable="@drawable/icon_pop"/>
</selector>
  • rewardReadyIconResId: 적립 가능한 포인트가 있을 때 표시할 아이콘을 지정하세요.
<!-- you_pop_icon_reward_ready.xml -->
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<!-- 종료 아이콘 -->
<item android:drawable="@drawable/icon_pop_selected" android:state_selected="true" />
<!-- 적립 가능 포인트가 있을 때 팝 아이콘 -->
<item android:drawable="@drawable/icon_pop_reward_ready"/>
</selector>

팝 포그라운드 서비스 알림

팝이 활성화되면 포그라운드 서비스 알림이 유저 모바일 기기 상단의 알림 창에 표시됩니다. Buzzvil SDK에서 기본으로 제공하는 UI를 설정해 팝 포그라운드 서비스 알림 디자인을 변경하거나 자체적으로 구현한 레이아웃으로 교체할 수 있습니다.

팝 포그라운드 서비스 알림 - 기본 설정

SDK 기본 UI로 변경할 수 있는 서비스 알림 디자인 요소는 아래 그림과 표를 참고하세요.

번호구성 요소설명
1Small icon (smallIconResId)팝을 연동한 앱 아이콘입니다.
❗️ 주의 아이콘을 정상적으로 표시하기 위해 Adaptive Icon은 권장하지 않습니다.
2Color (colorResId)팝을 연동한 앱 아이콘과 앱 이름에 적용되는 색상입니다.
❗️ 주의 포그라운드 서비스 알림의 배경 색상인 흰색은 권장하지 않습니다.
3Title (titleResId)팝 포그라운드 서비스 알림임을 표시하는 텍스트입니다.
4Text (textResId)팝 포그라운드 서비스 알림을 누르면 팝 베네핏허브를 실행할 수 있음을 알리는 텍스트입니다.

팝 포그라운드 서비스 알림의 디자인을 변경하려면 BuzzPopNotificationConfig에서 구성 요소 값을 설정한 다음 BuzzPopConfigBuzzPopNotificationConfig를 설정하세요.

다음은 팝 포그라운드 서비스 알림의 디자인을 변경하는 예시입니다.

import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopNotificationConfig

val buzzPopNotificationConfig = BuzzPopNotificationConfig.Builder(applicationContext)
.smallIconResId(R.drawable.your_small_icon)
.titleResId(R.string.your_pop_notification_title)
.textResId(R.string.your_pop_notification_text)
.colorResId(R.color.your_pop_notification_color)
.notificationId(5000) // 기본값
.build()

val buzzPopConfig = BuzzPopConfig.Builder()
.buzzPopNotificationConfig(buzzPopNotificationConfig)
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()

✏️  참고
UI 레이아웃 또는 알림의 동작을 변경하려면 알림을 직접 구현해야 합니다. 자세한 내용은 팝 포그라운드 서비스 알림 자체 구현하기 토픽을 참고하세요.

팝 포그라운드 서비스 알림 - 자체 구현

BuzzPopConfig를 사용해 팝 포그라운드 서비스 알림을 직접 구현해 알림의 동작과 UI 레이아웃을 변경할 수 있습니다.

팝을 사용하면 팝 포그라운드 서비스 알림이 활성화됩니다. BuzzPopConfig를 사용해 직접 구현하지 않으면 유저 모바일 기기 상단의 알림 창에는 Buzzvil SDK에서 기본으로 제공하는 포그라운드 서비스 알림이 표시됩니다.

✏️  참고
Buzzvil SDK에서 기본으로 제공하는 포그라운드 서비스 알림의 디자인을 변경하려면 팝 포그라운드 서비스 알림 토픽을 참고하세요.

팝 포그라운드 서비스 알림을 직접 구현하려면 다음의 절차를 따르세요.

  1. BuzzPopControlService의 상속 클래스를 구현하세요.
  • notificationChannel을 생성하거나 View를 등록할 수 있습니다.

  • getPopPendingIntent(context)으로 Pop 지면으로 진입하는 PendingIntent를 이용할 수 있습니다.

    다음은 BuzzPopControlService의 상속 클래스를 구현하는 예시입니다.

    ✏️  참고
    예제 코드의 .setForegroundServiceBehavior(FOREGROUND_SERVICE_IMMEDIATE);는 Android 12의 포그라운드 서비스 알림의 UX 지연에 대응하기 위해 지원되는 인터페이스입니다.

import android.annotation.TargetApi
import android.app.Notification
import android.os.Build
import android.widget.RemoteViews
import androidx.core.app.NotificationCompat
import com.buzzvil.buzzbenefit.pop.BuzzPopNotificationConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopControlService

class YourBuzzPopControlService : BuzzPopControlService() {
override fun buildForegroundNotification(
unitId: String,
buzzPopNotificationConfig: BuzzPopNotificationConfig,
): Notification {
// Pop을 표시하는 PendingIntent (원형 아이콘)
val popPendingIntent = getPopPendingIntent(unitId, this)

// 필요에 따라 notificationChannel을 등록합니다.
val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
createNotificationChannelIfNeeded()
NotificationCompat.Builder(this, POP_NOTIFICATION_CHANNEL_ID)
} else {
NotificationCompat.Builder(this)
}

// Pop Service Notification에 사용할 View 를 등록합니다.
val remoteView = RemoteViews(packageName, R.layout.your_buzz_pop_notification)
builder.setSmallIcon(buzzPopNotificationConfig.smallIconResId)
.setContent(remoteView)
.setContentIntent(popPendingIntent)
.setPriority(NotificationCompat.PRIORITY_LOW)
.setShowWhen(false)
builder.foregroundServiceBehavior = NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE
if (buzzPopNotificationConfig.color != null) {
builder.color = buzzPopNotificationConfig.color!!
}

return builder.build()
}

@TargetApi(Build.VERSION_CODES.O)
override fun createNotificationChannelIfNeeded() {
val notificationManager = getSystemService(NOTIFICATION_SERVICE) as android.app.NotificationManager
if (notificationManager.getNotificationChannel(POP_NOTIFICATION_CHANNEL_ID) == null) {
val channel = android.app.NotificationChannel(
POP_NOTIFICATION_CHANNEL_ID,
NOTIFICATION_CHANNEL_NAME,
android.app.NotificationManager.IMPORTANCE_LOW
)
notificationManager.createNotificationChannel(channel)
}
}

companion object {
const val POP_NOTIFICATION_CHANNEL_ID = "POP_NOTIFICATION_CHANNEL_ID"
const val POP_NOTIFICATION_ID = 1000
}
}
  • notificationIdPopNotificationConfig 객체에 설정하세요. 다음의 예시를 참고하세요.
import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopNotificationConfig

val buzzPopNotificationConfig = BuzzPopNotificationConfig.Builder(this@App)
.notificationId(YourBuzzPopControlService.POP_NOTIFICATION_ID)
.build()

val buzzPopConfig = BuzzPopConfig.Builder()
.buzzPopNotificationConfig(buzzPopNotificationConfig)
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()
  1. 구현한 상속 클래스를 AndroidManifest.xmlservice로 등록하세요.

✏️  참고
예제 코드의 specialUse type 과 사유는 Android 14의 포그라운드 서비스 타입에 대응하기 위해 꼭 필요합니다.

<!-- AndroidManifest.xml -->

<application>
<service android:name=".YourControlService"
android:foregroundServiceType="specialUse">
<property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
android:value="floating bubble for user to interact" />
</service>
</application>

팝 메시지 영역

팝을 통해 진입하는 베네핏허브에 광고가 있는 경우 PopAdMessageViewClass를 이용하여 말풍선(preview)이 표시됩니다. 기본 클래스에서는 현재 적립 가능한 포인트와 팝을 표시하는 초 단위 시간을 보여주는 값을 설정할 수 있습니다.

팝 메시지 영역을 커스텀하려면 다음의 절차를 따르세요.

  1. PopAdMessageViewClass에 아래의 함수들을 오버라이드하세요.
  • PopAdMessageViewClassPopAdMessageView를 상속받아 작성해야 합니다.
함수설명
updateView메시지 말풍선이 매 초 업데이트될 때마다 호출됩니다. 남은 초 단위 시간과 적립 가능한 reward 값이 인자로 넘어옵니다.
getDurationInSeconds팝을 표시할 초 단위 시간을 리턴해야 합니다. 권장 시간은 5초입니다.

다음의 코드 예시를 참고하세요.


class YourBuzzPopMessageView: BuzzPopMessageView {
private val textTitle: TextView
private val textDescription: TextView

constructor(context: Context): super(context) {
val view = LayoutInflater.from(context).inflate(R.layout.your_buzz_pop_message_view, this)
this.textTitle = view.findViewById(R.id.textTitle)
this.textDescription = view.findViewById(R.id.textDescription)
}

override fun updateView(reward: Int, remainSeconds: Int) {
textTitle.text = "$reward 포인트 적립 가능합니다."
textDescription.text = "$remainSeconds 초 후에 닫힙니다."
}

override fun getDurationInSeconds(): Int {
return 5
}

override fun getMessage(): String {
return textTitle.text.toString()
}
}
  1. 아래의 코드를 적용하여 메시지 영역을 커스텀한 팝을 사용하세요.
import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig

val buzzPopConfig = BuzzPopConfig.Builder()
.buzzPopMessageViewClass(YourBuzzPopMessageView::class.java)
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()

팝 버튼 표시 시간 변경하기

팝 버튼이 뜬 후 사라지기 전까지 노출되는 시간을 수정할 수 있습니다. 초기 설정 값은 5초입니다.

import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig

val buzzPopConfig = BuzzPopConfig.Builder()
.idleTimeInMillis(5000L) // Pop 표시 시간
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()

팝 버튼 표시 위치 변경하기

유저가 기기의 화면을 잠금해제할 때마다 팝 버튼이 표시되는 위치를 설정할 수 있습니다. 초기 설정 값은 BuzzPopSidePosition.RIGHT, 0.6f(유저 기기 화면 우측에서 상단 기준으로 60% 높이)입니다. (BuzzPopSidePosition.LEFT / BuzzPopSidePosition.RIGHT)

import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig

val buzzPopConfig = BuzzPopConfig.Builder()
.initialSidePosition(BuzzPopSidePosition.RIGHT, 0.6f) // Pop 표시 위치
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()

팝 버튼 좌우 여백 설정하기

팝 버튼과 팝 버튼 왼쪽의 미리보기 뷰 사이 여백, 그리고 팝 버튼과 오른쪽 화면 가장자리 여백을 원하는 대로 설정할 수 있습니다. 초기 설정 값은 팝 버튼과 메세지 사이 여백 값은 8dp, 팝 버튼과 화면 끝 사이 여백 값은 0dp 입니다.

import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig

val buzzPopConfig = BuzzPopConfig.Builder()
.marginBetweenIconAndPreviewInDp(8.0f) // 팝 버튼과 메시지 사이 간격
.marginBetweenIconAndScreenEdgeInDp(24.0f) // 팝 버튼과 화면 끝 사이 간격
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()

추가 구현

팝 베네핏허브 첫 화면 변경하기

초기화 시 PopConfigBuzzBenefitHubConfig를 설정하여 팝 베네핏허브의 메인 페이지가 아닌 다른 페이지를 바로 열 수 있습니다.

BuzzBenefitHubConfig에 대한 자세한 내용은 베네핏허브 첫 화면 변경하기 토픽을 참고하세요.

import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.buzzbenefit.benefithub.BuzzBenefitHubConfig
import com.buzzvil.buzzbenefit.pop.BuzzPopConfig

// 팝에서 사용할 BuzzBenefitHubConfig 생성
val popBuzzBenefitHubConfig = BuzzBenefitHubConfig.Builder()
.routePath(BuzzBenefitHubRoutePath.MAIN)
.build()

val buzzPopConfig = BuzzPopConfig.Builder()
.buzzPopBenefitHubConfig(popBuzzBenefitHubConfig)
.build()

val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
.setBuzzPopConfig(buzzPopConfig) // BuzzBenefitConfig에 BuzzPopConfig를 설정합니다.
.build()