Introduction

Introduction to ad formats and placements

Introduction

This guide contains the implementation of the various advertising formats organized as placements in the app. The app shall create a separate “Placement” through AATKit for every position of an advertisement inside the app that either:

• Has a different ad format.

• Shall be controlled separately from others.

Concept of Placements

Placements are the entry point for loading and receiving ads. AATKit provides a separate protocol for each ad format. Creating the placement should be done by calling AATSDK public APIs. Once you have created the placement, the later communication callbacks like loading and displaying ads will happen via the created placement instance.

Rules for Placement Names

In order to work with the Gravite backend, placement names must be constant at runtime, i.e. they shouldn’t change on each app start. Note that any placement instance is supposed to be reused. Do not create a placement instance for each ad you want to display. Keep the number of placements low.

The placement name cannot start nor end with a space, and can only contain the following characters:

Character	Unicode	Name
	U+0020	Space
()	U+0028 + U+0029	Parentheses
-	U+002D	Hyphen-Minus
.	U+002E	Full Stop
/	U+002F	Solidus
0-9	U+0030 – U+0039	Digits
:	U+003A	Colon
A-Z	U+0041 – U+005A	(ASCII) Uppercase Letters
_	U+005F	Low Line
a-z	U+0061 – U+007A	(ASCII) Lowercase Letters

In order to keep track of the performance of your placement over time, your placement name should not change as long as you use Gravite with your app unless you plan a substantial rework of your ad integration.

Placement Types

Placement Type	Explanation
Sticky Banner Placement	Classic banner integration. The Banner is positioned either above or below the fold at a sticky position and usually keeps being shown all the time. Typically, sticky banners refresh automatically every 30 seconds. The Banner also sticks to its initial size all the time. Mostly used in gaming apps.
Multi-Size Banner Placement	Like the sticky banner, but can change its size with every loaded ad.
Banner Cache	Convenient interface for banner ads that are displayed in moving (scrollable) feeds. It automatically takes care of loading and caching ads, so that the app can consume a banner any time a dedicated ad slot gets scrolled into the visible area - without latency. One banner cache is dedicated to populate all the ad slots of a feed. Also, it reports ad spaces automatically when the app consumes ads. Supports different and multiple banner sizes. A good choice for content based apps like e.g. news, weather, or classifieds apps.
Infeed Banner Placement	Barebone interface for banner ads. We recommend using this placement type only, if you need complete control over loading and caching strategies, selling strategy at every single ad slot. Needs more integration efforts than AATBannerCache (e.g. manual caching, and manual reporting of ad spaces). Supports different and multiple banner sizes. Please contact our support, if you plan to integrate this placement type.
Fullscreen Placement (Interstitial)	A fullscreen interstitial. Typically pre-loaded and presented on user interaction. Can be used in any kind of app.
AppOpen Placement	A special fullscreen interstitial that can be presented during the app’s start instead of a typical splash screen. The ad will contain the app’s logo to give it an app-specific look. Can be used in any kind of app.
Rewarded Video Placement	A special fullscreen interstitial that (typically only) plays videos. Once the videos have been watched to the end, the user can be rewarded by the app. Typically used in gaming apps to provide users with in-app currency as an alternative to real currency payment.
Native Ad Placement	Native ads in general behave like (in-feed) banners. But they don’t consist of just one image. Instead, they provide a couple of assets that the app developer can (and must) arrange to their liking. Most relevant for news or classified apps.

Communication with Placements

All the communication with placements is being done via placement instances. The app will also receive different kinds of callbacks for ad loads, displays and other events via the placement-specific delegates. So, each placement type has its own delegate that will notify the publisher about the different events.

Placement	Corresponding Delegate
AATStickyBannerPlacement	AATStickyBannerPlacementDelegate
AATMultiSizeBannerPlacement	AATMultiSizeBannerPlacementDelegate
AATBannerCache	AATBannerCacheDelegate
AATInfeedBannerPlacement	AATInfeedBannerPlacementDelegate
AATFullscreenPlacement	AATFullscreenPlacementDelegate
AATAppOpenAdPlacement	AATAppOpenPlacementDelegate
AATRewardedVideoPlacement	AATRewardedVideoPlacementDelegate
AATNativeAdPlacement	AATNativePlacementDelegate

All callback methods have AATPlacement as a parameter to let you verify which placement fired a specific callback. This will be needed if you have one class implementing two types of placements delegates (e.g. AATStickyBannerPlacementDelegate and AATFullscreenPlacementDelegate), in this case, you can check the placement name to verify which placement fired this callback.

Swift

// An example of aatHaveAd(:) callback that can belong to 
// either AATStickyBannerPlacementDelegate or AATFullscreenPlacementDelegate
func aatHaveAd(placement: AATPlacement) {
    if placement.getName() == "<fullscreen_placement_name>" {
        // The fullscreen placement has loaded a new ad
    } else if placement.getName() == "<banner_placement_name>" {
        // The banner placement has loaded a new ad
    }
}

Objective-C

// An example of aatHaveAd(:) callback that can belong to 
// either AATStickyBannerPlacementDelegate or AATFullscreenPlacementDelegate
- (void)aatHaveAdWithPlacement:(id<AATPlacement>)placement {
    if ([[placement getName] isEqualToString:@"Fullscreen_placement_name"]) {
        // The fullscreen placement has loaded a new ad
    } else if ([[placement getName] isEqualToString:@"banner_placement_name"]) {
        // The banner placement has loaded a new ad
    }
}

Handling (multiple) View Controllers

It is required to set the currently active view controller for AATKit before starting to request ads from placements. You should set the view controller in your view controller viewDidAppear(_ animated: Bool) lifecycle method.

Placements will not start loading ads before having the current view controller passed to AATKit.

Set the Current View Controller

Swift

AATSDK.controllerViewDidAppear(controller: self)

Objective-C

[AATSDK controllerViewDidAppearWithController:self];

Remove the Current View Controller

Swift

AATSDK.controllerViewWillDisappear()

Objective-C

[AATSDK controllerViewWillDisappear];