Skip to content
:docs

Getting started

Complete the setup below before using the Buzzvil Android SDK (referred to below as the Buzzvil SDK).

Requirements

  • Android 5.0 Lollipop (API level 21) or later
  • compileSdkVersion 35 or later
  • Android Studio Ladybug or later
  • Android Gradle Plugin 8.8 or later
  • Gradle 8.10.2 or later
  • Kotlin 1.9.25 or later
  • JDK 1.8

Obtain integration IDs

You need an App ID for your app and a Unit ID for each placement to integrate Buzzvil SDK. Contact your Buzzvil representative to obtain them.

ID typeDescription
App IDA unique identifier assigned to each app that integrates the Buzzvil SDK.
Unit IDA unique identifier assigned to each placement created through the Buzzvil SDK.

Integrate a reward server

Ads supplied by Buzzvil are classified as rewarded ads, which award points to users, and non-rewarded ads, which do not.

  • Non-rewarded ads: You do not need to award points when users engage with these ads, so a point-processing server is not required.
  • Rewarded ads: You must award points when users engage with these ads, so you need a server that can process reward requests from the client.

If you have your own server that can process reward requests for rewarded ads, integrate it by following the postback integration guide.

Install the SDK

  1. Add the Buzzvil Maven repository to settings.gradle.
settings.gradle · Kotlin
// 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" } // 버즈빌 저장소
    }
}
  1. Configure the Buzzvil SDK library in your module-level build.gradle file.
build.gradle · Code
// 모듈 레벨의 build.gradle

dependencies {
    def buzzvilBomVersion = 5.36.+

    api platform("com.buzzvil:buzzvil-bom:$buzzvilBomVersion")
    implementation "com.buzzvil:buzzvil-sdk"
}
  1. Update compileSdkVersion and targetSdkVersion to 35 in the module-level build.gradle file.
build.gradle · Kotlin
// 모듈 레벨의 build.gradle 

android {
    compileSdkVersion 35

    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 35
    }
}

Initialize the SDK

After installing the Buzzvil SDK, initialize it with the required information, including your App ID and user profile.

Initialize the Buzzvil SDK

  1. Call BuzzvilSdk.initialize() in onCreate() of Application to initialize the SDK.
Required/recommendedParameterDescription
RequiredapplicationThe Application Context required to run the SDK.
RequiredbuzzAdBenefitConfigThe default BenefitHub configuration used by the Buzzvil SDK.
Kotlin
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
        )
    }
}
  1. Set your Application class in AndroidManifest.xml.
XML
<manifest>
    <application
        android:name=".App">
    
        ...
                  
    </application>
</manifest>

Register a user profile

Register a user profile before requesting ads. The profile fields are listed below.

❗️❗️  Caution ❗️❗️  
Although gender (gender) and birth year (birthYear) are marked as recommended, targeted ads cannot be served without them. Most Buzzvil ads are targeted, so provide these fields to receive ads reliably.

Required/recommendedUser profileDescription
RequireduserIdA unique, non-identifying user ID. Do not use a login ID or email address. It must remain stable throughout service use and is required for ad allocation.
Limited to 255 ASCII characters.
❗️❗️ Caution ❗️❗️
If the ID changes after reinstalling the app or cannot remain stable for another reason, action-based ads cannot be served because of the risk of abuse. Contact your Buzzvil business representative if user identifiers can change.
RecommendedgenderThe user's gender.
  • Male: BuzzvilSdk.Gender.MALE
  • Female: BuzzvilSdk.Gender.FEMALE
RecommendedbirthYearThe user's year of birth.
OptionallistenerRegisters a listener to check login status.

The following example registers a user profile with the SDK. You can also delete a registered user profile.

Kotlin
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) {
            // 유저 정보를 정상적으로 등록하지 못한 경우 호출됩니다.
        }
    }
)
Kotlin
// 유저 정보를 삭제합니다.
BuzzvilSdk.setUserProfile(null)

Collect app crash information

Buzzvil uses Sentry to collect SDK crash reports and improve SDK and app reliability. Reports include stack traces containing the com.buzzvil package path, SDK version, app information and device information excluding unique identifiers. Reporting is enabled automatically if your app does not use Sentry or uses it without automatic initialization.

If your app already uses Sentry with automatic initialization through ContentProvider, add tools:node="replace" to AndroidManifest.xml.

XML
<manifest>
    <application>
    
        <meta-data
           android:name="io.sentry.dsn"
           android:value="YOUR DSN" //매체사 DSN
           tools:node="replace" /> 
                  
    </application>
</manifest>

Sample code

See the GitHub sample code for implementation examples.

Frequently asked questions

QuestionAnswer
What changed to support Android 14?See the release notes for the Android 14 compatibility changes in Buzzvil SDK 5.13.x.
Only the Buzzvil SDK UI uses dark mode, which looks inconsistent.You can disable the app's dark theme. See Disable dark theme in your app.
I want to change all Buzzvil SDK UI at once.Configure a theme to change colors and icons across the SDK. See Global theme.
Why must I add a user support button for action-based ads?If you allocate action-based ads, you must implement user support to operate the service reliably. See Add user support for action-based ads.
I want ads to open in a WebView.Use a custom launcher to open landing pages in an in-app browser. See Use a custom in-app browser.
I want to change video ad playback options.See Change video ad playback conditions.
I want to identify ad types in BenefitHub or Native.See Check the ad type.