> For the complete documentation index, see [llms.txt](https://docs.blueseasx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blueseasx.com/client-bidding/ios/banner-ads.md). # Banner Ads ### **Step1. Load** On the BlueSea console, create client bidding placement for the ad request. Please note the client bidding placements don’t support floor price setup.
Before requesting ads, please ensure that the SDK has been initialized. To request banner ads, declare a `BSXMediationInfo` object. This object should include the ad mediation platform, the mediation version, and the BlueSea Adapter version used when requesting the ads. If you are integrating BlueSea SDK through your own mediation platform, it is recommended to declare the `BSXMediationInfo` object and pass in the mediation information to facilitate monetization data management and channel monetization optimization. ``` BSXMediationInfo *mediationInfo = [[BSXMediationInfo alloc] initWithMediationName:@"" mediationVersion:@"" adapterVersion:@""]; ``` * ``: Pass the value as "in-house" * ``: Pass the version number of your app or meditation * ``: Pass the version number of the adapter. To request an ad, create a `BSXAdView` with the specified Placement and call the loadAd method. Add the `BSXAdView` as a child of your parent layout when you’re going to display the ad. You should also set a `BSXAdViewDelegate` to track ad load status and other related events. The following example shows how to request an ad: ``` @interface BannerViewController () @property(nonatomic, strong) BSXAdView *adView; @property(nonatomic, strong) UIView *adContainer; @end @implementation BannerViewController - (BSXAdView *)createAdView { BSXAdView *adView = [[BSXAdView alloc] initWithFrame:self.adContainer.bounds]; [adView setPlacementId:BSXBannerAdPlacementId]; [adView setMediationInfo:self.mediationInfo]; return adView; } - (void)loadBannerAd { self.adView = [self createAdView]; self.adView.delegate = self; [self.adView loadAd]; } #pragma mark - BSXAdViewDelegate - (void)didBSXBannerAd:(BSXAdView *)adView loadError:(BSXAdError*)error { NSLog(@"BannerAd load fail."); } - (void)didBSXBannerAdLoaded:(BSXAdView *)adView { NSLog(@"BannerAd loaded."); } - (void)didBSXBannerAd:(BSXAdView *)adView displayFailed:(BSXAdError*)error { NSLog(@"BannerAd display fail."); } - (void)didBSXBannerAdDisplayed:(BSXAdView *)adView { NSLog(@"BannerAd displayed."); } - (void)didBSXBannerAdClicked:(BSXAdView *)adView { NSLog(@"BannerAd clicked."); } @end ``` `BSXAdViewDelegate` callback: * `- (void)didBSXBannerAd:(BSXAdView *)adView loadError:(BSXAdError*)error`: Indicates that no ads were filled. This may be due to the advertiser not bidding or other issues. You can check the error code and message using `BSXAdError.errorCode` and `BSXAdError.errorMsg`. For details on error codes, refer to [Test & Error Handling](/client-bidding/ios/test-and-error-handling.md) * `- (void)didBSXBannerAdLoaded:(BSXAdView *)adView:` Indicates that the ad was successfully filled ### **Step2. Auction** When you receive a `(void)didBSXBannerAdLoaded:(BSXAdView *)adView` callback, use the `Price` method to get the price for this ad. (double type, unit: eCPM (USD) ) ``` double price = [BSXAdView price]; ``` The client reports the auction result to BlueSea via the following two methods of `BSXAdView`: ``` // BlueSea win，then publisher pass the following info * @param minBidder the bidder name of second highest price * @param auctionMinToWin Second-highest bid price, double type, unit: eCPM, rounded to 4 decimal places - (void)notifyAdWinWithMinBidder:(NSString *)minBidder auctionMinToWin:(double)auctionMinToWin; // BlueSea loss，then publisher pass the following info * @param winBidder Winning bidder name — string * @param auctionPrice Highest bid price — double, unit: eCPM, rounded to 4 decimal places * @param auctionLossCode BlueSea loss reason — reason why BlueSea lost the auction */ - (void)notifyAdLossWithWinBidder:(NSString *)winBidder auctionPrice:(double)auctionPrice auctionLossCode:(int32_t)auctionLossCode; ``` **Auction Loss Code**
ValueDefinition
1Internal Error
2Impression Opportunity Expired
9Missing Bid Price
100Bid was Below Auction Floor
102Lost to Higher Bid
1000+Publisher specific values; should be communicated with BlueSea beforehand.
### **Step3. Show** Once you receive the `onAdLoaded` callback, use the `addSubView` method to add the `adView` to your window, and set a `BSXAdViewDelegate` to listen for ad events. ``` @interface BannerViewController () @property(nonatomic, strong) BSXAdView *adView; @property(nonatomic, strong) UIView *adContainer; @end @implementation BannerViewController - (BSXAdView *)createAdView { BSXAdView *adView = [[BSXAdView alloc] initWithFrame:self.adContainer.bounds]; [adView setPlacementId:BSXBannerAdPlacementId]; [adView setMediationInfo:self.mediationInfo]; return adView; } - (void)showBannerView:(id)target { if (self.adView) { [self.adView removeFromSuperview]; BSXAdSize *adSize = [self.adView getAdSize]; self.adView.frame = CGRectMake(0, 0, adSize.width, adSize.height); self.adView.center = CGPointMake(CGRectGetWidth(self.adContainer.frame) / 2, CGRectGetHeight(self.adContainer.frame) / 2); [self.adContainer addSubview:self.adView]; } } #pragma mark - BSXAdViewDelegate - (void)didBSXBannerAd:(BSXAdView *)adView loadError:(BSXAdError*)error { NSLog(@"BannerAd load fail."); } - (void)didBSXBannerAdLoaded:(BSXAdView *)adView { NSLog(@"BannerAd loaded."); } - (void)didBSXBannerAd:(BSXAdView *)adView displayFailed:(BSXAdError*)error { NSLog(@"BannerAd display fail."); } - (void)didBSXBannerAdDisplayed:(BSXAdView *)adView { NSLog(@"BannerAd displayed."); } - (void)didBSXBannerAdClicked:(BSXAdView *)adView { NSLog(@"BannerAd clicked."); } @end ``` Before displaying the ad, call `[BSXAdView isExpired]` to check whether the ad has expired (the typical validity period is 1 hour). If the ad has expired, request a new one. ### **Step4. Destroy** If you no longer need the ad, you can destroy it using the following method: ``` @implementation BannerViewController - (void)destroyAdView { if (self.adView) { [self.adView removeFromSuperview]; [self.adView destroy]; } } @end ```