적응형 인라인 배너

적응형 인라인 배너는 장치에서 광고 크기를 최적화하여 최대 효율을 제공하는 유연한 배너 광고 형식입니다.

이 광고 유형은 개발자가 광고에 허용 가능한 최대 너비 및 높이를 설정할 수 있게 하지만, 최적의 광고 크기는 여전히 자동으로 결정됩니다. 최적의 광고 크기를 선택하기 위해, 내장된 적응형 배너는 고정 높이가 아닌 최대 높이를 사용합니다. 따라서 성과를 높일 여지가 있습니다.

일반적으로 이 형식은 피드형 앱이나 사용자의 주의를 주로 광고에 두어도 되는 맥락에서 사용됩니다.

표시 형태

이 가이드는 Compose Multiplatform 앱에 적응형 인라인 배너를 통합하는 과정을 다룹니다. 코드 샘플·안내 외에 형식별 권장 사항과 추가 자료 링크도 포함합니다.

사전 요건

  1. 빠른 시작에 따라 Yandex Mobile Ads Compose Multiplatform 플러그인을 통합합니다.
  2. 최신 Yandex Mobile Ads Compose Multiplatform 플러그인 버전을 사용하세요. 미디에이션을 사용하는 경우 최신 통합 빌드 버전도 사용하세요.

구현

적응형 인라인 배너 통합의 주요 단계:

  • UI에 Banner Composable을 추가하고 컨테이너 너비와 최대 높이로 BannerAdSize.Inline을 전달합니다.
  • BannerEvents로 광고 생명 주기 이벤트 콜백을 설정합니다.

적응형 인라인 배너 통합 시 특징

  1. onAdFailedToLoad에서 오류가 나면 새 광고를 바로 다시 로드하지 마세요. 부득이하면 재시도 횟수를 제한하세요.

  2. 적응형 인라인 배너가 올바르게 동작하려면 앱 레이아웃을 적응형으로 구성하세요. 그렇지 않으면 광고가 잘못 렌더링될 수 있습니다.

  3. 사용 가능한 전체 너비를 쓰는 것이 가장 좋습니다. 대부분 기기 화면 전체 너비입니다. 앱의 패딩과 디스플레이 안전 영역을 고려하세요.

  4. 적응형 인라인 배너는 스크롤 가능한 콘텐츠에 배치하도록 설계되었습니다. 높이는 API에 따라 화면과 같거나 최대 높이로 제한될 수 있습니다.

  5. 배너 크기는 사용 가능한 컨테이너 너비와 허용 최대 높이를 받는 BannerAdSize.Inline(width, maxHeight)로 지정합니다.

  6. BannerAdSize.Inline(width, maxHeight)로 만든 값은 백엔드에서 최적 크기를 고르는 기술 데이터를 담습니다. 로드마다 렌더 높이가 달라질 수 있습니다. 픽셀 단위 배치가 필요하면 로드 후 컨테이너를 측정하세요.

레이아웃에 배너 추가

인라인 배너가 들어갈 위치(예: 피드의 스크롤 컬럼 내부)에 Banner Composable을 사용합니다.

화면에 배너를 배치하는 예:

@Composable
fun BannerSlot(adRequest: AdRequest, containerWidth: Int, maxHeight: Int) {
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = containerWidth, maxHeight = maxHeight),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = { /* ad loaded */ },
            onAdFailedToLoad = { error -> /* handle error */ },
            onAdClicked = { /* ad clicked */ },
            onImpression = { data -> /* impression tracked */ },
        ),
    )
}

광고 로드 및 표시

Banner Composable은 컴포지션에 들어오면 주어진 AdRequest에 대해 광고를 자동으로 로드하고 갱신합니다.

BannerAdSize.Inline에는 컨테이너 너비와 허용 최대 높이를 넘기세요. 부모 또는 화면 전체 너비를 쓰는 것을 권장하며, 패딩과 안전 영역을 반영하세요. BoxWithConstraints나 자체 레이아웃 측정으로 너비를 구할 수 있습니다:

BoxWithConstraints(modifier = Modifier.fillMaxWidth()) {
    val widthDp = maxWidth.value.toInt()
    Banner(
        adRequest = adRequest,
        adSize = BannerAdSize.Inline(width = widthDp, maxHeight = bannerMaxHeightDp),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(/* ... */),
    )
}

광고를 로드하려면 Yandex Advertising Network 인터페이스에서 받은 광고 유닛 ID(adUnitId)가 필요합니다.

로드 성공·실패 알림과 적응형 인라인 배너 생명 주기 추적은 위 예시처럼 BannerEvents를 사용합니다.

AdRequest로 요청을 확장할 수 있습니다(예: targeting, parameters, preferredTheme). 추가 컨텍스트는 품질 향상에 도움이 됩니다. 광고 타게팅을 참고하세요.

적응형 인라인 배너 로드 예시. 로드되면 배너가 자동으로 표시됩니다:

@Composable
fun InlineBanner(adUnitId: String) {
    Banner(
        adRequest = AdRequest(adUnitId = adUnitId),
        adSize = BannerAdSize.Inline(width = 320, maxHeight = 50),
        modifier = Modifier.fillMaxWidth(),
        events = BannerEvents(
            onAdLoaded = {
                // The ad was loaded successfully and will be shown.
            },
            onAdFailedToLoad = { error ->
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
            },
            onAdClicked = {
                // Called when a click is recorded for an ad.
            },
            onImpression = { impressionData ->
                // Called when an impression is recorded for an ad.
            },
        ),
    )
}

통합 중에는 adUnitId로 'demo-banner-yandex'를 사용할 수 있으며, 출시 전 실제 유닛으로 바꾸세요.

리소스 해제

사용자가 화면을 벗어나면 Banner를 컴포지션에서 제거(또는 렌더링 중단)하세요. 플랫폼 뷰가 정리됩니다. 숨긴 배너만 재사용하려고 참조를 들고 있지 마세요. 슬롯이 다시 보일 때 새 AdRequest로 새 Banner를 만드세요.

적응형 인라인 배너 통합 테스트

광고 테스트를 위한 데모 광고 단위 사용

적응형 인라인 배너 통합 및 앱 자체를 테스트하기 위해 테스트 광고를 사용하는 것이 좋습니다.

모든 광고 요청에 대해 테스트 광고가 반환되도록 보장하기 위해 특별한 데모 광고 배치 ID를 생성했습니다. 광고 통합을 확인하는 데 사용하세요.

데모 adUnitId: demo-banner-yandex.

Важно

앱을 스토어에 게시하기 전에 데모 배치 ID를 Yandex Advertising Network 인터페이스에서 획득한 실제 ID로 교체해야 합니다.

사용 가능한 데모 광고 배치 ID 목록은 테스트용 데모 광고 단위 섹션에서 찾을 수 있습니다.

광고 통합 테스트

SDK의 내장 분석기를 사용하여 적응형 인라인 배너 통합을 확인할 수 있습니다.

이 도구는 광고가 제대로 통합되었는지 확인하고 로그에 상세한 보고서를 출력합니다. 보고서를 보려면 Android 앱 디버깅을 위한 Logcat 도구에서 "YandexAds" 키워드를 검색하세요.

adb logcat -v brief '*:S YandexAds'

통합에 성공하면 다음 메시지가 표시됩니다.

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully

배너 광고 통합에 문제가 있는 경우, 문제에 대한 상세한 보고서와 해결 방법에 대한 권장 사항을 받게 됩니다.

데모 광고 유닛으로 광고 테스트

광고 통합 및 앱 자체를 테스트하기 위해 테스트 광고를 사용하는 것이 좋습니다.

모든 광고 요청에 대해 테스트 광고가 반환되도록 보장하기 위해 특별한 데모 광고 배치 ID를 생성했습니다. 광고 통합을 확인하는 데 사용하세요.

데모 adUnitId: demo-banner-yandex.

Важно

앱을 스토어에 게시하기 전에 데모 배치 ID를 Yandex Advertising Network 인터페이스에서 획득한 실제 ID로 교체해야 합니다.

사용 가능한 데모 광고 배치 ID 목록은 테스트용 데모 광고 단위 섹션에서 찾을 수 있습니다.

광고 통합 검증

네이티브 콘솔 도구를 사용하여 광고 통합을 테스트할 수 있습니다.

자세한 로그를 보려면 YMAMobileAds 클래스의 enableLogging 메서드를 호출하세요.

YMAMobileAds.enableLogging()

SDK 로그를 보려면 콘솔 도구로 이동하여 Subsystem = com.mobile.ads.ads.sdk를 설정하세요. 카테고리와 오류 수준별로 로그를 필터링할 수도 있습니다.

광고 통합에 문제가 있는 경우, 문제에 대한 상세한 보고서와 해결 방법에 대한 권장 사항을 받게 됩니다.

Previous
광고 형식
Next
적응형 스티키 배너