시작하기
Buzzvil Android SDK(이하 Buzzvil SDK)에서 제공하는 기능을 사용하기 전 완료해야 하는 설정에 대해 알아보세요.
요구 사양
✅ 중요
- 요구 사양은 Buzzvil SDK의 최신 상태를 기준으로 명시됩니다.
- 버즈빌은 안정적인 광고 플랫폼 및 개선된 수익화 기능의 탑재와 Android OS와의 호환성을 위해 최신 버전으로 업데이트하는 것을 권장합니다.
- 크로스 플랫폼 프레임워크(React Native, Flutter 등)를 통한 SDK 사용은 가능하지만, 기술 지원은 제공되지 않습니다.
- Android 5.0 Lollipop (API 레벨 21) 이상
- Android Studio Jeyllyfish 이상
- Gradle 4.2 이상
- compileSdkVersion 34 이상
- AndroidX
- JDK 1.8
연동용 ID 발급받기
Buzzvil SDK를 연동하려면 반드시 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. ID를 발급받으려면 버즈빌 담당자에게 연락하세요.
ID 유형 | 설명 |
---|---|
App ID | Buzzvil SDK를 연동하는 앱별로 부여하는 고유 식별자입니다. |
Unit ID | Buzzvil SDK를 통해 생성하는 지면별로 부여하는 고유 식별자입니다. |
포인트 적립 서버 연동하기
버즈빌이 공급하는 광고는 유저에게 포인트를 지급하는 보상형 광고와 지급하지 않는 비보상형 광고로 분류됩니다.
- 비보상형 광고: 논리워드 광고라고도 합니다. 유저가 광고에 참여해도 별도의 포인트를 지급할 필요가 없으므로 포인트 처리 서버를 연동하지 않아도 됩니다.
- 보상형 광고: 리워드 광고라고도 합니다. 유저가 광고에 참여하면 포인트를 지급해야 하므로 클라이언트의 포인트 적립 요청을 처리할 수 있는 서버가 필요합니다.
보상형 광고의 포인트 적립 요청을 처리할 수 있는 자체 서버를 보유한 경우, 포스트백 연동 가이드를 참고해 포인트 처리 서버를 연동하세요.
SDK 설치하기
settings.gradle
에 버즈빌 Maven 저장소를 추가하세요.
// settings.gradle
pluginManagement {
repositories {
gradlePluginPortal()
google()
mavenCentral()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url "https://dl.buzzvil.com/public/maven" } // 버즈빌 저장소
}
}
- 모듈 레벨의
build.gradle
파일에 Buzzvil SDK 라이브러리를 설정하세요.
✏️ 참고
아래의 코드 스니펫은 최신 버전의 라이브러리를 기준으로 작성되었습니다.
// 모듈 레벨의 build.gradle
dependencies {
def buzzvilBomVersion = 5.29.+
api platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion")
implementation "com.buzzvil:buzzvil-sdk"
}
- 모듈 레벨의
build.gradle
파일에compileSdkVersion
과targetSdkVersion
을 34으로 업데이트하세요.
// 모듈 레벨의 build.gradle
android {
compileSdkVersion 34
defaultConfig {
minSdkVersion 21
targetSdkVersion 34
}
}
✏️ 참고
오프라인 빌드를 진행하는 경우, help@buzzvil.com에 오프라인 빌드에 필요한 JAR/AAR 라이브러리를 요청하세요.
❌ 오류
SDK 설치 시 문제가 발생하는 경우, 문제 해결하기 토픽을 참고하세요.
SDK 초기화하기
Buzzvil SDK를 설치한 후 App ID, 유저 프로필 등 필요한 정보를 추가해 SDK를 초기화하세요.
Buzzvil SDK 초기화하기
Application
의onCreate()
에서BuzzvilSdk.initialize()
를 호출해 SDK를 초기화하세요.
필수/권장 | 매개변수 이름 | 설명 |
---|---|---|
필수 | application | SDK 실행에 필요한 Application Context 입니다. |
필수 | buzzAdBenefitConfig | Buzzvil SDK에서 사용되는 기본 베네핏허브 설정 값입니다. |
✏️ 참고
BuzzAdBenefitConfig
를 사용해 베네핏허브 지면의 기능과 디자인을 변경할 수 있습니다. 자세한 내용은 추가 구현과 커스터마이징 토픽을 참고하세요.
import android.app.Application
import com.buzzvil.buzzad.benefit.BuzzAdBenefitConfig
import com.buzzvil.sdk.BuzzvilSdk
class App : Application() {
override fun onCreate() {
super.onCreate()
// Feed(베네핏허브) 설정
val feedConfig = FeedConfig.Builder("YOUR_FEED_UNIT_ID")
.build()
// BuzzBenefit 설정
val buzzAdBenefitConfig = BuzzAdBenefitConfig.Builder("YOUR_APP_ID")
.setDefaultFeedConfig(feedConfig)
.build()
// Buzzvil SDK 초기화
BuzzvilSdk.initialize(
application = this@App,
buzzAdBenefitConfig = buzzAdBenefitConfig
)
}
}
AndroidManifest.xml
에 Application 클래스를 설정하세요.
<manifest>
<application
android:name=".App">
...
</application>
</manifest>
유저 프로필 등록하기
광고 할당을 요청하려면 유저 프로필을 등록해야 합니다. 유저 프로필을 구성하는 항목에 대해서는 아래 표를 참고하세요.
❗️❗️ 주의 ❗️❗️
성별(gender
)과 출생연도(birthYear
) 정보는 권장으로 표기되어 있으나 등록하지 않으면 타겟팅 광고 송출이 불가능합니다. 버즈빌의 광고는 타겟팅 광고가 대부분이기에 해당 정보를 등록해야 정상적인 광고 할당이 가능합니다.
필수/권장 | 유저 프로필 | 설명 |
---|---|---|
필수 | userId | 유저별로 고유하게 생성하는 ID로, 개인정보 식별은 불가능한 값입니다 (로그인 ID, 이메일 사용 불가). 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다. ASCII 형식의 65자 이하로 제한됩니다. ❗️❗️ 주의 ❗️❗️ 앱을 삭제 후 재설치하여 유저의 ID 값이 변경되거나 다른 사유로 인해 고정 ID를 사용하지 못하는 경우, 어뷰징 발생 가능성으로 인해 액션형 광고 송출이 불가능합니다. 유저 고유 식별자가 변동되는 경우 버즈빌 사업 담당자에게 문의하세요. |
권장 | gender | 유저의 성별입니다.
|
권장 | birthYear | 유저의 출생연도입니다. |
선택 | listener | 로그인 상태를 확인할 수 있는 리스너를 등록합니다. |
다음은 SDK에 유저 프로필을 등록하는 예시입니다. 등록한 유저 프로필은 삭제할 수도 있습니다.
import com.buzzvil.buzzad.benefit.core.models.UserProfile
import com.buzzvil.sdk.BuzzvilSdk
import com.buzzvil.sdk.BuzzvilSetUserProfileListener
// 유저 정보를 등록합니다.
BuzzvilSdk.setUserProfile(
userId = "SAMPLE_USER_ID",
gender = UserProfile.Gender.MALE,
birthYear = 1980,
// (선택) 로그인 상태를 확인할 수 있는 리스너를 등록합니다.
listener = object : BuzzvilSetUserProfileListener {
override fun loggedIn() {
// 유저 정보가 정상적으로 등록된 경우 호출됩니다.
}
override fun loggedOut() {
// 유저 정보를 삭제하는 경우 호출됩니다.
}
override fun onSessionReady() {
// loggedIn() 이후에 버즈빌 서버에서 auth token을 정상적으로 받아오면 호출됩니다.
// onSessionReady가 호출된 이후부터 광고 할당이 가능합니다.
}
override fun onFailure(errorType: BuzzvilSetUserProfileListener.ErrorType) {
// 유저 정보를 정상적으로 등록하지 못한 경우 호출됩니다.
}
}
)
// 유저 정보를 삭제합니다.
BuzzvilSdk.setUserProfile(null)
❌ 오류
유저 정보 수집 코드를 정상적으로 추가한 후에 광고 할당에 문제가 발생하는 경우, 광고가 정상적으로 할당되지 않습니다 토픽을 참고하세요.
앱 충돌 정보 수집 기능 사용하기
버즈빌은 Buzzvil SDK와 앱의 안정성을 강화하기 위해 Sentry로 SDK에서 발생하는 앱 충돌 정보를 수집합니다. 수집 정보에는 com.buzzvil
패키지 경로가 포함된 함수 호출 스택, SDK 버전, 앱 정보, 고유 식별자를 제외한 기기 정보 등이 포함됩니다. 앱에 이미 Sentry를 연동한 상태에서 자동 초기화 기능을 사용하고 있지 않거나 Sentry를 아예 연동하지 않은 경우에는 별도의 조치를 취하지 않아도 자동으로 앱 충돌 정보 수집 기능이 적용됩니다.
앱에 이미 Sentry를 연동한 상태에서 ContentProvider
를 통해 자동 초기화 기능을 사용하고 있는 경우, AndroidManifest.xml
파일에 tools:node="replace"
를 추가하세요.
<manifest>
<application>
<meta-data
android:name="io.sentry.dsn"
android:value="YOUR DSN" //매체사 DSN
tools:node="replace" />
</application>
</manifest>
샘플 코드
Github 샘플 코드를 통해 실제 구현에 사용된 예제를 참고할 수 있습니다.
자주 하는 질문
질문 | 답변 |
---|---|
Android 14 대응을 위해 어떤 변경 사항이 있었는지 궁금합니다. | Buzzvil SDK 5.13.x 에 반영된 Android 14 대응 관련 변경 사항은 릴리스 뉴스에서 확인하실 수 있습니다. |
Buzzvil SDK의 UI에만 다크 테마가 적용되어 어색합니다. | 앱의 다크테마를 비활성화할 수 있습니다. 자세한 내용은 앱에서 다크 테마 비활성화하기 토픽을 참고하세요. |
Buzzvil SDK의 UI를 한꺼번에 변경하고 싶습니다. | 테마를 설정하여 SDK의 전반적인 색상과 아이콘을 변경할 수 있습니다. 자세한 내용은 전체 테마 토픽을 참고하세요. |
액션형 광고에 유저 문의 버튼을 추가해야하는 이유가 궁금합니다. | 액션형 광고를 할당할 경우, 안정적인 서비스 운영을 위해 유저의 문의 기능이 반드시 구현되어야 합니다. 자세한 내용은 액션형 광고의 유저 문의 기능 추가하기 토픽을 참고하세요. |
광고를 웹뷰(WebView)로 연결하고 싶습니다. | 커스텀 런처를 사용해 광고 랜딩 페이지를 인앱 브라우저로 열 수 있습니다. 자세한 내용은 커스텀 인앱 브라우저 사용하기 토픽을 참고하세요. |
동영상 광고 재생 옵션을 변경하고 싶습니다. | 동영상 광고 재생 조건 변경하기 토픽을 참고하세요. |
베네핏허브 또는 네이티브 지면의 광고 타입을 확인하고 싶습니다. | 광고 타입 확인하기를 참고하세요. |