Thumbnail Ad

This article will go through all the steps required to display a Thumbnail Ad in your application.

Thumbnail Ads are small rectangle ads that are displayed as overlays to your application content. They are closable and draggable by the user, and can be used to (i) monetize your application through new incremental inventories and (ii) push cross-promotion campaigns.

Requirements

You have registered an application on your Ogury Dashboard. If not, please refer to the Getting Started section before the next steps.

Step 1: Create a Thumbnail Ad ad unit

• Create a Thumbnail Ad ad unit.
• Copy the Ad unit id as you will need this information later to finish the integration.

In all the following code samples, we will refer to this Ad unit id by using the string AD_UNIT_ID.

Step 2: Load a Thumbnail Ad

The Ogury SDK provides the OguryThumbnailAd object that lets you load, display and control your Thumbnail Ad.

Instantiate a Thumbnail Ad

• Declare an OguryThumbnailAd instance variable in the ViewController where you want to display a Thumbnail Ad:

Swift

var thumbnailAd: OguryThumbnailAd?

Objective-C

@property (nonatomic, strong) OguryThumbnailAd *thumbnailAd;

• In the viewDidLoad method of the ViewController, instantiate the Thumbnail Ad:

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    
    thumbnailAd = OguryThumbnailAd(adUnitID: "AD_UNIT_ID")
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
}

OguryThumbnailAd takes the following parameter:

• an adUnitID: the Ad unit id of the Thumbnail Ad. If you do not have one yet, you can refer to the first step to create it.

Load a Thumbnail Ad

To start loading an ad, call the load method :

Swift

thumbnailAd?.load()

Objective-C

[self.thumbnailAd load];

The ad is loaded with a default max size of 180x180 points. The max size can be changed by following the instructions in this section.

Since it may take a few seconds to fetch the ad resources (video, image, ...) from the network, you should call the load method as soon as possible after getting the user's consent.

Ideally, you should implement one of the two following examples depending on your use case:

• Call the load method right after the ask method in the ViewController that also collects the consent:

Swift

import UIKit
import OgurySdk
import OguryAds
import OguryChoiceManager

class ViewController: UIViewController {

    var thumbnailAd: OguryThumbnailAd?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()
        Ogury.start(with: configuration) 
        
        thumbnailAd = OguryThumbnailAd(adUnitID: "AD_UNIT_ID")
        thumbnailAd?.load()
    }   
}

Objective-C

#import <UIKit/UIKit.h>
#import <OgurySdk/Ogury.h>
#import <OguryAds/OguryAds.h>
#import <OguryChoiceManager/OguryChoiceManager.h>

@interface ViewController : UIViewController

@property (nonatomic, strong) OguryThumbnailAd *thumbnailAd;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    OguryConfigurationBuilder *configurationBuilder = [[OguryConfigurationBuilder alloc] initWithAssetKey:@"OGY-XXXXXXXXXXXX"];
    [Ogury startWithConfiguration:[configurationBuilder build]];
    
    self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
    [self.thumbnailAd load];   
}

@end

• Call the load method in the viewDidLoad of your other ViewController:

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    
    thumbnailAd = OguryThumbnailAd(adUnitID: "AD_UNIT_ID")
    thumbnailAd?.load()
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];

    self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitID:@"AD_UNIT_ID"];
    [self.thumbnailAd load];
}

Additionally, if you want to follow the lifecycle of the Thumbnail Ad, you can register a delegate.

Step 3: Show a Thumbnail ad

To display the ad, call the show method:

Swift

thumbnailAd?.show()

Objective-C

[self.thumbnailAd show];

Thumbnail Ads are displayed bottom-right aligned, with a margin of 20 points on the right and 150 points on the bottom. More details on how to set the thumbnail position can be found in this section.

If the show method fails to show the ad, the following delegate is called didFailOguryThumbnailAdWithError .

If you encounter this callback, you can check the error codes section below to understand the error and get some advice on how to solve the issue.

By default the Thumbnail Ad remains on screen while the user is navigating between View Controllers of your application. A Thumbnail Ad is displayed in a ViewController if bundle identifier of the ViewController corresponds to the main bundle of application.

You can customize where Thumbnail Ads are displayed in this section.

Step 4: Test your integration

Ogury exclusively serves ads to users who have given consent. It is essential to have responded to a valid TCFv2 consent form before conducting any tests.

As our algorithm works with personified targeting, you may not receive any ad while testing your application.

You can test your integration by adding the suffix _test to your interstitial ad unit id, for more details go to Test your implementation page.

Note that if you have just registered your application in the Ogury Dashboard, it will take around 15 minutes until you can successfully load an ad.

If you are not able to display any Thumbnail Ad, we recommend you to log every delegate on your OguryThumbnailAd to follow the lifecycle of the Thumbnail Ad.

If you encounter the didFailOguryThumbnailAdWithErrorcallback , you can check the error codes section below to understand the error and get some advice on how to solve the issue.

Examples

Show an ad to a user entering your application

You may want to show a Thumbnail Ad to a user as soon as they enter your application.

You can achieve this behavior by using the didLoadOguryThumbnailAd delegate to display the Thumbnail Ad as soon as it is displayable. In the viewDidLoad of the first ViewController you can append the following lines:

Swift

import UIKit
import OgurySdk
import OguryAds

class ViewController: UIViewController {

    var thumbnailAd: OguryThumbnailAd?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        thumbnailAd = OguryThumbnailAd(adUnitID: "AD_UNIT_ID")
        thumbnailAd?.delegate = self
        thumbnailAd?.load(CGSize(width: maxWidth, height: maxHeight))
    }
}

extension ViewController: OguryThumbnailAdDelegate {

    func didLoad(_ thumbnail: OguryThumbnailAd) {
        thumbnailAd?.show(CGPoint(x: leftMargin, y: topMargin))
    }
}

Objective-C

#import <UIKit/UIKit.h>
#import <OgurySdk/Ogury.h>
#import <OguryAds/OguryAds.h>

@interface ViewController : UIViewController <OguryThumbnailAdDelegate>

@property (nonatomic, strong) OguryAdsThumbnailAd *thumbnailAd;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
    self.thumbnailAd.delegate = self;
    [self.thumbnailAd load:CGSizeMake(maxWidth, maxHeight)];
}

- (void)didLoadOguryThumbnailAd:(OguryThumbnailAd *)thumbnail {
    [self.thumbnailAd show:CGPointMake(leftMargin, topMargin)];
}

@end

You can also use this snippet to display the Thumbnail Ad when the user reaches a given ViewController.

Advanced Topics

Customize Thumbnail Ad size

In order to control the Thumbnail Ad size, call load method with maxWidth and maxHeight parameters:

Swift

thumbnailAd?.load(CGSize(width: maxWidth, height: maxHeight))

Objective-C

[self.thumbnailAd load:CGSizeMake(maxWidth, maxHeight)];

maxWidth and maxHeight parameters define the maximum size that the Thumbnail Ad will take on the screen. Both values are in points.

We recommend to use maxWidth = 180 and maxHeight = 180 to improve the readability of the content of the Thumbnail Ad.

Example: when given maxWidth= 180 and maxHeight= 180, the Ogury SDK may decide to display a 16:9 video ad inside. In this case the Thumbnail Ad size will be 180x101 points to match the ratio of the 16:9 video.

The following constraints apply on the values you can pass to these parameters:

• maxWidth and maxHeight must not be greater than the size of the screen.

• maxWidthandmaxHeight must be greater than or equal to 101 points.

• longest side, either maxWidth or maxHeight, must be greater than or equal to

  180 points.

Check if a Thumbnail Ad is loaded

Call the following method to check if a Thumbnail Ad is ready to be displayed:

Swift

thumbailAd?.isLoaded()

Objective-C

[self.thumbnailAd isLoaded];

If you want to be informed when the ad is ready to be displayed, you can also register a delegate and implement the didLoadOguryThumbnailAd method.

Customize Thumbnail Ad position

To set the Thumbnail Ad position, call the show method with OguryRectCorner and OguryOffset parameters:

Swift

thumbnailAd?.show(with: rectCorner, margin: OguryOffset(x: xMargin, y: yMargin))

Objective-C

[self.thumbnailAd showWithOguryRectCorner:rectCorner
                                   margin:OguryOffsetMake(xMargin, yMargin)];

The show method takes the following parameter:

• rectCorner: the corner based on which the Thumbnail Ad will be positioned. The OguryRectCorner enum has the following values:

  • OguryTopRight

  • OguryTopLeft

  • OguryBottomLeft

  • OguryBottomRight

• anOguryOffset: the distance from the corner to the Thumbnail Ad

  • xMargin: distance from the x axis to the Thumbnail Ad. Value must be in points.

  • yMargin: distance from the y axis to the Thumbnail Ad. Value must be in points.

Customize where the Thumbnail Ad is displayed

Thumbnail Ad remains on screen while the user is navigating between ViewController of your application.

By default, a Thumbnail Ad is displayed in an ViewController only if this bundle identifier are the main bundle of application.

You can override these default settings using whitelists and blacklists.

Whitelist bundles

You can increase the number of whitelisted bundles where Thumbnail Ads are displayed and stay on screen. This can be useful if you have ViewController provided by a library like a game engine, in this case you need to whitelist the bundle associated to this library.

Call the setWhitelistBundleIdentifiers method to whitelist bundles:

Swift

thumbnailAd?.setWhitelistBundleIdentifiers(["com.example.bundle", "com.example.bundle2"])

Objective-C

[self.thumbnailAd setWhitelistBundleIdentifiers:@[@"com.example.bundle", @"com.example.bundle2"]];

Blacklist View Controllers

You can prevent Thumbnail Ads from being displayed on a given ViewController by using the setBlacklistViewControllors method:

Swift

thumbnailAd?.setBlacklistViewControllers([NSStringFromClass(TermsAndConditionsViewController.classForCoder()), NSStringFromClass(SettingsViewController.classForCoder())])

Objective-C

[self.thumbnailAd setBlacklistViewControllers:@[NSStringFromClass([TermsAndConditionsViewController class]), NSStringFromClass([SettingsViewController class])]];

When the user navigates to an ViewController that is not in a whitelisted bundle or that is explicitly blacklisted, the Thumbnail Ad is hidden and paused. It comes back on the screen when the user navigates back to a ViewController that is allowed.

Delegate

The Ogury SDK provides OguryThumbnailAdDelegate to listen to the lifecycle of a Thumbnail Ad instance.

To register a OguryThumbnailAdDelegate, add the following code just after instantiating the OguryThumbnailAd :

Swift

thumbnailAd?.delegate = self

Objective-C

self.thumbnailAd.delegate = self;

The OguryThumbnailAdDelegate exposes the following methods:

Methods	Definition
didLoadOguryThumbnailAd	The SDK is ready to display the ad provided by the ad server.
didDisplayOguryThumbnailAd	The ad has been displayed on the screen.
didClickOguryThumbnailAd	The as has been clicked by the user.
didCloseOguryThumbnailAd	The ad has been closed by the user.
didFailOguryThumbnailAdWithError	The ad failed to load or display. The error parameter contains the reason of the failure. All error codes are detailed in the section below.
didTriggerImpressionOguryThumbnailAd	The ad has triggered an impression.

Error codes

When an ad fails to load or to be displayed, the SDK will call the didFailOguryTAdWithError callback with one of error code defined in OguryAdsError:

Name	Value	Definition
OguryCoreErrorTypeNoInternetConnection	0	No Internet connection The device has no Internet connection. Try again once the device is connected to the Internet.
OguryAdsAdDisabledError	2001	Ad disabled Ad serving has been disabled for this placement/application.
OguryAdsProfigNotSyncedError	2002	Profig not synchronized An internal SDK error has occurred.
OguryAdsAdExpiredError	2003	Ad expired The loaded ad is expired. You must call the show method within 4 hours after the load.
OguryAdsSdkInitNotCalledError	2004	SDK init not called The Ogury.start() method has not been called before a call to the load or show methods.
OguryAdsAnotherAdAlreadyDisplayedError	2005	Another ad already displayed Another ad is already displayed on the screen.
OguryAdsAssetKeyNotValidError	2006	SDK init failed An error occurred during the initialization of the SDK.
OguryAdsNotAvailableError	2008	Ad not available The server returns no ads.
OguryAdsCantShowAdsInPresentingViewControllerError	2010	A view controller is already being presented Only one view controller may be presented at a time.
OguryAdsUnknownError	2011	Unknown error An unknown error occurred.