헤더 비딩

헤더비딩

PrebidMobile, Amazon Publisher Services(이하 "APS"라고 칭함)을 통한 HeaderBidding을 지원합니다.

정보

PrebidMobile, APS 연동은 사전입찰 결과를 파라미터로 전달하고 낙찰 소재를 SDK가 렌더링하는 방식입니다. 낙찰 시 Prebid SDK가 직접 소재를 렌더링하는 방식은 Magnite Prebid 연동을 참고해주세요. (since 8.24.0)

각 연동은 아래 버전을 기준으로 샘플 개발 및 검증이 완료되었습니다.

PrebidMobile: 1.5
APS: 3.4.6
Magnite Prebid: PrebidMobile 3.3.1

source 'https://github.com/CocoaPods/Specs.git'

target 'MyApplication' do
    pod 'PrebidMobile', '1.5'
    pod 'AmazonPublisherServicesSDK', '3.4.6'
end

PrebidMobile 연동

PrebidMobile을 통한 헤더비딩 연동은 배너 광고에 한해 지원됩니다.

아래 가이드는 NAMSDK 연동과 관련된 내용을 다루고 있습니다. PrebidMobile에 대한 자세한 내용은 공식 가이드를 참고해주시기 바랍니다.

Prebid 설정

Swift
Objective-C

Prebid.shared.prebidServerAccountId = @"accountId 입력";
//testAccountId: "bfa84af2-bd16-4d35-96ad-31c6bb888df0"

let bannerAdUnit = BannerAdUnit(configId: "configId 입력", size: CGSize(width: 300, height: 250))
//testConfigId: "6ace8c7d-88c0-4623-8117-75bc3f0a2e45"

Prebid.shared.prebidServerAccountId = @"accountId 입력";
//testAccountId: "bfa84af2-bd16-4d35-96ad-31c6bb888df0"

BannerAdUnit *bannerAdUnit = [[BannerAdUnit alloc] initWithConfigId:@"configId 입력" size:CGSizeMake(300, 250)];
//testConfigId: "6ace8c7d-88c0-4623-8117-75bc3f0a2e45"

Prebid 정보 요청

NSMutableDictionary를 파라미터로 fetchDemandWithAdObject:completion: 을 호출합니다.
fetch 성공 시 생성한 Dictionary에 "hb_"의 prefix를 가진 데이터가 추가됩니다.

Swift
Objective-C

let requestPrebid = NSMutableDictionary.init()

bannerAdUnit.fetchDemand(adObject: requestPrebid) { (resultCode) in
    if resultCode == ResultCode.prebidDemandFetchSuccess {
          //TODO: adParam 설정 후 banner 광고 요청
    }
}

NSMutableDictionary *requestPrebid = [NSMutableDictionary dictionary];
[bannerAdUnit fetchDemandWithAdObject:requestPrebid completion:^(enum ResultCode result) {
    if(result == ResultCodePrebidDemandFetchSuccess) {
          //TODO: adParam 설정 후 banner 광고 요청
    }
}];

AdParam 설정 & 배너 로드

2번의 스텝에서 얻은 Dictionary 데이터를 AdParam의 prebidHBParam에 설정합니다.
AdParam을 GFPAdLoader 혹은 GFPBannerView에 설정한 후 광고를 요청합니다.
AdParam에 대한 자세한 내용은 광고 요청 정보 가이드를 참고해주세요.

Swift
Objective-C

let adParam = GFPAdParam()
adParam.gender = .female
adParam.yearOfBirth = 1995

if let prebidParam = requestPrebid as? [String : String] {
     adParam.prebidHBParam = prebidParam
}

//TODO: 광고 요청

GFPAdParam *adParam = [[GFPAdParam alloc] init];
adParam.gender = GFPAdParamGenderTypeFemale;
adParam.yearOfBirth = 1995;

adParam.prebidHBParam = requestPrebid;

//TODO: 광고 요청

APS 연동

APS을 통한 헤더비딩 연동은 배너 광고에 한해 지원됩니다.

아래 가이드는 NAMSDK 연동과 관련된 내용을 다루고 있습니다. APS에 대한 자세한 내용은 공식 가이드를 참고해주시기 바랍니다.

APS 설정

NAMSDK 에서는 MRAID 1.0, 2.0, 3.0 스펙 을 지원합니다. 아래의 MRAID 설정은 반드시 따라주시기 바랍니다.

Swift
Objective-C

DTBAds.sharedInstance().setAppKey("appKey 입력")
//testAppKey: "c5f20fe6e37146b08749d09bb2b6a4dd"

DTBAds.sharedInstance().mraidPolicy = CUSTOM_MRAID
DTBAds.sharedInstance().mraidCustomVersions = ["1.0", "2.0", "3.0"]

[[DTBAds sharedInstance] setAppKey: @"appKey 입력"];
//testAppKey: "c5f20fe6e37146b08749d09bb2b6a4dd"

[[DTBAds sharedInstance] setMraidPolicy:CUSTOM_MRAID];
[[DTBAds sharedInstance] setMraidCustomVersions:@[@"1.0", @"2.0", @"3.0"]];

APS 정보 요청

자세한 내용은 APS 공식 가이드를 참고해주세요.

Swift
Objective-C

let dtbAdSize = DTBAdSize(bannerAdSizeWithWidth: 320, height: 50, andSlotUUID: "slotUUID 입력")
//testSlotUUID: "88e6293b-0bf0-43fc-947b-925babe7bf3f"

let dtbAdLoader = DTBAdLoader()
dtbAdLoader.setAdSizes([dtbAdSize])
dtbAdLoader.loadAd(self)

func onFailure(_ error: DTBAdError) {
    /**Please implement the logic to send ad request without our parameters if you want to
     show ads from other ad networks when Amazon ad request fails**/
}

func onSuccess(_ adResponse: DTBAdResponse!) {
    /**Build the ad request to your ad server. This portion will differ depending on your 
     ad server**/
}

DTBAdSize *dtbAdSize = [[DTBAdSize alloc] initBannerAdSizeWithWidth:320 height:50 andSlotUUID:@"slotUUID 입력"];
//testSlotUUID: "88e6293b-0bf0-43fc-947b-925babe7bf3f"

DTBAdLoader *adLoader = [DTBAdLoader new];
[adLoader setSizes:dtbAdSize, nil];
[adLoader loadAd:self];

#pragma mark - DTBAdCallback
- (void)onFailure: (DTBAdError)error {
    NSLog(@"Failed to load ad :(");
    /**Please implement the logic to send ad request without our parameters if you want to
     show ads from other ad networks when Amazon ad request fails**/
}

- (void)onSuccess: (DTBAdResponse *)adResponse {
    /**Build the ad request to your ad server. This portion will differ depending on your 
     ad server**/
}

AdParam 설정 & 배너 로드

DTBAdCallback의 onSuccess 수신 시, APS 정보를 GFPAPSAdParam에 세팅 후, AdParam의 apsParam에 설정합니다.
AdParam을 GFPBannerView에 설정한 후 광고를 요청합니다.
- (주의) [광고 요청 전, 이전 데이터 초기화 필요] AdParam을 재사용 한다면, onFailure 수신 시 AdParam의 apsParam을 리셋해주어야 합니다.

Swift
Objective-C

func onSuccess(_ adResponse: DTBAdResponse!) {
    let adParam = GFPAdParam()
    adParam.gender = .female
    adParam.yearOfBirth = 1995

    let apsParam = GFPAPSAdParam()
    apsParam.crid = adResponse.crid
    apsParam.size = CGSize(width: adResponse.adSize.width, height: adResponse.adSize.height)

    if let customTargeting = adResponse.customTargeting().map as? [String : NSObject] {
        apsParam.apsHBParam = customTargeting
    }
    
    apsParam.skAdNetworkParams = adResponse.skAdNetworkParams;

    adParam.apsParam = apsParam;

    //TODO: banner 광고 요청
}

- (void)onSuccess: (DTBAdResponse *)adResponse {
    GFPAdParam *adParam = [[GFPAdParam alloc] init];
    adParam.gender = GFPAdParamGenderTypeFemale;
    adParam.yearOfBirth = 1995;
    
    GFPAPSAdParam *apsParam = [[GFPAPSAdParam alloc] init];
    apsParam.crid = adResponse.crid;
    apsParam.size = CGSizeMake(adResponse.adSize.width, adResponse.adSize.height);
    apsParam.apsHBParam = adResponse.customTargeting;
    apsParam.skAdNetworkParams = adResponse.skAdNetworkParams;

    adParam.apsParam = apsParam;
    
    //TODO: banner 광고 요청
}

MRAID 3.0 Unload

MRAID 3.0의 Unload 호출 시에 발생하는 이벤트를 알리기 위해 다음 메서드가 GFPBannerViewDelegate에 추가되었습니다.

Swift
Objective-C

func bannerShouldUnload(_ bannerView: GFPBannerView) {
    // ...
}

- (void)bannerShouldUnload:(GFPBannerView *)bannerView{
    // ...
}

Magnite Prebid 연동 (since 8.24.0)

Magnite Prebid는 Prebid Rendered 방식의 헤더비딩입니다. 사전입찰 결과(winning bid)를 광고 요청 시 전달하고, GFP 서버에서 낙찰될 경우 Prebid SDK가 직접 소재를 렌더링합니다.

Magnite Prebid를 통한 헤더비딩 연동은 배너 광고에 한해 지원됩니다.

Prebid SDK에 대한 자세한 내용은 공식 가이드를 참고해주시기 바랍니다.

의존성 추가

target 'MyApplication' do
    pod 'PrebidMobile', '3.3.1'
    pod 'NAMSDKMediationMagnitePrebid'
end

정보

NAMSDK와 NAMSDKMediationMagnitePrebid 간 버전 호환성은 미디에이션 네트워크 버전에서 확인 후 적용 부탁드립니다.

Prebid SDK 초기화

Prebid SDK의 초기화는 매체 앱에서 진행해야 합니다. serverURL과 accountId는 Magnite로부터 발급받은 값을 사용합니다.

Swift
Objective-C

Prebid.shared.prebidServerAccountId = "accountId 입력"

try? Prebid.initializeSDK(serverURL: "serverURL 입력") { status, error in
    // 초기화 결과 확인
}

Prebid.shared.prebidServerAccountId = @"accountId 입력";

[Prebid initializeSDKWithServerURL:@"serverURL 입력" error:nil :^(enum PrebidInitializationStatus status, NSError * _Nullable error) {
    // 초기화 결과 확인
}];

사전 입찰 요청

Prebid SDK의 MediationBannerAdUnit을 통해 사전 입찰을 요청합니다. 자세한 내용은 Prebid 공식 가이드를 참고해주세요.

주의

아래 내용은 PrebidMobile 3.3.1 기준으로 작성된 예제이며, 관련된 코드는 매체에서 직접 관리합니다.

Prebid SDK API의 사용 방법 및 변경 사항은 Prebid 공식 가이드를 확인해주세요.

PrebidMediationDelegate를 구현하여 사전 입찰 결과(setUpAdObject(with:)로 전달되는 values)를 보관합니다.
MediationBannerAdUnit 생성 후 fetchDemand를 호출합니다.
fetch 성공 시 values의 PBMMediationAdUnitBidKey, PBMMediationTargetingInfoKey 키로 winning bid와 targeting keywords를 얻습니다.
fetchDemand 콜백 시점까지 MediationBannerAdUnit과 delegate 인스턴스가 해제되지 않도록 강한 참조로 보관해야 합니다.

Swift
Objective-C

import PrebidMobile

final class ExampleMagnitePrebidBidder: NSObject, PrebidMediationDelegate {
    private(set) var values: [String: Any]?
    private let placeholderAdView = UIView()

    func setUpAdObject(with values: [String: Any]) -> Bool {
        self.values = values
        return true
    }

    func cleanUpAdObject() {
        values = nil
    }

    func getAdView() -> UIView? {
        return placeholderAdView
    }
}

let configId = "configId 입력"

self.bidder = ExampleMagnitePrebidBidder()
self.adUnit = MediationBannerAdUnit(configID: configId,
                                    size: CGSize(width: 320, height: 50),
                                    mediationDelegate: self.bidder)
self.adUnit.adFormat = .banner

self.adUnit.fetchDemand { [weak self] resultCode in
    guard let self = self else { return }

    if resultCode == .prebidDemandFetchSuccess {
        let bid = self.bidder.values?[PBMMediationAdUnitBidKey] as? Bid
        let keywords = self.bidder.values?[PBMMediationTargetingInfoKey] as? [String: String]
        //TODO: adParam 설정 후 banner 광고 요청
    }
}

@import PrebidMobile;

@interface ExampleMagnitePrebidBidder : NSObject <PrebidMediationDelegate>
@property (nonatomic, copy, nullable) NSDictionary<NSString *, id> *values;
@property (nonatomic, strong) UIView *placeholderAdView;
@end

@implementation ExampleMagnitePrebidBidder

- (instancetype)init {
    self = [super init];
    if (self) {
        _placeholderAdView = [[UIView alloc] init];
    }
    return self;
}

- (BOOL)setUpAdObjectWith:(NSDictionary<NSString *, id> *)values {
    self.values = values;
    return YES;
}

- (void)cleanUpAdObject {
    self.values = nil;
}

- (UIView *)getAdView {
    return self.placeholderAdView;
}

@end

NSString *configId = @"configId 입력";

self.bidder = [[ExampleMagnitePrebidBidder alloc] init];
self.adUnit = [[MediationBannerAdUnit alloc] initWithConfigID:configId
                                                         size:CGSizeMake(320, 50)
                                            mediationDelegate:self.bidder];
self.adUnit.adFormat = AdFormat.banner;

__weak typeof(self) weakSelf = self;
[self.adUnit fetchDemandWithCompletion:^(enum ResultCode resultCode) {
    if (resultCode == ResultCodePrebidDemandFetchSuccess) {
        Bid *bid = weakSelf.bidder.values[PBMMediationAdUnitBidKey];
        NSDictionary<NSString *, NSString *> *keywords = weakSelf.bidder.values[PBMMediationTargetingInfoKey];
        //TODO: adParam 설정 후 banner 광고 요청
    }
}];

AdParam 설정 & 배너 로드

사전 입찰 성공 시 GFPMagnitePrebidAdParam에 configId, targetingKeywords, winning bid를 설정합니다.
생성한 파라미터를 AdParam의 magnitePrebidParam에 설정한 후 광고를 요청합니다.
사전 입찰 실패 시에는 magnitePrebidParam 설정 없이 광고를 요청하면 일반 워터폴로 진행됩니다.

Swift
Objective-C

let magnitePrebidParam = GFPMagnitePrebidAdParam()
magnitePrebidParam.configId = configId
magnitePrebidParam.targetingKeywords = keywords
magnitePrebidParam.winningBid = bid

let adParam = GFPAdParam()
adParam.magnitePrebidParam = magnitePrebidParam

//TODO: 광고 요청

GFPMagnitePrebidAdParam *magnitePrebidParam = [[GFPMagnitePrebidAdParam alloc] init];
magnitePrebidParam.configId = configId;
magnitePrebidParam.targetingKeywords = keywords;
magnitePrebidParam.winningBid = bid;

GFPAdParam *adParam = [[GFPAdParam alloc] init];
adParam.magnitePrebidParam = magnitePrebidParam;

//TODO: 광고 요청

헤더비딩​

PrebidMobile 연동​

Prebid 설정​

Prebid 정보 요청​

AdParam 설정 & 배너 로드​

APS 연동​

APS 설정​

APS 정보 요청​

AdParam 설정 & 배너 로드​

MRAID 3.0 Unload​

Magnite Prebid 연동 (since 8.24.0)​

의존성 추가​

Prebid SDK 초기화​

사전 입찰 요청​

AdParam 설정 & 배너 로드​

헤더비딩

PrebidMobile 연동

Prebid 설정

Prebid 정보 요청

AdParam 설정 & 배너 로드

APS 연동

APS 설정

APS 정보 요청

AdParam 설정 & 배너 로드

MRAID 3.0 Unload

Magnite Prebid 연동 (since 8.24.0)

의존성 추가

Prebid SDK 초기화

사전 입찰 요청

AdParam 설정 & 배너 로드