전면 광고

전면 광고는 게임 레벨 전환이나 목표 작업 완료와 같은 자연스러운 중단 시 앱 콘텐츠 내에 삽입되는 전체 화면 광고 형식입니다.

앱이 전면 광고를 표시하면 사용자는 광고를 탭해 광고주 사이트로 이동하거나 광고를 닫고 앱으로 돌아올 수 있습니다.

전면 광고는 사용자의 주의를 광고에 집중시키기 때문에 CPM이 더 높습니다.

표시 형태

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

사전 요건

  1. 빠른 시작에 설명된 SDK 통합 단계를 수행하세요.
  2. 광고 SDK를 미리 초기화하세요.
  3. 최신 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"))
}

구현

전면 광고 통합의 주요 단계:

  • rememberInterstitialAdLoader()로 광고 로더를 생성합니다.
  • loadAd() suspend 함수로 광고를 로드하고 InterstitialAdLoadResult를 처리합니다.
  • 광고 이벤트 콜백용 리스너 InterstitialAdEventListener를 등록합니다.
  • InterstitialAd를 표시합니다.

전면 광고 통합 시 유의 사항

  1. Yandex Mobile Ads SDK 메서드 호출은 모두 메인 스레드에서 수행해야 합니다.

  2. InterstitialAdLoadResult.Failure로 오류가 오면 즉시 새 광고를 다시 로드하지 마세요. 재시도가 필요하면 재로드 횟수를 제한해 제한 환경에서 연속 실패 요청과 연결 문제를 피하세요.

  3. 가비지 컬렉션을 막기 위해 광고 상호작용이 일어나는 화면이 살아 있는 동안 광고에 대한 강한 참조를 유지하는 것이 좋습니다.

  4. Composable이 컴포지션 트리에서 사라지면 cancelLoading()이 자동으로 호출되므로 로더 리소스를 명시적으로 해제할 필요가 없습니다.

광고 로드

전면 광고는 rememberInterstitialAdLoader()로 로드합니다. 로드는 suspend 함수 loadAd()로 수행되며, 반환 타입은 InterstitialAdLoadResult입니다.

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

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

전면 광고를 로드하는 예시는 다음과 같습니다.

import com.yandex.mobile.ads.common.AdRequest
import com.yandex.mobile.ads.compose.rememberInterstitialAdLoader
import com.yandex.mobile.ads.interstitial.InterstitialAdLoadResult

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        when (val result = loader.loadAd(AdRequest.Builder("your-ad-unit-id").build())) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
                // Attempting to load a new ad from here is strongly discouraged.
            }
        }
    }
}

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

광고 표시

전면 광고는 앱 사용의 자연스러운 휴지기에 표시해야 합니다. 예를 들어 게임 레벨 사이나 파일 다운로드 완료와 같은 목표 동작 이후가 적절합니다.

광고를 표시하기 전에 광고 이벤트 리스너 InterstitialAdEventListener를 설정합니다.

@Composable
fun MyScreen(activity: Activity) {
    var interstitialAd by remember { mutableStateOf<InterstitialAd?>(null) }

    val loader = rememberInterstitialAdLoader()

    LaunchedEffect(Unit) {
        when (val result = loader.loadAd(AdRequest.Builder("your-ad-unit-id").build())) {
            is InterstitialAdLoadResult.Success -> interstitialAd = result.ad
            is InterstitialAdLoadResult.Failure -> {
                // Ad failed to load with AdRequestError.
            }
        }
    }

    LaunchedEffect(interstitialAd) {
        interstitialAd?.apply {
            setAdEventListener(object : InterstitialAdEventListener {
                override fun onAdShown() {
                    // Called when ad is shown.
                }
                override fun onAdFailedToShow(adError: AdError) {
                    // Called when an InterstitialAd failed to show.
                    loadInterstitialAd()
                }
                override fun onAdDismissed() {
                    // Called when ad is dismissed.
                    // Now you can preload the next interstitial ad.
                    loadInterstitialAd()
                }
                override fun onAdClicked() {
                    // Called when a click is recorded for an ad.
                }
                override fun onAdImpression(impressionData: ImpressionData?) {
                    // Called when an impression is recorded for an ad.
                }
            })
            show(activity)
        }
    }
}

전면 광고 통합 테스트

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

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

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

데모 adUnitId: demo-interstitial-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 interstitital was integrated successfully

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

추가 자료

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