Your application implements a banner view delegate to handle common events:
Respond when the user taps the banner.
Respond when the banner view loads an advertisement.
Respond when the banner view encounters an error.
If your application supports orientation changes, your view controller must also change the banner view’s size when the orientation changes.
Banner views use a delegate to communicate events to your application. Although you are not required to implement a delegate, your application almost always provides one to respond to banner events. A typical pattern is to implement these methods in your custom view controller class.
Before the banner view triggers an action, it calls the delegate’s bannerViewActionShouldBegin:willLeaveApplication: method. Your delegate method performs two tasks:
It decides whether to allow the action to be triggered.
If the action will cover your application’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 application should always allow actions to be triggered unless it cannot safely do so.
If the willLeave parameter is YES, then your application is going to be moved to the background after it returns from this delegate method. This process is described in “Understanding an Application’s States and Transitions” in iOS Application Programming Guide in the iOS Application Programming Guide.
If the willLeave parameter is NO, iAd is going to cover the application’s user interface after it returns from this delegate method. Your application 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.
“Allow the action to trigger” shows the structure for how your application should implement this delegate method:
Listing 2-1 Allowing an action to be triggered
- (BOOL)bannerViewActionShouldBegin:(ADBannerView *)banner willLeaveApplication:(BOOL)willLeave |
{ |
NSLog(@"Banner view 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; |
} |
If the banner view covered the application’s user interface, it calls the delegate’s bannerViewActionDidFinish: method after the interface is restored. Your implementation of this method should restore any services paused by your application.
Important: If your application was moved into the background because the willLeave parameter was YES, then the application’s user interface is never covered by the banner view and your application does not receive a call to bannerViewActionDidFinish:. However, if your interface was covered by the banner view, your application could still be moved into the background later, either because the advertisement launched another application or because the user chose to do so. In all cases, if your user interface was covered by the banner view, it is uncovered and your delegate’s bannerViewActionDidFinish: is invoked before your application moves to the background. Because the application may be moving into the background, your delegate should return quickly from its bannerViewActionDidFinish: method.
The iAd framework makes it easy to adopt an asynchronous model and only display an ad when one is available. This approach is recommended as it is more user-friendly than the synchronous model, where the user might be presented with an empty banner view until an ad is returned.
When a banner view has a new advertisement to display, it calls the delegate's bannerViewDidLoadAd: method. This method is called even if the banner view is not currently part of the view hierarchy. Your application can use this method to attach the view to a view hierarchy or to make the banner view visible. For example, “Animating in the banner view after a new advertisement is loaded” demonstrates a delegate that implement a property to track whether the banner view is visible. If the view is not visible when it receives a new advertisement, the delegate animates the view onto the screen.
Listing 2-2 Animating in the banner view after a new advertisement is loaded
- (void)bannerViewDidLoadAd:(ADBannerView *)banner |
{ |
if (!self.bannerIsVisible) |
{ |
[UIView beginAnimations:@"animateAdBannerOn" context:NULL]; |
// assumes the banner view is offset 50 pixels so that it is not visible. |
banner.frame = CGRectOffset(banner.frame, 0, 50); |
[UIView commitAnimations]; |
self.bannerIsVisible = YES; |
} |
} |
Once you display the ad banner, you should leave it visible for at least 30 seconds, unless the user requests a new page or screen as described in your agreement under “Minimum Rendering Time”.
If an error occurs, the banner view calls the delegate’s bannerView:didFailToReceiveAdWithError: method. The most common response when the banner delegate receives an error is to hide the banner view. “Removing a banner view when advertisements are not available” uses the same property and hides the banner view after receiving an error. Even after an error, the banner view continues to try to download new advertisements, so the combination of these two delegate methods displays the banner view when advertisements are available, and hides it when they are not.
Listing 2-3 Removing a banner view when advertisements are not available
- (void)bannerView:(ADBannerView *)banner didFailToReceiveAdWithError:(NSError *)error |
{ |
if (self.bannerIsVisible) |
{ |
[UIView beginAnimations:@"animateAdBannerOff" context:NULL]; |
// assumes the banner view is at the top of the screen. |
banner.frame = CGRectOffset(banner.frame, 0, -50); |
[UIView commitAnimations]; |
self.bannerIsVisible = NO; |
} |
} |
When the banner view covers your application’s user interface to perform its action, your application continues to receive events. Your application can read the isBannerViewActionInProgress property of the banner view to determine whether a banner action is executing. Your application should scale back its activities and avoid actions that require interaction with the user.
If an event occurs that requires the user’s attention, you can invoke the banner view’s cancelBannerViewAction method to cancel the advertising action. The action ends, and the banner view calls the delegate’s bannerViewActionDidFinish: method.
Important: Canceling an advertising action, or preventing an advertising action from executing, can potentially impact the advertisements your application receives, and the revenue you receive through showing advertisements. Your application should cancel the action only when it urgently requires the user’s attention. For example, an application that provides Voice over Internet Protocol (VoIP) might cancel an advertisement when the application receives a call from another user.
Applications that intend to resize the banner view after creation should configure the requiredContentSizeIdentifiers property with the set of all possible sizes the view can take in your application. The most common reason to support multiple sizes in your application is to support orientation changes. If your application changes its interface in response to an orientation change, it should resize the banner view to fit the new orientation.
Listing 2-4 shows how a view controller could configure the banner view to download advertisements that have both portrait and landscape images:
Listing 2-4 Configuring a banner view to handle landscape and portrait orientations
self.bannerView.requiredContentSizeIdentifiers = [NSSet setWithObjects: ADBannerContentSizeIdentifier320x50, ADBannerContentSizeIdentifier480x32, nil]; |
When an orientation change occurs, your view controller’s willRotateToInterfaceOrientation:duration: method changes the banner size.
Listing 2-5 Responding to an orientation change
- (void)willRotateToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation duration:(NSTimeInterval)duration |
{ |
if (UIInterfaceOrientationIsLandscape(toInterfaceOrientation)) |
self.bannerView.currentContentSizeIdentifier = |
ADBannerContentSizeIdentifier480x32; |
else |
self.bannerView.currentContentSizeIdentifier = |
ADBannerContentSizeIdentifier320x50; |
} |
When your application configures the requiredContentSizeIdentifiers property with more than one banner size, the iAd service only downloads advertisements that provide images for all of the specified sizes. This allows the banner view to seamlessly change the displayed advertisement when your application changes the size of the view. As this restricts the ads available to the banner view, you should only configure the requiredContentSizeIdentifiers property with sizes that are actually used by your application.
Note: The current version of iAd only supports portrait and landscape advertisements, so this restriction may not make much sense today. In fact, Apple expects most advertisers to provide both portrait and landscape views, so including both in the requiredContentSizeIdentifiers property should not significantly limit the inventory of advertisements. When additional sizes are added in the future, including unused content sizes may unnecessarily restrict your application to a smaller subset of advertisements.
While you are developing your application, iAd Network sends test advertisements to your application. To assist you in validating your implementation, the iAd Network occasionally returns errors to test your error handling code. You can also test your error handling support by turning your device’s wireless capability off.
To receive advertisements from iAd Network, you need to enable the advertising service for your application. Information on how to enable advertising in your shipping application will be available before the release of iOS 4.0.
iAd Network automatically displays the correct ad depending on the application binary:
Application | Audience | Displayed Ads |
|---|---|---|
Developer build | Developer | iAd Network serves test ads. |
Ad-hoc distribution build | Beta Testers | iAd Network serves test ads. |
Signed Distribution build | End Users | iAd Network serves live ads if you signed the iAd Network Agreement and enabled advertising for your application. |
Last updated: 2010-05-27