Adding Interstitial Ad to your iOS app

The Audience Network allows you to monetize your iOS apps with Facebook ads. An interstitial ad is a full screen ad that you can show in your app. Follow this guide to display this type of ad unit. Or, if you're interested in other kinds of ad units, see a list of available types.

Let's implement the following interstitial ad placement.

Step 1: Load and Show Interstitial Ad View

Step 2: Verify Impression and Click Logging

Step 3: How to Debug When Ad Not Shown

Step 1: Load and Show Interstitial Ad View

Ensure you have completed the Audience Network Getting Started and iOS Getting Started guides before you proceed.

  1. After you have created a new project from iOS Getting Started guide, open ViewController.h. Import the SDK header, declare that ViewController implements the FBInterstitialAdDelegate protocol and add an instance variable for the interstitial ad unit:
    #import <UIKit/UIKit.h>
    @import FBAudienceNetwork;
    @interface ViewController : UIViewController <FBInterstitialAdDelegate>
    @property (nonatomic, strong) FBInterstitialAd *interstitialAd;
  2. Next, implement viewDidLoad method and interstitialAdDidLoad in ViewController.m file.
    - (void) viewDidLoad 
      [super viewDidLoad];
      self.interstitialAd = [[FBInterstitialAd alloc] initWithPlacementID:@"YOUR_PLACEMENT_ID"];
      self.interstitialAd.delegate = self;
      // For auto play video ads, it's recommended to load the ad 
      // at least 30 seconds before it is shown
      [self.interstitialAd loadAd];
    - (void)interstitialAdDidLoad:(FBInterstitialAd *)interstitialAd
      NSLog(@"Ad is loaded and ready to be displayed");
      // You can now display the full screen ad using this code:
      [interstitialAd showAdFromRootViewController:self];
  3. Replace YOUR_PLACEMENT_ID with your own placement id string. If you don't have a placement id or don't know how to get one, refer to the Getting Started Guide. Choose your build target to be device and run the above code, you should see something like this:

When running in the simulator, you need to set test mode to view test ads. Please refer to How to Use Test Mode for more information.

Step 2: Verify Impression and Click Logging

Optionally, you can add the following functions to handle the cases when the ad is shown, clicked or closed by users:

- (void)interstitialAdWillLogImpression:(FBInterstitialAd *)interstitialAd 
  NSLog(@"The user sees the add");
  // Use this function as indication for a user's impression on the ad.

- (void)interstitialAdDidClick:(FBInterstitialAd *)interstitialAd
  NSLog(@"The user clicked on the ad and will be taken to its destination");
  // Use this function as indication for a user's click on the ad.

- (void)interstitialAdWillClose:(FBInterstitialAd *)interstitialAd
  NSLog(@"The user clicked on the close button, the ad is just about to close");
  // Consider to add code here to resume your app's flow

- (void)interstitialAdDidClose:(FBInterstitialAd *)interstitialAd
  NSLog(@"Interstitial had been closed");
  // Consider to add code here to resume your app's flow

Step 3: Debugging When Ad Is Not Shown

Add and implement the following function in your View Controller implementation file to handle ad loading failures and completions:

- (void)interstitialAd:(FBInterstitialAd *)interstitialAd didFailWithError:(NSError *)error
  NSLog(@"Ad failed to load");

When there is no ad to show, the interstitialAd:didFailWithError: will be called with error.code set to 1001. If you use your own custom reporting or mediation layer you might want to check the code value and detect this case. You can fallback to another ad network in this case, but do not re-request an ad immediately after.

How to Test Audience Network Ad Using Test Mode

Audience Network SDK provides a way to request and show test ads. FBAdSettings provides a test mode for testing Audience Network ad. Here is how you can enable test mode:

When using Testflight to distribute and test your app, you will not be able to see real ads in those test builds. Instead, you will need to set test mode as shown below in order to get ads from Audience Network. Each time a Testflight-distributed app asks for the the Identifier for Advertisers (IDFA), it will get a different IDFA. Normally, IDFA remains constant for a device until a user resets it manually. But when a Testflight build asks for the IDFA from the operating system, it doesn’t get the "real" IDFA. Instead, it gets a "dummy" IDFA that changes each time the app asks for it.

To resolve this issue, you can turn on the test mode to allow the test ad to be shown.

Before loading an ad, add following line of code:

[FBAdSettings setLogLevel:FBAdLogLevelLog];
[FBAdSettings addTestDevice:@"HASHED_ID"];

You would see the following log message:

When testing your app with Facebook ad units,  
you must specify the device hashed ID to ensure the delivery of test ads, 
add the following code before loading an ad: `[FBAdSettings addTestDevice:@"HASHED_ID"]`
Test mode device hash: bd675f960298a92003630d76fa612b1706b745ab

Replace HASHED_ID with the test mode device hash printed in the log above.

When you are finished testing, you should turn off the test mode with following call:

//Replace HASHED_ID with the test mode device hash string printed in the log above. 
[FBAdSettings clearTestDevice:@"HASHED_ID"]; 

Next Steps

  • Submit your app for review.

  • As soon as we receive a request for an ad from your app or website, we'll review it to make sure it complies with Audience Network policies and the Facebook community standards. Learn more about our review process.

  • Explore our code samples which demonstrate how to use native ads. The NativeAdSample is available as part of the SDK and can be found under the FBAudienceNetwork/samples folder. Open the project with Xcode and run it either on a device or the simulator.

When using latest Xcode with Facebook Audience Network samples, Xcode will give signing error that the app id used in the sample app cannot be registered to your development team. You would need to change your bundle identifier to a unique string and try again.