카드 배너 광고

아래 가이드에서는 카드 배너 광고를 로드하고, 표시하는 방법을 설명합니다.

기본 요건

시작 가이드에 따라 필요한 과정을 완료합니다.

---

테스트 광고 게재위치

Placement Code(게재위치 코드)는 어드민의 인벤토리 > 게재위치 메뉴에서 게재위치를 등록 시 시스템을 통해 자동으로 생성됩니다.

테스트 게재위치 목록

placementCode	설명
SAMPLE_MUTIPLE_IMAGE_BANNER_CARD_APP	카드형 배너 광고 자동 스크롤 지원 복수 광고 캐러셀 형태

어드민의 인벤토리 > 광고상품 > 광고상품 등록 메뉴에서 카드 배너 광고의 소재 스펙 및 기본 레이아웃을 설정할 수 있습니다.

---

광고 표시하기

1. 카드 배너 광고를 표시할 ViewController에서 NestAdsCardBannerAdView를 설정하고 로드합니다.

Swift

var cardBannerView: NestAdsCardBannerAdView?

// CardBannerAdView는 superview 중앙에 자동 배치되므로, 
// containerView로 감싸서 위치와 크기를 제어합니다.

// MARK: - ScrollView
let scrollView = UIScrollView()
let stackView = UIStackView()
let containerView = UIView()

// MARK: - CollectionView
// var collectionView: UICollectionView!
// var collectionViewContainerView = UIView()

// MARK: - TableView
// let tableView = UITableView()
// var tableViewContainerView = UIView()

override func viewDidLoad() {
  super.viewDidLoad()

  // 상위 뷰 세팅(스크롤뷰 / 컬렉션뷰 / 테이블뷰)
  setupScrollView()
  // setupCollectionView()
  // setupTableView()

  // 초기화 (size: 광고 사이즈, rootViewController: 현재 ViewController)
  let adSize = NestAdsAdSizeFluid
  cardBannerView = NestAdsCardBannerAdView(size: adSize, rootViewController: self)

  // (선택) 옵션 적용
  // 복수 광고 옵션
  // 복수 개의 광고를 요청하는 경우 해당 옵션을 설정합니다. (1~99)
  cardBannerView.multipleCardBannerOptions.loadOptions = NestAdsMultipleAdLoadOptions(numberOfAds: 5)

  // 광고 표시 시간 (초, 1~30), // 전환 애니메이션 시간 (초, 0.1~1.0)
  cardBannerView.multipleCardBannerOptions.carousel = NestAdsCarouselOptions(displayDuration: 1.0, transitionDuration: 0.5)

  // 모아보기 옵션 (useCustomClickAction이 false일 때 SDK가 AdListViewController 표시)
  cardBannerView.multipleCardBannerOptions.adList.useCustomClickAction = false
  cardBannerView.multipleCardBannerOptions.adList.adListViewOptions.title = "광고 모아보기"

  // 배경 옵션
  cardBannerView.backgroundOptions = NestAdsCardBannerBackgroundOptions(backgroundColor: .white, opacity: 1.0)

  // 레이아웃 옵션
  cardBannerView.layoutOptions.cornerRadius = 8

  // 필수값 적용
  cardBannerView.placementCode = "YOUR_PLACEMENT_CODE" // 설정하지 않으면 광고 호출에 실패
  cardBannerView.delegate = self

  // 광고 로드
  cardBannerView.load(NestAdsAdRequest())
}
...
// 예) 스크롤 뷰 세팅(Collection View / Table View 등 스크롤뷰가 내장되어있는 뷰면 가능)
func setupScrollView() {
  view.addSubview(scrollView)
  scrollView.translatesAutoresizingMaskIntoConstraints = false
  NSLayoutConstraint.activate([
      scrollView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
      scrollView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
      scrollView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
      scrollView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
  ])

  // StackView를 ScrollView 안에 배치
  scrollView.addSubview(stackView)
  stackView.axis = .vertical
  stackView.spacing = 20
  stackView.translatesAutoresizingMaskIntoConstraints = false
  NSLayoutConstraint.activate([
      stackView.topAnchor.constraint(equalTo: scrollView.contentLayoutGuide.topAnchor, constant: 20),
      stackView.leadingAnchor.constraint(equalTo: scrollView.frameLayoutGuide.leadingAnchor, constant: 20),
      stackView.trailingAnchor.constraint(equalTo: scrollView.frameLayoutGuide.trailingAnchor, constant: -20),
      stackView.bottomAnchor.constraint(equalTo: scrollView.contentLayoutGuide.bottomAnchor, constant: -20)
  ])
  ...
}

// func setupCollectionView() { ... }
// func setupTableView() { ... }

1. 광고 로드 완료 후 뷰에 추가합니다.

Swift

extension MyViewController: NestAdsCardBannerAdViewDelegate {
  func cardBannerAdViewDidReceiveAd(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("DID RECEIVE")
    stackView.addArrangedSubview(containerView)

    NSLayoutConstraint.activate([
        containerView.heightAnchor.constraint(equalToConstant: 250)
    ])

    view.layoutIfNeeded() // 상위 뷰의 프레임이 잡히지 않았을 수 있기 때문에 레이아웃 갱신
    containerView.addSubview(cardBannerAdView)

    // collectionView나 tableView의 경우
    // collectionView.reloadData()
    // tableView.reloadData()
  }

  func cardBannerAdView(
    _ cardBannerAdView: NestAdsCardBannerAdView,
    didFailToReceiveAdWithError error: NestAdsAdError
  ) {
    print("광고 로드 실패: \(error.message)")
  }
}

1. 광고 제거 시 뷰에서 제거합니다.

Swift

cardBannerView?.removeFromSuperview()
cardBannerView = nil

---

광고 사이즈

사이즈 타입	설명
NestAdsAdSizeBanner	고정 사이즈 배너
NestAdsAdSizeFluidBanner	가변 사이즈 배너 (컨테이너 너비에 맞춤)

---

자동 스크롤

카드 배너는 복수의 광고가 있을 경우 자동으로 스크롤됩니다.

• 자동 스크롤 조건: 광고가 화면에 조금이라도 노출되면 동작 (0% 초과)

• 일시정지: 화면에 0% 노출 시 자동 스크롤 일시정지

• 재개: 다시 화면에 노출되면 자동 스크롤 재개

50% 가시성 기준은 노출(Impression) 로그 전송에만 적용됩니다. 자동 스크롤은 0% 가시성일 때만 일시정지됩니다.

자동 스크롤 옵션은 multipleCardBannerOptions.carousel에서 설정할 수 있습니다.

cardBannerView.multipleCardBannerOptions.carousel = NestAdsCarouselOptions(
  displayDuration: 3.0,    // 각 광고 표시 시간 (기본값: 3초, 범위: 1~30초)
  transitionDuration: 0.5  // 전환 애니메이션 시간 (기본값: 0.5초, 범위: 0.1~1.0초)
)

---

광고 delegate

NestAdsCardBannerAdView에서 지원하는 delegate는 다음과 같습니다.

Swift

extension MyViewController: NestAdsCardBannerAdViewDelegate {
  // 광고 로드 완료
  func cardBannerAdViewDidReceiveAd(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("광고 로드 완료")
  }

  // 광고 로드 실패
  func cardBannerAdView(
    _ cardBannerAdView: NestAdsCardBannerAdView,
    didFailToReceiveAdWithError error: NestAdsAdError
  ) {
    print("광고 로드 실패: \(error.message)")
  }

  // 노출 기록
  func cardBannerAdViewDidRecordImpression(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("노출 기록")
  }

  // 클릭 기록
  func cardBannerAdViewDidRecordClick(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("클릭 기록")
  }

  // 외부 화면으로 전환 직전
  func cardBannerAdViewWillPresentScreen(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("외부 화면 전환")
  }

  // 외부 화면에서 돌아오기 직전
  func cardBannerAdViewWillDismissScreen(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("외부 화면 닫힘 예정")
  }

  // 외부 화면에서 돌아온 후
  func cardBannerAdViewDidDismissScreen(_ cardBannerAdView: NestAdsCardBannerAdView) {
    print("외부 화면 닫힘")
  }

  // 모아보기 버튼 클릭 시
  func cardBannerAdViewDidTapSeeAllButton(_ cardBannerAdView: NestAdsCardBannerAdView) {
    // 광고 목록이 필요한 경우 cardBannerAdView.adInfos 사용
    print("모아보기 클릭, 광고 수: \(cardBannerAdView.adInfos.count)")
  }

  // AdListViewController 생명주기
  func cardBannerAdViewAdListViewControllerWillAppear() { }
  func cardBannerAdViewAdListViewControllerDidAppear() { }
  func cardBannerAdViewAdListViewControllerWillDisappear() { }
  func cardBannerAdViewAdListViewControllerDidDisappear() { }
}

---

Reference

• NestAdsCardBannerAdView

• NestAdsCardBannerAdViewDelegate

• NestAdsCardBannerAdViewOptions