Wiki
Clone wikiAATKit iOS / Proposal / BannerCache2
Banner Cache
Banner Cache
Banner Cache
AATKit supports BannerCache - a special tool to help you integrate in-feed banners. It will automatically preload banner ads and try to have a defined amount of banners available for immediate handout to the app whenever they are needed.
Constructor: - (instancetype)initWithConfiguration:(AATBannerCacheConfiguration *) configuration
where:
configuration
- The configuration object that contains all needed configurations.
AATBannerCacheConfiguration object:
You can use any of the following 2 constructors:
- (instancetype)initWithPlacementName:(NSString *)placementName
cacheSize:(int)cacheSize
viewController:(UIViewController *) viewController;
placementName
- The name of the banner placement that will be created. The placement will be created by the cache and should not be created manually.
cacheSize
- Defines how many preloaded banners should be available in the cache. Max value: 5
viewController
- Defines the UIViewController that will display the ads
- (instancetype)initWithPlacementName:(NSString *)placementName
delegate:(nullable id<AATBannerCacheDelegate>)delegate
cacheSize:(int)cacheSize
shouldCacheAdditionalAdAtStart:(BOOL)shouldCacheAdditionalAdAtStart
adRequest:(AATAdRequest *)adRequest
minimumDelay:(NSTimeInterval) minimumDelay;
placementName
- The name of the banner placement that will be created. The placement will be created by the cache and should not be created manually.
delegate
- Optional cache delegate that will be called when the first banner ad gets loaded. Can be null. It will be notified when the first banner is loaded and ready to be consumed.
cacheSize
- Defines how many preloaded banners should be available in the cache. Max value: 5
shouldCacheAdditionalAdAtStart
- A BOOL defines if the cache should load additional ad at the beginning. False by default.
adRequest
- AATAdRequest with configurations.
minimumDelay
- NSTimeInterval minimum delay between two banner consumptions.
Consume Banners
- (nullable UIView *)consume
- returns an instance of UIView to be used within the app. Can return nil if there are no banners available in the cache. Also automatically counts an ad space. BannerCache will no longer hold any references to returned banners, and they need to be destroyed manually by the app.
In addition to the standard consume()
method, additional one: - (nullable UIView *)consume:(BOOL) forceConsume;
, allowing to consume banners ignoring the minimum delay set in BannerCacheConfiguration is available
- (void)destroy
- Destroys the BannerCache, clearing all preloaded banner ads and canceling pending reload requests. For proper memory management, it needs to be called when the BannerCache is no longer needed. Destroyed BannerCache can no longer be used.
Optional methods
- (void)updateRequestConfiguration:(AATAdRequest *)adRequest shouldRefresh:(BOOL)shouldRefresh
- updates the configuration that will be used when requesting new banners.
adRequest
- new AATAdRequest configuration, can not be null
shouldRefresh
- true if the whole cache should be re-loaded with new banner request configuration, false if new configuration should only be used for new requests.
- (void)setCacheDelegate:(nullable id<AATBannerCacheDelegate>)delegate
- sets the optional CacheDelegate.
Usage Example
Swift:
#!swift class BannerCacheViewController: UIViewController { ... override func viewWillAppear(_ animated: Bool) { super.viewWillAppear(animated) let request = AATAdRequest(delegate: self, viewController: self) request.bannerSizes = [NSNumber(value: AATKitAdType.banner320x53.rawValue)] let configuration = AATBannerCacheConfiguration(placementName: "<PLACEMENT_NAME>", cacheSize: 3, viewController: self) configuration.adRequest = request configuration.shouldCacheAdditionalAdAtStart = true configuration.delegate = self bannerCache = AATBannerCache(configuration: configuration) } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) bannerCache?.viewWillDisappear() bannerCache?.destroy() bannerCache = nil } ... } // MARK: AATBannerCacheDelegate extension BannerCacheViewController: AATBannerCacheDelegate { func firstBannerLoaded() { // Reload the corresponding view to display the banner if let bannerView = bannerCache?.consume() { // bannerView is ready to be used } } }
#!objective-c @interface BannersViewController () <AATBannerCacheDelegate> @property AATBannerCache *bannerCache; @end @implementation BannersViewController ... - (void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; AATAdRequest* adRequest = [[AATAdRequest alloc] initWithViewController:self]; NSArray *sizesArray = @[[NSNumber numberWithInt:AATKitBanner320x53]]; adRequest.bannerSizes = [[NSSet alloc] initWithArray:sizesArray]; AATBannerCacheConfiguration *configuration = [[AATBannerCacheConfiguration alloc] initWithPlacementName:@"<PLACEMENT_NAME>" cacheSize:3 viewController:self]; configuration.adRequest = adRequest; configuration.shouldCacheAdditionalAdAtStart = YES; configuration.delegate = self; self.bannerCache = [[AATBannerCache alloc] initWithConfiguration:configuration]; } - (void)viewWillDisappear:(BOOL)animated { [super viewWillDisappear]; /// Please call the following only if you are done with this BannerCache instance [self.bannerCache viewWillDisappear]; [self.bannerCache destroy]; self.bannerCache = nil; } ... #pragma mark - AATBannerCacheDelegate - (void)firstBannerLoaded { UIView *bannerView = [self.bannerCache consume]; if (bannerView != nil) { // bannerView is ready to be used } } @end
Configuring the ad request
You may configure the requested banner sizes, add keyword targeting, a content targeting url or a delegate to the ad request.
Objective-C:
#!objective-c AATAdRequest* adRequest = [[AATAdRequest alloc] initWithDelegate:self viewController:self]; adRequest.bannerSizes = [[NSSet alloc] initWithArray:@[@(AATKitBanner320x53), @(AATKitBanner300x250)]]; adRequest.targetingKeywords = @{@"news-category" : @"technology"}; adRequest.contentTargetingURL = [NSURL URLWithString:@"http://example.com/similar/content"]; adRequest.delegate = self;
#!swift let adRequest = AATAdRequest(delegate: self, viewController: self) adRequest.bannerSizes = [NSNumber(value: AATKitAdType.banner320x53.rawValue), NSNumber(value: AATKitAdType.banner300x250.rawValue)] adRequest.targetingKeywords["news-category"] = NSString(string: "technology") adRequest.contentTargetingURL = URL(string: "http://example.com/similar/content")
Listening to statistics events
AATKitStatisticsDelegate is an optional delegate you can implement if you need to get notified about statistics events. and pass it to placement while creating it using this method
- (instancetype)initWithConfiguration:(AATBannerCacheConfiguration *)configuration andStatisticsDelegate:(nullable NSObject <AATKitStatisticsDelegate>*)statisticsDelegate
Sample App
Updated