개요
배너 광고는 화면의 일부 영역에 표시되는 직사각형 광고입니다. XML 레이아웃과 코드 모두에서 사용할 수 있습니다.주요 특징
- 화면 상단, 하단 또는 중간에 고정 배치 가능
- 이미지 및 동영상 광고 지원
- XML 레이아웃 및 프로그래밍 방식 모두 지원
- 리스너를 통한 광고 이벤트 처리
개발 환경에서는 테스트 유닛 ID를 사용하세요:
PUBLIC_TEST_UNIT_ID_320_100XML 레이아웃 구현
XML 레이아웃에서AdropBanner를 정의하고 Activity나 Fragment에서 로드하는 방식입니다.
1. XML 레이아웃 정의
FrameLayout 또는 다른 컨테이너에 AdropBanner를 배치합니다.
activity_main.xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<!-- 메인 콘텐츠 -->
<TextView
android:id="@+id/content"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="메인 콘텐츠"
app:layout_constraintTop_toTopOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintEnd_toEndOf="parent" />
<!-- 배너 광고 컨테이너 -->
<FrameLayout
android:id="@+id/banner_container"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintEnd_toEndOf="parent">
<io.adrop.ads.banner.AdropBanner
android:id="@+id/adrop_banner"
android:layout_width="320dp"
android:layout_height="100dp"
android:layout_gravity="center"
app:adrop_unit_id="YOUR_UNIT_ID" />
</FrameLayout>
</androidx.constraintlayout.widget.ConstraintLayout>
2. Activity에서 로드
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode
class MainActivity : AppCompatActivity() {
private var banner: AdropBanner? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// 1. XML에서 정의한 배너 뷰 찾기
banner = findViewById(R.id.adrop_banner)
// 2. 리스너 설정
banner?.listener = object : AdropBannerListener {
override fun onAdReceived(banner: AdropBanner) {
println("배너 광고 수신 성공")
}
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
println("배너 광고 수신 실패: $errorCode")
}
override fun onAdImpression(banner: AdropBanner) {
println("배너 광고 노출")
}
override fun onAdClicked(banner: AdropBanner) {
println("배너 광고 클릭")
}
}
// 3. 광고 로드
banner?.load()
}
override fun onDestroy() {
super.onDestroy()
// 4. 메모리 해제
banner?.destroy()
banner = null
}
}
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;
public class MainActivity extends AppCompatActivity {
private AdropBanner banner;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 1. XML에서 정의한 배너 뷰 찾기
banner = findViewById(R.id.adrop_banner);
// 2. 리스너 설정
banner.setListener(new AdropBannerListener() {
@Override
public void onAdReceived(@NotNull AdropBanner banner) {
System.out.println("배너 광고 수신 성공");
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
System.out.println("배너 광고 수신 실패: " + errorCode);
}
@Override
public void onAdImpression(@NotNull AdropBanner banner) {
System.out.println("배너 광고 노출");
}
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
System.out.println("배너 광고 클릭");
}
});
// 3. 광고 로드
banner.load();
}
@Override
protected void onDestroy() {
super.onDestroy();
// 4. 메모리 해제
if (banner != null) {
banner.destroy();
banner = null;
}
}
}
XML 속성
| 속성 | 설명 | 필수 |
|---|---|---|
app:adrop_unit_id | 광고 유닛 ID | O |
app:adrop_context_id | 문맥 타겟팅을 위한 Context ID | |
android:layout_width | 배너 너비 (dp) | O |
android:layout_height | 배너 높이 (dp) | O |
프로그래밍 방식 구현
코드에서 직접AdropBanner 인스턴스를 생성하여 뷰에 추가하는 방식입니다.
import android.os.Bundle
import android.widget.FrameLayout
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode
class MainActivity : AppCompatActivity() {
private var banner: AdropBanner? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// 1. 배너 인스턴스 생성
banner = AdropBanner(this, "YOUR_UNIT_ID").apply {
// 2. 리스너 설정
listener = object : AdropBannerListener {
override fun onAdReceived(banner: AdropBanner) {
println("배너 광고 수신 성공")
}
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
println("배너 광고 수신 실패: $errorCode")
}
override fun onAdImpression(banner: AdropBanner) {
println("배너 광고 노출")
}
override fun onAdClicked(banner: AdropBanner) {
println("배너 광고 클릭")
}
}
}
// 3. 뷰 계층에 추가
val container = findViewById<FrameLayout>(R.id.banner_container)
val params = FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MATCH_PARENT,
FrameLayout.LayoutParams.WRAP_CONTENT
)
container.addView(banner, params)
// 4. 광고 로드
banner?.load()
}
override fun onDestroy() {
super.onDestroy()
// 5. 메모리 해제
banner?.destroy()
banner = null
}
}
import android.os.Bundle;
import android.widget.FrameLayout;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;
public class MainActivity extends AppCompatActivity {
private AdropBanner banner;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 1. 배너 인스턴스 생성 (unitId는 생성자에서 필수)
banner = new AdropBanner(this, "YOUR_UNIT_ID");
// 2. 리스너 설정
banner.setListener(new AdropBannerListener() {
@Override
public void onAdReceived(@NotNull AdropBanner banner) {
System.out.println("배너 광고 수신 성공");
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
System.out.println("배너 광고 수신 실패: " + errorCode);
}
@Override
public void onAdImpression(@NotNull AdropBanner banner) {
System.out.println("배너 광고 노출");
}
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
System.out.println("배너 광고 클릭");
}
});
// 3. 뷰 계층에 추가
FrameLayout container = findViewById(R.id.banner_container);
FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MATCH_PARENT,
FrameLayout.LayoutParams.WRAP_CONTENT
);
container.addView(banner, params);
// 4. 광고 로드
banner.load();
}
@Override
protected void onDestroy() {
super.onDestroy();
// 5. 메모리 해제
if (banner != null) {
banner.destroy();
banner = null;
}
}
}
AdropBanner 초기화
생성자
val banner = AdropBanner(context, "YOUR_UNIT_ID")
AdropBanner banner = new AdropBanner(context, "YOUR_UNIT_ID");
유닛 ID 설정
banner.setUnitId("YOUR_UNIT_ID")
banner.setUnitId("YOUR_UNIT_ID");
광고 로드
배너를 화면에 추가한 후load() 메서드를 호출하여 광고를 요청합니다.
banner.load()
banner.load();
배너가 화면에 보이는 시점에
load()를 호출하세요. 화면에 보이지 않는 상태에서 로드하면 노출이 정확하게 측정되지 않을 수 있습니다.리스너 구현
AdropBannerListener 인터페이스는 광고의 생명주기 이벤트를 처리합니다.
onAdReceived (필수)
광고 수신이 성공했을 때 호출됩니다.override fun onAdReceived(banner: AdropBanner) {
println("배너 광고 수신 성공")
// 광고 로딩 인디케이터 숨김 등의 처리
}
@Override
public void onAdReceived(@NotNull AdropBanner banner) {
System.out.println("배너 광고 수신 성공");
// 광고 로딩 인디케이터 숨김 등의 처리
}
onAdFailedToReceive (필수)
광고 수신이 실패했을 때 호출됩니다.override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
println("배너 광고 수신 실패: $errorCode")
// 에러 처리 및 대체 콘텐츠 표시
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
System.out.println("배너 광고 수신 실패: " + errorCode);
// 에러 처리 및 대체 콘텐츠 표시
}
에러 유형을 나타내는 코드. 자세한 내용은 레퍼런스를 참고하세요.
onAdImpression (선택)
광고가 화면에 노출되었을 때 호출됩니다.override fun onAdImpression(banner: AdropBanner) {
println("배너 광고 노출")
// 노출 분석 로깅 등의 처리
}
@Override
public void onAdImpression(@NotNull AdropBanner banner) {
System.out.println("배너 광고 노출");
// 노출 분석 로깅 등의 처리
}
onAdClicked (필수)
사용자가 광고를 클릭했을 때 호출됩니다.override fun onAdClicked(banner: AdropBanner) {
println("배너 광고 클릭")
// 클릭 분석 로깅 등의 처리
}
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
System.out.println("배너 광고 클릭");
// 클릭 분석 로깅 등의 처리
}
onAdVideoStart (선택)
동영상 배너 광고에서 동영상 재생이 시작되었을 때 호출됩니다.override fun onAdVideoStart(banner: AdropBanner) {
println("배너 동영상 재생 시작")
}
@Override
public void onAdVideoStart(@NotNull AdropBanner banner) {
System.out.println("배너 동영상 재생 시작");
}
onAdVideoEnd (선택)
동영상 배너 광고에서 동영상 재생이 종료되었을 때 호출됩니다.override fun onAdVideoEnd(banner: AdropBanner) {
println("배너 동영상 재생 종료")
}
@Override
public void onAdVideoEnd(@NotNull AdropBanner banner) {
System.out.println("배너 동영상 재생 종료");
}
Context ID 설정
문맥 타겟팅을 위해 Context ID를 설정할 수 있습니다.// contextId는 읽기 전용 — 생성자에서 설정
val banner = AdropBanner(this, "YOUR_UNIT_ID", "article_sports")
// contextId는 읽기 전용 — 생성자에서 설정
AdropBanner banner = new AdropBanner(this, "YOUR_UNIT_ID", "article_sports");
Context ID는 광고를 로드하기 전에 설정해야 합니다.
생명주기 관리
destroy()
배너를 더 이상 사용하지 않을 때는 반드시destroy()를 호출하여 리소스를 해제해야 합니다.
override fun onDestroy() {
super.onDestroy()
banner?.destroy()
banner = null
}
@Override
protected void onDestroy() {
super.onDestroy();
if (banner != null) {
banner.destroy();
banner = null;
}
}
destroy()를 호출하지 않으면 메모리 누수가 발생할 수 있습니다.광고 크기
배너 광고는 유닛에 설정한 크기에 맞춰 뷰의 크기를 지정해야 합니다.일반적인 배너 크기
| 크기 | 용도 |
|---|---|
| 320 x 50 | 소형 배너 |
| 320 x 100 | 중형 배너 |
| 16:9 비율 | 동영상 배너 |
XML에서 크기 지정
<io.adrop.ads.banner.AdropBanner
android:id="@+id/adrop_banner"
android:layout_width="320dp"
android:layout_height="100dp"
app:adrop_unit_id="YOUR_UNIT_ID" />
코드에서 크기 지정
val params = FrameLayout.LayoutParams(
dpToPx(320), // width
dpToPx(100) // height
)
container.addView(banner, params)
// dp를 px로 변환하는 유틸리티 함수
fun dpToPx(dp: Int): Int {
val density = resources.displayMetrics.density
return (dp * density).toInt()
}
FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
dpToPx(320), // width
dpToPx(100) // height
);
container.addView(banner, params);
// dp를 px로 변환하는 유틸리티 함수
private int dpToPx(int dp) {
float density = getResources().getDisplayMetrics().density;
return (int) (dp * density);
}
테스트 유닛 ID
개발 및 테스트 시 아래의 테스트 유닛 ID를 사용하세요.| 광고 유형 | 테스트 유닛 ID | 크기 |
|---|---|---|
| 배너 (320x50) | PUBLIC_TEST_UNIT_ID_320_50 | 320 x 50 |
| 배너 (320x100) | PUBLIC_TEST_UNIT_ID_320_100 | 320 x 100 |
| 캐러셀 배너 | PUBLIC_TEST_UNIT_ID_CAROUSEL | 가변 |
| 배너 비디오 (16:9) | PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_16_9 | 16:9 비율 |
| 배너 비디오 (9:16) | PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_9_16 | 9:16 비율 |
사용 예시
val banner = AdropBanner(this, "PUBLIC_TEST_UNIT_ID_320_100")
AdropBanner banner = new AdropBanner(this, "PUBLIC_TEST_UNIT_ID_320_100");
<io.adrop.ads.banner.AdropBanner
android:id="@+id/adrop_banner"
android:layout_width="320dp"
android:layout_height="100dp"
app:adrop_unit_id="PUBLIC_TEST_UNIT_ID_320_100" />
동영상 재생 제어
동영상 배너 광고의 경우,play()와 pause()를 사용하여 비디오 재생을 수동으로 제어할 수 있습니다.
play()
동영상 재생을 재개합니다. 팝업이 닫히거나 앱이 백그라운드에서 복귀해 배너가 다시 노출될 때 호출하세요.banner?.play()
banner.play();
pause()
동영상 재생을 일시 정지합니다. 배너가 팝업에 가려지거나 앱이 백그라운드로 진입할 때 호출하세요.banner?.pause()
banner.pause();
예시: 백그라운드/포그라운드 처리
override fun onResume() {
super.onResume()
banner?.play()
}
override fun onPause() {
super.onPause()
banner?.pause()
}
@Override
protected void onResume() {
super.onResume();
if (banner != null) {
banner.play();
}
}
@Override
protected void onPause() {
super.onPause();
if (banner != null) {
banner.pause();
}
}
play()와 pause()는 동영상 배너 광고에만 영향을 미칩니다. 이미지 배너에는 효과가 없습니다.커스텀 클릭 처리
기본적으로 SDK는 사용자가 배너 광고를 클릭하면 자동으로 도착 URL을 엽니다. 클릭 이벤트를 직접 처리하고 싶다면 (예: 확인 다이얼로그 표시, 분석 로깅 후 이동 등)useCustomClick을 사용할 수 있습니다.
true로 설정하면 SDK가 클릭 시 자동으로 도착 URL을 열지 않습니다. onAdClicked 이벤트만 발생하며, 직접 open()을 호출해야 합니다.// 1. 커스텀 클릭 처리 활성화
banner?.useCustomClick = true
// 2. 리스너에서 클릭 처리
banner?.listener = object : AdropBannerListener {
override fun onAdClicked(banner: AdropBanner) {
// 커스텀 로직 수행 (다이얼로그 표시, 분석 로깅 등)
println("광고 클릭됨 — 도착 URL 열기")
banner.open()
}
// ... 기타 리스너 메서드
}
// 1. 커스텀 클릭 처리 활성화
banner.setUseCustomClick(true);
// 2. 리스너에서 클릭 처리
banner.setListener(new AdropBannerListener() {
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
// 커스텀 로직 수행 (다이얼로그 표시, 분석 로깅 등)
System.out.println("광고 클릭됨 — 도착 URL 열기");
banner.open();
}
// ... 기타 리스너 메서드
});
open()
광고의 도착 URL을 엽니다. 커스텀 URL을 전달하여 다른 URL을 열 수도 있습니다.// 기본 도착 URL 열기
banner?.open()
// 커스텀 URL 열기
banner?.open("https://example.com")
// 기본 도착 URL 열기
banner.open();
// 커스텀 URL 열기
banner.open("https://example.com");
open()은 useCustomClick이 true로 설정된 경우에만 동작합니다. useCustomClick이 false(기본값)이면 SDK가 자동으로 URL을 엽니다.모범 사례
1. 메모리 관리
Activity나 Fragment가 종료될 때 배너를 반드시 해제하세요.override fun onDestroy() {
super.onDestroy()
banner?.destroy()
banner = null
}
@Override
protected void onDestroy() {
super.onDestroy();
if (banner != null) {
banner.destroy();
banner = null;
}
}
2. 화면 가시성
배너가 화면에 보일 때 광고를 로드하세요.override fun onResume() {
super.onResume()
banner?.load()
}
@Override
protected void onResume() {
super.onResume();
if (banner != null) {
banner.load();
}
}
3. 에러 처리
광고 로드 실패 시 적절한 에러 처리를 구현하세요.override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
when (errorCode) {
AdropErrorCode.ERROR_CODE_NETWORK -> {
println("네트워크 오류: 연결을 확인하세요")
}
AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
println("노출 가능한 광고 없음")
}
else -> {
println("광고 로드 실패: $errorCode")
}
}
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
if (errorCode == AdropErrorCode.ERROR_CODE_NETWORK) {
System.out.println("네트워크 오류: 연결을 확인하세요");
} else if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
System.out.println("노출 가능한 광고 없음");
} else {
System.out.println("광고 로드 실패: " + errorCode);
}
}
4. 리사이클러뷰에서 사용
리사이클러뷰에서 배너를 사용할 때는 뷰홀더에서 적절히 관리하세요.class BannerViewHolder(view: View) : RecyclerView.ViewHolder(view) {
private val banner: AdropBanner = view.findViewById(R.id.adrop_banner)
fun bind() {
banner.listener = object : AdropBannerListener {
// 리스너 구현
}
banner.load()
}
fun recycle() {
banner.destroy()
}
}
// 어댑터에서
override fun onViewRecycled(holder: BannerViewHolder) {
holder.recycle()
}
class BannerViewHolder extends RecyclerView.ViewHolder {
private AdropBanner banner;
public BannerViewHolder(View view) {
super(view);
banner = view.findViewById(R.id.adrop_banner);
}
public void bind() {
banner.setListener(new AdropBannerListener() {
// 리스너 구현
});
banner.load();
}
public void recycle() {
banner.destroy();
}
}
// 어댑터에서
@Override
public void onViewRecycled(BannerViewHolder holder) {
holder.recycle();
}
전체 예제
Kotlin 예제
import android.os.Bundle
import android.view.View
import android.widget.FrameLayout
import android.widget.ProgressBar
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode
class BannerActivity : AppCompatActivity() {
private var banner: AdropBanner? = null
private lateinit var progressBar: ProgressBar
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_banner)
progressBar = findViewById(R.id.progress_bar)
setupBanner()
}
private fun setupBanner() {
// 1. 배너 인스턴스 생성
// contextId는 읽기 전용 프로퍼티 — 생성자에서 설정
banner = AdropBanner(this, "YOUR_UNIT_ID", "article_sports").apply {
// 2. 리스너 설정
listener = object : AdropBannerListener {
override fun onAdReceived(banner: AdropBanner) {
println("배너 광고 수신 성공")
progressBar.visibility = View.GONE
}
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
println("배너 광고 수신 실패: $errorCode")
progressBar.visibility = View.GONE
// 에러에 따른 처리
when (errorCode) {
AdropErrorCode.ERROR_CODE_NETWORK -> {
showToast("네트워크 연결을 확인하세요")
}
AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
println("노출 가능한 광고가 없습니다")
}
else -> {
showToast("광고를 불러올 수 없습니다")
}
}
}
override fun onAdImpression(banner: AdropBanner) {
println("배너 광고 노출")
}
override fun onAdClicked(banner: AdropBanner) {
println("배너 광고 클릭")
}
}
}
// 3. 뷰 계층에 추가
val container = findViewById<FrameLayout>(R.id.banner_container)
val params = FrameLayout.LayoutParams(
dpToPx(320),
dpToPx(100)
)
container.addView(banner, params)
// 4. 광고 로드
progressBar.visibility = View.VISIBLE
banner?.load()
}
private fun dpToPx(dp: Int): Int {
val density = resources.displayMetrics.density
return (dp * density).toInt()
}
private fun showToast(message: String) {
Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
}
override fun onDestroy() {
super.onDestroy()
// 5. 메모리 해제
banner?.destroy()
banner = null
}
}
Java 예제
import android.os.Bundle;
import android.view.View;
import android.widget.FrameLayout;
import android.widget.ProgressBar;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import org.jetbrains.annotations.NotNull;
public class BannerActivity extends AppCompatActivity {
private AdropBanner banner;
private ProgressBar progressBar;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_banner);
progressBar = findViewById(R.id.progress_bar);
setupBanner();
}
private void setupBanner() {
// 1. 배너 인스턴스 생성 (Context ID 포함)
banner = new AdropBanner(this, "YOUR_UNIT_ID", "article_sports");
// 2. 리스너 설정
banner.setListener(new AdropBannerListener() {
@Override
public void onAdReceived(@NotNull AdropBanner banner) {
System.out.println("배너 광고 수신 성공");
progressBar.setVisibility(View.GONE);
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
System.out.println("배너 광고 수신 실패: " + errorCode);
progressBar.setVisibility(View.GONE);
// 에러에 따른 처리
if (errorCode == AdropErrorCode.ERROR_CODE_NETWORK) {
showToast("네트워크 연결을 확인하세요");
} else if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
System.out.println("노출 가능한 광고가 없습니다");
} else {
showToast("광고를 불러올 수 없습니다");
}
}
@Override
public void onAdImpression(@NotNull AdropBanner banner) {
System.out.println("배너 광고 노출");
}
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
System.out.println("배너 광고 클릭");
}
});
// 3. 뷰 계층에 추가
FrameLayout container = findViewById(R.id.banner_container);
FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
dpToPx(320),
dpToPx(100)
);
container.addView(banner, params);
// 4. 광고 로드
progressBar.setVisibility(View.VISIBLE);
banner.load();
}
private int dpToPx(int dp) {
float density = getResources().getDisplayMetrics().density;
return (int) (dp * density);
}
private void showToast(String message) {
Toast.makeText(this, message, Toast.LENGTH_SHORT).show();
}
@Override
protected void onDestroy() {
super.onDestroy();
// 5. 메모리 해제
if (banner != null) {
banner.destroy();
banner = null;
}
}
}
XML 레이아웃
activity_banner.xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView
android:id="@+id/title"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="배너 광고 예제"
android:textSize="24sp"
android:textStyle="bold"
android:layout_marginTop="32dp"
app:layout_constraintTop_toTopOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintEnd_toEndOf="parent" />
<ProgressBar
android:id="@+id/progress_bar"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:visibility="gone"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintTop_toTopOf="parent" />
<FrameLayout
android:id="@+id/banner_container"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_margin="16dp"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintEnd_toEndOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>
일괄 로드 (loads)
AdropBanner.loads()를 사용하면 한 번의 호출로 여러 배너 광고를 요청할 수 있습니다. 캐러셀, 페이지네이션 피드, 광고 풀 프리페칭 등에 유용합니다.
시그니처
AdropBanner.loads(
context: Context,
unitId: String,
contextId: String? = null,
listener: AdropBannerListener,
)
AdropBanner.loads(context, "YOUR_UNIT_ID", null, listener);
사용 방법
AdropBanner.loads(
context = this,
unitId = "YOUR_UNIT_ID",
contextId = null,
listener = object : AdropBannerListener {
// 배치 성공 — 최대 5개의 준비된 배너가 전달됩니다.
override fun onAdsReceived(banners: List<AdropBanner>) {
banners.forEach { banner ->
// 뷰 계층에 추가 (ViewPager2, RecyclerView 등)
container.addView(banner)
}
}
// 배치 실패
override fun onAdsFailedToReceive(errorCode: AdropErrorCode) {
println("배치 로드 실패: $errorCode")
}
// 단건 콜백은 loads 경로에서 호출되지 않습니다.
override fun onAdReceived(banner: AdropBanner) { /* batch path */ }
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {}
// 클릭/노출/비디오 콜백은 각 인스턴스에 대해 정상 호출됩니다.
override fun onAdClicked(banner: AdropBanner) {
println("배너 클릭: ${banner.creativeId}")
}
override fun onAdImpression(banner: AdropBanner) {
println("배너 노출: ${banner.creativeId}")
}
},
)
AdropBanner.loads(this, "YOUR_UNIT_ID", null, new AdropBannerListener() {
@Override
public void onAdsReceived(@NotNull List<AdropBanner> banners) {
for (AdropBanner banner : banners) {
container.addView(banner);
}
}
@Override
public void onAdsFailedToReceive(@NotNull AdropErrorCode errorCode) {
System.out.println("배치 로드 실패: " + errorCode);
}
// 단건 콜백 — 배치 경로에서는 사용되지 않습니다.
@Override
public void onAdReceived(@NotNull AdropBanner banner) { }
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) { }
@Override
public void onAdClicked(@NotNull AdropBanner banner) {
System.out.println("배너 클릭: " + banner.getCreativeId());
}
@Override
public void onAdImpression(@NotNull AdropBanner banner) {
System.out.println("배너 노출: " + banner.getCreativeId());
}
});
리스너 콜백
| 콜백 | 호출 시점 |
|---|---|
onAdsReceived(banners) | 배치 전달 완료. 각 AdropBanner에는 리스너가 이미 부착되어 있고 광고 데이터가 적용된 상태입니다. |
onAdsFailedToReceive(errorCode) | 요청 거부, 네트워크 실패 또는 표시 가능한 광고가 없는 경우(ERROR_CODE_AD_NO_FILL). |
onAdClicked / onAdImpression / onAdVideoStart / onAdVideoEnd | 단건 load()와 동일하게 각 배너별로 호출됩니다. |
단건
onAdReceived / onAdFailedToReceive 콜백은 loads() 경로에서 호출되지 않습니다. 배치 결과는 반드시 onAdsReceived / onAdsFailedToReceive로만 수신하세요.제약 사항
- 호출당 최대 5개. 서버가 그 이상을 반환하더라도 앞의 5개만 전달됩니다.
- 백필은 적용되지 않습니다. 직광고 채움이 없으면 백필 설정과 무관하게
onAdsFailedToReceive가ERROR_CODE_AD_NO_FILL로 호출됩니다. onAdsReceived안에서destroy()를 호출하지 마세요. 먼저 각 배너를 뷰 계층에 부착한 뒤, 부모Activity.onDestroy()(또는 동등한 시점)에서destroy()하세요.onAdsReceived는 광고 데이터가 적용되는 즉시 발화되며, 이는 단건load()동작과 동일합니다 — 뷰에 부착된 뒤 크리에이티브가 그려집니다.
백필 광고
백필 광고가 활성화된 경우, 직광고가 없을 때 자동으로 백필 광고가 로드됩니다.isBackfilled 프로퍼티로 백필 광고 여부를 확인할 수 있습니다.
banner.listener = object : AdropBannerListener {
override fun onAdReceived(banner: AdropBanner) {
if (banner.isBackfilled) {
println("백필 광고가 로드되었습니다")
} else {
println("직광고가 로드되었습니다")
}
}
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {
when (errorCode) {
AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
println("직광고 없음, 백필 광고 요청 중...")
}
AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL -> {
println("백필 광고도 없음")
}
else -> {
println("광고 로드 실패: $errorCode")
}
}
}
}
banner.setListener(new AdropBannerListener() {
@Override
public void onAdReceived(@NotNull AdropBanner banner) {
if (banner.isBackfilled()) {
System.out.println("백필 광고가 로드되었습니다");
} else {
System.out.println("직광고가 로드되었습니다");
}
}
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) {
if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
System.out.println("직광고 없음, 백필 광고 요청 중...");
} else if (errorCode == AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL) {
System.out.println("백필 광고도 없음");
} else {
System.out.println("광고 로드 실패: " + errorCode);
}
}
});
백필 광고를 사용하려면
io.adrop:adrop-ads-backfill 의존성을 추가해야 합니다.백필 광고 미리 로드 (preload)
SDK 1.17.0부터AdropBanner.preload()로 백필 배너 광고를 미리 받아 둘 수 있습니다. 같은 유닛 ID와 같은 크기로 load()한 배너가 직광고 없이 백필 광고로 넘어가면, 백필 광고를 다시 요청하지 않고 미리 받아 둔 광고를 바로 표시합니다.
load()는 preload와 관계없이 직광고를 먼저 요청합니다. 직광고가 표시되면 미리 받아 둔 광고는 그대로 남습니다. preload를 호출하지 않으면 동작은 이전과 같습니다.
동작 조건
io.adrop:adrop-ads와io.adrop:adrop-ads-backfill이 모두 1.17.0 이상이어야 합니다.- 서버가 앱에 지금 노출할 직광고가 없다고 알려 준 상태에서만 백필 광고를 받습니다. 그 밖에는 백필 광고를 요청하지 않고
ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다. 직광고 캠페인이 있는 앱에서는 정상적인 결과입니다. - 앱 설치 직후, 앱 키를 바꾼 직후,
setUID로 다른 사용자로 바꾼 직후에는 서버 응답을 받기 전까지ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다. - 테스트 유닛 ID로는 항상
ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다.
사용 방법
배너를 표시할 Activity를context로 넘겨, 배너가 있는 화면을 띄우기 직전에 호출하세요. 미리 받은 광고는 쓰이지 않으면 30분 뒤 폐기되므로 곧 표시할 배너에만 호출하세요. 결과를 기다렸다가 load()할 필요는 없습니다. 아직 받는 중이면 load()가 그 결과를 기다려 사용합니다.
import io.adrop.ads.banner.AdropBanner
import io.adrop.ads.banner.AdropBannerListener
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.model.CreativeSize
AdropBanner.preload(
context = this, // 배너를 표시할 Activity
unitId = "YOUR_UNIT_ID",
adSize = CreativeSize(320.0, 50.0), // 생략하면 320x50
listener = object : AdropBannerListener {
override fun onAdPreloadReceived(unitId: String, contextId: String?) {
println("미리 로드 완료: $unitId")
}
override fun onAdPreloadFailedToReceive(unitId: String, contextId: String?, errorCode: AdropErrorCode) {
// ERROR_CODE_AD_PRELOAD_SKIPPED는 정상 결과입니다.
// 여기서 preload를 바로 다시 호출하지 마세요.
println("미리 로드 안 됨: $errorCode")
}
// preload에서는 호출되지 않습니다.
override fun onAdReceived(banner: AdropBanner) {}
override fun onAdClicked(banner: AdropBanner) {}
override fun onAdFailedToReceive(banner: AdropBanner, errorCode: AdropErrorCode) {}
},
)
import io.adrop.ads.banner.AdropBanner;
import io.adrop.ads.banner.AdropBannerListener;
import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.model.CreativeSize;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
AdropBanner.preload(this, "YOUR_UNIT_ID", null, new CreativeSize(320.0, 50.0), new AdropBannerListener() {
@Override
public void onAdPreloadReceived(@NotNull String unitId, @Nullable String contextId) {
System.out.println("미리 로드 완료: " + unitId);
}
@Override
public void onAdPreloadFailedToReceive(@NotNull String unitId, @Nullable String contextId, @NotNull AdropErrorCode errorCode) {
// ERROR_CODE_AD_PRELOAD_SKIPPED는 정상 결과입니다.
// 여기서 preload를 바로 다시 호출하지 마세요.
System.out.println("미리 로드 안 됨: " + errorCode);
}
// preload에서는 호출되지 않습니다.
@Override
public void onAdReceived(@NotNull AdropBanner banner) { }
@Override
public void onAdClicked(@NotNull AdropBanner banner) { }
@Override
public void onAdFailedToReceive(@NotNull AdropBanner banner, @NotNull AdropErrorCode errorCode) { }
});
load()할 배너의 adSize를 preload에 넘긴 크기와 같게 지정하세요.
val banner = AdropBanner(this, "YOUR_UNIT_ID")
banner.adSize = CreativeSize(320.0, 50.0) // preload에 넘긴 크기
container.addView(banner)
banner.load()
AdropBanner banner = new AdropBanner(this, "YOUR_UNIT_ID", null);
banner.setAdSize(new CreativeSize(320.0, 50.0)); // preload에 넘긴 크기
container.addView(banner);
banner.load();
미리 받은 광고가 쓰이는 조건
- 같은 유닛 ID와 같은 크기:
load()하는 배너의adSize(지정하지 않았으면 화면에 배치된 뷰 크기, dp)가 preload에 넘긴 크기와 같아야 합니다. 크기가 다르면 미리 받은 광고는 그대로 남고,load()는 평소처럼 백필 광고를 요청합니다. - 같은 Activity: preload에 넘긴 Activity와 다른 Activity로 만든 배너에는 쓰이지 않습니다(예: 스플래시 Activity에서 preload하고 메인 Activity에서
load()). preload에 넘긴 Activity가 종료되면 미리 받은 광고도 폐기됩니다. - 한 번만 사용: 미리 받은 광고는
load()한 번에 쓰이면 없어집니다. 다시 미리 받으려면 preload를 다시 호출하세요. - 유효 시간과 개수: 30분 안에 쓰이지 않은 광고는 폐기됩니다. 같은 유닛·크기에는 1개만 보관하고, 배너는 서로 다른 유닛·크기 조합을 최대 5개까지 보관합니다. 5개를 넘으면 가장 먼저 받은 광고부터 폐기합니다.
- 다시 호출할 때: 같은 유닛·크기로 다시 호출해도 새로 요청하지 않습니다. 받아 둔 광고가 있으면 새 요청 없이
onAdPreloadReceived가 호출되고, 받는 중이면 그 로드의 결과(성공 또는 실패)가 똑같이 전달됩니다. 광고를 새로 고치는 용도로는 쓸 수 없습니다. 단, 그 사이 사용자 동의 상태가 바뀌었거나 다른 Activity를 넘겨 호출하면 기존 광고를 버리고 새로 받습니다. - 동의 상태 변경: 미리 받은 뒤 사용자 동의 상태가 바뀌면 그 광고는
load()에 쓰이지 않습니다.
결과 콜백
AdropBannerListener에 다음 콜백이 추가되었습니다. 둘 다 선택 구현이며, preload를 호출할 때마다 둘 중 하나가 한 번 메인 스레드에서 호출됩니다. preload에서는 다른 리스너 콜백이 호출되지 않습니다.
| 콜백 | 호출 시점 |
|---|---|
onAdPreloadReceived(unitId, contextId) | 미리 받기가 끝났을 때. 그 결과를 기다리던 load()가 이미 사용했을 수도 있습니다. |
onAdPreloadFailedToReceive(unitId, contextId, errorCode) | 미리 받지 못했을 때 |
contextId는 preload에 넘긴 값을 그대로 돌려줍니다. 미리 받은 광고를 고르는 데는 쓰이지 않습니다.
실패 코드
| 에러 코드 | 설명 |
|---|---|
ERROR_CODE_AD_PRELOAD_SKIPPED | 직광고가 노출될 수 있거나 아직 확인되지 않아 백필 광고를 요청하지 않았습니다. 정상 결과이므로 다음 화면을 띄우기 직전에 다시 호출하세요. |
ERROR_CODE_AD_NO_FILL | 1.17.0 이상의 백필 의존성이 없거나, 유닛에 백필이 설정되지 않았거나 SDK가 그 설정을 아직 받지 못했습니다. 잠시 뒤 다시 호출하세요. 백필 의존성이 없으면 계속 이 코드로 끝납니다. |
ERROR_CODE_AD_BACKFILL_NO_FILL | 백필 광고가 없습니다. |
ERROR_CODE_INTERNAL | 요청이 중단되었거나(예: 받는 중에 preload에 넘긴 Activity가 종료됨) 내부 오류가 발생했습니다. 나중에 다시 호출하세요. |
ERROR_CODE_INITIALIZE | SDK가 초기화되지 않았습니다. Adrop.initialize()의 대상 국가에 속하지 않는 기기에서도 이 코드로 끝납니다. |
ERROR_CODE_INVALID_UNIT | 유닛 ID가 비어 있습니다. |
실패 콜백 안에서 preload를 바로 다시 호출하지 마세요. 백필 의존성이 없을 때처럼 결과가 바뀌지 않으면 호출이 끝없이 반복됩니다. 다음 화면을 띄우기 전처럼 나중에 다시 호출하세요.
다음 단계
네이티브 광고
UI에 맞게 커스터마이징 가능한 네이티브 광고 구현하기
전면 광고
화면 전체를 덮는 전면 광고 구현하기
타겟팅 설정
사용자 속성 및 문맥 타겟팅 설정하기
레퍼런스
클래스, 리스너, 에러 코드 참고하기