시작하기

Buzzvil Android SDK(이하 Buzzvil SDK)에서 제공하는 기능을 사용하기 전 완료해야 하는 설정에 대해 알아보세요.

요구 사양

• Android 5.0 Lollipop (API 레벨 21) 이상
• Android Studio Jeyllyfish 이상
• Gradle 4.2 이상
• compileSdkVersion 34 이상
• AndroidX
• JDK 1.8

✅  중요

• 요구 사양은 Buzzvil SDK의 최신 상태를 기준으로 명시됩니다.
• 버즈빌은 안정적인 광고 플랫폼 및 개선된 수익화 기능의 탑재와 Android OS와의 호환성을 위해 최신 버전으로 업데이트하는 것을 권장합니다.
• 크로스 플랫폼 프레임워크(React Native, Flutter 등)를 통한 SDK 사용은 가능하지만, 기술 지원은 제공되지 않습니다.

연동용 ID 발급받기

Buzzvil SDK를 연동하려면 반드시 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. ID를 발급받으려면 버즈빌 담당자(help@buzzvil.com)에게 연락하세요.

ID 유형	설명
App ID	Buzzvil SDK를 연동하는 앱별로 부여하는 고유 식별자입니다.
Unit ID	Buzzvil SDK를 통해 생성하는 지면별로 부여하는 고유 식별자입니다.

포인트 적립 서버 연동하기

버즈빌이 공급하는 광고는 유저에게 포인트를 지급하는 보상형 광고와 지급하지 않는 비보상형 광고로 분류됩니다.

• 비보상형 광고: 논리워드 광고라고도 합니다. 유저가 광고에 참여해도 별도의 포인트를 지급할 필요가 없으므로 포인트 처리 서버를 연동하지 않아도 됩니다.
• 보상형 광고: 리워드 광고라고도 합니다. 유저가 광고에 참여하면 포인트를 지급해야 하므로 클라이언트의 포인트 적립 요청을 처리할 수 있는 서버가 필요합니다.

보상형 광고의 포인트 적립 요청을 처리할 수 있는 자체 서버를 보유한 경우, 포스트백 연동 가이드를 참고해 포인트 처리 서버를 연동하세요.

SDK 설치하기

1. settings.gradle에 버즈빌 Maven 저장소를 추가하세요.

// settings.gradle

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://dl.buzzvil.com/public/maven") // 버즈빌 저장소
    }
}

2. 모듈 레벨의 build.gradle 파일에 Buzzvil SDK 라이브러리를 설정하세요.

✏️  참고
아래의 코드 스니펫은 최신 버전의 라이브러리를 기준으로 작성되었습니다.

// 모듈 레벨의 build.gradle

dependencies { 
    val buzzvilBomVersion = 6.0.+

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

3. 모듈 레벨의 build.gradle 파일에 compileSdk과 targetSdk을 34로 업데이트하세요.

// 모듈 레벨의 build.gradle 

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        targetSdk = 34
    }
}

✏️ 참고
오프라인 빌드를 진행하는 경우, help@buzzvil.com에 오프라인 빌드에 필요한 JAR/AAR 라이브러리를 요청하세요.

❌  오류
SDK 설치 시 문제가 발생하는 경우, 문제 해결하기 토픽을 참고하세요.

SDK 초기화하기

Buzzvil SDK를 설치한 후 App ID, 유저 프로필 등 필요한 정보를 추가해 SDK를 초기화하세요.

Buzzvil SDK 초기화하기

1. BuzzvilSdk.initialize()를 호출해 SDK를 초기화하세요.

❌  오류
BuzzvilSdk.initialize() 호출 전에 다른 함수들이 실행될 경우, SDK가 정상적으로 동작하지 않을 수 있습니다. 반드시 초기화 함수를 가장 먼저 호출해 주세요.
Application의 onCreate()에서 초기화하는 것을 권장합니다.

❗️ 주의
팝(Pop)을 사용하는 경우 반드시 Application의 onCreate()에서 BuzzvilSdk.initialize()를 호출해야 합니다.

필수/권장	매개변수 이름	설명
필수	application	SDK 실행에 필요한 Application Context 입니다.
필수	buzzBenefitConfig	Buzzvil SDK에서 사용되는 기본 베네핏허브 설정 값입니다.

import android.app.Application
import com.buzzvil.buzzbenefit.BuzzBenefitConfig
import com.buzzvil.sdk.BuzzvilSdk

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

        // BuzzBenefit 설정
        val buzzBenefitConfig = BuzzBenefitConfig.Builder("YOUR_APP_ID")
            .build()

        // Buzzvil SDK 초기화
        BuzzvilSdk.initialize(
            application = this@App,
            buzzBenefitConfig = buzzBenefitConfig
        )
    }
}

2. AndroidManifest.xml 에 Application 클래스를 설정하세요.

<manifest>
    <application
        android:name=".YourApp">
    
        ...
                  
    </application>
</manifest>

로그인 요청하기

광고 할당을 요청하려면 로그인을 요청해야 합니다. 로그인 요청을 구성하는 항목에 대해서는 아래 표를 참고하세요.

❗️❗️❗️  중요  ❗️❗️❗️ 
성별과 출생연도 정보는 권장으로 표기되어 있으나 등록하지 않으면 타겟팅 광고 송출이 불가능합니다. 버즈빌의 광고는 타겟팅 광고가 대부분이기에 해당 정보를 등록해야 정상적인 광고 할당이 가능합니다.

필수/권장	유저 프로필	설명
필수	userId	유저별로 고유하게 생성하는 ID로, 개인정보 식별은 불가능한 값입니다 (로그인 ID, 이메일 사용 불가). 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다. ASCII 형식의 255자 이하로 제한됩니다. ⚠️  주의 앱을 삭제 후 재설치하여 유저의 ID 값이 변경되거나 다른 사유로 인해 고정 ID를 사용하지 못하는 경우, 어뷰징 발생 가능성으로 인해 액션형 광고 송출이 불가능합니다. 유저 고유 식별자가 변동되는 경우 버즈빌 사업 담당자에게 문의하세요.
권장	gender	유저의 성별입니다. 남성: BuzzvilSdk.Gender.MALE 여성: BuzzvilSdk.Gender.FEMALE
권장	birthYear	유저의 출생연도입니다.

다음은 SDK에 유저 프로필을 등록하는 예시입니다. 등록한 유저 프로필은 삭제할 수도 있습니다.

import com.buzzvil.sdk.BuzzvilSdk
import com.buzzvil.sdk.BuzzvilSdkLoginListener
import com.buzzvil.sdk.BuzzvilSdkUser

// 유저 정보를 구성합니다.
val buzzvilSdkUser = BuzzvilSdkUser(
    userId = "YOUR_USER_ID",
    gender = BuzzvilSdkUser.Gender.MALE,
    birthYear = 1980,
)

// 유저 정보로 로그인을 요청합니다.
BuzzvilSdk.login(
    buzzvilSdkUser = buzzvilSdkUser,
    // (선택) 로그인 상태를 확인할 수 있는 리스너를 등록합니다.
    listener = object : BuzzvilSdkLoginListener {
        override fun onSuccess() {
            // 로그인에 성공한 경우 호출됩니다.
            // `BuzzvilSdk.isLoggedIn`이 true 상태가 됩니다.
            // onSuccess가 호출된 이후부터 광고 할당이 가능합니다.
        }

        override fun onFailure(errorType: BuzzvilSdkLoginListener.ErrorType) {
            // 로그인에 실패한 경우 호출됩니다.
            // NOT_INITIALIZED: SDK 초기화를 하지 않고 로그인을 시도한 경우
            // INVALID_USER_ID: 적절하지 않은 값을 입력한 경우 (e.g. userId가 빈 문자열인 경우)
            // UNKNOWN: 그 외 알 수 없는 오류
        }
    }
)

// 로그인 상태를 확인합니다.
val isLoggedIn: Boolean = BuzzvilSdk.isLoggedIn

// 로그아웃을 호출하면 로컬에 저장된 모든 유저 정보가 삭제됩니다.
BuzzvilSdk.logout()

샘플 코드

GitHub 샘플 코드를 통해 실제 구현에 사용된 예제를 참고할 수 있습니다.

자주 하는 질문

질문	답변
Android 14 대응을 위해 어떤 변경 사항이 있었는지 궁금합니다.	Buzzvil SDK 5.13.x 에 반영된 Android 14 대응 관련 변경 사항은 릴리스 뉴스에서 확인하실 수 있습니다.