Banner Cache

Integrate banner cache

The banner cache is a special tool to help you integrate infeed banners more easily. It will wrap an infeed banner and use it to automatically preload banner ads aiming to have a defined amount of banners available for an immediate handout to the app whenever they are needed. Compared to using the infeed banner directly, it comes with the following

Pros

• Automatically caches banner ads, so your app can consume and present them whenever needed (i.e. when the dedicated feed cell enters the visible area of the screen)

• Automatically takes care of correct ad space counting (it counts an ad space whenever you try to consume an ad because we assume, you only consume an ad when you need to present it right now).

Cons

• You cannot specify specific configurations for the ad request (like e.g. keyword targeting X for the first ad request and keyword targeting Y for the next one and so on) and control the load cycle of a specific ad.

We strongly recommend using the banner cache instead of the infeed banner, unless you actually need to control the ad request configuration separately per loaded ad (e.g. in very specific targeting scenarios per ad position in the feed).

Create Banner Cache

Java

BannerCacheConfiguration configuration = new BannerCacheConfiguration("<PLACEMENT_NAME>", 3);
// Alternatively, you can use self-adjusting cache size by passing just the name:
// BannerCacheConfiguration configuration = new BannerCacheConfiguration("<PLACEMENT_NAME>");
configuration.setDelegate(this);
BannerCache bannerCache = AATKit.createBannerCache(configuration);

Kotlin

Banner Cache Configuration

BannerCacheConfiguration can be configured with the following:

• placementName defines the name of the internally wrapped placement (e.g. important for the statistics on the Dashboard).

• size defines how many preloaded banners should be available in the cache. Max value: 5.

Starting with AATKit 3.15, you can skip the size parameter to let banner the cache try to automatically adjust its size.

We recommend starting with a cache size of 1 and testing, if all your ad spaces get filled. If not, increase the cache size by 1 and repeat your test. The general rule should be: use the smallest possible cache size to achieve good fill rates but avoid waisting ads at the same time. Waisted ads may influence paid prices in a negative way.

• delegate an instance of BannerCacheDelegate that will notify you when the first banner is loaded and ready to be consumed.

• requestConfiguration an instance of BannerRequest that will be used internally for requesting banner ads from the InfeedBannerPlacement.

• retryInterval represents the retry interval (in seconds) for failed ad load requests.

• minimumDelay represents the minimum delay between two banner consumptions in seconds. Useful to prevent consuming too many ads when the user is fast scrolling. Default: 1 s.

• shouldCacheAdditionalAdAtStart defines if the cache should load an additional ad at the beginning. false by default.

Configure Banner Request

See the banner request configuration for infeed banner placement.

Java

BannerRequest request = new BannerRequest(this);
Map<String, List<String>> targeting = new HashMap<>();
targeting.put("key", Arrays.asList("value1", "value2"));
request.setTargetingInformation(targeting);
Set<BannerSize> allowedBannerSizes = new HashSet<>();
allowedBannerSizes.add(BannerSize.Banner320x53);
allowedBannerSizes.add(BannerSize.Banner300x250);
request.setBannerSizes(allowedBannerSizes);
request.setContentTargetingUrl("http://example.com/similar/content");
OR
request.setMultiContentTargetingUrls(Arrays.asList("URL1", "URL2"));

Kotlin

Consume Banners

To consume banners, use the consume method. It returns an instance of BannerPlacementLayout to be used within the app. Can return null 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.

If the force parameter is true, the minDelay parameter of the BannerCacheConfiguration instance will be ignored.

Java

BannerPlacementLayout bannerView = bannerCache.consume();

Kotlin

The ads are served from the cache using a 'first in, first out' (FIFO) approach, meaning the oldest loaded banners are displayed first.

Destroy old banner

When you no longer need a banner, you have to destroy it manually by removing it from your view and calling the "destroy" method:

Java

[remove loadedMultiSizeBanner from your layout]
oldBanner.destroy();

Kotlin

Destroy no longer needed BannerCache

For proper memory management, BannerCache needs to be destroyed when is no longer needed. The destroy() method destroys the BannerCache, clearing all preloaded banner ads and canceling pending reload requests. Destroyed BannerCache can no longer be used.

Java

bannerCache.destroy();

Kotlin

(Optional) Cache Status Delegate

To listen to the banner cache status, implement the CacheStatusDelegate

Java

bannerCache.setCacheStatusDelegate(delegate);

Kotlin

Complete Code Example

Java

private BannerCache bannerCache;

private void setUpBannerCache() {
    BannerCacheConfiguration configuration = new BannerCacheConfiguration("<PLACEMENT_NAME>", 3);
    configuration.setDelegate(this);

    BannerRequest request = new BannerRequest(this);
    request.setContentTargetingUrl("http://example.com/similar/content");
    Map<String, List<String>> targeting = new HashMap<>();
    targeting.put("key", Arrays.asList("value1", "value2"));
    request.setTargetingInformation(targeting);
    Set<BannerSize> allowedBannerSizes = new HashSet<>();
    allowedBannerSizes.add(BannerSize.Banner320x53);
    allowedBannerSizes.add(BannerSize.Banner300x250);
    request.setBannerSizes(allowedBannerSizes);

    configuration.setRequestConfiguration(request);

    BannerCache bannerCache = AATKit.createBannerCache(configuration);
}

@Override
protected void onResume() {
    super.onResume();
    // [IMPORTANT] Notify AATKit about activity lifecycle
    AATKit.onActivityResume(this);
}

@Override
protected void onPause() {
    // [IMPORTANT] Notify AATKit about activity lifecycle
    AATKit.onActivityPause(this);
    super.onPause();
}

@Override
protected void onDestroy() {
    bannerCache.destroy();
    super.onDestroy();
}

@Override
public void firstBannerLoaded() {
    // Get the banner view
    BannerPlacementLayout bannerView = bannerCache.consume();
    if (bannerView != null) {
        //place the loaded banner in your layout
    }
}

Kotlin