Thumbnail

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.

Prerequisites

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

Step 1: Create a Thumbnail ad unit

• Create an Interstitial ad unit on your asset page in the Ogury Dashboard.

• Copy the ad unit ID, 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 Google AdMob dashboard.

• 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.

• Go on the Mediation Group page.
• 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:

com.ogury.mobileads.OguryThumbnailAdCustomEvent

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.

Kotlin

Ogury.start(this, "OGY-XXXXXXXXXXXX", object : OguryOnStartListener {
    override fun onStarted() {
        // Initialization successful
    }
    override fun onFailed(error: OguryError) {
        // Handle initialization failure
    }
})

Java

Ogury.start(this, "OGY-XXXXXXXXXXXX", new OguryOnStartListener() {
    @Override
    public void onStarted() {
        // Initialization successful
    }

    @Override
    public void onFailed(OguryError error) {
        // Handle initialization failure
    }
});

The start() method requires two key parameters :

• the Application context
• the Ogury asset key associated with your app. If you have not an asset key yet, please refer to the Getting started page to create one.

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

OguryStartErrorCode

Enum value	Description
MODULE_MISSING	The SDK could not be started because a required SDK module is missing.
MODULE_FAILED_TO_START	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 OguryThumbnailAdForAdmob object and call its load() method.

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

Kotlin

class MyActivity : Activity() {

    private lateinit var thumbnailAd: OguryThumbnailAdForAdmob

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        thumbnailAd = OguryThumbnailAdForAdmob(
            this, 
            "your Google AdMob ad unit ID"
        )
        thumbnailAd.load()
    }
}

Java

public class MyActivity extends Activity {

    private OguryThumbnailAdForAdmob thumbnailAd;
    
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
                        
        thumbnailAd = new OguryThumbnailAdForAdmob(this, "your Google AdMob ad unit ID")
        thumbnailAd.load() 
    }
    
}

OguryThumbnailAdForGam requires the following parameters:

• context: a reference to any kind of Context.
• 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 OguryThumbnailAdListener interface. This listener provides real-time updates on key events, such as successful ad loading, display, or errors.

To use it, set the listener on the instance of OguryThumbnailAdForAdmob by calling the setListener() method before invoking the load() method. Implement the necessary methods in your class to ensure timely notifications, allowing you to manage the ad experience effectively.

If the onAdErrorcallback is triggered, refer to the Error handling section below for detailed information on troubleshooting.

Kotlin

thumbnailAd.listener = object : OguryThumbnailAdListener {

    // Called when the ad is loaded and ready to be shown
    override fun onAdLoaded(thumbnailAd: OguryThumbnailAdForAdmob) {
        // Call show() to display the ad
    }

    // Called when an impression is recorded
    override fun onAdImpression(thumbnailAd: OguryThumbnailAdForAdmob) {
        // Track ad performance here
    }

    // Called when the user clicks on the ad
    override fun onAdClicked(thumbnailAd: OguryThumbnailAdForAdmob) {
        // Handle ad click tracking here
    }

    // Called when the ad is closed
    override fun onAdClosed(thumbnailAd: OguryThumbnailAdForAdmob) {
        // Resume app flow after ad is closed
    }

    // Called when the ad fails to load or display
    override fun onAdError(thumbnailAd: OguryThumbnailAdForAdmob, error: OguryAdError) {
        when (error.type) {
            OguryAdError.Type.LOAD_ERROR -> {
                // Handle loading error
            }
            OguryAdError.Type.SHOW_ERROR -> {
                // Handle display error
            }
        }
    }
})

Java

thumbnailAd.listener = new OguryThumbnailAdListener() {

    // Called when the ad is loaded and ready to be shown
    @Override
    public void onAdLoaded(OguryThumbnailAdForAdmob) {
        // Call show() to display the ad
    }
    
    // Called when an impression is recorded
    @Override
    public void onAdImpression(OguryThumbnailAdForAdmob) {
        // Track ad performance here
    }
    
    // Called when the user clicks on the ad
    @Override
    public void onAdClicked(OguryThumbnailAdForAdmob thumbnailAd) {
        // Handle ad click tracking here
    }
    
    // Called when the ad is closed
    @Override
    public void onAdClosed(OguryThumbnailAdForAdmob) {
        // Resume app flow after ad is closed
    }
    
    // Called when the ad fails to load or display
    @Override
    public void onAdError(OguryThumbnailAdForAdmob, OguryAdError error) {
        switch (error.type) {
            case OguryAdError.Type.LOAD_ERROR:
                // Handle loading error
                break;
            case OguryAdError.Type.SHOW_ERROR:
                // Handle display error
                break;
        }
    }
    
});

Step 4.4: Show a Thumbnail ad

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

By default, Thumbnail ad is aligned to the bottom-right corner, maintaining a margin of 20 dp from the right edge and 70 dp from the bottom. For more information on configuring the ad's position, please refer to the Customizing Thumbnail ad position section.

Additionally, a Thumbnail ad stays visible while the user navigates between the activities of your application. It is displayed in an activity only if the first two packages of its class name match the first two packages of the class name of the activity specified in the show() method. For details on how to customize these default settings using whitelists and blacklists, please see the Customizing Thumbnail ad display section.

Kotlin

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

Java

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

The show method takes the following parameter:

• activity: a reference to the Activity in which you want to display the Thumbnail ad.

Step 5: Test your integration

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

Ogury exclusively serves ads to users who have provided their consent. Before conducting any tests, it is essential to ensure that your implementation complies with applicable privacy regulations. For more information on the regulations supported by Ogury, please visit the Privacy compliance page.

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.

For further details on test mode and enabling debug logs, please refer to the Test your implementation page.

Advanced Topics

Customizing Thumbnail ad size

In order to control the thumbnail size, set the size when initialising the OguryThumbnailAdForAdmob object with maxWidth and maxHeight parameters before calling load method

Kotlin

thumbnailAd = OguryThumbnailAdForAdmob(
    this, 
    "your Google AdMob ad unit ID",
    maxWidth,
    maxHeight
);

Java

thumbnailAd = new OguryThumbnailAdForAdmob(
    this,
    "your Google AdMob ad unit ID",
    maxWidth,
    maxHeight
);

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

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 180x102dp 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 101dp.

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

  180dp.

Customizing Thumbnail ad position

To set the thumbnail position, call the setPosition method with gravity and margin parameters before calling the show method:

thumbnailAd.setPosition(gravity, xMargin, yMargin);

The setPosition method takes the following parameters:

• gravity : the corner based on which the thumbnail will be positioned, it can have the following values:

  • OguryThumbnailGravity.TOP_LEFT

  • OguryThumbnailGravity.TOP_RIGHT

  • OguryThumbnailGravity.BOTTOM_LEFT

  • OguryThumbnailGravity.BOTTOM_RIGHT

• xMargin: distance on the x axis from the gravity corner to thumbnail. Value must be in dp.
• yMargin: distance on the y axis from the gravity corner to thumbnail. Value must be in dp.

Customizing Thumbnail ad display

Customizing in which activities Thumbnail ad is displayed

Thumbnail ad remains on screen while the user navigates across the activities of your application.

By default, a Thumbnail ad is displayed in an Activity only if the two first packages of its classname match the two first packages of the classname of the Activity passed as parameter to the show method.

Example: If you pass com.ogury.game.GameActivity as parameter of the show method, the Thumbnail Ad will stay on screen in all the activities in the com.ogury package and all packages at any level under it.

You can override these default settings using whitelists and blacklists.

Whitelist packages:

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

Call the setWhiteListPackages method to whitelist packages:

thumbnailAd.setWhiteListPackages("org.games.ui", "com.settings.activities");

Blacklist activities:

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

thumbnailAd.setBlackListActivities(
    TermsAndConditionsActivity.class, 
    SettingsActivity.class);

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

The method logWhiteListedActivities can be used to display all whitelisted activities. It should be called only after setting the whitelist and blacklist.

thumbnailAd.logWhiteListedActivities(true)

After calling the method logWhiteListedActivities, connect your device to Android studio and filter the logs by OGURY tag. You will see logs that start with Whitelisted:, for example Whitelisted: com.ogury.HomeActivity

Customize in which fragments Thumbnail Ad is displayed

Filtering by fragments is supported for androidx fragments and v4 support fragments, but is not supported for native fragments. Thumbnail Ad needs FragmentLifecycleCallbacks to work and the native fragments have lifecycle callbacks only starting with android 8.

In case the application is based mostly on fragments and there are fragments in which the thumbnail ad should not be displayed, a filtering on fragments instead of activities can be done. In order to change the filtering from activities to fragments, setBlackListFragments or setWhiteListFragmentPackages must be called.

By default, a Thumbnail Ad is displayed in a Fragment only if the two first packages of its classname matches the two first packages of the classname of the Activity passed as parameter to the show method.

Example: If you pass com.ogury.game.GameFragmentActivity as parameter of the show method, the Thumbnail Ad will stay on screen as long as a fragment is visible to the user and is part ofcom.ogury package and all packages at any level under it.

You can override these default settings using whitelists and blacklists.

Whitelist packages:

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

Call the setWhiteListFragmentPackages method to whitelist packages:

thumbnailAd.setWhiteListFragmentPackages("org.games.ui", "com.settings.fragments");

Blacklist fragments:

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

thumbnailAd.setBlackListFragments(
    BannerAdsFragment.class, 
    SettingsFragment.class);

When fragment filters are set, Thumbnail Ad is displayed only if the top activity contains no blacklisted visible fragment and it contains at least one whitelisted visible fragment. This condition is checked every time a fragment's onResume or onPause is called and if the condition is not true anymore, Thumbnail Ad is hidden.

Error handling

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

• type: indicates the error type through the OguryAdError.Type enum, which distinguishes between loading errors (Load) and showing errors (Show).

• code: An integer that identifies the specific error. Errors that can occur during ad loading or displaying are defined in the OguryLoadErrorCode and OguryShowErrorCode classes. Detailed explanations of these error codes are provided in the tables below to assist you in troubleshooting effectively.

• message: 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.