Full-Screen Advertisements

Presenting a Full-Screen Advertisement as Content

In this use case, the advertisement is displayed alongside other content provided by your application. 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 application 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 application displays full-screen advertisements alongside its own content, iAd blocks other behaviors in your application only when the user chooses to interact with an ad.

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 application. 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 application, the user explicitly taps the ad’s close button.

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 Network. Your application determines whether the ad object has successfully loaded its content in one of two ways:

• Your application 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 application 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 application’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.

if (interstitial.loaded)

{

    [interstitial presentFromViewController:self];

}

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.

- (BOOL)interstitialAdActionShouldBegin:(ADInterstitialAd *)banner willLeaveApplication:(BOOL)willLeave

{

    NSLog(@"Interstitial ad is beginning an ad action");

    BOOL shouldExecuteAction = [self allowActionToRun]; // your application implements this method

    if (!willLeave && shouldExecuteAction)

    {

        // insert code here to suspend any services that might conflict with the advertisement

    }

    return shouldExecuteAction;

}

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 application. Here are some common cases where the contents may expire:

• If the ad object encounters an error, it reports the error to your application 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 application must implement after the ad object unloads its content. Your application may need to perform additional tasks. For example, a modal application might create a new ad object so that it has an ad to display next time it needs an advertisement. A modeless application 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 application to process the error. Full-screen ad objects share error codes with the ADBannerView class. Your application 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 application. A configuration error indicates that you have not enabled iAd for your application in iTunes Connect; ads are served to your application only after you enable iAd.