배너 광고 - Ad Control Help Center

개요

배너 광고는 화면의 일부 영역에 표시되는 직사각형 광고입니다. UIKit과 SwiftUI 모두에서 사용할 수 있습니다.

주요 특징

화면 상단, 하단 또는 중간에 고정 배치 가능
이미지 및 동영상 광고 지원
UIKit 및 SwiftUI 모두 지원
Delegate를 통한 광고 이벤트 처리

개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_320_100

UIKit 구현

UIKit 환경에서는 AdropBanner 클래스를 사용하여 배너 광고를 구현합니다.

기본 구현

import UIKit
import AdropAds

class ViewController: UIViewController {
    private var banner: AdropBanner?

    override func viewDidLoad() {
        super.viewDidLoad()

        // 1. 배너 인스턴스 생성
        banner = AdropBanner(unitId: "YOUR_UNIT_ID")

        // 2. Delegate 설정
        banner?.delegate = self

        // 3. 뷰 계층에 추가
        if let bannerView = banner {
            view.addSubview(bannerView)

            // 4. Auto Layout 설정
            bannerView.translatesAutoresizingMaskIntoConstraints = false
            NSLayoutConstraint.activate([
                bannerView.centerXAnchor.constraint(equalTo: view.centerXAnchor),
                bannerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
                bannerView.widthAnchor.constraint(equalToConstant: 320),
                bannerView.heightAnchor.constraint(equalToConstant: 100)
            ])
        }

        // 5. 광고 로드
        banner?.load()
    }

    deinit {
        // 6. 메모리 해제 전 배너 리소스 정리
        banner?.destroy()
        banner = nil
    }
}

// MARK: - AdropBannerDelegate
extension ViewController: AdropBannerDelegate {
    func onAdReceived(_ banner: AdropBanner) {
        print("배너 광고 수신 성공")
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        print("배너 광고 수신 실패: \(errorCode)")
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("배너 광고 노출")
    }

    func onAdClicked(_ banner: AdropBanner) {
        print("배너 광고 클릭")
    }
}

AdropBanner 초기화

String

필수

애드컨트롤 콘솔에서 생성한 유닛 ID

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")

광고 로드

배너를 화면에 추가한 후 load() 메서드를 호출하여 광고를 요청합니다.

banner?.load()

배너가 화면에 보이는 시점에 load()를 호출하세요. 화면에 보이지 않는 상태에서 로드하면 노출이 정확하게 측정되지 않을 수 있습니다.

Context ID 설정

문맥 타겟팅을 위해 Context ID를 설정할 수 있습니다.

// contextId는 읽기 전용 — 초기화 시 설정
let banner = AdropBanner(unitId: "YOUR_UNIT_ID", contextId: "sport")

SwiftUI 구현

SwiftUI 환경에서는 AdropBannerRepresented를 사용하여 배너 광고를 구현합니다.

기본 구현

import SwiftUI
import AdropAds

struct ContentView: View {
    @State private var represented = AdropBannerRepresented(unitId: "YOUR_UNIT_ID")

    var body: some View {
        VStack {
            Spacer()

            Text("메인 콘텐츠")

            Spacer()

            // 배너 광고
            represented
                .frame(width: 320, height: 100)
                .onAppear {
                    represented.banner.load()
                }
        }
    }
}

Delegate 처리

Delegate를 통해 광고 이벤트를 처리할 수 있습니다.

import SwiftUI
import AdropAds

struct ContentView: View {
    @StateObject private var bannerDelegate = BannerDelegate()
    @State private var represented = AdropBannerRepresented(unitId: "YOUR_UNIT_ID")

    var body: some View {
        VStack {
            Spacer()

            if bannerDelegate.isLoaded {
                Text("광고 로드 완료")
            }

            represented
                .frame(width: 320, height: 100)
                .onAppear {
                    represented.delegate = bannerDelegate
                    represented.banner.load()
                }
        }
    }
}

// Delegate 구현
class BannerDelegate: NSObject, ObservableObject, AdropBannerDelegate {
    @Published var isLoaded = false

    func onAdReceived(_ banner: AdropBanner) {
        print("배너 광고 수신 성공")
        isLoaded = true
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        print("배너 광고 수신 실패: \(errorCode)")
        isLoaded = false
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("배너 광고 노출")
    }

    func onAdClicked(_ banner: AdropBanner) {
        print("배너 광고 클릭")
    }
}

Context ID 설정

AdropBannerRepresented(
    unitId: "YOUR_UNIT_ID",
    contextId: "sport"
)
.frame(width: 320, height: 100)

Objective-C 구현

Objective-C 환경에서 배너 광고를 구현하는 방법입니다.

기본 구현

@import AdropAds;

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) AdropBanner *banner;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. 배너 인스턴스 생성
    self.banner = [[AdropBanner alloc] initWithUnitId:@"YOUR_UNIT_ID"];

    // 2. Delegate 설정
    self.banner.delegate = self;

    // 3. 뷰 계층에 추가
    [self.view addSubview:self.banner];

    // 4. Auto Layout 설정
    self.banner.translatesAutoresizingMaskIntoConstraints = NO;
    [NSLayoutConstraint activateConstraints:@[
        [self.banner.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
        [self.banner.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor],
        [self.banner.widthAnchor constraintEqualToConstant:320],
        [self.banner.heightAnchor constraintEqualToConstant:100]
    ]];

    // 5. 광고 로드
    [self.banner load];
}

- (void)dealloc {
    [self.banner destroy];
    self.banner = nil;
}

#pragma mark - AdropBannerDelegate

- (void)onAdReceived:(AdropBanner *)banner {
    NSLog(@"배너 광고 수신 성공");
}

- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {
    NSLog(@"배너 광고 수신 실패: %ld", (long)errorCode);
}

- (void)onAdImpression:(AdropBanner *)banner {
    NSLog(@"배너 광고 노출");
}

- (void)onAdClicked:(AdropBanner *)banner {
    NSLog(@"배너 광고 클릭");
}

@end

Context ID 설정

// contextId는 읽기 전용 — 초기화 시 설정
AdropBanner *banner = [[AdropBanner alloc] initWithUnitId:@"YOUR_UNIT_ID" contextId:@"sport"];

Delegate 메서드

AdropBannerDelegate 프로토콜은 광고의 생명주기 이벤트를 처리합니다.

onAdReceived (필수)

광고 수신이 성공했을 때 호출됩니다.

func onAdReceived(_ banner: AdropBanner) {
    print("배너 광고 수신 성공")
    // 광고 로딩 인디케이터 숨김 등의 처리
}

onAdFailedToReceive (필수)

광고 수신이 실패했을 때 호출됩니다.

func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
    print("배너 광고 수신 실패: \(errorCode)")
    // 에러 처리 및 대체 콘텐츠 표시
}

AdropErrorCode

에러 유형을 나타내는 코드. 자세한 내용은 레퍼런스를 참고하세요.

onAdImpression (선택)

광고가 화면에 노출되었을 때 호출됩니다.

func onAdImpression(_ banner: AdropBanner) {
    print("배너 광고 노출")
    // 노출 분석 로깅 등의 처리
}

onAdClicked (선택)

사용자가 광고를 클릭했을 때 호출됩니다.

func onAdClicked(_ banner: AdropBanner) {
    print("배너 광고 클릭")
    // 클릭 분석 로깅 등의 처리
}

onAdVideoStart (선택)

동영상 광고가 재생을 시작했을 때 호출됩니다.

func onAdVideoStart(_ banner: AdropBanner) {
    print("배너 동영상 재생 시작")
    // 동영상 시작 분석 로깅 등의 처리
}

onAdVideoEnd (선택)

동영상 광고 재생이 완료되었을 때 호출됩니다.

func onAdVideoEnd(_ banner: AdropBanner) {
    print("배너 동영상 재생 완료")
    // 동영상 종료 분석 로깅 등의 처리
}

클로저 콜백

Delegate 대신 클로저 기반 콜백을 사용할 수 있습니다.

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")

banner.onAdReceived = { banner in
    print("배너 광고 수신 성공")
}

banner.onAdFailedToReceive = { banner, errorCode in
    print("배너 광고 수신 실패: \(errorCode)")
}

banner.onAdImpression = { banner in
    print("배너 광고 노출")
}

banner.onAdClicked = { banner in
    print("배너 광고 클릭")
}

banner.onAdVideoStart = { banner in
    print("배너 동영상 재생 시작")
}

banner.onAdVideoEnd = { banner in
    print("배너 동영상 재생 완료")
}

Delegate와 클로저를 동시에 설정하면 두 가지 모두 호출됩니다.

생명주기 관리

destroy()

배너를 더 이상 사용하지 않을 때는 destroy()를 호출하여 리소스를 해제하세요. WebView, 트래킹, 동영상 재생 등 배너가 잡고 있는 리소스를 능동적으로 정리합니다. destroy()는 idempotent 하므로 여러 번 호출해도 안전하며, 호출 후 해당 인스턴스는 재사용할 수 없습니다.

deinit {
    banner?.destroy()
    banner = nil
}

- (void)dealloc {
    [self.banner destroy];
    self.banner = nil;
}

뷰 컨트롤러 해제 시 destroy()를 호출하지 않으면 WebView와 관련 리소스가 정리되지 않아 메모리 누수 및 성능 저하가 발생할 수 있습니다. 특히 동영상 배너에서 영향이 큽니다.

광고 크기

배너 광고는 유닛에 설정한 크기에 맞춰 뷰의 크기를 지정해야 합니다.

일반적인 배너 크기

크기	용도
320 x 50	소형 배너
320 x 100	대형 배너
16:9 비율	동영상 배너

UIKit

bannerView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    bannerView.widthAnchor.constraint(equalToConstant: 320),
    bannerView.heightAnchor.constraint(equalToConstant: 100)
])

SwiftUI

represented
    .frame(width: 320, height: 100)
    .onAppear {
        represented.banner.load()
    }

모범 사례

1. 메모리 관리

뷰 컨트롤러가 해제될 때 destroy()를 호출하여 배너 리소스를 정리하세요.

deinit {
    banner?.destroy()
    banner = nil
}

2. 화면 가시성

배너가 화면에 보일 때 광고를 로드하세요.

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    banner?.load()
}

3. 배너 인스턴스 재사용

AdropBanner 인스턴스는 하나만 유지하고 새 광고가 필요할 때마다 load()를 다시 호출하세요. 광고 갱신마다 새 AdropBanner를 생성하지 마세요. 배너를 매번 다시 만들면 요청마다 새 WKWebView와 WebContent 프로세스가 할당됩니다. 특히 비디오 배너에서 잦은 갱신이 반복되면 리소스가 누적되어 렌더링 성능에 영향을 줄 수 있습니다.

class ViewController: UIViewController {
    private var banner: AdropBanner?

    override func viewDidLoad() {
        super.viewDidLoad()
        banner = AdropBanner(unitId: "YOUR_UNIT_ID")
        banner?.delegate = self
        // 뷰 계층에 추가...
        banner?.load()
    }

    func refreshAd() {
        // 기존 인스턴스를 재사용
        banner?.load()
    }
}

func refreshAd() {
    // 광고 갱신마다 새 AdropBanner를 생성하지 마세요
    banner?.destroy()
    banner = AdropBanner(unitId: "YOUR_UNIT_ID")
    banner?.delegate = self
    // ...뷰 계층에 다시 추가
    banner?.load()
}

load()를 다시 호출할 때마다 onAdReceived가 다시 호출되므로, 기존 delegate가 새 광고를 자동으로 처리합니다.

4. 에러 처리

광고 로드 실패 시 적절한 에러 처리를 구현하세요.

func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
    switch errorCode {
    case .ERROR_CODE_NETWORK:
        print("네트워크 오류: 연결을 확인하세요")
    case .ERROR_CODE_AD_NO_FILL:
        print("노출 가능한 광고 없음")
    default:
        print("광고 로드 실패: \(errorCode)")
    }

    // 대체 콘텐츠 표시 또는 광고 영역 숨김
    bannerContainerView.isHidden = true

    // 또는 자체 프로모션 배너 표시
    showPromotionBanner()
}

테스트 유닛 ID

개발 및 테스트 시 아래의 테스트 유닛 ID를 사용하세요.

광고 유형	테스트 유닛 ID	크기
배너 (320x50)	`PUBLIC_TEST_UNIT_ID_320_50`	320 x 50
배너 (320x100)	`PUBLIC_TEST_UNIT_ID_320_100`	320 x 100
캐러셀 배너	`PUBLIC_TEST_UNIT_ID_CAROUSEL`	가변
배너 비디오 (16:9)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_16_9`	16:9 비율
배너 비디오 (9:16)	`PUBLIC_TEST_UNIT_ID_BANNER_VIDEO_9_16`	9:16 비율

사용 예시

let banner = AdropBanner(unitId: AdropUnitId.PUBLIC_TEST_UNIT_ID_320_100)

AdropBanner *banner = [[AdropBanner alloc] initWithUnitId:PUBLIC_TEST_UNIT_ID_320_100];

동영상 재생 제어

동영상 배너 광고의 경우, play()와 pause()를 사용하여 비디오 재생을 수동으로 제어할 수 있습니다.

play()

동영상 재생을 재개합니다. 팝업이 닫히거나 앱이 백그라운드에서 복귀해 배너가 다시 노출될 때 호출하세요.

banner?.play()

[self.banner play];

pause()

동영상 재생을 일시 정지합니다. 배너가 팝업에 가려지거나 앱이 백그라운드로 진입할 때 호출하세요.

banner?.pause()

[self.banner pause];

예시: 백그라운드/포그라운드 처리

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    banner?.play()
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    banner?.pause()
}

play()와 pause()는 동영상 배너 광고에만 영향을 미칩니다. 이미지 배너에는 효과가 없습니다.

커스텀 클릭 처리

useCustomClick을 사용하여 광고 클릭 동작을 직접 제어할 수 있습니다. 활성화하면 SDK가 클릭 시 자동으로 목적지 URL을 열지 않으며, 직접 처리할 수 있습니다.

useCustomClick

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")
banner.useCustomClick = true
banner.delegate = self
banner.load()

useCustomClick이 true이면 광고 클릭 시 SDK가 자동으로 목적지 URL을 열지 않습니다. onAdClicked delegate 콜백은 계속 호출되며, open() 메서드를 사용하거나 직접 네비게이션을 처리할 수 있습니다.

open()

광고의 목적지 URL을 엽니다. 선택적으로 커스텀 URL을 전달할 수 있습니다.

// 광고의 기본 목적지 URL 열기
banner?.open()

// 커스텀 URL 열기
banner?.open("https://example.com")

// 인앱 브라우저로 열기
banner?.open(nil, useInAppBrowser: true)

일괄 로드 (loads)

AdropBanner.loads(...)를 사용하면 한 번의 호출로 여러 배너 광고를 요청할 수 있습니다. 캐러셀, 페이지네이션 피드, 광고 풀 프리페칭 등에 유용합니다.

시그니처

AdropBanner.loads(
    unitId: String,
    contextId: String = "",
    delegate: AdropBannerDelegate
)

[AdropBanner loadsWithUnitId:@"YOUR_UNIT_ID"
                   contextId:@""
                    delegate:delegate];

사용 방법

class ViewController: UIViewController {
    private var banners: [AdropBanner] = []

    override func viewDidLoad() {
        super.viewDidLoad()
        AdropBanner.loads(unitId: "YOUR_UNIT_ID", delegate: self)
    }
}

extension ViewController: AdropBannerDelegate {
    // 단건 콜백 — 배치 경로에서는 사용되지 않습니다.
    func onAdReceived(_ banner: AdropBanner) { /* batch path */ }
    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {}

    // 배치 성공 — 최대 5개의 준비된 배너가 전달됩니다.
    func onAdsReceived(_ banners: [AdropBanner]) {
        self.banners = banners
        banners.forEach { banner in
            // 뷰 계층에 추가 (UIScrollView, UIPageViewController 등)
            stackView.addArrangedSubview(banner)
        }
    }

    // 배치 실패
    func onAdsFailedToReceive(_ errorCode: AdropErrorCode) {
        print("배치 로드 실패: \(errorCode)")
    }

    // 클릭/노출/비디오 콜백은 각 인스턴스에 대해 정상 호출됩니다.
    func onAdClicked(_ banner: AdropBanner) {
        print("배너 클릭")
    }

    func onAdImpression(_ banner: AdropBanner) {
        print("배너 노출")
    }
}

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) NSArray<AdropBanner *> *banners;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [AdropBanner loadsWithUnitId:@"YOUR_UNIT_ID" contextId:@"" delegate:self];
}

#pragma mark - AdropBannerDelegate

- (void)onAdReceived:(AdropBanner *)banner { /* batch path */ }
- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {}

- (void)onAdsReceived:(NSArray<AdropBanner *> *)banners {
    self.banners = banners;
    for (AdropBanner *banner in banners) {
        [self.stackView addArrangedSubview:banner];
    }
}

- (void)onAdsFailedToReceive:(AdropErrorCode)errorCode {
    NSLog(@"배치 로드 실패: %ld", (long)errorCode);
}

- (void)onAdClicked:(AdropBanner *)banner {
    NSLog(@"배너 클릭");
}

- (void)onAdImpression:(AdropBanner *)banner {
    NSLog(@"배너 노출");
}

@end

델리게이트 메서드

메서드	호출 시점
`onAdsReceived(_:)`	배치 전달 완료. 각 `AdropBanner`에는 델리게이트가 이미 부착되어 있고 광고 데이터가 적용된 상태입니다.
`onAdsFailedToReceive(_:)`	요청 거부, 네트워크 실패 또는 표시 가능한 광고가 없는 경우(`ERROR_CODE_AD_NO_FILL`).
`onAdClicked` / `onAdImpression` / `onAdVideoStart` / `onAdVideoEnd`	단건 `load()`와 동일하게 각 배너별로 호출됩니다.

단건 onAdReceived(_:) / onAdFailedToReceive(_:_:) 콜백은 loads 경로에서 호출되지 않습니다. 배치 결과는 반드시 onAdsReceived(_:) / onAdsFailedToReceive(_:)로만 수신하세요.

상수

Int

기본값:"5"

단일 loads(...) 호출에서 반환되는 광고의 최대 개수.

제약 사항

호출당 최대 5개. 서버가 그 이상을 반환하더라도 앞의 5개만 전달됩니다.
백필은 적용되지 않습니다. 직광고 채움이 없으면 백필 설정과 무관하게 onAdsFailedToReceive가 ERROR_CODE_AD_NO_FILL로 호출됩니다.
onAdsReceived 안에서 destroy()를 호출하지 마세요. 먼저 각 배너를 뷰 계층에 부착하고, 뷰 컨트롤러가 해제되는 시점에 destroy()를 호출하세요.
onAdsReceived는 광고 데이터가 적용되는 즉시 발화되며, 이는 단건 load() 동작과 동일합니다 — 뷰에 부착된 뒤 크리에이티브가 그려집니다.
반환된 배너에 대해 강한 참조를 유지하세요 (예: 뷰 컨트롤러에 저장). 뷰 계층에 부착되기 전에 해제되면 조용히 드롭됩니다.

백필 광고

백필 광고가 활성화된 경우, 직광고가 없을 때 자동으로 백필 광고가 로드됩니다. isBackfilled 프로퍼티로 백필 광고 여부를 확인할 수 있습니다.

class ViewController: UIViewController, AdropBannerDelegate {
    private var banner: AdropBanner?

    func onAdReceived(_ banner: AdropBanner) {
        if banner.isBackfilled {
            print("백필 광고가 로드되었습니다")
        } else {
            print("직광고가 로드되었습니다")
        }
    }

    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {
        switch errorCode {
        case .ERROR_CODE_AD_NO_FILL:
            print("직광고 없음, 백필 광고 요청 중...")
        case .ERROR_CODE_AD_BACKFILL_NO_FILL:
            print("백필 광고도 없습니다")
            // 광고 영역 숨김 처리
            banner.isHidden = true
        default:
            print("광고 로드 실패: \(errorCode)")
        }
    }
}

@interface ViewController () <AdropBannerDelegate>
@property (nonatomic, strong) AdropBanner *banner;
@end

@implementation ViewController

- (void)onAdReceived:(AdropBanner *)banner {
    if (banner.isBackfilled) {
        NSLog(@"백필 광고가 로드되었습니다");
    } else {
        NSLog(@"직광고가 로드되었습니다");
    }
}

- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {
    if (errorCode == AdropErrorCodeAdNoFill) {
        NSLog(@"직광고 없음, 백필 광고 요청 중...");
    } else if (errorCode == AdropErrorCodeBackfillNoFill) {
        NSLog(@"백필 광고도 없습니다");
        // 광고 영역 숨김 처리
        banner.hidden = YES;
    } else {
        NSLog(@"광고 로드 실패: %ld", (long)errorCode);
    }
}

@end

백필 광고를 사용하려면 AdropAds-Backfill 의존성을 추가해야 합니다. 시작하기를 참고하세요.

백필 광고 미리 로드 (preload)

SDK 1.17.0부터 AdropBanner.preload()로 백필 배너 광고를 미리 받아 둘 수 있습니다. 같은 유닛 ID와 같은 크기로 load()한 배너가 직광고 없이 백필 광고로 넘어가면, 백필 광고를 다시 요청하지 않고 미리 받아 둔 광고를 바로 표시합니다. load()는 preload와 관계없이 직광고를 먼저 요청합니다. 직광고가 표시되면 미리 받아 둔 광고는 그대로 남습니다. preload를 호출하지 않으면 동작은 이전과 같습니다.

동작 조건

adrop-ads와 adrop-ads-backfill이 모두 1.17.0 이상이어야 합니다.
서버가 앱에 지금 노출할 직광고가 없다고 알려 준 상태에서만 백필 광고를 받습니다. 그 밖에는 백필 광고를 요청하지 않고 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다. 직광고 캠페인이 있는 앱에서는 정상적인 결과입니다.
앱 설치 직후, 앱 키를 바꾼 직후, setUID로 다른 사용자로 바꾼 직후에는 서버 응답을 받기 전까지 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다.
테스트 유닛 ID로는 항상 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다.

사용 방법

배너가 있는 화면을 띄우기 직전에 호출하세요. 미리 받은 광고는 쓰이지 않으면 30분 뒤 폐기되므로 곧 표시할 배너에만 호출하세요. 결과를 기다렸다가 load()할 필요는 없습니다. 아직 받는 중이면 load()가 그 결과를 기다려 사용합니다. delegate는 약한 참조로 보관됩니다. 결과 콜백을 받으려면 결과가 올 때까지 delegate 객체를 유지하세요.

import UIKit
import AdropAds

final class HomeViewController: UIViewController, AdropBannerDelegate {
    // 배너가 있는 화면을 띄우기 직전에 호출합니다.
    func preloadFeedBanner() {
        AdropBanner.preload(
            unitId: "YOUR_UNIT_ID",
            adSize: CGSize(width: 320, height: 50), // 생략하면 320x50
            delegate: self
        )
    }

    func onAdPreloadReceived(_ unitId: String, _ contextId: String) {
        print("미리 로드 완료: \(unitId)")
    }

    func onAdPreloadFailedToReceive(_ unitId: String, _ contextId: String, _ errorCode: AdropErrorCode) {
        // ERROR_CODE_AD_PRELOAD_SKIPPED는 정상 결과입니다.
        // 여기서 preload를 바로 다시 호출하지 마세요.
        print("미리 로드 안 됨: \(errorCode.rawValue)")
    }

    // preload에서는 호출되지 않습니다.
    func onAdReceived(_ banner: AdropBanner) {}
    func onAdFailedToReceive(_ banner: AdropBanner, _ errorCode: AdropErrorCode) {}
}

@import AdropAds;

@interface HomeViewController () <AdropBannerDelegate>
@end

@implementation HomeViewController

// 배너가 있는 화면을 띄우기 직전에 호출합니다.
- (void)preloadFeedBanner {
    [AdropBanner preloadWithUnitId:@"YOUR_UNIT_ID"
                         contextId:@""
                            adSize:CGSizeMake(320, 50)
                          delegate:self];
}

- (void)onAdPreloadReceived:(NSString *)unitId :(NSString *)contextId {
    NSLog(@"미리 로드 완료: %@", unitId);
}

- (void)onAdPreloadFailedToReceive:(NSString *)unitId :(NSString *)contextId :(AdropErrorCode)errorCode {
    // AdropErrorCodeERROR_CODE_AD_PRELOAD_SKIPPED는 정상 결과입니다.
    // 여기서 preload를 바로 다시 호출하지 마세요.
    NSLog(@"미리 로드 안 됨: %ld", (long)errorCode);
}

// preload에서는 호출되지 않습니다.
- (void)onAdReceived:(AdropBanner *)banner {}
- (void)onAdFailedToReceive:(AdropBanner *)banner :(AdropErrorCode)errorCode {}

@end

미리 받아 둔 광고를 쓰려면 load()를 호출하기 전에 배너의 frame 크기를 preload에 넘긴 adSize와 같게 맞추세요.

let banner = AdropBanner(unitId: "YOUR_UNIT_ID")
banner.frame = CGRect(x: 0, y: 0, width: 320, height: 50) // preload에 넘긴 크기
banner.delegate = self
view.addSubview(banner)
banner.load()

AdropBanner *banner = [[AdropBanner alloc] initWithUnitId:@"YOUR_UNIT_ID" contextId:@""];
banner.frame = CGRectMake(0, 0, 320, 50); // preload에 넘긴 크기
banner.delegate = self;
[self.view addSubview:banner];
[banner load];

미리 받은 광고가 쓰이는 조건

같은 유닛 ID와 같은 크기: load()할 때 배너의 frame 크기가 preload에 넘긴 adSize와 같아야 합니다. Auto Layout으로만 크기를 정하면 load() 시점에 크기가 아직 정해지지 않았을 수 있습니다. 크기가 다르면 미리 받은 광고는 그대로 남고, load()는 평소처럼 백필 광고를 요청합니다.
화면과 무관: preload는 뷰 컨트롤러를 받지 않습니다. 다른 화면에서 미리 받은 광고도 load()한 배너에 쓰입니다.
한 번만 사용: 미리 받은 광고는 load() 한 번에 쓰이면 없어집니다. 다시 미리 받으려면 preload를 다시 호출하세요.
유효 시간과 개수: 30분 안에 쓰이지 않은 광고는 폐기됩니다. 같은 유닛·크기에는 1개만 보관하고, 배너는 서로 다른 유닛·크기 조합을 최대 5개까지 보관합니다. 5개를 넘으면 가장 먼저 받은 광고부터 폐기합니다.
다시 호출할 때: 같은 유닛·크기로 다시 호출해도 새로 요청하지 않습니다. 받아 둔 광고가 있으면 새 요청 없이 onAdPreloadReceived가 호출되고, 받는 중이면 그 로드의 결과(성공 또는 실패)가 똑같이 전달됩니다. 광고를 새로 고치는 용도로는 쓸 수 없습니다. 단, 그 사이 사용자 동의 상태가 바뀌었으면 기존 광고를 버리고 새로 받습니다.
동의 상태 변경: 미리 받은 뒤 사용자 동의 상태가 바뀌면 그 광고는 load()에 쓰이지 않습니다.

결과 콜백

AdropBannerDelegate에 다음 선택 메서드가 추가되었습니다. preload를 호출할 때마다 둘 중 하나가 한 번 메인 스레드에서 호출됩니다. preload에서는 다른 delegate 메서드가 호출되지 않습니다.

메서드	호출 시점
`onAdPreloadReceived(_:_:)`	미리 받기가 끝났을 때. 그 결과를 기다리던 `load()`가 이미 사용했을 수도 있습니다.
`onAdPreloadFailedToReceive(_:_:_:)`	미리 받지 못했을 때

두 번째 인자 contextId는 preload에 넘긴 값을 그대로 돌려줍니다(기본값: 빈 문자열). 미리 받은 광고를 고르는 데는 쓰이지 않습니다.

실패 코드

에러 코드	설명
`ERROR_CODE_AD_PRELOAD_SKIPPED`	직광고가 노출될 수 있거나 아직 확인되지 않아 백필 광고를 요청하지 않았습니다. 정상 결과이므로 다음 화면을 띄우기 직전에 다시 호출하세요.
`ERROR_CODE_AD_NO_FILL`	1.17.0 이상의 백필 의존성이 없거나, 기기가 `Adrop.initialize()`의 대상 국가에 속하지 않거나, 유닛에 백필이 설정되지 않았거나 SDK가 그 설정을 아직 받지 못했습니다. 잠시 뒤 다시 호출하세요. 백필 의존성이 없거나 대상 국가가 아니면 계속 이 코드로 끝납니다.
`ERROR_CODE_AD_BACKFILL_NO_FILL`	백필 광고가 없습니다.
`ERROR_CODE_INITIALIZE`	SDK가 초기화되지 않았습니다.
`ERROR_CODE_INVALID_UNIT`	유닛 ID가 비어 있습니다.

실패 콜백 안에서 preload를 바로 다시 호출하지 마세요. 백필 의존성이 없을 때처럼 결과가 바뀌지 않으면 호출이 끝없이 반복됩니다. 다음 화면을 띄우기 전처럼 나중에 다시 호출하세요.

다음 단계

네이티브 광고

UI에 맞게 커스터마이징 가능한 네이티브 광고 구현하기

전면 광고

화면 전체를 덮는 전면 광고 구현하기

타겟팅 설정

사용자 속성 및 문맥 타겟팅 설정하기

레퍼런스

클래스, Delegate, 에러 코드 참고하기