앱 오프닝 광고(SwiftUI)

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

이 가이드는 iOS 앱에서 SwiftUI로 앱 오프닝 광고를 연동하는 방법을 설명합니다.

모양

앱 오프닝 광고에는 Go to the app 버튼이 있어 사용자가 앱 안에 있음을 알고 광고를 닫을 수 있습니다. 광고 모습 예시:

사전 요구 사항

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

용어

• 콜드 스타트 — 앱이 메모리에 없을 때 실행하여 새 세션을 만드는 경우.
• 웜 스타트 — 앱이 백그라운드(메모리에 일시 중단된 상태)에서 포그라운드로 전환되는 경우.

구현

1. 앱 시작 시 SDK를 초기화합니다.
2. 루트 View(예: WindowGroup 안)에 .appOpenAd(request:onEvent:) 수정자를 추가합니다.
3. Binding<AdRequest?>로 로드를 제어합니다. nil이 아니면 로드가 시작됩니다.
4. 로드에 성공하면 request가 리셋되기 전까지 앱이 활성(포그라운드)이 될 때 광고가 자동으로 표시됩니다.
5. onEvent(AppOpenAdEvent)에서 라이프사이클을 처리합니다.
6. 광고가 닫히거나 표시/로드 오류가 나면 request가 nil로 돌아갑니다 — 다음 로드가 필요할 때 새 AdRequest를 설정하세요(보통 씬 단계 변경 핸들러).

주요 단계

1. 앱 시작 시 SDK 초기화.

   // 광고 로드 전 SDK 초기화 완료 대기
   YandexAds.initializeSDK(completionHandler: completionHandler)
   

2. 루트 뷰에 수정자를 붙이고 요청 상태를 보관합니다.

   Yandex Advertising Network에서 받은 광고 단위 ID(AD_UNIT_ID)가 필요합니다.

   AdRequest로 관심사·컨텍스트·위치 등을 넘겨 요청을 확장할 수 있습니다. 광고 타겟팅을 참고하세요.

   **iOS 14+**에서 ScenePhase 사용 예(request가 nil로 리셋된 뒤 다시 로드):

   import SwiftUI
   import YandexMobileAds
   
   @main
   struct MyApp: App {
       @State private var adRequest: AdRequest?
       @Environment(\.scenePhase) private var scenePhase
   
       var body: some Scene {
           WindowGroup {
               ContentView()
                   .appOpenAd(request: $adRequest) { event in
                       if case .didFailToLoad = event {
                           // 필요 시 지연 재시도 — 아래 권장 사항 참고
                       }
                   }
           }
           .onChange(of: scenePhase) {
               if scenePhase == .active, adRequest == nil {
                   adRequest = AdRequest(adUnitID: "demo-appopenad-yandex")
               }
           }
       }
   }
   

   iOS 13에서는 scenePhase 대신 UIApplication.didBecomeActiveNotification 등으로 nil 이후 새 AdRequest를 설정합니다.

3. 로드·표시 이벤트는 onEvent에서 처리합니다.

   .appOpenAd(request: $adRequest) { event in
       switch event {
       case .didLoad:
           // 준비됨 — 다음 포그라운드에서 표시
           break
       case .didShow:
           break
       case .didDismiss:
           // request는 수정자가 이미 리셋함
           break
       case .didFailToShow:
           break
       case .didFailToLoad:
           // request 리셋됨 — 루프에서 즉시 재시도 비권장
           break
       case .didClick:
           break
       case .didTrackImpression(_):
           break
       }
   }
   

   Примечание

   광고가 이미 제공된 경우, show(from:) 메서드를 호출하면 AppOpenAdDelegate.appOpenAd(_:didFailToShowError:)에서 표시 오류가 반환됩니다.

앱 오프닝 광고 연동 시 유의사항

1. 로드에 시간이 걸릴 수 있으므로 광고가 없다고 콜드 스타트를 지연하지 마세요.
2. 웜 스타트 표시를 위해 미리 프리로드하세요. 바인딩이 nil이면 로드하지 않습니다 — 백그라운드에서 준비할 때 AdRequest를 설정하세요.
3. 앱 시작 시 앱 오프닝과 다른 형식을 동시에 로드하지 마세요. 이때 데이터 다운로드로 기기·네트워크가 바빠 로드가 느려질 수 있습니다.
4. .didFailToLoad 후 루프로 즉시 재로드하지 마세요. 재시도 시 횟수를 제한하세요.

앱 오프닝 광고 연동 테스트

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

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

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

데모 adUnitId: demo-appopenad-yandex.

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

연동이 올바른지 확인

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

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

YMAMobileAds.enableLogging()

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

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

권장 사항

1. 스플래시(로딩 화면) 전에 앱 오프닝 광고를 보여주지 마세요.

2. 요청과 표시 사이 지연이 있으면 사용자 경험이 나빠질 수 있습니다. 메인 콘텐츠 전 스플래시에서 표시를 시작하는 방안을 고려하세요.

3. 설치 직후가 아니라 사용자가 앱을 여러 번 연 뒤, 일정 조건을 충족한 사용자에게만 표시하세요.

4. 매 콜드/웜 스타트마다 보여주지 말고 행동에 따라 빈도를 조절하세요.

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

6. 앱마다 최적 전략이 다르므로 테스트와 주기적 점검을 권장합니다.

추가 자료

• GitHub 링크.