# 시작하기 Source: https://docs.buzzvil.com/docs/buzzbenefit-android/v6/getting-started Platform: Android SDK major version: v6 Language: Korean (ko) Buzzvil Android SDK(이하 Buzzvil SDK)에서 제공하는 기능을 사용하기 전 완료해야 하는 설정에 대해 알아보세요. ## 요구 사양 - Android 5.0 Lollipop (API 레벨 21) 이상 - compileSdkVersion 35 이상 - Android Studio Ladybug 이상 - Android Gradle Plugin 8.8 이상 - Gradle 8.10.2 이상 - Kotlin 1.9.25 이상 - JDK 1.8 > ✅  **중요** > > - 요구 사양은 Buzzvil SDK의 최신 상태를 기준으로 명시됩니다. > - 버즈빌은 안정적인 광고 플랫폼 및 개선된 수익화 기능의 탑재와 Android OS와의 호환성을 위해 최신 버전으로 업데이트하는 것을 권장합니다. > - 크로스 플랫폼 프레임워크(React Native, Flutter 등)를 통한 SDK 사용은 가능하지만, 기술 지원은 제공되지 않습니다. ## 연동용 ID 발급받기 Buzzvil SDK를 연동하려면 반드시 연동하려는 앱의 고유 식별자(App ID)와 광고 지면의 고유 식별자(Unit ID)가 필요합니다. ID를 발급받으려면 버즈빌 담당자()에게 연락하세요. ![](https://docs.buzzvil.com/api/content-image/buzzbenefit-android/v6/image/A-app_unit_id.png) | ID 유형 | 설명 | | ------- | ----------------------------------------- | | App ID | Buzzvil SDK를 연동하는 앱별로 부여하는 고유 식별자입니다. | | Unit ID | Buzzvil SDK를 통해 생성하는 지면별로 부여하는 고유 식별자입니다. | ## 포인트 적립 서버 연동하기 버즈빌이 공급하는 광고는 유저에게 포인트를 지급하는 보상형 광고와 지급하지 않는 비보상형 광고로 분류됩니다. - 비보상형 광고: 논리워드 광고라고도 합니다. 유저가 광고에 참여해도 별도의 포인트를 지급할 필요가 없으므로 포인트 처리 서버를 연동하지 않아도 됩니다. - 보상형 광고: 리워드 광고라고도 합니다. 유저가 광고에 참여하면 포인트를 지급해야 하므로 클라이언트의 포인트 적립 요청을 처리할 수 있는 서버가 필요합니다. 보상형 광고의 포인트 적립 요청을 처리할 수 있는 자체 서버를 보유한 경우, [포스트백 연동 가이드](https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/1756004654/API)를 참고해 포인트 처리 서버를 연동하세요. ![](https://docs.buzzvil.com/api/content-image/buzzbenefit-android/v6/image/D-postback.png) ## SDK 설치하기 > ⚠️  **SDK 6.8.0 이상 필수 저장소**\ > 6.8.0부터 애드캐시 미디에이션(AdFit·Cauly·Pangle 포함)이 `buzzvil-sdk`에 기본 포함됩니다([자세히](https://docs.buzzvil.com/docs/buzzbenefit-android/v6/banner#%EC%9E%90%EB%8F%99-%ED%8F%AC%ED%95%A8-adn-%EC%A0%9C%EC%99%B8)). 아래 저장소 3개를 추가하지 않으면 `Could not find com.kakao.adfit:ads-base`, `com.fsn.cauly:cauly-sdk`, `com.pangle.global:pag-sdk` 등의 의존성 해석 오류로 빌드가 실패합니다. 해당 네트워크를 사용하지 않는다면 저장소 추가 대신 [배너 - 자동 포함 ADN 제외](https://docs.buzzvil.com/docs/buzzbenefit-android/v6/banner#%EC%9E%90%EB%8F%99-%ED%8F%AC%ED%95%A8-adn-%EC%A0%9C%EC%99%B8)를 참고해 개별 제외하세요. 1. `settings.gradle`에 버즈빌 Maven 저장소를 추가하세요. ```kotlin // 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") // 버즈빌 저장소 maven("https://devrepo.kakao.com/nexus/content/groups/public/") // AdFit maven("https://cauly.github.io/cauly-sdk-android-maven/maven-repo") // Cauly maven("https://artifact.bytedance.com/repository/pangle") // Pangle } } ``` 2. 모듈 레벨의 `build.gradle` 파일에 Buzzvil SDK 라이브러리를 설정하세요. > ✏️  **참고**\ > 아래의 코드 스니펫은 최신 버전의 라이브러리를 기준으로 작성되었습니다. > ⚠️  **Android 16 대응이 필요한 경우**\ > Android 16(API 36) 대응이 필요하다면 `buzzvilBomVersion`을 **6.9.+** 로 설정하세요. 6.9.x는 Android 16 대응을 위한 별도 릴리스입니다. ``` // 모듈 레벨의 build.gradle dependencies {     val buzzvilBomVersion = "6.9.+"     api(platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion"))     implementation("com.buzzvil:buzzvil-sdk") } ``` 3. 모듈 레벨의 `build.gradle` 파일에 `compileSdk`과 `targetSdk`을 **35**로 업데이트하세요. ```kotlin // 모듈 레벨의 build.gradle android { compileSdk = 35 defaultConfig { minSdk = 21 targetSdk = 35 } } ``` > ✏️ **참고**\ > 오프라인 빌드를 진행하는 경우, 에 오프라인 빌드에 필요한 JAR/AAR 라이브러리를 요청하세요. > ❌  **오류**\ > SDK 설치 시 문제가 발생하는 경우, [문제 해결하기](https://docs.buzzvil.com/docs/buzzbenefit-android/v6/troubleshooting) 토픽을 참고하세요. ## SDK 초기화하기 Buzzvil SDK를 설치한 후 App ID, 유저 프로필 등 필요한 정보를 추가해 SDK를 초기화하세요. ### Buzzvil SDK 초기화하기 1. `BuzzvilSdk.initialize()`를 호출해 SDK를 초기화하세요. > ❌  **오류**\ > `BuzzvilSdk.initialize()` 호출 전에 다른 함수들이 실행될 경우, SDK가 정상적으로 동작하지 않을 수 있습니다. **반드시 초기화 함수를 가장 먼저 호출해 주세요.**\ > `Application`의 `onCreate()`에서 초기화하는 것을 권장합니다. > ❗️ **주의** > > - **팝(Pop)을 사용하는 경우** 반드시 `Application`의 `onCreate()`에서 `BuzzvilSdk.initialize()`를 호출해야 합니다. > - Android 15(API 35) 이상에서는 백그라운드 상태에서의 네트워크 요청이 제한됩니다. `Application` 클래스에서 `BuzzvilSdk.initialize`를 제외한 버즈빌의 다른 함수를 호출할 경우 오류가 발생할 수 있습니다. | 필수/권장 | 매개변수 이름 | 설명 | | ----- | ------------------- | ------------------------------------ | | 필수 | `application` | SDK 실행에 필요한 Application Context 입니다. | | 필수 | `buzzBenefitConfig` | Buzzvil SDK에서 사용되는 기본 베네핏허브 설정 값입니다. | ```kotlin 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 클래스를 설정하세요. ```xml ... ``` ### 로그인 요청하기 광고 할당을 요청하려면 로그인을 요청해야 합니다. 로그인 요청을 구성하는 항목에 대해서는 아래 표를 참고하세요. ❗️❗️❗️  **중요**  ❗️❗️❗️ \ **성별**과 **출생연도** 정보는 권장으로 표기되어 있으나 등록하지 않으면 타겟팅 광고 송출이 불가능합니다. 버즈빌의 광고는 타겟팅 광고가 대부분이기에 **_해당 정보를 등록해야 정상적인 광고 할당이 가능_**합니다. | 필수/권장 | 유저 프로필 | 설명 | | ----- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 필수 | `userId` | 유저별로 고유하게 생성하는 ID로, 개인정보 식별은 불가능한 값입니다 (로그인 ID, 이메일 사용 불가). 서비스 도중 변하지 않는 고정 값이며, 광고 할당을 위한 필수 정보입니다. ASCII 형식의 255자 이하로 제한됩니다. ⚠️  **주의** 앱을 삭제 후 재설치하여 유저의 ID 값이 변경되거나 다른 사유로 인해 고정 ID를 사용하지 못하는 경우, **_어뷰징 발생 가능성으로 인해 액션형 광고 송출이 불가능_**합니다. 유저 고유 식별자가 변동되는 경우 버즈빌 사업 담당자에게 문의하세요. | | 권장 | `gender` | 유저의 성별입니다. * 남성: `BuzzvilSdk.Gender.MALE` * 여성: `BuzzvilSdk.Gender.FEMALE` | | 권장 | `birthYear` | 유저의 출생연도입니다. | 다음은 SDK에 유저 프로필을 등록하는 예시입니다. 등록한 유저 프로필은 삭제할 수도 있습니다. ```kotlin 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 샘플 코드](https://github.com/Buzzvil/buzz-sdk-samples/tree/master/buzzvil-sdk-v6-android)를 통해 실제 구현에 사용된 예제를 참고할 수 있습니다. ## 자주 하는 질문 | 질문 | 답변 | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Android 14 대응을 위해 어떤 변경 사항이 있었는지 궁금합니다. | Buzzvil SDK 5.13.x 에 반영된 Android 14 대응 관련 변경 사항은 [릴리스 뉴스](https://docs.buzzvil.com/docs/release-news/android/buzzvil5.13)에서 확인하실 수 있습니다. |