앱 오픈 광고

앱 실행 광고는 앱 로드 화면을 수익화하기 위한 특별한 광고 형식입니다. 이러한 광고는 언제든지 종료할 수 있으며, 사용자가 앱을 전면으로 가져올 때, 즉 앱을 시작할 때 또는 백그라운드에서 돌아올 때 제공되도록 설계되었습니다.

이 가이드는 Compose Multiplatform 앱에 앱 오픈 광고를 통합하는 방법을 설명합니다. 코드 예시·안내와 함께 형식별 권장 사항과 추가 자료 링크를 제공합니다.

Внимание

앱 실행 광고는 세로 방향의 앱에만 배치할 수 있습니다. 가로 방향에서는 광고가 제공되지 않습니다.

레이아웃

앱 오픈 광고에는 사용자가 앱 안에 있음을 알고 광고를 닫을 수 있도록 Go to the app 버튼이 포함됩니다. 광고 예시는 다음과 같습니다.

사전 요건

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

용어

  • 콜드 스타트: RAM에 없는 앱을 시작해 새 세션을 만드는 경우입니다.
  • 핫 스타트: RAM에 일시 중지된 상태로 있는 앱을 백그라운드에서 포그라운드로 전환하는 경우입니다.

구현

  1. Composable 범위에서 rememberAppOpenAdLoader()를 얻습니다.
  2. Yandex Advertising Network 인터페이스의 adUnitId로 AdRequest를 만듭니다.
  3. 코루틴에서 loadAd(AdRequest)로 광고를 로드하고, 표시할 때까지 AppOpenAd 참조를 유지합니다.
  4. 필요 시 show() 전에 AppOpenAdEventListener를 연결해 표시·닫기·노출 콜백을 받습니다.
  5. 아래 권장 사항에 따라 앱이 포그라운드로 돌아오거나 스플래시 흐름이 끝날 때 AppOpenAd.show()를 호출합니다.

주요 단계

  1. AppOpenAdLoader 광고 로더 만들기

    @Composable
fun AppOpenRoot() {
    val loader = rememberAppOpenAdLoader()
    // ...
}

  2. 광고 요청 구성

    val adUnitId = "demo-appopenad-yandex" // "R-M-XXXXXX-Y"로 교체
val request = AdRequest(adUnitId = adUnitId)

    adUnitId: Yandex Advertising Network 인터페이스에서 발급되는 고유 식별자로, 형식은 R-M-XXXXXX-Y입니다.

    Совет

    테스트에는 데모 광고 유닛 ID "demo-appopenad-yandex"를 사용할 수 있습니다. 출시 전에는 실제 광고 유닛 ID로 바꾸세요.

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

  3. UI 스코프에 묶인 백그라운드 디스패처에서 광고 로드

    val scope = rememberCoroutineScope()
var appOpenAd by remember { mutableStateOf<AppOpenAd?>(null) }
var isLoading by remember { mutableStateOf(false) }

fun loadAppOpen() {
    isLoading = true
    scope.launch {
        try {
            val ad = loader.loadAd(request)
            appOpenAd = ad
            isLoading = false
        } catch (e: Exception) {
            isLoading = false
            // Ad failed for to load with error
            // Attempting to load a new ad from the OnAdFailedToLoad event is strongly discouraged.
        }
    }
}

  4. 표시 시점 결정. Compose Multiplatform에서는 보통 플랫폼 생명 주기 신호(Android ProcessLifecycleOwner, iOS scenePhase, expect/actual 헬퍼 등)를 연결하고, 앱이 포그라운드로 올 때 loadAppOpen() / show() 조율을 호출합니다. 콜드·핫 스타트를 이미 구분하는 위치에 붙이세요.

  5. 사용자에게 보이는 이벤트용 리스너 등록

    val ad = appOpenAd ?: return
ad.setAdEventListener(
    object : AppOpenAdEventListener {
        override fun onAdShown() {
            // Called when an ad is shown.
        }

        override fun onAdFailedToShow(adError: AdError) {
            // Called when an ad failed to show.
            appOpenAd = null
            // Preload the next ad if appropriate.
        }

        override fun onAdDismissed() {
            // Called when an ad is dismissed.
            appOpenAd = null
            // Preload the next ad if appropriate.
        }

        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.
        }
    },
)
ad.show()

  6. show() 이후에는 광고가 화면에 있는 동안만 AppOpenAd 인스턴스를 유지합니다. 닫힘 콜백 후 참조를 해제한 뒤 다른 소재를 로드하세요.

  7. 로드된 광고가 더 이상 필요 없으면 nullable 참조를 비워 가비지 컬렉션되게 하세요.

    appOpenAd = null

전체 코드 예시

공개 샘플 앱은 전용 화면에서 로드·표시를 시연합니다. 아래 패턴은 참고용으로 단일 Composable에 동일 흐름을 옮긴 것입니다.

@Composable
fun AppOpenSample(adUnitId: String) {
    val loader = rememberAppOpenAdLoader()
    val scope = rememberCoroutineScope()
    var appOpenAd by remember { mutableStateOf<AppOpenAd?>(null) }
    var isLoading by remember { mutableStateOf(false) }

    Column {
        Button(
            onClick = {
                isLoading = true
                scope.launch {
                    try {
                        appOpenAd = loader.loadAd(AdRequest(adUnitId = adUnitId))
                    } catch (e: Exception) {
                        // Ad failed to load with AdRequestError.
                        // Attempting to load a new ad from the onAdFailedToLoad() method is strongly discouraged.
                    }
                    isLoading = false
                }
            },
            enabled = !isLoading,
        ) {
            Text(if (isLoading) "로드 중..." else "앱 오픈 로드")
        }

        Button(
            onClick = { appOpenAd?.show(); appOpenAd = null },
            enabled = appOpenAd != null,
        ) {
            Text("앱 오픈 표시")
        }
    }
}

프로덕션에서는 버튼 대신 실제 생명 주기 진입점에 로드/표시를 연결하세요.

앱 오픈 광고 통합 시 특징

  1. 로드에 시간이 걸릴 수 있으므로, 광고가 아직 로드되지 않았다면 콜드 스타트 시간을 늘리지 마세요.
  2. 핫 스타트 시 표시할 광고는 미리 로드하세요.
  3. 앱 실행 직후 앱 오픈 광고와 다른 형식을 동시에 로드하는 것은 권장하지 않습니다. 그 시점에 운영 데이터를 받아 기기·네트워크가 바빠져 로드가 길어질 수 있습니다.
  4. 로드 중 오류가 발생하면 바로 새 광고를 다시 로드하지 마세요. 꼭 재시도해야 한다면 횟수를 제한하세요. 그래야 제한이 걸렸을 때 끊임없는 실패 요청과 연결 문제를 줄일 수 있습니다.

실행 시 광고 통합 테스트

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

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

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

데모 adUnitId: demo-appopenad-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 App Open Ad was integrated successfully

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

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

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

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

데모 adUnitId: demo-appopenad-yandex.

Важно

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

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

광고 통합 검증

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

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

YMAMobileAds.enableLogging()

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

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

권장 사항

  1. 스플래시 화면보다 먼저 앱 오픈 광고를 보여 주지 마세요.

    스플래시를 보여 주면 사용자 경험이 자연스러워지고, 올바른 앱을 열었다는 확신을 줍니다. 같은 화면에서 곧 광고가 나온다고 알릴 수 있습니다. 로딩 표시나 짧은 문구로 광고 후 콘텐츠로 돌아간다고 안내하세요.

  2. 요청과 렌더 사이에 지연이 있으면 사용자가 잠깐 앱을 본 뒤 콘텐츠와 무관한 광고를 보게 될 수 있습니다. 피하려면 메인 콘텐츠 전에 스플래시에서 렌더링을 시작하세요. 스플래시 뒤에 바로 콘텐츠를 연다면 광고를 렌더링하지 않는 편이 낫습니다.

  3. 신규 사용자는 앱을 몇 번 사용한 뒤에만 앱 오픈 광고를 보여 주세요. 일정 조건(특정 레벨 통과, 실행 횟수, 보상 참여 제외 등)을 만족한 사용자에게만 표시하고, 설치 직후에는 표시하지 마세요.

  4. 사용자 행동에 따라 표시 빈도를 조절하세요. 매 콜드/핫 스타트마다 보여 주지 마세요.

  5. 앱이 백그라운드에 있던 시간이 일정 기준(예: 30초, 2분, 15분) 이상일 때만 표시하세요.

  6. 앱마다 최적 전략이 다르므로 철저히 테스트하세요. 사용자 행동은 변하므로 앱 오픈 전략은 주기적으로 재검증하는 것이 좋습니다.

추가 자료

통합 전체 예시는 여기에서 확인할 수 있습니다.

Previous
보상형 광고
Next
YAN에서의 광고 타겟팅