보상형 광고 어댑터 구현

중요: 미디에이션 서비스와 함께 Google 모바일 광고 SDK를 사용하는 경우 미디에이션 서비스 약관이 적용됩니다.

미디에이션 어댑터는 Google 모바일 광고 SDK에서 메시지 및 요청을 수신하고 서드 파티 네트워크 SDK와 통신하여 이러한 요청을 처리합니다.

이 가이드는 Google 모바일 광고 미디에이션용 보상형 광고 미디에이션 어댑터를 만들려는 광고 네트워크를 대상으로 합니다. 예시를 위해 아래의 코드 스니펫에 샘플 SDK가 사용되었습니다. 이 샘플 SDK용으로 빌드된 어댑터의 전체 구현은 iOS미디에이션 프로젝트에서 확인할 수 있습니다. 이 가이드에서는 어댑터를 제작하는 방법을 설명합니다.

어댑터 클래스 이름 및 서버 매개변수 정의

AdMob 미디에이션 플랫폼을 통해 미디에이션되는 광고 네트워크는 일반적으로 게시자를 식별하기 위해 하나 이상의 식별자가 필요합니다. 이러한 식별자는 서버 매개변수로 표현되며, AdMob UI에서 미디에이션을 위해 서드 파티 광고 네트워크를 구성할 때 정의됩니다.

미디에이션 어댑터를 개발하기 전에 Google에 어댑터 클래스 이름 및 기타 필수 매개변수를 제공하여 광고 네트워크에 대한 액세스 권한을 얻어야 합니다.

GADMediationAdapter 프로토콜을 준수합니다.

첫 번째 단계는 어댑터 클래스가 GADMediationAdapter 프로토콜을 구현하도록 하는 것입니다.

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

이렇게 변경하면 클래스에서 아래에 설명된 여러 메서드를 구현할 수 있습니다.

추가 클래스 보고

서드 파티 네트워크에서 게시자가 광고 요청에 대해 추가 선택 매개변수를 전달할 수 있게 하려면 networkExtrasClass 메서드에서 extras 클래스를 반환해야 합니다. 서드 파티가 게시자가 제공한 추가 항목을 지원하지 않으면 Nil를 반환합니다.

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

버전 번호 보고

어댑터는 어댑터의 버전과 서드 파티 SDK 버전을 모두 Google 모바일 광고 SDK에 보고해야 합니다. 버전은 GADVersionNumber를 사용하여 보고됩니다.

Google의 오픈소스 및 버전이 명시된 어댑터에서는 4자리 어댑터 버전 체계를 사용하지만, GADVersionNumber 3자리만 사용합니다. 이 문제를 해결하려면 마지막 두 자리를 패치 버전에 결합하는 것이 좋습니다(아래 참고).

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

어댑터 초기화

앱에서 Google 모바일 광고 SDK를 초기화하면 AdMob UI 내의 앱용으로 구성된 모든 어댑터에서 setUpWithConfiguration:completionHandler:가 호출됩니다.

GADMediationServerConfiguration 인수는 AdMob UI 내에서 앱용으로 구성된 모든 게재위치에 대한 정보를 제공합니다. 광고 네트워크 SDK를 초기화하려면 이 정보를 사용하세요. 광고 네트워크 SDK가 초기화되면 GADMediationAdapterSetUpCompletionBlock 인수를 호출하세요. 이 블록을 사용하면 nil 또는 NSError 객체로 완료 핸들러를 호출하여 초기화 성공 또는 실패를 Google 모바일 광고 SDK에 보고할 수 있습니다.

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

보상형 광고 요청

앱에서 Google 모바일 광고 SDK를 사용하여 보상형 광고를 로드할 때 광고 네트워크가 연쇄 광고 호출 조정에 도달한 경우 어댑터에서 loadRewardedAdForAdConfiguration:completionHandler:가 호출됩니다.

GADRewardedLoadCompletionHandler를 사용하면 GADMediationRewardedAd 프로토콜을 준수하는 객체에 대한 참조를 제공하거나 nil 참조 및 NSError 객체를 제공하여 광고 로드에 실패한 경우 Google 모바일 광고 SDK에 광고 로드 성공을 보고할 수 있습니다. 로드 완료 핸들러를 호출하면 어댑터가 광고 수명 주기 동안 Google 모바일 광고 SDK에 후속 이벤트를 알리는 GADMediationRewardedAdEventDelegate를 반환하게 됩니다.

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

광고 로드 이벤트 릴레이

어댑터는 서드 파티 SDK 콜백을 수신 대기하여 적절한 Google 모바일 광고 SDK 콜백에 매핑합니다.

광고 또는 오류와 함께 loadCompletionHandler를 호출하여 서드 파티 광고 로드 이벤트의 성공 여부를 보고합니다. 오류 없이 완료 핸들러를 광고와 함께 호출하면 광고 이벤트 대리자 객체가 반환됩니다. 어댑터가 나중에 프레젠테이션 이벤트를 전달할 수 있도록 이 대리자에 대한 참조를 유지합니다.

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

광고 게재

앱에서 Google 모바일 광고 SDK에 보상형 광고를 표시하도록 요청하면 SDK는 로드 완료 핸들러 호출 시 제공된 GADMediationRewardedAd 인스턴스에서 presentFromViewController: 메서드를 호출합니다. 다음과 같이 보상형 광고를 표시해야 합니다.

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

모바일 광고 SDK에 광고 이벤트 보고

광고를 표시한 후 어댑터는 성공적인 광고 로드 시간에 반환된 광고 이벤트 대리자를 사용하여 광고 프레젠테이션 수명 주기 이벤트를 보고해야 합니다.

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

Google 모바일 광고 SDK에 보고해야 하는 광고 이벤트는 다음과 같습니다.

광고 이벤트	설명
willPresentFullScreenView	Google 모바일 광고 SDK에 광고가 표시될 것임을 알립니다.
didStartVideo	Google 모바일 광고 SDK에 보상형 광고의 재생이 시작되었음을 알립니다.
reportImpression	Google 모바일 광고 SDK에 광고 노출이 발생했음을 알립니다.
didEndVideo	Google 모바일 광고 SDK에 보상형 광고의 재생이 완료되었음을 알립니다.
didRewardUserWithReward	Google 모바일 광고 SDK에 사용자가 리워드를 받았음을 알립니다.
reportClick	Google 모바일 광고 SDK에 광고가 클릭되었음을 알립니다.
willDismissFullScreenView	Google 모바일 광고 SDK에 광고가 닫힐 것임을 알립니다.
didDismissFullScreenView	Google 모바일 광고 SDK에 광고가 닫혔음을 알립니다.