Full-Screen Advertisements

Full-Screen advertisements are a new kind of advertisement introduced in iOS 4.3. Full-screen advertisements are implemented by the ADInterstitialAd class.

Full-Screen Advertising Concepts

The full-screen advertisements provided by iAd have two common use cases:

Before you embark on adding full-screen advertisements to your app, be sure you understand the expected behavior from your app for each use case you intend to introduce in your app. The iAdInterstitialSuite sample includes examples of both use cases.

Presenting a Full-Screen Advertisement as Content

In this use case, the advertisement is displayed alongside other content provided by your app. Your content is organized into screen-sized pages and placed into scroll view configured to scroll the visible content area on page boundaries. Figure 3-1 illustrates this concept. The scroll view contains four views. Three views hold app content, while the fourth view contains a full-screen advertisement. The user can swipe left or right to navigate through the content. If the user taps on the iAd, the advertisement launches its rich media experience.

When your app displays full-screen advertisements alongside its own content, iAd blocks other behaviors in your app only when the user chooses to interact with an ad.

Figure 3-1  A full-screen advertisement as a modeless page

Presenting a Full-Screen Advertisement as a Transitional Screen

In this use case, the advertisement appears as a transitional screen between two other screens displayed by your app. Figure 3-2 shows an example of this behavior. For example, the game sample in iAdInterstitialSuite displays an advertisement after the players finish playing a match and before allowing them to play another match. When an advertisement is displayed as a transitional page, it is displayed modally, which allows the user to interact with the ad. To continue to the next screen in your app, the user explicitly taps the ad’s close button.

Figure 3-2  A full-screen advertisement as a modal page

The Programming Model For Full-Screen Ads Differs From Banner Views

The programming model for an ADInterstitialAd object is similar to that of an ADBannerView object, but there are a couple of important differences.

An ADInterstitialAd object is not actually a view. The ad object manages downloading its content, and it may create views to display the ad. However, to display the full screen ad, your app explicitly presents the advertisement. When your app displays a modal advertisement, it presents the advertisement using a view controller. In contrast, to add the advertisement as a modeless page, your app creates a custom view with the appropriate dimensions and adds it to the view hierarchy associated with a view controller. Then, your app presents the ad using this view. iAd uses your view to host the ad’s content.

The second major difference between a banner view and an full-screen advertisement is that the full-screen advertisement does not cycle through new content. An full-screen ad object loads a single advertisement; once that content expires, your app must release the ad object. Each time your app needs to show a new advertisement, it must explicitly create a new ad object.

The Lifecycle of an Full-Screen Ad Object

Figure 3-3 shows the process your app uses to implement full-screen advertising in your app. The lifecycle begins when your app creates an ADInterstitialAd object and sets its delegate. The delegate is necessary because the ad object sends messages to the delegate at critical points in its lifecycle. Figure 3-3 shows most of the essential critical delegate methods.

Figure 3-3  How your app interacts with a full-screen advertisement.

After the ad object is created, it automatically downloads an advertisement from the iAd App Network. When the ad object finishes downloading the advertisement, it signals your delegate. Your app takes the loaded ad and presents it to the user. The actual process your app uses to present the advertisement varies depending on whether you want to present it modally or as a modeless page.

If the touches the ad, your app is informed so that it can pause any activities that might interfere with the advertisement — this procedure is similar to the procedure a banner view uses to inform your app of a user’s interests. After your app suspends its activities, the ad object loads the interactive advertisement from the iAd App Network and displays it to the user. After the user finishes interacting with the ad, the ad object notifies your delegate so that your app can resume the activities it paused.

At some point after creating the ad object, the ad’s content expires. The content may expire at different times, depending on how the ad is presented and how the user interacts with your app. When an ad object’s content is unloaded, your delegate is called. Your app is required to release the ad object, but it often performs other tasks at this time. For example, the ADGame example found in iAdInterstitialSuite creates a new ad object to start the cycle over again, while the ADMagazine example removes shifts other content pages to fill the space vacated by the ad’s view.

Next, you’ll learn how to implement each step of the diagram above.

Creating an Ad Object

Listing 3-1 shows a common implementation for creating a full-screen ad object. There are no other properties on the ad object to configure.

Listing 3-1  Creating a full-screen ad object

interstitial = [[ADInterstitialAd alloc] init];
interstitial.delegate = self;

After the ad object is created, it automatically starts downloading an advertisement from the iAd App Network. Your app determines whether the ad object has successfully loaded its content in one of two ways:

  • Your app can read the ad object’s loaded property, which states whether the object has a loaded advertisement. Do not regularly poll this value to determine if the ad is ready to be presented. However, it may be useful for your app to check the value of this property at the moment it wants to transition to a new screen of content, particularly when displaying the advertisement is optional. For example, the ADGame example in iAdInterstitialSuite tests the loaded property on the ad object after a match finishes. If the value of this property is YES, then it displays the ad. If the value is NO, then the game skips advertising and begins a new match.

  • Your delegate can implement the interstitialAdDidLoad: method to be informed as soon as the ad object loads the ad content. Typically, your delegate method presents the ad. Implementing a delegate method is best used when you want to insert the ad into your app’s content as soon as the ad loads. You should not use this method to immediately present a modal ad to the user, as that would interrupt the task the user was performing at the moment the ad content loaded.

Presenting an Ad

After the ad loads its content, you can present the advertisement to the user. The process you use depends on whether you plan to present it modally or as a modeless page of content.

Presenting an Ad Modally

An ad is presented modally by a view controller object. Your app creates a view controller and calls the ad object’s presentFromViewController: method, passing in the view controller as the only parameter. Listing 3-2 shows a minimal implementation of this behavior. In practice, because the ad is displayed modally on top of your app, your app may want to pause other activities now, before presenting the ad.

Listing 3-2  Presenting the Ad Modally

if (interstitial.loaded)
    [interstitial presentFromViewController:self];

After presenting the ad, your view controller is no longer the topmost view controller; the ad object creates a view controller and uses it to present the ad. The ad’s view controller is removed after the user dismisses the ad.

Presenting an Ad as a Page of Content

Your app presents an ad modelessly by creating a view to host the ad. This view object must follow the following rules:

  • The view must be contained in the view hierarchy of a view controller object; this restriction is identical to the behavior required of banner views.

  • The width of the view must equal the width of the screen.

  • The height of the view must be no smaller than 113 points smaller than the height of the screen and no larger than the height of the screen. For example, when an iPad is in landscape orientation, the height of the screen is 768 points; the hosting view must therefore be between 655 and 768 points in height, inclusive.

  • If your view controller supports orientation changes, the view must be resized to match the new orientation.

  • The view must be capable of hosting subviews.

Listing 3-3 shows a typical implementation. It uses an index for the new page to calculate the page’s frame, allocates a view with that frame, and adds it to the scroll view. Then, it calls the ad’s presentInView: method to associate the ad with the new view.

Listing 3-3  Adding an ad page to a scroll view

CGRect interstitialFrame = scrollView.bounds;
 interstitialFrame.origin = CGPointMake(interstitialFrame.size.width * index, 0);
 UIView *view = [[UIView alloc] initWithFrame:interstitialFrame];
 [scrollView addSubview:view];
[interstitial presentInView:view];

Handling User Interactions with the Ad

When a user taps on the ad, it triggers an action. The behavior is identical to that of a banner view.

Beginning an Advertising Action

Before the ad triggers an action, it calls the delegate’s interstitialAdActionShouldBegin:willLeaveApplication: method. Your delegate method performs two tasks:

  • It decides whether to allow the action to be triggered.

  • If the action will cover your app’s user interface, this method pauses any activities that require user interaction.

Your delegate should return YES from this method if it wants to allow the action to be triggered. It can prevent the action from being triggered by returning NO. Your app should always allow actions to be triggered unless it cannot safely do so.

  • If the willLeave parameter is YES, then your app is moved to the background after it returns from this delegate method. This process is described in Defining a Document-Based Data Model.

  • If the willLeave parameter is NO, iAd is going to cover the app’s user interface after it returns from this delegate method. Your app should disable sounds, animations or other activities that require user interaction. For example, a real-time game should pause gameplay before allowing the action to be triggered.

Listing 3-4 shows the structure for how your app should implement this delegate method:

Listing 3-4  Allowing an action to be triggered

- (BOOL)interstitialAdActionShouldBegin:(ADInterstitialAd *)banner willLeaveApplication:(BOOL)willLeave
    NSLog(@"Interstitial ad is beginning an ad action");
    BOOL shouldExecuteAction = [self allowActionToRun]; // your app implements this method
    if (!willLeave && shouldExecuteAction)
        // insert code here to suspend any services that might conflict with the advertisement
    return shouldExecuteAction;

Completing an Advertising Action

If the full-screen ad displayed the rich media ad inside your app, it calls your delegate’s interstitialAdActionDidFinish: method after the ad finishes. Your implementation of this method should restore any services paused by your app when the action started.

Canceling an Advertising Action

When the full-screen ad executes its action, your app continues to receive events. Your app can read the actionInProgress property of the ad object to determine whether an action is executing. While the ad is running, your app should scale back its activities and avoid actions that require interaction with the user.

If an event occurs that demands the user’s attention, you can invoke the ad object’s cancelAction method to cancel the advertising action. The action ends immediately. Your delegate’s interstitialAdActionDidFinish: is not called, but your app is still expected to restart any services it paused before the ad action started.

An Ad Object’s Contents Only Persist For a Limited Period of Time

The content provided by an ad object eventually expires. When it does, ad object unloads the contents and calls your delegate. The exact circumstances where an ad’s contents expire are not under the control of your app. Here are some common cases where the contents may expire:

  • If the ad object encounters an error, it reports the error to your app and then unloads its contents.

  • If an ad object is not presented by a view or a view controller, its contents expire after a period of 5 to 15 minutes.

  • If an ad object is presented modelessly, its contents also expire after a period of 5 to 15 minutes. If the view associated with the ad object is offscreen when the content expires, the ad object unloads its contents immediately. If the advertisement is visible to the user when the contents expire, the contents are unloaded as soon as the view moves offscreen.

  • If an ad object is presented modally, its contents expire immediately after the user dismisses the ad.

Listing 3-5 shows the minimum behavior your app must implement after the ad object unloads its content. Your app may need to perform additional tasks. For example, a modal app might create a new ad object so that it has an ad to display next time it needs an advertisement. A modeless app might remove the view that hosted the ad, and shift other views to cover the gap in the displayed content. Both of these behaviors are demonstrated by the examples in the iAdInterstitialSuite sample.

Listing 3-5  Releasing an ad object after it unloads its content

- (void)interstitialAdDidUnload:(ADInterstitialAd *)interstitialAd
   [interstitialAd release];

Handling Full-Screen Ad Errors

When a full-screen ad object encounters an error, the ad object calls the delegate’s interstitialAd:didFailWithError: method to allow your app to process the error. Full-screen ad objects share error codes with the ADBannerView class. Your app should not display the error to the user. The minimum response when an error occurs is to release the ad object. As with the case when an ad object unloads its content, you may want to perform other actions.

Listing 3-6  Logging full-screen ad errors

- (void)interstitialAd:(ADInterstitialAd *)interstitialAd didFailWithError:(NSError *)error
    NSLog(@"interstitialAd <%@> recieved error <%@>", interstitialAd, error);
    [interstitialAd release];

Most errors returned from a full-screen ad object can be handled equally. The exception is when a full-screen ad object returns ADErrorConfigurationError to your app. A configuration error indicates that you have not properly set up iAd for your app in iTunes Connect.