Thumbnail

This guide explains how to integrate Thumbnail ads using the Ogury SDK in your iOS application.

Prerequisites

Before proceeding, make sure you have completed the steps outlined in the Getting Started section:

Registered your app and created ad units in the Ogury Publisher Platform.
Retrieved your asset key and ad unit IDs.
Updated your app-ads.txt file.

Before integrating any ad format, ensure you have completed the SDK Setup:

Integrated and initialized the Ogury SDK in your app.

Load a Thumbnail ad

To load a Thumbnial ad:

Instantiate an OguryThumbnailAd object with a valid Thumbnial ad unit ID.
Call its load() method.

By default, the ad loads with a maximum size of 180x180 points. If needed, you can customize the maximum size by following the guidelines provided in Customizing Thumbnail ad size section.

import UIKit
import OguryAds

class ViewController: UIViewController {
    private(set) var thumbnailAd: OguryThumbnailAd!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        thumbnailAd = OguryThumbnailAd(adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        thumbnailAd.load()
    }
}

#import "ViewController.h"
#import <OguryAds/OguryAds.h>

@interface ViewController ()
@property (nonatomic, retain) OguryThumbnailAd *thumbnailAd;
@end

@implementation ViewController

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

@end

The OguryThumbnailAd initializer takes the following parameters:

Your Ogury ad unit ID for the Thumbnail ad. It is in the form of a UUID, which consists of a 36-character string formatted as follows: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where each x represents a hexadecimal digit. See Ad Unit Creation if you haven’t generated one.
If you are building a mediation adapter, an additional parameter, OguryMediation which should be instantiated with:
- name: the name of the mediation.
- version: the version of the mediation SDK.

self.thumbnailAd = OguryThumbnailAd(
    adUnitId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
    mediation: OguryMediation(name: "your mediation name", 
                              version: "your mediation SDK version")
)

OguryMediation *mediation = [[OguryMediation alloc] initWithName:@"your mediation name" version:@"your mediation SDK version"];
self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitId:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" mediation:mediation];

Register for callbacks

You can monitor the lifecycle of your Thumbnail ad by implementing the OguryThumbnailAdDelegate protocol. This delegate provides real-time updates on key events, such as successful ad loading, display or errors.

To use it, set your class as the delegate of OguryThumbnailAd and implement the necessary methods. This ensures timely notifications, allowing you to manage the ad experience effectively.

If the thumbnailAd:didFailWithError callback is triggered, refer to the Ad Error handling section below for detailed information on troubleshooting.

override func viewDidLoad() {
    super.viewDidLoad()
    thumbnailAd = OguryThumbnailAd(
        adUnitID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    )
    thumbnailAd.delegate = self
    thumbnailAd.load()
}

// Called when the ad is loaded and ready to be shown
func thumbnailAdDidLoad(_ thumbnailAd: OguryThumbnailAd) {
    // Call show() to display the ad
}

// Called when an impression is recorded
func thumbnailAdDidTriggerImpression(_ thumbnailAd: OguryThumbnailAd) {
    // Track ad performance here
}

// Called when the user clicks on the ad
func thumbnailAdDidClick(_ thumbnailAd: OguryThumbnailAd) {
    // Handle ad click tracking here
}

// Called when the ad is closed
func thumbnailAdDidClose(_ thumbnailAd: OguryThumbnailAd) {
    // Resume app flow after ad is closed
}

// Called when the ad fails to load or display
func thumbnailAd(_ thumbnailAd: OguryThumbnailAd, 
        didFailWithError error: OguryAdError) {
    switch error.type {
        case .load:
            // Handle loading error
        case .show:
            // Handle display error
    }
}

 - (void)viewDidLoad {
    [super viewDidLoad];
    self.thumbnailAd = [[OguryThumbnailAd alloc] initWithAdUnitID:@"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"];
    [self.thumbnailAd load];
}

// Called when the ad is loaded and ready to be shown
- (void)thumbnailAdDidLoad:(OguryThumbnailAd *)thumbnailAd {
    // call [interstitialAd show] to display the ad
}

// Called when an impression is recorded
- (void)thumbnailAdDidTriggerImpression:(OguryThumbnailAd *)thumbnailAd { {
    // Track ad performance here
}

// Called when the user clicks on the ad
- (void)thumbnailAdDidClick:(OguryThumbnailAd *)thumbnailAd {
    // Handle ad click tracking here
}

// Called when the ad is closed
- (void)thumbnailAdDidClose:(OguryThumbnailAd *)thumbnailAd {
    // Resume app flow after ad is closed
}

// Called when the ad fails to load or display
- (void)thumbnailAd:(OguryThumbnailAd *)thumbnailAd 
   didFailWithError:(OguryAdError *)error  {
    switch (error.type) {
        case OguryAdErrorTypeLoad:
            // Handle loading error
        case OguryAdErrorTypeShow:
            // Handle display error
    }
}

Show a Thumbnail ad

To display an loaded Thumbnail ad, invoke the show() method on the instantiated OguryThumbnailAd object.

By default, Thumbnail ad is aligned to the bottom-right corner, maintaining a margin of 20 points from the right edge and 150 points from the bottom.

Additionally, a Thumbnail ad is shown in a ViewController only if its bundle identifier matches the main bundle of the application. For details on how to customize these default settings using whitelists and blacklists, please see the Customizing Thumbnail ad display section.

if thumbnailAd.isLoaded {
    // The ad is loaded and ready to be displayed.
    thumbnailAd.show(in: self)
} else {
    // The ad is not loaded yet. Handle this situation appropriately.
}

if (self.thumbnailAd.isLoaded) {
    [self.thumbnailAd showAdInViewController:self];
}

The show() method takes the following parameter:

A reference to the ViewController where the Thumbnail ad will be presented.

Always check isLoaded before calling show(), unless you are calling directly from the thumbnailAdDidLoad callback

Additional Resources

Integration Testing

Ensure your implementation works correctly by testing with sample ads and verifying ad behavior.

See the Testing Guide.

Ad Error Handling

If Interstitial ads fail to load or display, we recommend implementing and logging the callbacks from OgurythumbnailAdDelegate to track the full ad lifecycle. Pay particular attention to the thumbnailAd:didFailWithError callback, which returns an OguryAdError object containing detailed information about the failure.

For a full list of error types, refer to the Ad Error Handling page.

Migration Guide

Still using Ogury SDK v4? Follow our step-by-step migration guide to smoothly upgrade to v5 and take advantage of the latest features and improvements.

View the Migration Guide.

Advanced Integration

Customizing Thumbnail ad size

To adjust the size of a Thumbnail ad, use the load() method with maxWidth and maxHeight parameters:

thumbnailAd.loadWithMaxSize(CGSize(width: maxWidth, height: maxHeight))

[thumbnailAd loadWithMaxSize:CGSizeMake(maxWidth, maxHeight)];

The maxWidth and maxHeight parameters specify the maximum dimensions, in points, that the Thumbnail ad will occupy on the screen.

For optimal readability and ad display quality, we recommend setting maxWidth = 180 and maxHeight = 180. For instance, if you set these values and the Ogury SDK decides to show a 16:9 video ad, the Thumbnail ad will resize to 180x101 points to maintain the 16:9 ratio.

Constraints:

maxWidth and maxHeight cannot exceed the device’s screen size.
Both maxWidth and maxHeight must be at least 101 points.
The longest side, either maxWidth or maxHeight, must be at least 180 points.

Customizing Thumbnail ad display

Thumbnail ads remain visible while users navigate between ViewControllers in your application.

By default, a Thumbnail ad is shown in a ViewController only if its bundle identifier matches the main bundle of the application. However, you can customize these default settings using whitelists and blacklists.

Whitelist Bundles

You can expand the list of whitelisted bundles where Thumbnail ads can be displayed and remain on-screen. This is particularly useful if your app includes ViewControllers provided by a library, such as a game engine. In this case, you will need to whitelist the associated bundle.

To whitelist bundles, call the setWhitelistBundleIdentifiers method:

thumbnailAd.setWhitelistBundleIdentifiers(["BUNDLE_TO_WHITELIST"])

[thumbnailAd setWhitelistBundleIdentifiers:@[@"BUNDLE_TO_WHITELIST"]];

Blacklist View Controllers

To prevent Thumbnail ads from being displayed in specific ViewControllers, use the setBlacklistViewControllers method:

thumbnailAd.setBlacklistViewControllers(["VIEWCONTROLLER_TO_BLACKLIST"])

[thumbnailAd setBlacklistViewControllers:@[@"VIEWCONTROLLER_TO_BLACKLIST"]];

When a user navigates to a ViewController that is neither in the whitelisted bundles nor explicitly blacklisted, the Thumbnail ad will be hidden and paused. It will reappear when the user returns to a permitted ViewController.

Last updated 4 days ago

Was this helpful?