Thumbnail

This guide explains how to integrate Thumbnail ads using the Ogury SDK in your Android 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 Thumbnail ad:

Instantiate an OguryThumbnailAd object with a valid Thumbnail ad unit ID.
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.

class MyActivity : Activity() {

    private lateinit var thumbnailAd: OguryThumbnailAd

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

        thumbnailAd = OguryThumbnailAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        thumbnailAd.load()
    }
}

public class MyActivity extends Activity {

    private OguryThumbnailAd thumbnailAd;
    
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
                        
        thumbnailAd = new OguryThumbnailAd(this, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
        thumbnailAd.load() 
    }
    
}

The OguryThumbnailAd constructor takes the following parameters:

A reference to any kind of context.
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.

thumbnailAd = OguryThumbnailAd(
    this, 
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    OguryMediation("your mediation name", "your mediation SDK version")
)

thumbnailAd = new OguryThumbnailAd(
    this, 
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    new OguryMediation("your mediation name", "your mediation SDK version")
);

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 OguryThumbnailAd 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 Ad Error handling section below for detailed information on troubleshooting.

thumbnailAd.setListener(object : OguryThumbnailAdListener {

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

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

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

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

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

thumbnailAd.setListener(new OguryThumbnailAdListener() {

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

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

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:

A reference to the Activity in which you want to display the Thumbnail ad.

Always check isLoaded() before calling show(), unless you are calling directly from the onAdLoaded 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 OguryInterstitialAdListener to track the full ad lifecycle. Pay particular attention to the onAdError 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 v5? Follow our step-by-step migration guide to smoothly upgrade to v6 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.load(maxWidth, maxHeight)

thumbnailAd.load(maxWidth, maxHeight);

The maxWidth and maxHeight parameters specify the maximum dimensions, in dp, 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 dp 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 dp.
The longest side, either maxWidth or maxHeight, must be at least 180 dp.

Customizing Thumbnail ad position

To specify the position of a Thumbnail ad, invoke the show() method with additional parameters: OguryThumbnailGravity, xMargin and yMargin.

thumbnailAd.show(activity, gravity, xMargin, yMargin)

thumbnailAd.show(activity, gravity, xMargin, yMargin);

The show() method takes the following parameters:

activity: a reference to the Activity in which you want to display the Thumbnail ad.
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
xMargin: the horizontal distance from the x-axis to the Thumbnail ad, expressed in dp.
yMargin: the vertical distance from the y-axis to the Thumbnail ad, expressed 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(activity)

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

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.

Last updated 4 days ago

Was this helpful?