Adding In-Stream Video Ads to your iOS App

In-stream Video monetization for Audience Network is available to select publishers on an invitation-only basis.

Video publishers can now use Audience Network's In-stream solution to deliver video ads to their global audience across mobile and desktop environments in pre-roll and mid-roll settings. Follow this guide to display this type of ad unit for iOS-based video content. For monetizing your web video content with in-stream ads, see the Web implementation guide. For in-stream video ads within Android mobile apps, see the Android implementation guide. Or see a list of available types.


Please refer to the "In-Stream Video Requirements" section of the Design Guidelines for Audience Network Ads.


This guide will walk you through implementing in-stream video ads on iOS following these steps:

Step 1: Apply for Audience Network In-stream Video

Step 2: Create Placements

Step 3: Load and Show In-stream Video Ad

Step 4: Handle Impressions and Clicks

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

Step 1: Apply for Audience Network In-stream Video

Go to your app dashboard and from the Audience Network menu on the left side of the screen, select Apps and Websites. Then, go to the "Apply for in-stream video ads" section. Please review the Requirements and, if applicable, click on the Apply button and follow the on screen instructions.

Step 2: Create Placements

Audience Network offers 4 types of ad units: banner, interstitial (app only), native ads, and In-stream Video. You will see In-stream Video as a Display Format type after you have been approved for In-stream Video. Each ad unit in your app or website is identified using a unique placement ID. The first step in adding an ad unit is to create this identifier.

Click the Create Ad Placement button to start creating placement IDs to test in your video player.

In the Create Ad Placement form, enter a Name for your placement, information on how to invoke the ad in the Steps to Trigger Ad, and select In-stream Video as the Display Format.

Create a separate placement for each location in your website or app where you want to show ads. This will allow better insights tracking and performance calibration.

If you are using Audience Network In-stream Video for multiple properties such as desktop, mobile web, and mobile apps, be sure to name your placements accordingly (e.g. desktop_placement_1 and iOS_placement_1) as this will allow you to differentiate your placements and performance across platforms.

Once you click Save, you will see your new placement listed on the Placements tab.

To learn more about creating placements, please refer to our FAQ. To maximize your revenue, check out best practices for the Performance Optimization tool.

Step 3: Load and Show In-stream Video Ad

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

Now, in your ViewController header file, import the SDK header, declare that you implement the FBInstreamAdViewDelegate protocol and add an instance variable for the interstitial ad unit:

#import <UIKit/UIKit.h>
@import FBAudienceNetwork;

@interface MyViewController : UIViewController <FBInstreamAdViewDelegate>

@property (nonatomic, strong) FBInstreamAdView *adView;


Initialize and load an in-stream ad view when it's time to show an ad. This can also be done ahead of time, to pre-cache an ad. In place of YOUR_PLACEMENT_ID, use the id of the in-stream video placement you created earlier.

- (void)loadInstreamAd
    // Instantiate an InstreamAdView object. 
    // NOTE: the placement ID will eventually identify this as your App, you can ignore it for
    // now, 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).
    self.adView = [[FBInstreamAdView alloc] initWithPlacementID:YOUR_PLACEMENT_ID];
    self.adView.delegate = self;
    [self.adView loadAd];

Now that you have added the code to load the ad add the necessary delegate implementation to display the ad, and handle failures.

When there is no ad to show, the adView:didFailWithError: will be called with error.code set to 1001. You should detect this and return to the content.

- (void)showInstreamVideoAd
    if (self.adView && self.adView.isAdValid) {
        // The ad can now be added to the layout and shown
        self.adView.frame = self.view.bounds;
        self.adView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
        [self.view addSubview:self.adView];
        [self.adView showAdFromRootViewController:self];

- (void)adViewDidLoad:(FBInstreamAdView *)adView
    NSLog(@"Ad is loaded and ready to be displayed");

    [self showInstreamVideoAd];

- (void)adViewDidEnd:(FBInstreamAdView *)adView
    NSLog(@"Ad ended");
    [self.adView removeFromSuperview];
    self.adView = nil;

    // The app should now proceed to content

- (void)adView:(FBInstreamAdView *)adView didFailWithError:(NSError *)error
    NSLog(@"Ad failed: %@", error.localizedDescription);
    [self.adView removeFromSuperview];
    self.adView = nil;

    // The app should now proceed to content

Once you run the above code and present the in-stream ad, you should see something like this:

Step 4: Handle Impressions and Clicks

Optionally, you can add the following functions to handle ad clicks and impressions:

- (void)adViewDidClick:(FBInstreamAdView *)adView
    NSLog(@"Ad clicked");
    // Called when the user clicks on the "Learn More" button.

- (void)adViewWillLogImpression:(FBInstreamAdView *)adView
    NSLog(@"Ad impression");
    // Called when the ad logs an impression

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. Normally, the Identifier for Advertisers (IDFA) remains constant for a device until a user resets it manually. However, each time a Testflight-distributed app asks for the IDFA, it will get a different IDFA.

To resolve this issue, you can turn on 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