적응형 인라인 배너

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

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

이 형식은 주로 피드형 앱이나 광고에 시선을 두는 것이 허용되는 화면에 사용됩니다.

표시 형태

이 가이드는 Jetpack Compose 확장을 사용해 Android 앱에 적응형 인라인 배너를 통합하는 방법을 설명합니다. 코드 예시와 절차 외에도 이 광고 형식 사용 권장 사항과 추가 자료 링크를 제공합니다.

사전 요건

빠른 시작에 설명된 SDK 통합 단계를 수행하세요.
광고 SDK를 미리 초기화하세요.
최신 Yandex Mobile Ads SDK 버전을 사용하고 있는지 확인하세요. 미디에이션을 사용하는 경우, 최신 통합 빌드 버전을 실행하고 있는지도 확인하세요.

Compose 확장을 사용하려면 build.gradle.kts에 의존성을 추가합니다.

dependencies {
    implementation("com.yandex.android:mobileads:8.0.0")
    implementation("com.yandex.android:mobileads-compose:8.0.0")

    // Compose BOM (minimum 2024.01.00)
    implementation(platform("androidx.compose:compose-bom:2025.03.00"))
}

구현

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

BannerSize.Inline 크기와 함께 Banner Composable을 사용합니다.
광고 이벤트를 추적하려면 선택적으로 BannerEvents를 넘깁니다.

적응형 인라인 배너 통합 시 유의 사항

Yandex Mobile Ads SDK 메서드 호출은 모두 메인 스레드에서 수행해야 합니다.
동영상 광고가 올바르게 렌더링되려면 하드웨어 가속을 켜 두세요. 기본적으로 켜져 있지만 일부 앱에서는 끕니다. 끈 경우 광고를 표시하는 액티비티에 대해서는 하드웨어 가속을 켜는 것을 권장합니다.
onAdFailedToLoad() 콜백으로 오류가 오면 즉시 새 광고를 다시 로드하지 마세요. 재시도가 필요하면 재로드 횟수를 제한해 제한 환경에서 연속 실패 요청과 연결 문제를 피하세요.
적응형 인라인 배너가 제대로 동작하려면 앱 레이아웃을 적응형으로 구성해야 합니다. 그렇지 않으면 광고가 잘못 렌더링될 수 있습니다.
적응형 인라인 배너는 사용 가능한 전체 너비를 쓰는 것이 가장 좋습니다. 대부분의 경우 기기 화면 전체 너비입니다. 앱 패딩과 디스플레이 세이프 영역을 반영하세요.
적응형 인라인 배너는 스크롤 가능한 콘텐츠 안에 두도록 설계되었습니다. 배너 높이는 API에 따라 기기 화면 높이와 같거나 최대 높이로 제한될 수 있습니다.
광고 크기는 BannerSize.Inline(width, maxHeight)로 설정하며, 너비와 최대 높이는 Dp로 전달합니다(예: 320.dp). 계산에 쓰는 Context는 Composable 내부에서 자동으로 해석됩니다.
배너 상태는 rememberBannerAdState()로 만들고 loadAd()를 명시적으로 호출해 로드를 시작합니다. adSize가 바뀌면 BannerAdView가 자동으로 다시 생성됩니다.

상단의 클릭할 수 없는 안전 영역의 높이는 80dp입니다. 영역 내에 있는 컨트롤은 클릭할 수 있습니다.
시각적 요소(자산)의 크기는 32×32dp 이상이어야 합니다. 여기에는 닫기 버튼과 기타 모든 아이콘이 포함됩니다.
자산 주변의 클릭 가능한 영역은 64×64dp 이상이어야 합니다. 예를 들어 자산의 크기가 32×32dp인 경우, 주변에 충분한 여백을 두어 전체 클릭 가능한 영역이 64×64dp이 되도록 해야 합니다.
컨트롤이 지연되어 나타나는 경우, 요소가 로드될 때까지 타이머나 진행 표시줄을 표시해야 합니다.

예시

광고 로드 및 표시

인라인 배너를 표시하려면 BannerSize.Inline 크기로 rememberBannerAdState()로 상태를 만든 뒤 Banner Composable에 넘깁니다. loadAd()를 명시적으로 호출해 로드를 시작합니다.

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

AdRequest.Builder()로 사용자 관심 데이터, 페이지 컨텍스트, 위치 등 추가 데이터를 넘겨 광고 요청 매개변수를 확장할 수 있습니다. 요청에 컨텍스트 데이터를 더하면 광고 품질을 크게 높일 수 있습니다. 자세한 내용은 광고 타겟팅을 참고하세요.

적응형 인라인 배너를 표시하는 예시는 다음과 같습니다. 로드에 성공하면 배너가 자동으로 표시됩니다.

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.Banner
import com.yandex.mobile.ads.compose.BannerSize
import com.yandex.mobile.ads.compose.rememberBannerAdState

@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Inline(width = 320.dp, maxHeight = 400.dp),
    )

    LaunchedEffect(Unit) {
        bannerState.loadAd(AdRequest.Builder("your-ad-unit-id").build())
    }

    Banner(
        state = bannerState,
        modifier = Modifier.fillMaxWidth(),
    )
}

광고 이벤트를 추적하려면 상태를 만들 때 BannerEvents를 넘깁니다.

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.Banner
import com.yandex.mobile.ads.compose.BannerEvents
import com.yandex.mobile.ads.compose.BannerSize
import com.yandex.mobile.ads.compose.rememberBannerAdState

@Composable
fun MyScreen() {
    val bannerState = rememberBannerAdState(
        adSize = BannerSize.Inline(width = 320.dp, maxHeight = 400.dp),
        events = BannerEvents(
            onAdLoaded = { Log.d("YandexAds", "Banner loaded") },
            onAdFailedToLoad = { error -> Log.e("YandexAds", error.description) },
            onAdClicked = { Log.d("YandexAds", "Banner clicked") },
            onImpression = { data -> Log.d("YandexAds", "Impression: ${data?.rawData}") },
        ),
    )

    LaunchedEffect(Unit) {
        bannerState.loadAd(AdRequest.Builder("your-ad-unit-id").build())
    }

    Banner(
        state = bannerState,
        modifier = Modifier.fillMaxWidth(),
    )
}

Adfox를 통해 광고를 제공하는 경우, 배너 광고 응답 이후에는 campaignId, bannerId, 그리고 placeId 데이터에 AdAttributes 유형의 adAttributes 속성을 사용하여 BannerAdView 객체에서 액세스할 수 있습니다.

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

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

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

모든 광고 요청에 대해 테스트 광고가 반환되도록 보장하기 위해 특별한 데모 광고 배치 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

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

추가 자료

GitHub 링크.

Was the article helpful?

TradPlus ↗

적응형 스티키 배너