배너 광고 - 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?.removeFromSuperview()
        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 초기화

unitId

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: "article_123")

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: "article_123"
)
.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 removeFromSuperview];
    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:@"article_123"];

Delegate 메서드

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

onAdReceived (필수)

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

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

onAdFailedToReceive (필수)

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

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

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와 클로저를 동시에 설정하면 두 가지 모두 호출됩니다.

광고 크기

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

일반적인 배너 크기

크기	용도
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. 메모리 관리

뷰 컨트롤러가 해제될 때 배너를 함께 제거하세요.

deinit {
    banner?.removeFromSuperview()
    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?.removeFromSuperview()
    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(_:)로만 수신하세요.

상수

AdropBanner.maxLoadsBatch

Int

기본값:"5"

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

제약 사항

호출당 최대 5개. 서버가 그 이상을 반환하더라도 앞의 5개만 전달됩니다.
백필은 적용되지 않습니다. 직광고 채움이 없으면 백필 설정과 무관하게 onAdsFailedToReceive가 ERROR_CODE_AD_NO_FILL로 호출됩니다.
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 의존성을 추가해야 합니다. 시작하기를 참고하세요.

다음 단계

네이티브 광고

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

전면 광고

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

타겟팅 설정

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

레퍼런스

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

​개요

​주요 특징

​UIKit 구현

​기본 구현

​AdropBanner 초기화

​광고 로드

​Context ID 설정

​SwiftUI 구현

​기본 구현

​Delegate 처리

​Context ID 설정

​Objective-C 구현

​기본 구현

​Context ID 설정

​Delegate 메서드

​onAdReceived (필수)

​onAdFailedToReceive (필수)

​onAdImpression (선택)

​onAdClicked (선택)

​onAdVideoStart (선택)

​onAdVideoEnd (선택)

​클로저 콜백

​광고 크기

​일반적인 배너 크기

​UIKit

​SwiftUI

​모범 사례

​1. 메모리 관리

​2. 화면 가시성

​3. 배너 인스턴스 재사용

​4. 에러 처리

​테스트 유닛 ID

​사용 예시

​동영상 재생 제어

​play()

​pause()

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

​커스텀 클릭 처리

​useCustomClick

​open()

​일괄 로드 (loads)

​시그니처

​사용 방법

​델리게이트 메서드

​상수

​제약 사항

​백필 광고

​다음 단계

네이티브 광고

전면 광고

타겟팅 설정

레퍼런스

개요

주요 특징

UIKit 구현

기본 구현

AdropBanner 초기화

광고 로드

Context ID 설정

SwiftUI 구현

기본 구현

Delegate 처리

Context ID 설정

Objective-C 구현

기본 구현

Context ID 설정

Delegate 메서드

onAdReceived (필수)

onAdFailedToReceive (필수)

onAdImpression (선택)

onAdClicked (선택)

onAdVideoStart (선택)

onAdVideoEnd (선택)

클로저 콜백

광고 크기

일반적인 배너 크기

UIKit

SwiftUI

모범 사례

1. 메모리 관리

2. 화면 가시성

3. 배너 인스턴스 재사용

4. 에러 처리

테스트 유닛 ID

사용 예시

동영상 재생 제어

play()

pause()

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

커스텀 클릭 처리

useCustomClick

open()

일괄 로드 (loads)

시그니처

사용 방법

델리게이트 메서드

상수

제약 사항

백필 광고

다음 단계