ADBannerView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/iAd.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
ADBannerView.h
ADBannerView_Deprecated.h
Related sample code

Overview

The ADBannerView class provides a view that displays banner advertisements to the user. When the user taps a banner view, the view triggers an action programmed into the advertisement. For example, an advertisement might show a movie, present a modal advertisement, or launch Safari to show a webpage. Your application is notified when an action starts and stops, but does not otherwise interact with the advertisement. You receive revenue when users see new advertisements or trigger their actions.

The banner view’s delegate is called when a banner view cycles to show a new advertisement as well as when the user interacts with the banner view. For example, your delegate typically pauses your application’s activities when a user taps an advertisement and restores those activities when the user finishes interacting with the advertisement.

A banner view must always use one of the standard sizes defined in “Content Size Identifiers.” This is to ensure that the advertisement is drawn correctly. You configure the banner view’s requiredContentSizeIdentifiers property with the set of possible sizes your view is allowed to use in your application. To change the size of the banner view, do not set the bounds directly; instead set the currentContentSizeIdentifier property to one of the size identifiers included in that set. You can retrieve the actual dimensions that a particular identifier equates to on a specific device by calling the sizeFromBannerContentSizeIdentifier: class method.

Subclassing Notes

The ADBannerView class provides a self-contained view. Your application should not subclass ADBannerView, nor should your application attempt to change the behavior of the banner view. For example, your application should never add subviews to a banner view.

Tasks

Managing Ad Types

Setting and Getting the Delegate

Configuring the Advertising Shown in a Banner View

Resizing a Banner View (Deprecated)

Determining If a Banner View Is Showing an Advertisement

Banner Actions

Properties

adType

The ad type of the banner view.

@property (nonatomic, readonly) ADAdType adType
Availability
  • Available in iOS 6.0 and later.
Declared In
ADBannerView.h

advertisingSection

Reserved for future use.

@property(nonatomic, copy) NSString *advertisingSection
Discussion

This property is reserved for future use.

Availability
  • Available in iOS 4.0 and later.
Declared In
ADBannerView.h

bannerLoaded

A Boolean value that states whether the banner view has downloaded an advertisement. (read-only)

@property(nonatomic, readonly, getter=isBannerLoaded) BOOL bannerLoaded
Discussion

Banner views automatically download new advertisements in the background. This property returns YES if an advertisement is loaded; NO otherwise.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
ADBannerView.h

bannerViewActionInProgress

A Boolean value that states whether the banner is currently executing an user-triggered action. (read-only)

@property(nonatomic, readonly, getter=isBannerViewActionInProgress) BOOL bannerViewActionInProgress
Discussion

Advertisements have an action that is triggered when the user taps the banner. Some actions remain in the application, covering the application’s user interface until the action completes. The value of this property is YES when such an action is running; otherwise it is NO.

Your application should avoid polling this property. Instead, implement the delegate methods to detect when an action begins or ends.

Availability
  • Available in iOS 4.0 and later.
Declared In
ADBannerView.h

delegate

The delegate of the banner view.

@property(nonatomic, assign) id<ADBannerViewDelegate> delegate
Discussion

The banner view delegate is notified when events related to the banner view and current ad occur, such as when a new ad is loaded, when errors occur while fetching ads, or when banner actions begin and end.

Availability
  • Available in iOS 4.0 and later.
Declared In
ADBannerView.h

Instance Methods

cancelBannerViewAction

Cancels an executing banner view action.

- (void)cancelBannerViewAction
Discussion

A banner view action can cover your application’s user interface. However, your application continues to run, and receives events normally. If your application receives an event that requires the user’s attention, it can programmatically cancel the action and uncover its interface by calling cancelBannerViewAction. Canceling actions frequently can cause a loss of revenue for your application.

Availability
  • Available in iOS 4.0 and later.
Declared In
ADBannerView.h

initWithAdType:

Initializes a banner view with the specified ad type.

- (id)initWithAdType:(ADAdType)type
Parameters
type

The type of banner view to configure the receiver as.

Return Value

A newly-configured banner view of the specified ad type.

Availability
  • Available in iOS 6.0 and later.
Related Sample Code
Declared In
ADBannerView.h

Constants

Content Size Identifiers

These strings are used to identify the size of an advertisement.

extern NSString * const ADBannerContentSizeIdentifier320x50;
extern NSString * const ADBannerContentSizeIdentifier480x32;
extern NSString * const ADBannerContentSizeIdentifierPortrait;
extern NSString * const ADBannerContentSizeIdentifierLandscape;
Constants
ADBannerContentSizeIdentifier320x50

Indicates that the banner view is 320 points by 50 points in size. This size is used on iPhone for portrait advertisements.

Available in iOS 4.0 and later.

Deprecated in iOS 4.2.

Declared in ADBannerView_Deprecated.h.

ADBannerContentSizeIdentifier480x32

Indicates that the banner view is 480 points by 32 points in size. This size is used on iPhone for landscape advertisements.

Available in iOS 4.0 and later.

Deprecated in iOS 4.2.

Declared in ADBannerView_Deprecated.h.

ADBannerContentSizeIdentifierPortrait

Indicates that the banner view is in portait mode. The exact size of the portait view is dependent on the iOS device the advertisement is displayed on. On iPhone, a portrait banner is 320 points by 50 points in size. On iPad, a portrait banner is 768 points by 66 points in size.

Available in iOS 4.2 and later.

Deprecated in iOS 6.0.

Declared in ADBannerView_Deprecated.h.

ADBannerContentSizeIdentifierLandscape

Indicates that the banner view is in landscape mode. The exact size of the view is dependent on the iOS device the advertisement is displayed on. On iPhone, a landscape banner is 480 points by 32 points in size. On iPad, a landscape banner is 1024 points by 66 points in size.

Available in iOS 4.2 and later.

Deprecated in iOS 6.0.

Declared in ADBannerView_Deprecated.h.

Special Considerations

To resize a banner view, use sizeThatFits: on the banner view, specifying the bounds of the view that contains the banner view. Resize the banner view with the returned size. The banner view will be sized to the correct width and height of the current device and orientation. The following code snippet shows a possible implementation:

ADBannerView *myBannerView = <#Get a banner view#>;
UIView *myContainingView = <#Get the containing view#>;
 
NSSize newBannerSize = [myBannerView sizeThatFits:myContainingView];
[myBannerView setBounds:newBannerSize];

See ADAdTypeBanner for a list of sizes.

See iAdSuite for a full example of this, including how to support resizing on older versions of iOS.

ADErrorDomain

This constant defines the iAd framework error domain.

extern NSString * const ADErrorDomain;
Constants
ADErrorDomain

Indicates an error occurred in iAd.

Available in iOS 4.0 and later.

Declared in ADBannerView.h.

ADError

Error codes for the iAd error domain.

typedef enum : NSInteger {
   ADErrorUnknown = 0,
   ADErrorServerFailure = 1,
   ADErrorLoadingThrottled = 2,
   ADErrorInventoryUnavailable = 3,
   ADErrorConfigurationError = 4,
   ADErrorBannerVisibleWithoutContent = 5,
   ADErrorApplicationInactive = 6
   ADErrorAdUnloaded = 7,
} ADError;
Constants
ADErrorUnknown

Indicates that an unknown or unexpected error occurred.

Available in iOS 4.0 and later.

Declared in ADBannerView.h.

ADErrorServerFailure

Indicates that the connection to the advertisements server failed.

Available in iOS 4.0 and later.

Declared in ADBannerView.h.

ADErrorLoadingThrottled

Indicates that the download from the advertisements server is currently being throttled.

Available in iOS 4.0 and later.

Declared in ADBannerView.h.

ADErrorInventoryUnavailable

Indicates that no advertisements are currently available to download.

Available in iOS 4.0 and later.

Declared in ADBannerView.h.

ADErrorConfigurationError

Indicates that your application has not been configured to receive advertisements. Check your application’s configuration on iTunes Connect. This error is not received when your application is running in Sandbox.

Available in iOS 4.1 and later.

Declared in ADBannerView.h.

ADErrorBannerVisibleWithoutContent

Indicates that the banner is visible, but no advertisement is shown. Your application must always hide the banner when it does not have an advertisement to display.

Available in iOS 4.1 and later.

Declared in ADBannerView.h.

ADErrorApplicationInactive

Indicates that ad content is not available because the application is not currently active.

Available in iOS 4.3 and later.

Declared in ADBannerView.h.

ADErrorAdUnloaded

The ad being displayed in the banner was unloaded. This might happen when an ad expires or when an ad is moved from a non-visible banner to a visible banner.

Available in iOS 6.0 and later.

Declared in ADBannerView.h.

Availability
  • Available in iOS 4.0 and later.
Declared In
ADBannerView.h

ADAdType

Constants that indicate the types of ads.

typedef enum : NSInteger,
) {
   ADAdTypeBanner,
   ADAdTypeMediumRectangle
} ADAdType;
Constants
ADAdTypeBanner

A device-width banner ad.

The banner height varies with device type and orientation as follows:

UI Idiom and Orientation

Ad Height

phone, portrait

50 points

phone, landscape

32 points

pad, portrait or landscape

66 points

Available in iOS 6.0 and later.

Declared in ADBannerView.h.

ADAdTypeMediumRectangle

A pad-only 320x250 point ad, based on the International Advertising Bureau’s “Medium Rectangle” Interactive Marketing Unit.

Available in iOS 6.0 and later.

Declared in ADBannerView.h.