Integrating Banner Cache

Index:

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:

#!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:

#!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

for more info about it please refer to AATKitStatisticsDelegate Guide

Wiki

AATKit iOS / AATKit2 / AATKit Integration Banner Cache