배너 및 전면 광고에 대한 맞춤 이벤트

이 가이드는 AdMob 미디에이션에서 배너 및 전면 광고 맞춤 이벤트에 대한 지원을 추가하려는 게시자를 대상으로 작성되었습니다.

맞춤 이벤트를 사용하면 광고 공간에 원하는 보기를 넣을 수 있습니다. 맞춤 이벤트를 통해 미디에이션으로 직접 지원되지 않는 광고 네트워크로 수익을 창출할 수도 있습니다. 맞춤 이벤트는 GADCustomEventBanner 또는 GADCustomEventInterstitial 프로토콜을 통해 구현됩니다.

기본 요건

배너 또는 전면 광고에 맞춤 이벤트를 통합하려면 먼저 해당 광고 형식을 앱에 통합해야 합니다. 다음은 관련 가이드입니다.

샘플 광고 네트워크

이 가이드에는 SampleCustomEventBannerSampleCustomEventInterstital 맞춤 이벤트 클래스를 사용하여 샘플 광고 네트워크에서 배너 및 전면 광고를 게재하는 방법이 나와 있습니다. 샘플 광고 네트워크 SDK는 맞춤 이벤트의 실제 구현을 보여주기 위해 개발된 모의 SDK입니다. 이 SDK에는 대부분의 광고 네트워크가 제공하는 클래스가 포함되어 있습니다. 이러한 클래스에 대해 자세히 알아보려면 전체 샘플 SDK 구현을 참고하세요.

다음 예시에서는 먼저 AdMob 미디에이션 내에서 배너 맞춤 이벤트를 만듭니다. 이 배너 맞춤 이벤트를 만들려면 AdMob UI를 통해 애플리케이션에서 해당 특정 클래스를 가리키는 맞춤 이벤트를 정의한 다음 배너 맞춤 이벤트를 구현하여 보기를 반환해야 합니다.

맞춤 이벤트 정의

맞춤 이벤트는 AdMob UI에서 정의해야 합니다. 맞춤 이벤트 만들기에 UI 탐색 방법이 나와 있습니다.

다음은 샘플 맞춤 이벤트 설정을 보여주는 스크린샷입니다.

이러한 매개변수를 채우는 방법을 알아보려면 다음 표를 참조하세요.

클래스 이름

맞춤 이벤트를 구현하는 클래스의 정규화된 이름을 입력합니다.

클래스가 Swift로 구현된 경우 클래스 이름 앞에 앱/프레임워크 모듈의 이름을 추가해야 합니다(예: appName.className).

프로젝트에 대상이 여러 개 있거나 프로젝트 이름이 대상 이름과 다른 경우 대상 이름이 필요합니다. 타겟 이름은 appName_targetName.className과 같은 형식으로 구성해야 합니다. 또한 대시와 같이 영숫자 문자가 아닌 문자는 밑줄로 바꿔야 합니다.

자세한 내용은 예시를 참고하세요.

라벨 이벤트의 고유 이름을 입력합니다.
매개변수 맞춤 이벤트에 인수를 전달하려면 적절한 문자열을 입력하세요.

배너 요청

맞춤 이벤트 배너 요청의 경우 맞춤 이벤트 클래스가 인스턴스화된 직후에 requestBannerAd:parameter:label:request: 메서드가 호출됩니다. 이 메서드에서는 반환되는 값이 없습니다. 맞춤 이벤트가 네트워크를 통해 비동기 광고를 가져오는 것으로 가정합니다. 맞춤 이벤트는 콜백 수신을 위해 SDK의 대리자 역할을 합니다.

SDK가 지정된 광고 크기를 지원하지 않거나 배너 광고를 지원하지 않는 경우 맞춤 이벤트 대리자의 customEventBanner:didFailAd: 메서드를 호출합니다. serverParameterserverLabel 매개변수는 AdMob UI에서 맞춤 이벤트를 만들 때 정의한 매개변수 및 라벨 필드에 해당합니다.

다음은 샘플 광고 네트워크를 사용한 requestBannerAd:parameter:label:request: 구현의 예시입니다.

Swift

func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  // Create a banner view with the appropriate size.
  bannerAd = SampleBanner(frame: CGRectMake(
      0, 0, adSize.size.width, adSize.size.height))
  bannerAd.delegate = self
  bannerAd.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  bannerAd.fetchAd(adRequest)
}

Objective-C

- (void)requestBannerAd:(GADAdSize)adSize
              parameter:(NSString *)serverParameter
                  label:(NSString *)serverLabel
                request:(GADCustomEventRequest *)request {
  // Create the bannerView with the appropriate size.
  self.bannerAd =
      [[SampleBanner alloc] initWithFrame:CGRectMake(0,
                                                     0,
                                                     adSize.size.width,
                                                     adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.bannerAd fetchAd:adRequest];
}

맞춤 이벤트 요청을 위한 광고 네트워크 추가 전송

처리할 맞춤 이벤트 요청과 함께 광고 네트워크 추가를 보내려면 GADRequest registerAdNetworkExtras: 함수를 사용하세요. GADCustomEventRequest.additionalParameters 속성을 채우려면 GADAdNetworkExtras 프로토콜을 준수하는 GADCustomEventExtras 인스턴스를 만들어야 합니다. 네트워크 추가를 전달하려면 GADCustomEventExtras setExtras:forLabel:을 호출하여 AdMob UI에서 정의한 맞춤 이벤트의 라벨과 사전으로 네트워크 추가를 전달하세요.

다음은 앞에서 정의한 SampleCustomEvent 라벨의 SampleExtra 매개변수를 전달하는 방법을 보여주는 코드 스니펫입니다.

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

맞춤 이벤트 요청에 GADCustomEventExtras의 인스턴스를 등록하지 않은 경우 GADCustomEventRequestadditionalParameters 속성은 nil이 됩니다.

AdMob 미디에이션 알림

네트워크의 광고 리스너를 구현하고 맞춤 이벤트의 대리자에서 관련 콜백을 호출하여 미디에이션 모듈에 다시 메시지를 전송합니다. 다음 예시에서는 샘플 광고 네트워크의 SampleBannerAdDelegate 인터페이스를 구현하여 이러한 메시지를 전송합니다.

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when banner ad has loaded.
func bannerDidLoad(banner: SampleBanner!) {
  delegate.customEventBanner(self, didReceiveAd: banner)
}

// Sent when banner has failed to load.
func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
      code: error.rawValue, userInfo: nil)
  delegate.customEventBanner(self, didFailAd: nsError)
}

// Sent when a banner is clicked and an external application is launched
func bannerWillLeaveApplication(banner: SampleBanner!) {
  delegate.customEventBannerWasClicked(self)
  delegate.customEventBannerWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when banner ad has loaded.
- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.delegate customEventBanner:self didReceiveAd:banner];
}

// Sent when banner has failed to load.
- (void)banner:(SampleBanner *)banner
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventBanner:self didFailAd:error];
}

// Sent when a banner is clicked and an external application is launched.
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.delegate customEventBannerWasClicked:self];
  [self.delegate customEventBannerWillLeaveApplication:self];
}

AdMob 미디에이션에서는 다음과 같은 콜백을 지원합니다.

메서드 호출 시점
customEventBanner:didReceiveAd: 배너 요청에 성공한 경우
customEventBanner:didFailAd: 배너 요청에 실패한 경우
customEventBannerWillPresentModal: 배너가 전체 화면 모달 보기로 표시되는 경우
customEventBannerWillDismissModal: 배너의 전체 화면 모달 보기가 닫히는 경우
customEventBannerDidDismissModal: 배너의 전체 화면 모달 보기가 닫힌 경우
customEventBannerWillLeaveApplication: 배너로 인해 사용자가 앱을 떠난 경우
customEventBannerWasClicked: 배너를 클릭한 경우

전면 광고

메서드 호출 시점
customEventInterstitial:DidReceiveAd: 전면 광고 요청에 성공한 경우
customEventInterstitial:didFailAd: 전면 광고 요청에 실패한 경우
customEventInterstitialWillPresent: 전면 광고가 전체 화면 모달 보기로 표시되는 경우
customEventInterstitialWillDismiss: 전면 광고의 전체 화면 모달 보기가 닫히는 경우
customEventInterstitialDidDismiss: 전면 광고의 전체 화면 모달 보기가 닫힌 경우
customEventInterstitialWillLeaveApplication: 전면 광고로 인해 사용자가 앱을 떠난 경우
customEventInterstitialWasClicked: 전면 광고를 클릭한 경우

자세한 내용은 맞춤 이벤트 배너의 샘플 구현을 참고하세요.

전면 광고 맞춤 이벤트

전면 광고 맞춤 이벤트 구현은 배너 맞춤 이벤트 구현과 유사합니다. 가장 큰 차이점은 전면 광고 맞춤 이벤트 클래스는 GADCustomEventBanner 프로토콜 대신 GADCustomEventInterstitial 프로토콜을 구현해야 한다는 점입니다.

맞춤 이벤트 정의

맞춤 이벤트는 AdMob UI에서 정의해야 합니다. 맞춤 이벤트 만들기에 UI 탐색 방법이 나와 있습니다.

다음은 샘플 맞춤 이벤트 설정을 보여주는 스크린샷입니다.

이러한 매개변수를 채우는 방법을 알아보려면 다음 표를 참조하세요.

클래스 이름

맞춤 이벤트를 구현하는 클래스의 정규화된 이름을 입력합니다.

클래스가 Swift로 구현된 경우 클래스 이름 앞에 앱/프레임워크 모듈의 이름을 추가해야 합니다(예: appName.className).

프로젝트에 대상이 여러 개 있거나 프로젝트 이름이 대상 이름과 다른 경우 대상 이름이 필요합니다. 타겟 이름은 appName_targetName.className과 같은 형식으로 구성해야 합니다. 또한 대시와 같이 영숫자 문자가 아닌 문자는 밑줄로 바꿔야 합니다.

자세한 내용은 예시를 참고하세요.

라벨 이벤트의 고유 이름을 입력합니다.
매개변수 맞춤 이벤트에 인수를 전달하려면 적절한 문자열을 입력하세요.

전면 광고 요청

맞춤 이벤트 전면 광고 요청의 경우 맞춤 이벤트 클래스가 인스턴스화된 직후에 requestInterstitialAdWithParameter:label:request: 메서드가 호출됩니다. 이 메서드에서는 반환되는 값이 없습니다. 맞춤 이벤트가 네트워크를 통해 비동기 광고를 가져오는 것으로 가정합니다.

맞춤 이벤트는 콜백 수신을 위해 SDK의 대리자 역할을 합니다. serverParameterserverLabel 매개변수는 AdMob UI에서 맞춤 이벤트를 만들 때 정의한 매개변수 및 라벨 필드에 해당합니다.

다음은 샘플 광고 네트워크를 사용한 requestInterstitialAdWithParameter:label:request: 구현의 예시입니다.

Swift

func requestInterstitialAdWithParameter(serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  interstitial = SampleInterstitial()
  interstitial.delegate = self
  interstitial.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  interstitial.fetchAd(adRequest)
}

Objective-C

- (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                     label:(NSString *)serverLabel
                                   request:(GADCustomEventRequest *)request {
  self.interstitial = [[SampleInterstitial alloc] init];
  self.interstitial.delegate = self;
  self.interstitial.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.interstitial fetchAd:adRequest];
}

GADCustomEventInterstitial 맞춤 이벤트 프로토콜에서는 presentFromRootViewController: 메서드를 구현해야 합니다. 다음과 같이 모바일 광고 SDK에 전면 광고를 표시하도록 지시하면 미디에이션에서 이 메서드를 호출합니다.

Swift

func presentFromRootViewController(rootViewController: UIViewController!) {
  if interstitial.interstitialLoaded {
    interstitial.show()
  }
}

Objective-C

- (void)presentFromRootViewController:(UIViewController *)rootViewController {
  if ([self.interstitial isInterstitialLoaded]) {
    [self.interstitial show];
  }
}

맞춤 이벤트 요청을 위한 광고 네트워크 추가 전송

처리할 맞춤 이벤트 요청과 함께 광고 네트워크 추가를 보내려면 GADRequest registerAdNetworkExtras: 함수를 사용하세요. GADCustomEventRequest.additionalParameters 속성을 채우려면 GADAdNetworkExtras 프로토콜을 준수하는 GADCustomEventExtras 인스턴스를 만들어야 합니다. 네트워크 추가를 전달하려면 GADCustomEventExtras setExtras:forLabel:을 호출하여 AdMob UI에서 정의한 맞춤 이벤트의 라벨과 사전으로 네트워크 추가를 전달하세요.

다음은 앞에서 정의한 SampleCustomEvent 라벨의 SampleExtra 매개변수를 전달하는 방법을 보여주는 코드 스니펫입니다.

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

맞춤 이벤트 요청에 GADCustomEventExtras의 인스턴스를 등록하지 않은 경우 GADCustomEventRequestadditionalParameters 속성은 nil이 됩니다.

AdMob 미디에이션 알림

배너 맞춤 이벤트와 마찬가지로 네트워크의 광고 리스너를 구현하여 미디에이션에 메시지를 다시 전달합니다. 다음은 샘플 광고 네트워크의 SampleInterstitialAdDelegate 인터페이스 구현을 보여주는 예시입니다.

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when an interstitial ad has loaded.
func interstitialDidLoad(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidReceiveAd(self)
}

// Sent when interstitial ad has failed to load.
func interstitial(interstitial: SampleInterstitial!,
    didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
      code: errorCode.rawValue, userInfo: nil)
  delegate.customEventInterstitial(self, didFailAd: nsError)
}

// Sent when an interstitial is about to be shown.
func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillPresent(self)
}

// Sent when an interstitial is about to be dismissed.
func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillDismiss(self)
}

// Sent when an interstitial has been dismissed.
func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidDismiss(self)
}

// Sent when an interstitial is clicked and an external application is launched.
func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWasClicked(self)
  delegate.customEventInterstitialWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when an interstitial ad has loaded.
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidReceiveAd:self];
}

// Sent when an interstitial ad has failed to load.
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventInterstitial:self didFailAd:error];
}

// Sent when an interstitial is about to be shown.
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillPresent:self];
}

// Sent when an interstitial is about to be dismissed.
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillDismiss:self];
}

// Sent when an interstitial has been dismissed.
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidDismiss:self];
}

// Sent when an interstitial is clicked and an external application is launched.
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWasClicked:self];
  [self.delegate customEventInterstitialWillLeaveApplication:self];
}

미디에이션 모듈에 다시 메시지를 전송하면 미디에이션이 다음 단계로 진행됩니다.

자세한 내용은 전면 광고 맞춤 이벤트의 샘플 구현을 참고하세요.