# Add Native Banner Ads to an iOS App The Audience Network allows you to monetize your iOS apps with Facebook ads. This guide explains how to create an iOS app that shows native banner ads. The Native Banner Ad API allows you to build a customized experience for the ads you show in your app. When using the Native Banner Ad API, instead of receiving an ad ready to be displayed, you will receive a group of ad properties such as a title, an image, a call to action, and you will have to use them to construct a custom UIView where the ad is shown. Let's implement the following native banner ad placement. You will create the following views to our native banner ad. #### View #1: ad icon image view #### View #2: ad choices view #### View #3: ad advertiser name label #### View #4: ad sponsored label #### View #5: ad call to action button #### [Step 1: Create Native Banner Ad Views in Storyboard](#ui) #### [Step 2: Load and Show Native Banner Ad](#load) #### [Step 3: Verify Impression and Click Logging](#logging) #### [Step 4: How to Debug When Ad Not Shown](#debug) #### [Step 5: Test Ads Integration](https://developers.facebook.com/documentation/audience-network/setting-up/testing/platform) #### [See Known Issues in the Change Log](https://developers.facebook.com/documentation/audience-network/setting-up/platform-setup/ios/changelog) ## Step 1: Create Native Banner Ad Views in Storyboard {#ui} **Warning:** Ensure you have completed the Audience Network [Getting Started](https://developers.facebook.com/documentation/audience-network/setting-up/platform-setup) and [iOS Getting Started](https://developers.facebook.com/documentation/audience-network/setting-up/platform-setup/ios/get-started) guides before you proceed. **Warning:** When designing native ads and banner ads, ensure you have followed [iOS layout guideline](https://developers.facebook.com/documentation/audience-network/optimization/layout-best-practices/ios) for optimal user experience. - After you have created a new project from [iOS Getting Started](https://developers.facebook.com/documentation/audience-network/setting-up/platform-setup/ios/get-started) guides, open `Main.storyboard`. Add a UIView element to the main View element and name it to `adUIView`. - In addition, add `adIconImageView` (FBMediaView), `adChoicesView` (FBAdChoicesView), `adAdvertiserNameLabel` (UILabel), `adSponsoredLabel` (UILabel), `adCallToActionButton` (UIButton) under `adUIView` as illustrated in the image below. - You may notice that there is a red arrow nearby **View Controller Scene**. This usually means that there are missing constraints in your layout. You would need to select all the view objects in your scene and click the "resolve layout issue" icon to add missing constraints. - Now that you have created all the UI elements for showing a native banner ad, you will need to reference these UI elements in the ViewController interface. First open the `ViewController.m` (`ViewController.swift` if you are a Swift user), then hold down the Control key and drag `adUIView` inside the ViewController interface object. You can name it as `adUIView`. After, you will need to do the same thing for `adIconImageView` , `adChoicesView`, `adAdvertiserNameLabel`, `adSponsoredLabel`, and `adCallToActionButton`. - Build and run the project. You should see from your device or simulator empty content as follows: Now that you have created all the UI elements to show native banner ads, the next step is to load the native banner ad and bind the contents to the UI elements. ## Step 2: Load and Show Native Banner Ad {#load} - Now, in your View Controller header file (or Swift file, if you are a Swift user), import `FBAudienceNetwork`, declare conformance to the `FBNativeBannerAdDelegate` protocol, and add an instance variable for the ad unit ### Swift ``` import UIKit import FBAudienceNetwork class ViewController: UIViewController, FBNativeBannerAdDelegate { private var nativeBannerAd: FBNativeBannerAd? } ``` ### Objective-C ``` #import <UIKit/UIKit.h> @import FBAudienceNetwork; @interface ViewController : UIViewController <FBNativeBannerAdDelegate> @property (nonatomic, strong) FBNativeBannerAd *nativeBannerAd; @end ``` - In `viewDidLoad` method, add the following lines of code to load native ad content ### Swift ``` override func viewDidLoad() { super.viewDidLoad() // Instantiate a native banner ad object. // NOTE: the placement ID will eventually identify this as your app. You can ignore it while you are testing // and replace it later when you have signed up. // While you are using this temporary code you will only get test ads and if you release // your code like this to the App Store your users will not receive ads (you will get a ‘No Fill’ error). let nativeBannerAd = FBNativeBannerAd(placementID: "YOUR_PLACEMENT_ID") // Set a delegate to get notified when the ad was loaded. nativeBannerAd.delegate = self // Initiate a request to load an ad. nativeBannerAd.loadAd() } ``` ### Objective-C ``` - (void)viewDidLoad { [super viewDidLoad]; // Instantiate a native banner ad object. // NOTE: the placement ID will eventually identify this as your app. You can ignore it while you are testing // and replace it later when you have signed up. // While you are using this temporary code you will only get test ads and if you release // your code like this to the App Store your users will not receive ads (you will get a ‘No Fill’ error). // your code like this to the App Store your users will not receive ads (you will get a ‘No Fill’ error). FBNativeBannerAd *nativeBannerAd = [[FBNativeBannerAd alloc] initWithPlacementID:@"YOUR_PLACEMENT_ID"]; // Set a delegate to get notified when the ad was loaded. nativeBannerAd.delegate = self; // Initiate a request to load an ad. [nativeBannerAd loadAd]; } ``` The ID that displays at `YOUR_PLACEMENT_ID` is a temporary ID for test purposes only. If you use this temporary ID in your live code, your users will not receive ads (they will get a **No Fill** error). You must return here after testing and replace this temporary ID with a live Placement ID. To find out how the generate a live Placement ID, refer to [Audience Network Setup](https://developers.facebook.com/documentation/audience-network/bidding/partner-mediation/audience-network-setup) - The next step is to show ad when content is ready. You would need your View Controller to implement the `nativeBannerAdDidLoad` method ### Swift ``` func nativeBannerAdDidLoad(_ nativeBannerAd: FBNativeBannerAd) { if let previousAd = self.nativeBannerAd, previousAd.isAdValid { previousAd.unregisterView() } self.nativeBannerAd = nativeBannerAd adAdvertiserNameLabel.text = nativeBannerAd.advertiserName adSponsoredLabel.text = nativeBannerAd.sponsoredTranslation if let callToAction = nativeBannerAd.callToAction { adCallToActionButton.isHidden = false adCallToActionButton.setTitle(callToAction, for: .normal) } else { adCallToActionButton.isHidden = true } // Set native banner ad view tags to declare roles of your views for better analysis in future // We will be able to provide you statistics how often these views were clicked by users // Views provided by Facebook already have appropriate tag set self.adAdvertiserNameLabel.nativeAdViewTag = .title self.adCallToActionButton.nativeAdViewTag = .callToAction // Specify the clickable areas. View you were using to set ad view tags should be clickable. let clickableViews: [UIView] = [adCallToActionButton] nativeBannerAd.registerView( forInteraction: adUIView, iconView: adIconImageView, viewController: self, clickableViews: clickableViews ) /* // If you don't want to provide native ad view tags you can simply // Wire up UIView with the native banner ad; the whole UIView will be clickable. nativeBannerAd.registerView( forInteraction: adUIView, iconView: adIconImageView, viewController: self ) */ adChoicesView.corner = .topLeft adChoicesView.nativeAd = nativeBannerAd } ``` ### Objective-C ``` - (void)nativeBannerAdDidLoad:(FBNativeBannerAd *)nativeBannerAd { if (self.nativeBannerAd && self.nativeBannerAd.isAdValid) { [self.nativeBannerAd unregisterView]; } self.nativeBannerAd = nativeBannerAd; // Render native banner ads onto UIView self.adAdvertiserNameLabel.text = self.nativeBannerAd.advertiserName; self.adSponsoredLabel.text = self.nativeBannerAd.sponsoredTranslation; if (self.nativeBannerAd.callToAction) { [self.adCallToActionButton setHidden:NO]; [self.adCallToActionButton setTitle:self.nativeBannerAd.callToAction forState:UIControlStateNormal]; } else { [self.adCallToActionButton setHidden:YES]; } // Set native banner ad view tags to declare roles of your views for better analysis in future // We will be able to provide you statistics how often these views were clicked by users // Views provided by Facebook already have appropriate tag set self.adAdvertiserNameLabel.nativeAdViewTag = FBNativeAdViewTagTitle; self.adCallToActionButton.nativeAdViewTag = FBNativeAdViewTagCallToAction; // Specify the clickable areas. View you were using to set ad view tags should be clickable. NSArray<UIView *> *clickableViews = @[self.adCallToActionButton]; [nativeBannerAd registerViewForInteraction:self.adUIView iconView:self.adIconImageView viewController:self clickableViews:clickableViews]; // If you don't want to provide native ad view tags you can simply // Wire up UIView with the native banner ad; the whole UIView will be clickable. // [nativeBannerAd registerViewForInteraction:self.adUIView // iconView:self.adIconView // viewController:self]; self.adChoicesView.corner = UIRectCornerTopLeft; self.adChoicesView.nativeAd = nativeBannerAd; } ``` First, you need to check if there is an existing valid `FBNativeBannerAd` object. If there is, you will need to unregister it your register the new ad object ### Controlling Clickable Area **Warning:** For a better user experience and better results, you should always consider controlling the clickable area of your ad to avoid unintentional clicks. Please refer to [Audience Network SDK Policy](https://developers.facebook.com/documentation/audience-network/optimization/best-practices/an-policy) page for more details about white space unclickable enforcement. What `registerViewForInteraction` mainly does is register what views will be tappable and what the delegate is to notify when a registered view is tapped. In this case, `adCallToActionButton` will be tappable and when the view is tapped, `ViewController` will be notified through `FBNativeBannerAdDelegate`. - Choose your build target to be device and run the above code, you should see something like this: **Warning:** When running ads in the simulator, change the setting to test mode to view test ads. Please go to [How to Use Test Mode](https://developers.facebook.com/documentation/audience-network/setting-up/testing/platform#testing-testAd) for more information. ## Step 3: Verify Impression and Click Logging {#logging} Optionally, you can add the following functions to handle the cases where the native banner ad is closed or when the user clicks on it: ### Swift ``` func nativeBannerAdDidClick(_ nativeBannerAd: FBNativeBannerAd) { print("Native banner ad was clicked.") } func nativeBannerAdDidFinishHandlingClick(_ nativeBannerAd: FBNativeBannerAd) { print("Native banner ad did finish click handling.") } func nativeBannerAdWillLogImpression(_ nativeBannerAd: FBNativeBannerAd) { print("Native banner ad impression is being captured.") } ``` ### Objective-C ``` - (void)nativeBannerAdDidClick:(FBNativeBannerAd *)nativeBannerAd { NSLog(@"Native banner ad was clicked."); } - (void)nativeBannerAdDidFinishHandlingClick:(FBNativeBannerAd *)nativeBannerAd { NSLog(@"Native banner ad did finish click handling."); } - (void)nativeBannerAdWillLogImpression:(FBNativeBannerAd *)nativeBannerAd { NSLog(@"Native banner ad impression is being captured."); } ``` ## Step 4: How to Debug When Ad Not Shown {#debug} Add and implement the following function in your View Controller to handle ad loading failures ### Swift ``` func nativeBannerAd(_ nativeBannerAd: FBNativeBannerAd, didFailWithError error: Error) { print("Native banner ad failed to load with error: \(error.localizedDescription)") } ``` ### Objective-C ``` - (void)nativeBannerAd:(FBNativeBannerAd *)nativeBannerAd didFailWithError:(NSError *)error { NSLog(@"Native banner ad failed to load with error: %@", error); } ``` ## Next steps {#next-steps} Learn more about the [ad formats](https://developers.facebook.com/documentation/audience-network/ad-formats) available for Audience Network apps. ### See also * Visit [our GitHub sample app repository](https://github.com/fbsamples/audience-network/tree/master/samples/ios) to view sample code. * View the [Audience Network policies](https://developers.facebook.com/documentation/audience-network/optimization/best-practices/an-policy) and the [Facebook community standards](https://www.facebook.com/communitystandards) to ensure you app complies. # More Resources #### [Getting Started Guide](https://developers.facebook.com/documentation/audience-network/setting-up/platform-setup) Technical guide to get started with the Audience Network #### [Code Samples](https://developers.facebook.com/docs/audience-network/samples) Audience Network Ads Integration Samples #### [FAQ](https://developers.facebook.com/documentation/audience-network/support) Audience Network FAQ #### [Native Ads Template](https://developers.facebook.com/documentation/audience-network/setting-up/ad-setup/ios/native/template) A more hands off approach when integrating Native Ads