Thumbnail Ad

This article provides a comprehensive guide on the steps necessary to display Ogury Thumbnail ads in your application using Google AdMob mediation.

Last updated 5 months ago

Was this helpful?

Thumbnail Ad

This article provides a comprehensive guide on the steps necessary to display Ogury Thumbnail ads in your application using Google AdMob mediation.

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.

Unlike other ad formats, there is no out-of-the-box equivalent for Thumbnail ads in Google AdMob mediation. To integrate them, the Ogury SDK leverages Google Mobile Ads custom events, presenting Thumbnail ads as banners within the mediation.

You must create a dedicated banner ad unit mediation group in Google AdMob specifically for the Thumbnail ads. Failing to do so could result in undesirable effects, such as blank banners.

However, you can configure it so that a Thumbnail ad unit is called first, and if not filled, a Banner ad unit is called as a fallback. See an example here.

Prerequisites

Ensure your application is registered on the Ogury Dashboard. If not, please refer to the page before proceeding.

Step 1: Create a Thumbnail ad unit

on your asset page in the Ogury Dashboard.
, as you will need it for integration. 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.

In the following code samples, this ad unit ID will be represented as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Step 2: Create a dedicated Google AdMob ad unit

Access your .
Navigate to the list of Ad units and click on the Add ad unit button.
Click on Banner.

Configure the ad unit as following:
- Name: Enter a name for the ad unit (e.g., Thumbnail Ad).
- Click on the Advanced settings link to expand the options.
  - Automatic refresh: select Disabled, to prevent Thumbnail ads from appearing in front of users every few seconds.
  - eCPM floor: set the global eCPM floor to $1000 to prevent Google AdMob to serve its ads on this dedicated ad unit.

Step 3: Create a dedicated Mediation Group

In order to display Ogury Thumbnail ads through Google AdMob mediation, you need to configure a Custom Event for Ogury within a dedicated mediation group.

Click CREATE MEDIATION GROUP.
Select Banner as the ad format.
Enter a Name for the mediation group.
In the Ad Units section, click ADD AD UNITS.
Select the dedicated ad unit you created earlier.
In the Waterfall section, click on ADD CUSTOM EVENT.

Enter Ogury as the Label, set the eCPM, and click on CONTINUE.

For eCPM, set the value that you have agreed upon with your Ogury Account Manager.

Next to the name of your Thumbnail ad unit, enter the following configuration, and click DONE:

Class Name:

OguryThumbnailCustomEvents

Parameter:

{"assetKey":"OGY-XXXXXXXXXXXX","adUnitId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

Click on SAVE

Step 4: Integrate an Ogury Thumbnail Ad

To manage a Thumbnail ad through Google AdMob mediation, Ogury provides a dedicated API that simplifies the integration process.

Step 4.1: Initialize the Ogury SDK

When using a Consent Management Platform (CMP), it is recommended to wait for the CMP to establish the consent status before initializing the Ogury SDK.

To initialize the Ogury SDK, simply call the Ogury.start() method.

Ogury.start(with: "OGY-XXXXXXXXXXXX") { success, error in
    guard error == nil, success else {
        // handle error here
        return
    }
    // handle start here
}

[Ogury startWith:@"OGY-XXXXXXXXXXXX" completionHandler:^(BOOL success, OguryError * _Nullable error) {
    if (error) {
        // handle the error
    } else if (success) {
        // handle start here
    }
}];

Though optional, the StartCompletionBlock is recommended. It provides callbacks for successful initialization or errors. If initialization fails, the listener returns an OguryError with an error code and localizedDescription, helping you troubleshoot. The possible errors are defined in the OguryStartErrorCode enum for easy reference.

OguryStartErrorCode

Enum value

Description

ModuleMissing

The SDK could not be started because a required SDK module is missing.

ModuleFailedToStart

The SDK could not be started because one of the required SDK modules failed to start.

Step 4.2: Load a Thumbnail ad

To load a Thumbnail ad, instantiate an OguryThumbnailAdForGoogleMobileAds object and call its load() method.

import UIKit
import OguryAds

class ViewController: UIViewController {
    private(set) var thumbnailAd: OguryThumbnailAdForGoogleMobileAds!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        thumbnailAd = OguryThumbnailAdForGoogleMobileAds(adUnitID: "your Google AdMob ad unit ID")
        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 = [[OguryThumbnailAdForGoogleMobileAds alloc] initWithAdUnitId:@"your Google AdMob ad unit ID"];
    [self.thumbnailAd load];  
}

@end

OguryThumbnailAdForGoogleMobileAds requires the following parameter:

adUnitID: the Google AdMob ad unit ID for the Thumbnail ad.

Step 4.3: 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 OguryThumbnailAdForGoogleMobileAds and implement the necessary methods. This ensures timely notifications, allowing you to manage the ad experience effectively.

override func viewDidLoad() {
    super.viewDidLoad()
    thumbnailAd = OguryThumbnailAdForGoogleMobileAds(
        adUnitID: "your Google AdMob ad unit ID"
    )
    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 = [[OguryThumbnailAdForGoogleMobileAds alloc] initWithAdUnitID:@"your Google AdMob ad unit ID"];
    self.thumbnailAd.delegate = self;
    [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
    }
}

Step 4.4: Show a Thumbnail ad

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

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];
}

Step 5: Test your integration

After registering your app, it may take up to 15 minutes before ads are available.

Since our algorithm uses personalized targeting, you may not receive ads during testing. To obtain test ads, you can append _test to your Thumbnail ad unit ID in your mediation group, for example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_test.

Advanced Topics

Customizing Thumbnail ad size

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

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

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

Constraints:

maxWidth and maxHeight cannot exceed the device’s screen size.

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:

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

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

Blacklist View Controllers

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

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

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

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.

Error handling

If you are unable to load or display any Thumbnail ads, we recommend logging callbacks from the OgurythumbnailAdDelegate to monitor the ad's lifecycle, especially the thumbnailAd:didFailWithError callback. This method provides an an OguryAdError instance containing important error details:

type: indicates the error type through the OguryAdErrorType enum, which distinguishes between loading errors (OguryAdErrorTypeLoad) and showing errors (OguryAdErrorTypeShow).
code: An integer that identifies the specific error. The enums OguryLoadErrorCode and OguryShowErrorCode define potential error codes that may occur during loading or showing ads. Further details on these enums are provided in the tables below.
localizedDescription: A descriptive message that provides additional context about the error.

You can utilize these details to diagnose the issue and take appropriate action to resolve it.

Last updated 5 months ago

Was this helpful?