Thumbnail

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

Last updated 6 months ago

Was this helpful?

Thumbnail

This article provides a comprehensive guide on the steps necessary to display Ogury Thumbnail ads in your application using Google Ad Manager 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 Ad Manager 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 and yield group in Google Ad Manager specifically for 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 Ad Manager ad unit

Access your .
Navigate to the list of Ad units and click on the New ad unit button.
Configure the ad unit as following:
- Name: enter a name for the ad unit (e.g., Thumbnail Ad).
- Code: set a unique code for the integration.
- Size Mode: select Fixed size.
Sizes: Choose the various sizes of Thumbnail Ads you plan to use in your app. We recommend using a size of 200x200 to enhance the readability of the Thumbnail ad content
Refresh Rate: Select No refresh, to prevent Thumbnail ads from appearing in front of users every few seconds.

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

maxWidth and maxHeight must not exceed the screen size.
Both maxWidth and maxHeight must be greater than or equal to 101dp.
The longest side, either maxWidth or maxHeight, must be at least 180dp.

Step 3: Create a dedicated Yield Group

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

In your GAM dashboard, navigate to Delivery > Yield groups from the left menu.
Click on Delivery > Yield groups in the left-menu of your Google Ad Manager dashboard.
Click on New yield group.
Configure the details of the yield group as follows:
- Name: Enter a name for the yield group (e.g., Thumbnail Ad Android).
- Status: Set to Active.
- Ad Format: Select Banner.
- Inventory Type: Choose Mobile app.

Scroll down to the Targeting section.
Expand the Inventory size section.
- Click the checkbox next to this size to select it.

Expand the Inventory section.
- Click the arrow next to Ad units.
- Search for the ad units where you want to display a Thumbnail ad.
- Click the check mark to include them in the targeting.

Scroll down to the Yield partners section at the bottom of the page.
- Click on Add yield partner.
- Select Ogury from the Yield Partner dropdown menu.

In the New yield partner pop-up, choose Custom Event as the Integration type and enter the CPM you agreed upon with your Ogury Account Manager as the Default CPM.
Under Additional yield partner details, set the Label to match your ad unit name in the Ogury dashboard (e.g., Ogury). This helps ensure that your settings are consistent across both Ogury and GAM.
Configure the Class Name and Parameter as follows:

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 Ad Manager 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(this, "OGY-XXXXXXXXXXXX", object : OguryOnStartListener {
    override fun onStarted() {
        // Initialization successful
    }
    override fun onFailed(error: OguryError) {
        // Handle initialization failure
    }
})

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 :

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 OguryThumbnailAdForGam object and call its load() method.

class MyActivity : Activity() {

    private lateinit var thumbnailAd: OguryThumbnailAdForGam

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

        thumbnailAd = OguryThumbnailAdForGam(
            this, 
            "your Google Ad Manager ad unit ID"
        )
        thumbnailAd.load()
    }
}

public class MyActivity extends Activity {

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

OguryThumbnailAdForGam requires the following parameters:

adUnitID: the Google Ad Manager 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 OguryThumbnailAdForGam 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.

thumbnailAd.listener = object : OguryThumbnailAdListener {

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

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

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

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

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

thumbnailAd.listener = new OguryThumbnailAdListener() {

    // Called when the ad is loaded and ready to be shown
    @Override
    public void onAdLoaded(OguryThumbnailAdForGam) {
        // Call show() to display the ad
    }
    
    // Called when an impression is recorded
    @Override
    public void onAdImpression(OguryThumbnailAdForGam thumbnailAd) {
        // Track ad performance here
    }
    
    // Called when the user clicks on the ad
    @Override
    public void onAdClicked(OguryThumbnailAdForGam thumbnailAd) {
        // Handle ad click tracking here
    }
    
    // Called when the ad is closed
    @Override
    public void onAdClosed(OguryThumbnailAdForGam thumbnailAd) {
        // Resume app flow after ad is closed
    }
    
    // Called when the ad fails to load or display
    @Override
    public void onAdError(OguryThumbnailAdForGam thumbnailAd, 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 OguryThumbnailAdForGam object.

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

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:

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 yield group, for example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_test.

Advanced Topics

Customizing Thumbnail ad size

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

thumbnailAd = new OguryThumbnailAdForGam(this, "YOUR_GAM_UNIT_ID", maxWidth, maxHeight);

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

Example: when given maxWidth= 200 and maxHeight= 200, the Ogury SDK may decide to display a 16:9 video ad inside. In this case the Thumbnail Ad size will be 180x113dp 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 specify the position of a Thumbnail ad, invoke the setPosition() method with parameters: OguryThumbnailGravity, xMargin and yMargin.

thumbnailAd.setPosition(gravity, xMargin, yMargin)

thumbnailAd.setPosition(gravity, xMargin, yMargin);

The setPosition method takes the following parameters:

gravity : the corner from which the Thumbnail ad will be positioned. The OguryThumbnailGravityenum includes the following values:
- TOP_LEFT
- TOP_RIGHT
- BOTTOM_LEFT
- BOTTOM_RIGHT

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.

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:

Call the setWhiteListPackages method to whitelist packages:

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

Blacklist activities:

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

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

Customizing in which fragments Thumbnail Ad is displayed

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.

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:

Call the setWhiteListFragmentPackages method to whitelist packages:

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

Blacklist fragments:

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.

Last updated 6 months ago

Was this helpful?