Adding In-stream Video Ads to your iOS app

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.

Requirements

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

Implementation

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;

@end

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
{
    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)adViewDidLoad:(FBInstreamAdView *)adView
{
    NSLog(@"Ad is loaded and ready to be displayed");

    // 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)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. 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:

[FBAudienceNetworkLog/FBAdSettings:94] 
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.