header bidding - adform/adform-ios-sdk GitHub Wiki

Adform Advertising SDK allows you to use header bidding.

Since v.2.5 release of Adform Advertising SDK, it also includes Adform Header Bidding SDK.

It is very easy to make a request to the Adform ad exchange server with header bidding SDK. You just have to create an AFBidRequest and send it using AFBidLoader. There is no need to create new instances of AFBidLoader, therefore you should just use the default bid loader. The example below shows you how to request bids:

Swift

let bidRequest = AFBidRequest(masterTagId: mid, palcementType: .inline, supportedAdSizes: [AFAdDimension(320, 50)])

AFBidLoader.default().requestBids(bidRequest) { bidResponses, error in
    if let error = error {
        // Handle failed request.
        return
    }
    
    // Handle response of successful request.
    // The bidResponses array contains only one AFBidResponse instance,
    // therefore you can access it like this.
    let bidResponse = bidResponses.first
    
    // Do something with bid response.
}

AFBidRequest *bidRequest = [[AFBidRequest alloc] initWithMasterTagId:mid
                                                       palcementType:AFAdPlacementTypeInline
                                                    supportedAdSizes:@[AFAdDimension(320, 50)]];
                                                     
[[AFBidLoader defaultLoader] requestBids:bidRequest
                       completionHandler:^(NSArray<AFBidResponse *> *bidResponses, NSError *error) {
    if (error != null) {
        // Handle failed request.
    } else {
        // Handle response of successful request.
        // The bidResponses array contains only one AFBidResponse instance, 
        // therefore you can access it like this.
            
        AFBidResponse *response = bidResponses.firstObject;
            
        // Do something with bid response.
    }
}];

Bid request must have masterTagId, placementType and supportedAdSizes properties set before executing. To do so you should use convenience initializer initWithMasterTagId:palcementType:supportedAdSizes:. It is possible to set nil to supportedAdSizes, in this case, ad size will be determined dinamically on the server side based on the master tag configuration. Additionaly you can set bidTimeOut and adxDomain properties. bidTimeOut defines HTTP request timeout for bid requests, default value 15s. adxDomain defines the server to which the request should be sent. You can set AFAdxDomainEUR or AFAdxDomainUSA, default value AFAdxDomainEUR. AFAdxDomainEUR is used for European markets and AFAdxDomainUSA is used for USA markets.

Adform Header Bidding SDK has the ability to track user location. This feature is enabled globally through AFHeaderBiddingSDK class. By default user location tracking is disabled. This setting doesn't persist between application launches, therefore you need to enable location tracking on every app launch. The best place to do this is application:didFinishLaunchingWithOptions: application delegate method. Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    AFHeaderBiddingSDK.setAllowUseOfLocation(true)    
    
    return true
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [AFHeaderBiddingSDK allowUseOfLocation:YES];
    
    return YES;
}

It is important that you define NSLocationWhenInUseUsageDescription key in your application's info.plist file, if you don't have one. Otherwise, location tracking won't work on iOS 8+. You should set its value to "Your location will be used to show relevant ads nearby." or its translation.

There are additional functions that help during the header bidder setup. These functions are created for different means and provide an easy way of setting pricing and pass custom data to the ad server that then is returned to the ad code – i.e. ad ID that should be rendered.

To set the actual winning price from the header bidder auction for a placement you have to use price property of the ad view. This functionality is available for all ad types. The example below illustrates how to do it.

Swift

adView = AFAdInline(masterTagId: masterTag, presenting: self)

adView.price = 8.5

AFAdInline *adView = [[AFAdInline alloc] initWithMasterTagId:self.masterTagId presentingViewController:self];

adView.price = 8.5;

To set custom key-value data (an easy way of passing some data back to the ad that needs to be rendered) to a placement you have to use customData property of the ad view. This property is a dictionary containing key-value pairs. Custom data functionality is available for all ad types. The example below illustrates how to do it.

Swift

adView.customData = ["gender": "male", "age": "25"]

adView.customData = @{@"gender": @"male", @"age": @"25"};

In order to load Adform banners with Google DFP SDK using Adform Header Bidding SDK you need to follow these steps:

• Configure a creative for header bidding on DFP interface. Please visit our Publisher help center for more information.

• Import Adform Header Bidding SDK and Google DFP SDK to your project. For more information on Adform Header Bidding SDK integration take a look at the top of the document and more information about Google DFP SDK integration can be found here.

• Make a bid request using Adform Header Bidding SDK.

Swift

func requestBid(with masterTagId: Int, adSize: CGSize) {
    let bidRequest = AFBidRequest(masterTagId: masterTagId, palcementType: .inline, supportedAdSizes: [NSValue(cgSize: adSize)])
    
    AFBidLoader.default().requestBids(bidRequest) { bidResponses, error in
        handleBidResponse(bidResponses)
    }
}

- (void)requestBidWithMasterTagId:(long)mid adSize:(CGSize )size {
    AFBidRequest *bidRequest = [[AFBidRequest alloc] initWithMasterTagId:mid
                                                           palcementType:AFAdPlacementTypeInline
                                                        supportedAdSizes:@[[NSValue valueWithCGSize:size]]];
    
    [[AFBidLoader defaultLoader] requestBids:bidRequest
                           completionHandler:^(NSArray<AFBidResponse *> *bidResponses, NSError *error) {
                               [self handleBidResponses:bidResponses];
                           }];
}

• Pass bid price, ad unit, and bidder name to DFP ad request.

Swift

func handleBidResponse(_ bidResponses: [AFBidResponse]) {
    // Take the first response.
    // Check if we succesfully received a bid response.
    // Bid may be not available.
    guard let bidResponse = bidResponses.first, bidResponse.status == .available else {
        // Handle no bid response.
        return
    }
    
    // Create DFP ad request.
    let adRequest = DFPRequest.request()
    
    // Set custom targeting parameters. We use these parameters to pass header bidding data to DFP SDK.
    // You need to customize the bidding price for hb_pb parameter, which would be formatted with two trailing zeros (e.g."1.00").
    // To display ads by using Google DFP SDK requires base64 encoded hb_adid parameter.
    adRequest.customTargeting = [
        "hb_pb": String(format: "%.2f", bidResponse.cpm),
        "hb_bidder": "Bidder",
        "hb_adid": bidResponse.adUnitScriptEncoded?.replacingOccurrences(of: "=", with: "-")
    ]
    
    // Load the DFP banner.
    loadBanner(for: adRequest)
}

- (void)handleBidResponses:(NSArray<AFBidResponse *> *)bidResponses {

    // Take the first response.
    AFBidResponse *bidResponse = bidResponses.firstObject;
    
    // Check if we succesfully received a bid response.
    // Bid may be not available.
    if (bidResponse && bidResponse.status == AFBidStatusAvailable) {
        
        // Create DFP ad request.
        DFPRequest *adRequest = [DFPRequest request];
        
        // Set custom targeting parameters. We use these parameters to pass
        // header bidding data to DFP sdk.
        // You need to customize bidding price for hb_pb parameter, that it would be formatted with two trailing zeros (e.g."1.00").
        // To display ads by using Google DFP SDK it requires base64 encoded hb_adid parameter.
        NSDictionary *customTargeting = @{@"hb_pb": [NSString stringWithFormat:@"%.2f", bidResponse.cpm],
                                      @"hb_bidder": @"Bidder",
                                      @"hb_adid":  [bidResponse.adUnitScriptEncoded stringByReplacingOccurrencesOfString:@"=" withString:@"-"] };
        adRequest.customTargeting = customTargeting;
        
        // Load the DFP banner.
        [self loadBanner:adRequest];
    } else {
        // Show error
    }
}

• Load the ad.

Swift

func loadBanner(for adRequest: DFPRequest) {
    bannerView.laodRequest(adRequest)
}

- (void)loadBanner:(DFPRequest *)adRequest {

    [self.bannerView loadRequest:adRequest];
}