Integrating Stand-Alone Ads in iOS

This guide walks you through all necessary steps to integrate stand-alone ads into your app.

If you have not done so already, please start with the Getting Started guide before reading on.

---

Integration

Overview

Follow these steps to integrate stand-alone ads into your app:

1. Prepare your UI
2. Prepare your UIViewController
3. Set up and request a stand-alone ad
4. Implement FAStandaloneAdDelegate
5. Implement resizing
6. Implement what to do after the stand-alone ad has been displayed

This will take between 60 and 120 minutes depending on your layout's complexity. This guide shows the relevant steps to integrate a simple stand-alone ad. For a more detailed example check the source code of the stand-alone example inside the demo app, which features a sample integration of a stand-alone ad as a pre-roll placement.

1. Prepare your UI

Choose a place in your UI, where you would like to integrate feed ads. You need a container view to hold a feed ad.

Create your container view, and prepare its UI to hold your feed ad.

2. Prepare your UIViewController

Create a property to hold your instance of FAStandaloneAd in your view controller. Make sure it is cancelled and cleaned up when the view controller disappears.

Using Objective-C:

@interface StandaloneAdViewController ()

@property (nonatomic, strong) FAStandaloneAd *standaloneAd;

@end


@implementation StandaloneAdViewController

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];

    [self.standaloneAd cancel];
    [self.standaloneAd.adView removeFromSuperview];
    self.standaloneAd.delegate = nil;
    self.standaloneAd = nil;
}

@end  

Using Swift:

class StandaloneAdViewController: UIViewController {
    var standaloneAd: FAStandaloneAd? = nil

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)

        standaloneAd?.cancel()

        standaloneAd?.adView.removeFromSuperview()
        standaloneAd?.delegate = nil
        standaloneAd = nil
    }
}

3. Set Up and Request a Stand-Alone Ad

To set up an instance of FAStandaloneAd, you first have to check the availability of the placement. If it is available, initialize your standalone ad with that placement ID. Finally, call load to have the SDK load an ad.

Placement ID?

You can choose placement IDs yourself. A placement ID should be named after the ad position inside your product. For example, if you want to display an ad inside a list of news articles, you could name it "ad-news-overview".
A placement ID may consist of lowercase a-z, 0-9, - and _. You do not have to manually create the placement IDs before using them. Just specify them within the code, and they will appear in the FeedAd admin panel after the first request. Learn more about Placement IDs and how they are grouped to play the same Creative

Using Objective-C:

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    if (self.standaloneAd) {
        return;
    }

    if ([FAStandaloneAd isAvailableForPlacementId:@"your-placement-id"]) {
        // Setup FAStandaloneAdConfig
        FAStandaloneAdConfig *config = [FAStandaloneAdConfig new];
        config.placementId = @"your-placement-id";

        // Setup your FAStandaloneAd instance
        self.standaloneAd = [[FAStandaloneAd alloc] initWithConfig:config];
        self.standaloneAd.delegate = self;

        [self.standaloneAd load];
    }
}

Using Swift:

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)

    if let _ = standaloneAd {
        return
    }

    if FAStandaloneAd.isAvailable("your-placement-id") {
        // Setup FAStandaloneAdConfig
        let config = FAStandaloneAdConfig()
        config.placementId = "your-placement-id"

        // Setup your FAStandaloneAd instance
        standaloneAd = FAStandaloneAd(config: config)
        standaloneAd?.delegate = self
        standaloneAd?.load()
    }
}

4. Implement FAStandaloneAdDelegate

Declare conformance to the protocol FAStandaloneAdDelegate and implement its methods in your view controller.

Stand-alone ads start playing as soon as the ad view of an FAStandaloneAd becomes visible in your UI. Add it to your container view, when the method standaloneAdDidFinishLoading: gets called.

Using Objective-C:

- (void)standaloneAdDidFinishLoading:(FAStandaloneAd *)standaloneAd {
    // Add ad view to container view
    UIView *adView = self.standaloneAd.adView;
    adView.frame = self.adContainerView.bounds;
    [self.adContainerView addSubview:adView];
}

Using Swift:

func standaloneAdDidFinishLoading(_ standaloneAd: FAStandaloneAd!) {
    // Add ad view to container view
    if let adView = standaloneAd.adView {
      adView.frame = adContainerView.bounds
      adContainerView.addSubview(adView)
    }
}

FAStandaloneAdDelegate

For a detailed description of the FAStandaloneAdDelegate and its methods see FAStandaloneAd Delegate Methods.

5. Implement Resizing

To guarantee a seamless integration into your UI and to prevent distractions by letterboxing, you should resize your container views in your UI to match the preferred size of a standalone ad.

The ad views of FAStandaloneAd are set up to adjust their sizes following the desired size, aspect ratio and scalability of the displayed ad. The default aspect ratio is 16:9.

Every time an FAStandaloneAd changes its size following those parameters, the delegate method standaloneAdDidChangeSize: gets called. To determine the perfect size for your container views, use - (CGSize) [FAStandaloneAd sizeForSuperviewSize:].

The method sizeForSuperviewSize: takes a parameter of type CGSize, into which you should pass the size of your container view. If either width or height of your container view is flexible, set it to CGFLOAT_MAX.

For example, in the case of an iPhone app with content that runs over the full width of the screen: When you integrate a feed ad here, you will most likely be limited by the width of the screen. However, your container view can be flexible in height. In this case, pass the width of the screen and set the height to CFLOAT_MAX, to have sizeForSuperviewSize: determine the perfect height for your container view.

Using Objective-C:

- (void)standaloneAdDidChangeSize:(FAStandaloneAd *) {
    CGSize preferredSize = [standaloneAd sizeForSuperviewSize:CGSizeMake(self.view.frame.size.width, CGFLOAT_MAX)];

    self.adContainerView.frame = ({
        CGRect frame = self.adContainerView.frame;
        frame.size   = preferredSize;
        frame;
    });

    self.adContainerView.center = self.view.center;
}

Using Swift:

func standaloneAdDidChangeSize(_ standaloneAd: FAStandaloneAd!) {
    let preferredSize = standaloneAd.size(forSuperview: CGSize(width: view.frame.size.width, height: CGFloat.greatestFiniteMagnitude))

    adContainerView.frame.size = preferredSize
    adContainerView.center = view.center
}

6. Implement What to Do after the Stand-Alone Ad Has Been Displayed

After an FAStandaloneAd has finished playing or got skipped, the delegate method standaloneAdDidFinishPlaying: gets called, to enable you to execute some code afterwards.

Instances of FAStandaloneAd cannot be reused. If you would like to show another standalone ad, you have to start over with a fresh instance of FAStandaloneAd.

It's a Wrap

Once you have completed all of the above steps, you should have a working stand-alone ads integration.

---

FAStandaloneAd Delegate Methods

Implement the delegate methods from FAStandaloneAdDelegate to be notified about any events and to customize its appearance:

• an ad has been loaded successfully

- (void)standaloneAdDidFinishLoading:(FAStandaloneAd *)standaloneAd;

• An ad has played through successfully

- (void)standaloneAdDidFinishPlaying:(FAStandaloneAd *)standaloneAd;

• Errors occured during loading or playback of an ad

- (void)standaloneAd:(FAStandaloneAd *)standaloneAd didFailWithError:(NSError *)error;

• An ad has changed its desired size

- (void)standaloneDidChangeSize:(FAStandaloneAd *)standaloneAd;

• An ad logged an impression

- (void)standaloneAdDidLogImpression:(FAStandaloneAd *)standaloneAd;

• Should a loading indicator be displayed for this standalone ad?

- (BOOL)standaloneAdShouldDisplayLoadingIndicator:(FAStandaloneAd *)standaloneAd;

• An ad has been clicked

- (void)standaloneAdWasClicked:(FAStandaloneAd *)standaloneAd;

• An ad has been skipped

- (void)standaloneAdWasSkipped:(FAStandaloneAd *)standaloneAd;

• An ad will leave the application to show its landing page after the user has clicked the ad

- (void)standaloneAdWillLeaveApplication:(FAStandaloneAd *)standaloneAd;

---

Ad Request Options

The class FAInterstitialAdConfig provides additional properties that allow you specify optional details about the context of an ad placement.

Property Name	Description
contentURL	iOS Universal Link for the screen where the ad will be displayed.
customParameters	Specify custom parameters to pass additional tracking data about the context of your placement. For example, this could be the category of a certain item an user viewed in your app.
placementType	Type of the placement. See FAPlacementType for available options.
webContentURL	Can be an iOS Universal Link or a regular website URL to the equivalent page on the publisher's website for the screen where the ad will be displayed.